@withgateway/sdk 0.3.0 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/README.md +6 -1
  2. package/dist/cli.js +3971 -2338
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +3950 -2318
  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 +214 -41
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +206 -35
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/{index-DAb-FCMg.d.ts → index-DUHmS74p.d.ts} +3 -13
  13. package/dist/{index-D6oi1TWE.d.mts → index-mJhG3vZU.d.mts} +3 -13
  14. package/dist/index.d.mts +4 -4
  15. package/dist/index.d.ts +4 -4
  16. package/dist/index.js +1456 -564
  17. package/dist/index.js.map +1 -1
  18. package/dist/index.mjs +1433 -557
  19. package/dist/index.mjs.map +1 -1
  20. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  21. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  22. package/dist/traces/index.d.mts +1 -1
  23. package/dist/traces/index.d.ts +1 -1
  24. package/dist/traces/index.js +211 -38
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +203 -32
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.d.mts +2 -2
  29. package/dist/tracing/index.d.ts +2 -2
  30. package/dist/tracing/index.js +96 -21
  31. package/dist/tracing/index.js.map +1 -1
  32. package/dist/tracing/index.mjs +96 -21
  33. package/dist/tracing/index.mjs.map +1 -1
  34. package/dist/worlds/index.d.mts +300 -123
  35. package/dist/worlds/index.d.ts +300 -123
  36. package/dist/worlds/index.js +1385 -508
  37. package/dist/worlds/index.js.map +1 -1
  38. package/dist/worlds/index.mjs +1377 -501
  39. package/dist/worlds/index.mjs.map +1 -1
  40. package/package.json +1 -1
  41. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  42. package/runtime/gatewaysdk/environment/_materialize.py +49 -69
  43. package/runtime/gatewaysdk/environment/_world.py +122 -197
  44. package/runtime/gatewaysdk/environment/backing.py +137 -0
  45. package/runtime/gatewaysdk/environment/core.py +1 -1
  46. package/runtime/gatewaysdk/environment/legacy_sqlite.py +301 -0
  47. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  48. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  49. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  50. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  51. package/runtime/gatewaysdk/environment/schema/api.py +266 -515
  52. package/runtime/gatewaysdk/environment/schema/batch.py +42 -37
  53. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  54. package/runtime/gatewaysdk/environment/schema/call_log.py +291 -0
  55. package/runtime/gatewaysdk/environment/schema/call_redaction.py +344 -0
  56. package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
  57. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  58. package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
  59. package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
  60. package/runtime/gatewaysdk/environment/schema/data.py +50 -207
  61. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  62. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  63. package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
  64. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  65. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  66. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  67. package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
  68. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  69. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  70. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  71. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  72. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  73. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
  74. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  75. package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
  76. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  77. package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
  78. package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
  79. package/runtime/gatewaysdk/environment/schema/host.py +158 -250
  80. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  81. package/runtime/gatewaysdk/environment/schema/local.py +44 -71
  82. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  83. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  84. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  85. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  86. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  87. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  88. package/runtime/gatewaysdk/environment/schema/platform.py +124 -178
  89. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  90. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  91. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  92. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  93. package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
  94. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  95. package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
  96. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
  97. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +22 -14
  98. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
  99. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +16 -16
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +18 -18
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  102. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
  103. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  104. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  105. package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
  106. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  107. package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
  108. package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
  109. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  110. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  111. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  112. package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
  113. package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
  114. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  115. package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
  116. package/runtime/gatewaysdk/environment/score.py +57 -0
  117. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  118. package/runtime/gatewaysdk/environment/world.py +42 -3
  119. package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
  120. package/skills/benchmarks-getting-started/SKILL.md +2 -2
  121. package/skills/connector-schema-authoring/SKILL.md +22 -14
  122. package/skills/connector-schema-authoring/connector-worlds.md +26 -10
  123. package/skills/connector-schema-authoring/world-schema.md +111 -51
  124. package/skills/world-data-ingestion/ROWS.md +29 -3
  125. package/skills/world-data-ingestion/SKILL.md +16 -16
  126. package/skills/worlds-getting-started/SKILL.md +18 -18
  127. package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  128. package/skills/worlds-getting-started/references/gotchas.md +15 -0
  129. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  130. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -0,0 +1,301 @@
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`."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import shutil
9
+ import sqlite3
10
+ import tempfile
11
+ from contextlib import AbstractContextManager, nullcontext
12
+ from pathlib import Path
13
+ from typing import Any, Dict, List, Optional
14
+
15
+ from .backing import WorldBacking
16
+ from .errors import VerifierError, WorldStartError
17
+ from .schema.compiler import Contract, quote
18
+ from .schema.database import SQLiteWorldDatabase
19
+ from .schema.database.runtime_rows import CONVERSATION_EVENTS, RUN_PARAMETERS, TASK_CONTEXT, RuntimeRows, Statement
20
+ from .schema.validation import fail
21
+
22
+ MODES = ("append", "replace")
23
+ #: Undoing a failed runtime write: the outermost savepoint is the transaction, and its RELEASE is the
24
+ #: commit, so a busy RELEASE must be answered with ROLLBACK or the connection stays inside it.
25
+ ABORT = {True: ("ROLLBACK",), False: ("ROLLBACK TO gateway_runtime", "RELEASE gateway_runtime")}
26
+ Rows = Dict[str, List[dict]]
27
+
28
+
29
+ def _sql_literal(value: Any) -> str:
30
+ if value is None:
31
+ return "NULL"
32
+ if isinstance(value, bool):
33
+ return "1" if value else "0"
34
+ if isinstance(value, (int, float)):
35
+ return repr(value)
36
+ return "'" + str(value).replace("'", "''") + "'"
37
+
38
+
39
+ def _check_rows(columns: Dict[str, List[str]], rows: Rows) -> None:
40
+ for table, listed in rows.items():
41
+ if table not in columns:
42
+ fail(
43
+ "table",
44
+ f"No table {table} in db/schema.sql; tables: {', '.join(sorted(columns)) or 'none'}",
45
+ f"/{table}",
46
+ )
47
+ for index, row in enumerate(listed):
48
+ if not isinstance(row, dict):
49
+ fail("rows", "A row must be an object", f"/{table}/{index}")
50
+ _check_row(columns[table], table, index, row)
51
+
52
+
53
+ def _check_row(columns: List[str], table: str, index: int, row: dict) -> None:
54
+ for column, value in row.items():
55
+ if column not in columns:
56
+ fail(
57
+ "column",
58
+ f"Column {column} is not in table {table}; columns: {', '.join(columns)}",
59
+ f"/{table}/{index}/{column}",
60
+ )
61
+ if not isinstance(value, (str, int, float, bool, type(None))):
62
+ fail(
63
+ "value",
64
+ f"Column {column} of {table} takes a scalar; encode nested values as text yourself",
65
+ f"/{table}/{index}/{column}",
66
+ )
67
+
68
+
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
+ """
76
+ if mode not in MODES:
77
+ fail("mode", f"mode must be one of {', '.join(MODES)}", "/mode")
78
+ _check_rows(columns, rows)
79
+ statements: List[str] = []
80
+ verb = "INSERT" if mode == "replace" else "INSERT OR REPLACE"
81
+ for table, listed in rows.items():
82
+ if mode == "replace":
83
+ statements.append(f"DELETE FROM {quote(table)};")
84
+ statements.extend(_insert(verb, table, row) for row in listed)
85
+ return statements
86
+
87
+
88
+ def _insert(verb: str, table: str, row: dict) -> str:
89
+ if not row:
90
+ return f"{verb} INTO {quote(table)} DEFAULT VALUES;"
91
+ names = ", ".join(quote(column) for column in row)
92
+ values = ", ".join(_sql_literal(value) for value in row.values())
93
+ return f"{verb} INTO {quote(table)} ({names}) VALUES ({values});"
94
+
95
+
96
+ def columns_of(conn: sqlite3.Connection) -> Dict[str, List[str]]:
97
+ """Every user table's columns, in declaration order."""
98
+ tables = [
99
+ row[0]
100
+ for row in conn.execute("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'")
101
+ ]
102
+ return {table: [row[1] for row in conn.execute(f"PRAGMA table_info({quote(table)})")] for table in tables}
103
+
104
+
105
+ 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
+ statements = seed_statements(columns_of(conn), rows, mode)
112
+ try:
113
+ conn.execute("BEGIN")
114
+ for statement in statements:
115
+ conn.execute(statement)
116
+ conn.commit()
117
+ except sqlite3.Error as error:
118
+ conn.rollback()
119
+ fail("sqlite", f"seed refused by the database: {error}", "/rows")
120
+ return {table: conn.execute(f"SELECT COUNT(*) FROM {quote(table)}").fetchone()[0] for table in rows}
121
+
122
+
123
+ def schema_columns(schema: Path) -> Dict[str, List[str]]:
124
+ """The tables and columns ``db/schema.sql`` declares, loaded in memory."""
125
+ with sqlite3.connect(":memory:") as probe:
126
+ try:
127
+ probe.executescript(schema.read_text(encoding="utf-8"))
128
+ except sqlite3.Error as error:
129
+ fail("schema", f"db/schema.sql does not load: {error}", "db/schema.sql")
130
+ return columns_of(probe)
131
+
132
+
133
+ 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
+ conn = sqlite3.connect(destination)
136
+ try:
137
+ if schema.is_file():
138
+ conn.executescript(schema.read_text(encoding="utf-8"))
139
+ if seed.is_file():
140
+ conn.executescript(seed.read_text(encoding="utf-8"))
141
+ conn.commit()
142
+ except sqlite3.Error as error:
143
+ raise WorldStartError("Failed to build seed database; check db/schema.sql and db/seed.sql") from error
144
+ finally:
145
+ conn.close()
146
+
147
+
148
+ 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)."""
151
+
152
+ def __init__(self, path: Path, contract: Optional[Contract] = None) -> None:
153
+ self.path = Path(path)
154
+ self._conn = sqlite3.connect(self.path, isolation_level=None, check_same_thread=False)
155
+ self._conn.row_factory = sqlite3.Row
156
+
157
+ def transaction(self) -> AbstractContextManager[Any]:
158
+ return nullcontext()
159
+
160
+ def handler_connection(self) -> Any:
161
+ return self._conn
162
+
163
+ def split_statements(self, script: str) -> List[str]:
164
+ return SQLiteWorldDatabase.split_statements(script)
165
+
166
+ def rows(self, sql: str, params: tuple) -> List[Dict[str, Any]]:
167
+ head = sql.lstrip().split(None, 1)[0].upper() if sql.strip() else ""
168
+ if head not in ("SELECT", "WITH"):
169
+ raise ValueError(
170
+ "world.state() is read-only — only SELECT/WITH queries are "
171
+ "allowed (use tool handlers or verifiers for writes)."
172
+ )
173
+ return [dict(row) for row in self._conn.execute(sql, params).fetchall()]
174
+
175
+ def verifier_rows(self, verifier: str, statement: str) -> Optional[List[Any]]:
176
+ try:
177
+ cursor = self._conn.execute(statement)
178
+ except sqlite3.Error as error:
179
+ raise VerifierError(f"verifier '{verifier}' failed: {error}\n SQL: {statement}") from error
180
+ if cursor.description is None:
181
+ return None
182
+ row = cursor.fetchone()
183
+ return [] if row is None else [row]
184
+
185
+ def snapshot(self, destination: Path) -> Path:
186
+ dest = Path(destination)
187
+ dest.parent.mkdir(parents=True, exist_ok=True)
188
+ shutil.copyfile(self.path, dest)
189
+ return dest
190
+
191
+ def columns(self) -> Dict[str, List[str]]:
192
+ return columns_of(self._conn)
193
+
194
+ def counts(self) -> Dict[str, int]:
195
+ return {
196
+ table: self._conn.execute(f"SELECT COUNT(*) FROM {quote(table)}").fetchone()[0] for table in self.columns()
197
+ }
198
+
199
+ def seed(self, rows: Rows, mode: str = "append") -> Dict[str, int]:
200
+ """:func:`seed_sqlite` into this world's live file."""
201
+ return seed_sqlite(self._conn, rows, mode)
202
+
203
+ def entities(self) -> Rows:
204
+ """Every table's rows, tables by name."""
205
+ return {
206
+ table: [dict(row) for row in self._conn.execute(f"SELECT * FROM {quote(table)}")]
207
+ for table in sorted(self.columns())
208
+ }
209
+
210
+ def table_rows(self, table: str) -> tuple[List[dict], List[str]]:
211
+ columns = self.columns()
212
+ if table not in columns:
213
+ fail("table", f"No table {table}; tables: {', '.join(sorted(columns)) or 'none'}", f"/{table}")
214
+ return [dict(row) for row in self._conn.execute(f"SELECT * FROM {quote(table)}")], columns[table]
215
+
216
+ def _declares(self, table: str) -> bool:
217
+ found = self._conn.execute("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?", (table,))
218
+ return found.fetchone() is not None
219
+
220
+ 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
+ if not self._declares(table):
223
+ return False
224
+ outer = not self._conn.in_transaction
225
+ self._conn.execute("SAVEPOINT gateway_runtime")
226
+ try:
227
+ for sql, params in statements:
228
+ self._conn.execute(sql, params)
229
+ self._conn.execute("RELEASE gateway_runtime")
230
+ except BaseException:
231
+ for abort in ABORT[outer]:
232
+ self._conn.execute(abort)
233
+ raise
234
+ return True
235
+
236
+ def set_task_context(self, scenario_id: str) -> bool:
237
+ return self._write_runtime(TASK_CONTEXT, RuntimeRows.task_context(scenario_id))
238
+
239
+ def set_run_parameters(self, parameters: Dict[str, str]) -> bool:
240
+ return self._write_runtime(RUN_PARAMETERS, RuntimeRows.run_parameters(parameters))
241
+
242
+ def record_conversation_event(
243
+ self,
244
+ scenario_id: str,
245
+ user_turn_index: int,
246
+ event_type: str,
247
+ actor: str,
248
+ name: Optional[str],
249
+ payload_json: str,
250
+ ) -> bool:
251
+ return self._write_runtime(
252
+ CONVERSATION_EVENTS,
253
+ RuntimeRows.conversation_event(scenario_id, user_turn_index, event_type, actor, name, payload_json),
254
+ )
255
+
256
+ def close(self) -> None:
257
+ try:
258
+ self._conn.close()
259
+ except sqlite3.Error:
260
+ pass
261
+
262
+
263
+ 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."""
266
+
267
+ def __init__(self, root: Path) -> None:
268
+ self.root = Path(root)
269
+ self.paths = sorted((self.root / "verifiers").glob("*.sql"))
270
+
271
+ def scores(self) -> List[Dict[str, Any]]:
272
+ """``{path, ok, score[, error]}`` per verifier; a world that does not build fails every one."""
273
+ schema = self.root / "db" / "schema.sql"
274
+ if not schema.is_file():
275
+ return [self._refused(path, "db/schema.sql is missing") for path in self.paths]
276
+ with tempfile.TemporaryDirectory(prefix="gateway-verify-") as scratch:
277
+ template = Path(scratch) / "template.db"
278
+ try:
279
+ materialize(schema, self.root / "db" / "seed.sql", template)
280
+ except WorldStartError as error:
281
+ return [self._refused(path, f"{error}: {error.__cause__}") for path in self.paths]
282
+ return [self._score(path, template, Path(scratch) / f"{index}.db") for index, path in enumerate(self.paths)]
283
+
284
+ def _score(self, path: Path, template: Path, copy: Path) -> Dict[str, Any]:
285
+ from ._world import SqlVerifier
286
+
287
+ backing = WorldBacking.branch(template, copy, None)
288
+ try:
289
+ verifier = SqlVerifier.read(path, backing.split_statements)
290
+ score, _sql = verifier.score(lambda statement: backing.verifier_rows(verifier.name, statement))
291
+ except (VerifierError, ValueError, OSError) as error:
292
+ return self._refused(path, str(error))
293
+ finally:
294
+ backing.close()
295
+ return {"path": self._relative(path), "ok": True, "score": score}
296
+
297
+ def _refused(self, path: Path, reason: str) -> Dict[str, Any]:
298
+ return {"path": self._relative(path), "ok": False, "score": None, "error": reason}
299
+
300
+ def _relative(self, path: Path) -> str:
301
+ return path.relative_to(self.root).as_posix()
@@ -0,0 +1,25 @@
1
+ """How a task's grade names its rewards, so no two of them share a key.
2
+
3
+ Each world scores under its alias (``<alias>``, ``<alias>.<check>``) and each
4
+ cross-world verifier under ``x`` (``x.<name>``, ``x.<name>.<check>``). A world
5
+ aliased ``x``, or ``x.<anything>``, would score its checks under a verifier's
6
+ key, and the flattened grade would keep only one of the two. Stdlib only,
7
+ inside the vendored ``gatewaysdk.environment``; the platform's twin is
8
+ ``TaskRewardKeys`` in ``gateway/packages/shared/src/domain/worldTaskRewardKeys.ts``,
9
+ both pinned by ``gatewaysdk/fixtures/tasks/grade-vectors.json``.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+
15
+ class RewardKeys:
16
+ VERIFIERS = "x"
17
+ PREFIX = f"{VERIFIERS}."
18
+
19
+ @staticmethod
20
+ def reserved(alias: str) -> bool:
21
+ return alias == RewardKeys.VERIFIERS or alias.startswith(RewardKeys.PREFIX)
22
+
23
+ @staticmethod
24
+ def refusal(alias: str) -> str:
25
+ return f"'{alias}' is reserved: cross-world verifiers' rewards are named x.<name>; give the world another alias"
@@ -14,7 +14,7 @@ FIXED contract::
14
14
  ``gateway_env`` is importable ONLY while a bundle's handler modules are being
15
15
  loaded — the loader injects this module into ``sys.modules`` under that name
16
16
  for the duration of the load and restores it after (never globally installed).
17
- ``db`` operations bind to the ACTIVE world's sqlite connection at call time via
17
+ ``db`` operations bind to the ACTIVE world's connection at call time via
18
18
  a contextvar, so the same handler object serves every world/branch.
19
19
 
20
20
  Handlers may also be plain ``def <tool_name>(...)`` functions — the loader
@@ -24,7 +24,6 @@ falls back to discovery by function name == served tool name.
24
24
  from __future__ import annotations
25
25
 
26
26
  import re
27
- import sqlite3
28
27
  from contextvars import ContextVar
29
28
  from typing import Any, Callable, Dict, Optional
30
29
 
@@ -32,12 +31,8 @@ from .schema.store_contract import STORE_METHOD_NAMES, unknown_store_method_deta
32
31
 
33
32
  __all__ = ["tool", "db", "store"]
34
33
 
35
- #: The active world's sqlite connection. Set by ``World.execute`` around each
36
- #: handler invocation; ``db`` reads it at call time.
37
- _active_connection: ContextVar[Optional[sqlite3.Connection]] = ContextVar("gateway_env_active_connection", default=None)
34
+ _active_connection: ContextVar[Optional[Any]] = ContextVar("gateway_env_active_connection", default=None)
38
35
 
39
- #: The registry the loader is currently filling. ``@tool`` registers into it
40
- #: at module-exec time; outside a bundle load the decorator is a no-op tagger.
41
36
  _load_registry: ContextVar[Optional[Dict[str, Callable[..., Any]]]] = ContextVar(
42
37
  "gateway_env_load_registry", default=None
43
38
  )
@@ -67,7 +62,7 @@ store = _Store()
67
62
  _IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
68
63
 
69
64
 
70
- def _connection() -> sqlite3.Connection:
65
+ def _connection() -> Any:
71
66
  conn = _active_connection.get()
72
67
  if conn is None:
73
68
  raise RuntimeError(
@@ -84,14 +79,14 @@ def _identifier(name: str, what: str) -> str:
84
79
 
85
80
 
86
81
  class _Db:
87
- """Tiny sqlite facade bound to the active world (rows are ``sqlite3.Row``,
88
- dict-like: ``row["col"]`` and ``dict(row)`` both work)."""
82
+ """Tiny SQL facade bound to the active world (rows are dict-like:
83
+ ``row["col"]`` and ``dict(row)`` both work)."""
89
84
 
90
- def one(self, sql: str, *params: Any) -> Optional[sqlite3.Row]:
85
+ def one(self, sql: str, *params: Any) -> Optional[Any]:
91
86
  """First row of the query, or ``None``."""
92
87
  return _connection().execute(sql, params).fetchone()
93
88
 
94
- def all(self, sql: str, *params: Any) -> list[sqlite3.Row]:
89
+ def all(self, sql: str, *params: Any) -> list[Any]:
95
90
  """Every row of the query."""
96
91
  return list(_connection().execute(sql, params).fetchall())
97
92
 
@@ -115,7 +110,7 @@ class _Db:
115
110
 
116
111
  def execute(self, sql: str, *params: Any) -> int:
117
112
  """Run any statement (UPDATE/DELETE/DDL…), returning the affected
118
- rowcount (-1 for non-DML per sqlite3 semantics)."""
113
+ rowcount (-1 for a statement that changes no rows' count, e.g. DDL)."""
119
114
  if _active_store.get() is not None:
120
115
  from .schema import ContractError
121
116
 
@@ -1,5 +1,7 @@
1
1
  """Offline executable world contracts: compile, validate, and store state."""
2
2
 
3
+ from .api import build_api_bundle
4
+ from .api import serve as serve_api
3
5
  from .compiler import (
4
6
  Contract,
5
7
  bundle_mode,
@@ -11,10 +13,8 @@ from .connector import capture as capture_connection
11
13
  from .connector import ingest as ingest_captures
12
14
  from .connector import load_spec as load_connection
13
15
  from .connector import parse_spec, redaction_of, stored_forms
16
+ from .database import IngestConnection, WorldDatabase
14
17
  from .scaffold import init_bundle, list_templates
15
- from .store import IngestConnection, SQLiteStore
16
- from .api import build_api_bundle
17
- from .api import serve as serve_api
18
18
  from .transforms import TRANSFORMS, apply_transforms, parse_transform
19
19
  from .validation import ContractError
20
20
 
@@ -22,8 +22,8 @@ __all__ = [
22
22
  "Contract",
23
23
  "ContractError",
24
24
  "IngestConnection",
25
- "SQLiteStore",
26
25
  "TRANSFORMS",
26
+ "WorldDatabase",
27
27
  "apply_transforms",
28
28
  "build_api_bundle",
29
29
  "bundle_mode",
@@ -0,0 +1,86 @@
1
+ """The runner's ``/__world/*`` routes, and the per-run token that admits a caller to them.
2
+
3
+ Whoever starts a world's server mints the token and hands it to the one process that drives
4
+ the world: the platform to a session pod's world and runner containers, the Batch runner to a
5
+ world it boots, a local session to ``worlds test``. A server started without one refuses the
6
+ routes, and the World Host serves none of them on a session's doors."""
7
+
8
+ from __future__ import annotations
9
+
10
+ import hmac
11
+ import os
12
+ import posixpath
13
+ import re
14
+ import secrets
15
+ import urllib.parse
16
+ from collections.abc import Iterable, Mapping
17
+ from dataclasses import dataclass
18
+
19
+ from ..world_session_contract import ADMIN_TOKEN_ENV
20
+
21
+ ADMIN = {
22
+ "seed": "/__world/seed",
23
+ "reset": "/__world/reset",
24
+ "state": "/__world/state",
25
+ "calls": "/__world/calls",
26
+ "health": "/healthz",
27
+ }
28
+ ADMIN_TOKEN_HEADER = "X-World-Admin-Token"
29
+ RESERVED_SEGMENT = ADMIN["seed"].split("/")[1]
30
+
31
+
32
+ def resolved_path(path: str) -> str:
33
+ """``path`` as any server could read it: decoded, slashes merged, dot segments resolved, lower case."""
34
+ decoded = urllib.parse.unquote(path.split("?", 1)[0])
35
+ return posixpath.normpath(re.sub(r"[/\\]+", "/", "/" + decoded)).lower()
36
+
37
+
38
+ @dataclass(frozen=True)
39
+ class ReservedPaths:
40
+ """What a world's server answers as the runner's own routes: every ``/__world/*`` path and any
41
+ ``[admin]`` path its manifest names, at the root or under the ui's ``api_path``."""
42
+
43
+ admin: frozenset[str] = frozenset()
44
+ prefixes: frozenset[str] = frozenset()
45
+
46
+ @classmethod
47
+ def of(cls, admin: Iterable[str], api_path: str | None) -> ReservedPaths:
48
+ return cls(frozenset(map(resolved_path, admin)), frozenset(map(resolved_path, filter(None, [api_path]))))
49
+
50
+ def __contains__(self, path: object) -> bool:
51
+ whole = resolved_path(str(path))
52
+ under = [whole[len(prefix) :] for prefix in self.prefixes if whole.startswith(prefix + "/")]
53
+ return any(self._names(candidate) for candidate in (whole, *under))
54
+
55
+ def _names(self, candidate: str) -> bool:
56
+ return candidate.split("/")[1] == RESERVED_SEGMENT or candidate in self.admin
57
+
58
+
59
+ RUNNER_PATHS = ReservedPaths()
60
+
61
+
62
+ @dataclass(frozen=True, repr=False)
63
+ class AdminToken:
64
+ """The secret that admits a caller to the runner's routes; without a value it admits nobody."""
65
+
66
+ value: str | None = None
67
+
68
+ @classmethod
69
+ def mint(cls) -> AdminToken:
70
+ return cls(secrets.token_urlsafe(32))
71
+
72
+ @classmethod
73
+ def from_env(cls) -> AdminToken:
74
+ return cls(os.environ.get(ADMIN_TOKEN_ENV) or None)
75
+
76
+ def admits(self, headers: Mapping[str, str]) -> bool:
77
+ """``headers`` keyed lower-case, as ``WorldApp.handle`` takes them; compared in constant time."""
78
+ expected = self.value or ""
79
+ presented = headers.get(ADMIN_TOKEN_HEADER.lower(), "")
80
+ return bool(expected) and hmac.compare_digest(presented.encode("utf-8", "replace"), expected.encode())
81
+
82
+ def header(self) -> dict[str, str]:
83
+ return {ADMIN_TOKEN_HEADER: self.value} if self.value else {}
84
+
85
+ def __repr__(self) -> str:
86
+ return f"AdminToken({'set' if self.value else 'unset'})"