@withgateway/sdk 0.3.3 → 0.6.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 (158) hide show
  1. package/README.md +4 -3
  2. package/dist/cli.js +3005 -1401
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2996 -1392
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +128 -37
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +126 -35
  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-mJhG3vZU.d.mts → index-Di9nNqOY.d.mts} +26 -3
  19. package/dist/{index-DUHmS74p.d.ts → index-LA-PMRJT.d.ts} +26 -3
  20. package/dist/index.d.mts +4 -4
  21. package/dist/index.d.ts +4 -4
  22. package/dist/index.js +1078 -260
  23. package/dist/index.js.map +1 -1
  24. package/dist/index.mjs +1040 -251
  25. package/dist/index.mjs.map +1 -1
  26. package/dist/replay/index.d.mts +1 -1
  27. package/dist/replay/index.d.ts +1 -1
  28. package/dist/replay/index.js.map +1 -1
  29. package/dist/replay/index.mjs.map +1 -1
  30. package/dist/traces/index.js +125 -34
  31. package/dist/traces/index.js.map +1 -1
  32. package/dist/traces/index.mjs +123 -32
  33. package/dist/traces/index.mjs.map +1 -1
  34. package/dist/tracing/index.d.mts +1 -1
  35. package/dist/tracing/index.d.ts +1 -1
  36. package/dist/tracing/index.js +7 -1
  37. package/dist/tracing/index.js.map +1 -1
  38. package/dist/tracing/index.mjs +7 -1
  39. package/dist/tracing/index.mjs.map +1 -1
  40. package/dist/worlds/index.d.mts +819 -438
  41. package/dist/worlds/index.d.ts +819 -438
  42. package/dist/worlds/index.js +912 -236
  43. package/dist/worlds/index.js.map +1 -1
  44. package/dist/worlds/index.mjs +908 -232
  45. package/dist/worlds/index.mjs.map +1 -1
  46. package/package.json +1 -1
  47. package/runtime/gatewaysdk/environment/_bundle.py +4 -6
  48. package/runtime/gatewaysdk/environment/_materialize.py +5 -25
  49. package/runtime/gatewaysdk/environment/_world.py +82 -66
  50. package/runtime/gatewaysdk/environment/backing.py +20 -24
  51. package/runtime/gatewaysdk/environment/core.py +1 -16
  52. package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
  53. package/runtime/gatewaysdk/environment/runtime.py +45 -2
  54. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  55. package/runtime/gatewaysdk/environment/schema/api.py +198 -474
  56. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  57. package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
  58. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  59. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  60. package/runtime/gatewaysdk/environment/schema/call_capture.py +321 -0
  61. package/runtime/gatewaysdk/environment/schema/call_log.py +276 -18
  62. package/runtime/gatewaysdk/environment/schema/call_redaction.py +207 -19
  63. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  64. package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
  65. package/runtime/gatewaysdk/environment/schema/conform.py +38 -35
  66. package/runtime/gatewaysdk/environment/schema/connector.py +94 -152
  67. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  68. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
  69. package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
  70. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +10 -19
  71. package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
  72. package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
  75. package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
  76. package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
  77. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
  78. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
  79. package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
  80. package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
  81. package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
  82. package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
  83. package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
  84. package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
  85. package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
  86. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  87. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  88. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  89. package/runtime/gatewaysdk/environment/schema/data.py +14 -13
  90. package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
  91. package/runtime/gatewaysdk/environment/schema/database/guard.py +45 -37
  92. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  93. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
  94. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  95. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  96. package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
  97. package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +52 -5
  99. package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
  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 +438 -0
  112. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  113. package/runtime/gatewaysdk/environment/schema/local.py +32 -116
  114. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
  115. package/runtime/gatewaysdk/environment/schema/platform.py +29 -234
  116. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  117. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  118. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  119. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  120. package/runtime/gatewaysdk/environment/schema/runtime.py +136 -176
  121. package/runtime/gatewaysdk/environment/schema/scaffold.py +2 -1
  122. package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
  123. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  124. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  125. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
  126. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  127. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +50 -28
  128. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
  129. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +20 -22
  130. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +25 -25
  131. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
  132. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +71 -7
  133. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  134. package/runtime/gatewaysdk/environment/schema/snapshot.py +150 -30
  135. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  136. package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
  137. package/runtime/gatewaysdk/environment/schema/tools_world.py +103 -203
  138. package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
  139. package/runtime/gatewaysdk/environment/schema/verbs.py +38 -36
  140. package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
  141. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  142. package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
  143. package/runtime/gatewaysdk/environment/schema/world_host.py +970 -0
  144. package/runtime/gatewaysdk/environment/schema/world_tests.py +83 -11
  145. package/runtime/gatewaysdk/environment/world.py +1 -1
  146. package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
  147. package/skills/agents/connector-template-author.md +5 -1
  148. package/skills/benchmarks-getting-started/SKILL.md +8 -9
  149. package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  150. package/skills/connector-schema-authoring/SKILL.md +50 -28
  151. package/skills/connector-schema-authoring/connector-worlds.md +282 -18
  152. package/skills/connector-schema-authoring/world-schema.md +7 -6
  153. package/skills/world-data-ingestion/ROWS.md +12 -8
  154. package/skills/world-data-ingestion/SKILL.md +20 -22
  155. package/skills/worlds-getting-started/SKILL.md +25 -25
  156. package/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
  157. package/skills/worlds-getting-started/references/gotchas.md +71 -7
  158. 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.6.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",
@@ -18,6 +18,7 @@ import importlib.util
18
18
  import inspect
19
19
  import sys
20
20
  import uuid
21
+ from contextlib import ExitStack
21
22
  from dataclasses import dataclass, field
22
23
  from pathlib import Path
23
24
  from typing import Any, Callable, Dict, List, Optional
@@ -124,8 +125,8 @@ def load_handlers(bundle_path: Path, manifest: EnvManifest) -> Dict[str, Callabl
124
125
  handler_files = sorted(tools_dir.glob("*.py")) if tools_dir.is_dir() else []
125
126
  load_token = runtime._load_registry.set(registry)
126
127
  strict_token = runtime._strict_registration.set(contract is not None)
127
- saved = sys.modules.get("gateway_env")
128
- sys.modules["gateway_env"] = runtime
128
+ installed = ExitStack()
129
+ installed.enter_context(runtime.installed(runtime))
129
130
  # Generated bundles use intra-bundle imports ("from tools._db import …"),
130
131
  # so the bundle root must be importable for the load's dynamic extent.
131
132
  bundle_root = str(bundle_path)
@@ -158,10 +159,7 @@ def load_handlers(bundle_path: Path, manifest: EnvManifest) -> Dict[str, Callabl
158
159
  modules.append(module)
159
160
  modules_by_stem[handler_file.stem] = module
160
161
  finally:
161
- if saved is not None:
162
- sys.modules["gateway_env"] = saved
163
- else:
164
- sys.modules.pop("gateway_env", None)
162
+ installed.close()
165
163
  if path_added:
166
164
  try:
167
165
  sys.path.remove(bundle_root)
@@ -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,25 @@ 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
23
+ from .schema.webhooks import WebhookOutbox, Webhooks
30
24
 
31
25
 
32
26
  @dataclass
33
27
  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``."""
28
+ """``passed`` is ``score >= 1.0``; a ``None`` score is ungraded, never 0, and has ``passed=None``."""
37
29
 
38
30
  name: str
39
31
  passed: Optional[bool]
40
32
  score: Optional[float]
41
33
  detail: str = ""
42
34
  rewards: Dict[str, float] = field(default_factory=dict)
35
+ closed: Optional[str] = None
43
36
 
44
37
 
45
38
  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)."""
39
+ """Every reader's score rule, pinned by ``sql-verifier-vectors.json``: NULL or no rows is ``None``, never 0."""
53
40
 
54
41
  def __init__(self, name: str, script: str, split: Callable[[str], List[str]]) -> None:
55
42
  self.name = name[:-4] if name.endswith(".sql") else name
@@ -57,14 +44,9 @@ class SqlVerifier:
57
44
 
58
45
  @classmethod
59
46
  def read(cls, path: Path, split: Callable[[str], List[str]]) -> "SqlVerifier":
60
- """``split`` is the engine's statement splitter (``WorldDatabase.split_statements``)."""
61
47
  return cls(path.stem, path.read_text(encoding="utf-8"), split)
62
48
 
63
49
  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
50
  value: Any = None
69
51
  last_sql: Optional[str] = None
70
52
  for statement in self.statements:
@@ -92,18 +74,12 @@ _NO_INPUT = object()
92
74
 
93
75
 
94
76
  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
77
  if tool_input is not _NO_INPUT:
98
78
  return tool_input
99
79
  return kwargs if kwargs else _NO_INPUT
100
80
 
101
81
 
102
82
  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
83
  def __init__(self, world: "World") -> None:
108
84
  self._world = world
109
85
 
@@ -129,14 +105,6 @@ class WorldRegistry(StubRegistryMapping):
129
105
 
130
106
 
131
107
  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
108
  def __init__(
141
109
  self,
142
110
  env: "Environment",
@@ -147,12 +115,17 @@ class World:
147
115
  ) -> None:
148
116
  self.env = env
149
117
  self.id = world_id or uuid.uuid4().hex[:8]
150
- self.db_path: Path = env._worlds_dir / f"world-{self.id}.db"
118
+ self.db_path: Path = self.database_file(env._worlds_dir, self.id)
151
119
  self.call_log: List[Dict[str, Any]] = []
152
120
  self._template = self._proven(template)
153
121
  self.contract = template.contract if template is not None else self._bundle_contract()
154
122
  source, audit = (Path(snapshot), True) if snapshot is not None else self._seed()
155
123
  self._backing = WorldBacking.branch(source, self.db_path, self.contract, audit=audit)
124
+ self.webhooks = self._webhook_outbox(None)
125
+
126
+ @staticmethod
127
+ def database_file(directory: Path, world_id: str) -> Path:
128
+ return Path(directory) / f"world-{world_id}.db"
156
129
 
157
130
  @staticmethod
158
131
  def _proven(template: Any) -> Any:
@@ -162,24 +135,40 @@ class World:
162
135
 
163
136
  return ProvenTemplate.required(template)
164
137
 
138
+ def serve_webhooks(self, webhooks: "Webhooks | None") -> None:
139
+ """Deliveries this world's tools stage go to the subscriptions ``webhooks`` declares."""
140
+ if webhooks is not None and self.contract is not None:
141
+ webhooks.check_contract(self.contract.entities)
142
+ self.webhooks = self._webhook_outbox(webhooks if self.contract is not None else None)
143
+
144
+ def _webhook_outbox(self, webhooks: "Webhooks | None") -> "WebhookOutbox":
145
+ from .schema.api import ApiContext
146
+ from .schema.primary_key import PrimaryKey
147
+ from .schema.webhooks import WebhookOutbox
148
+
149
+ return WebhookOutbox(
150
+ webhooks,
151
+ lambda entity: list(self.store.list(entity)),
152
+ lambda entity, row: PrimaryKey.in_contract(self.contract, entity).key(row),
153
+ ApiContext.clock,
154
+ )
155
+
165
156
  def _bundle_contract(self) -> Any:
166
157
  from .schema import bundle_mode, check_bundle
167
158
 
168
159
  return check_bundle(self.env.bundle_path) if bundle_mode(self.env.bundle_path) is not None else None
169
160
 
170
161
  def _seed(self) -> "tuple[Path, bool]":
171
- """The file a fresh or reset world copies, and whether its rows are audited."""
172
162
  if self._template is None:
173
163
  return Path(self.env._template_db), True
174
164
  return self._template.path, False
175
165
 
176
166
  @property
177
167
  def store(self):
178
- """The world database of a schema world; ``None`` for a contract-less mock-tools world."""
168
+ """``None`` for a contract-less mock-tools world."""
179
169
  return self._backing.store
180
170
 
181
171
  def execute(self, tool_name: str, tool_input: Any = _NO_INPUT) -> Any:
182
- """Execute atomically in schema mode, validating both input and output."""
183
172
  from .schema.validation import validate
184
173
 
185
174
  handler = self.env._handlers.get(tool_name)
@@ -187,7 +176,7 @@ class World:
187
176
  raise ToolRouteError(f"tool '{tool_name}' has no declared env handler")
188
177
  supplied = ({} if self.contract else None) if tool_input is _NO_INPUT else tool_input
189
178
  started = time.perf_counter()
190
- with self._backing.transaction():
179
+ with self.webhooks.transaction(), self._backing.transaction():
191
180
  if self.contract is not None:
192
181
  validate(
193
182
  self.contract.tools[tool_name]["input_schema"],
@@ -196,6 +185,7 @@ class World:
196
185
  )
197
186
  token = runtime._active_connection.set(self._backing.handler_connection())
198
187
  store_token = runtime._active_store.set(self.store)
188
+ webhooks_token = runtime._active_webhooks.set(self.webhooks)
199
189
  try:
200
190
  if isinstance(supplied, Mapping):
201
191
  result = handler(**supplied)
@@ -212,6 +202,7 @@ class World:
212
202
  finally:
213
203
  runtime._active_connection.reset(token)
214
204
  runtime._active_store.reset(store_token)
205
+ runtime._active_webhooks.reset(webhooks_token)
215
206
  duration_ms = (time.perf_counter() - started) * 1000.0
216
207
  self.call_log.append({"tool": tool_name, "match": "env", "input": supplied})
217
208
  self.env._record_route(tool_name, "env", duration_ms, self.id)
@@ -236,14 +227,10 @@ class World:
236
227
  )
237
228
 
238
229
  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."""
230
+ """Drop-in for agent tool layers, with the contract of replay's ``ToolStubRegistry.as_registry()``."""
241
231
  return WorldRegistry(self)
242
232
 
243
233
  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
234
  def routed_to_env(name: Optional[str]) -> bool:
248
235
  return bool(name) and name in self.env._handlers and self.env.resolve_route(name) == "env"
249
236
 
@@ -265,11 +252,11 @@ class World:
265
252
  return wrapped
266
253
 
267
254
  def reset(self) -> None:
268
- """Back to the seed, in place (same world instance)."""
269
255
  if self._template is None:
270
256
  self._refuse_a_changed_contract()
271
257
  source, audit = self._seed()
272
258
  self._relay(source, audit=audit)
259
+ self.webhooks.clear()
273
260
 
274
261
  def _refuse_a_changed_contract(self) -> None:
275
262
  """An environment's bundle can change under a live world; a version's cannot."""
@@ -281,14 +268,11 @@ class World:
281
268
  raise ContractError("state_contract", "Bundle contract changed; create a new world explicitly")
282
269
 
283
270
  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."""
271
+ """Audited row by row: the file is not one this store wrote."""
287
272
  self._relay(Path(source), audit=True)
288
273
 
289
274
  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."""
275
+ """No second row audit: a :class:`SessionExport` is digest-verified or this session's own recovered store."""
292
276
  from .schema.session_files import SessionExport
293
277
 
294
278
  self._relay(SessionExport.required(export).path, audit=False)
@@ -298,39 +282,43 @@ class World:
298
282
  self._backing = WorldBacking.branch(source, self.db_path, self.contract, audit=audit)
299
283
 
300
284
  def snapshot(self, destination: Union[str, Path]) -> Path:
301
- """Pin this world's current state to a file (for debugging fixtures)."""
302
285
  return self._backing.snapshot(Path(destination))
303
286
 
304
287
  def close(self) -> None:
305
288
  self._backing.close()
306
289
 
307
290
  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."""
291
+ """``False`` when a mock-tools world does not declare the table."""
309
292
  return self._backing.set_task_context(scenario_id)
310
293
 
311
294
  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."""
295
+ """``False`` when a mock-tools world does not declare the table."""
313
296
  return self._backing.set_run_parameters(parameters)
314
297
 
315
298
  def record_conversation_event(
316
- self, scenario_id: str, user_turn_index: int, event_type: str, actor: str, name: Optional[str], payload_json: str
299
+ self,
300
+ scenario_id: str,
301
+ user_turn_index: int,
302
+ event_type: str,
303
+ actor: str,
304
+ name: Optional[str],
305
+ payload_json: str,
317
306
  ) -> bool:
318
- """Log one turn event for verifiers; ``False`` when a mock-tools world does not declare the table."""
307
+ """``False`` when a mock-tools world does not declare the table."""
319
308
  return self._backing.record_conversation_event(
320
309
  scenario_id, user_turn_index, event_type, actor, name, payload_json
321
310
  )
322
311
 
323
312
  def state(self, sql: str, *params: Any) -> List[Dict[str, Any]]:
324
- """Read-only SQL against the world's db (SELECT/WITH only)."""
325
313
  return self._backing.rows(sql, params)
326
314
 
327
- def verify(self, name: str) -> VerifierResult:
328
- """Run ``verifiers/<name>.sql`` against this world.
315
+ def verify(self, name: str, journal: Optional["WorldJournal"] = None) -> VerifierResult:
316
+ """NULL or no rows scores ``None``, never 0. A verifier that read the journal fails closed when none was
317
+ recorded, and on an incomplete one unless ``gateway-env.toml`` declares
318
+ ``[verifiers.<name>] accepts_incomplete_journal = true``."""
319
+ from .schema.journal import JournalDatabase, WorldJournal
320
+ from .schema.validation import ContractError
329
321
 
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
322
  verifier_name = name[:-4] if name.endswith(".sql") else name
335
323
  path = self.env.bundle_path / "verifiers" / f"{verifier_name}.sql"
336
324
  if not path.is_file():
@@ -340,7 +328,20 @@ class World:
340
328
  def execute(statement: str) -> Optional[List[Any]]:
341
329
  return self._backing.verifier_rows(verifier_name, statement)
342
330
 
343
- score, last_sql = SqlVerifier.read(path, self._backing.split_statements).score(execute)
331
+ database = JournalDatabase(journal or WorldJournal.unrecorded(), self.db_path.parent / "journal")
332
+ verifier = SqlVerifier.read(path, self._backing.split_statements)
333
+ with self._backing.journal(database) as used:
334
+ try:
335
+ score, last_sql = verifier.score(execute)
336
+ except (ContractError, VerifierError):
337
+ closed = self._closed_on(verifier_name, database.journal, used(verifier.statements))
338
+ if closed is None:
339
+ raise
340
+ return VerifierResult(name=verifier_name, passed=False, score=0.0, detail=closed, closed=closed)
341
+ use = used(verifier.statements)
342
+ closed = self._closed_on(verifier_name, database.journal, use)
343
+ if closed is not None:
344
+ return VerifierResult(name=verifier_name, passed=False, score=0.0, detail=closed, closed=closed)
344
345
  if last_sql is None:
345
346
  detail = "no row-returning statement — score is null"
346
347
  elif score is None:
@@ -349,3 +350,18 @@ class World:
349
350
  detail = f"score {score} from: {last_sql}"
350
351
  passed = None if score is None else score >= 1.0
351
352
  return VerifierResult(name=verifier_name, passed=passed, score=score, detail=detail)
353
+
354
+ def _closed_on(self, verifier: str, journal: "WorldJournal", use: "JournalUse") -> Optional[str]:
355
+ from .schema.journal import accepting_incomplete
356
+
357
+ gap = journal.gap(use)
358
+ if gap is None:
359
+ return None
360
+ if not journal.recorded:
361
+ return f"{gap}: verifier '{verifier}' reads the journal"
362
+ if verifier in accepting_incomplete(self.env.bundle_path):
363
+ return None
364
+ return (
365
+ f"{gap}: verifier '{verifier}' reads the journal; declare "
366
+ f"[verifiers.{verifier}] accepts_incomplete_journal = true to grade an incomplete one"
367
+ )
@@ -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")