@withgateway/sdk 0.3.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (176) hide show
  1. package/README.md +8 -6
  2. package/dist/cli.js +4372 -2265
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +4362 -2256
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -1
  7. package/dist/files/index.d.ts +1 -1
  8. package/dist/files/index.js +259 -58
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +249 -50
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/hooks/index.d.mts +1 -1
  13. package/dist/hooks/index.d.ts +1 -1
  14. package/dist/hooks/index.js +124 -11
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +124 -11
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  19. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  20. package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
  21. package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
  22. package/dist/index.d.mts +5 -5
  23. package/dist/index.d.ts +5 -5
  24. package/dist/index.js +2240 -789
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2150 -739
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  29. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  30. package/dist/traces/index.d.mts +1 -1
  31. package/dist/traces/index.d.ts +1 -1
  32. package/dist/traces/index.js +253 -52
  33. package/dist/traces/index.js.map +1 -1
  34. package/dist/traces/index.mjs +243 -44
  35. package/dist/traces/index.mjs.map +1 -1
  36. package/dist/tracing/index.d.mts +2 -2
  37. package/dist/tracing/index.d.ts +2 -2
  38. package/dist/tracing/index.js +75 -13
  39. package/dist/tracing/index.js.map +1 -1
  40. package/dist/tracing/index.mjs +75 -13
  41. package/dist/tracing/index.mjs.map +1 -1
  42. package/dist/worlds/index.d.mts +893 -482
  43. package/dist/worlds/index.d.ts +893 -482
  44. package/dist/worlds/index.js +1968 -669
  45. package/dist/worlds/index.js.map +1 -1
  46. package/dist/worlds/index.mjs +1960 -662
  47. package/dist/worlds/index.mjs.map +1 -1
  48. package/package.json +1 -1
  49. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  50. package/runtime/gatewaysdk/environment/_materialize.py +48 -88
  51. package/runtime/gatewaysdk/environment/_world.py +155 -237
  52. package/runtime/gatewaysdk/environment/backing.py +133 -0
  53. package/runtime/gatewaysdk/environment/core.py +2 -17
  54. package/runtime/gatewaysdk/environment/legacy_sqlite.py +288 -0
  55. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  56. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  57. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  58. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  59. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  60. package/runtime/gatewaysdk/environment/schema/api.py +347 -892
  61. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  62. package/runtime/gatewaysdk/environment/schema/batch.py +44 -39
  63. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  64. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  65. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +503 -0
  67. package/runtime/gatewaysdk/environment/schema/call_redaction.py +526 -0
  68. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  69. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  70. package/runtime/gatewaysdk/environment/schema/conform.py +14 -39
  71. package/runtime/gatewaysdk/environment/schema/connector.py +113 -211
  72. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  75. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  76. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  77. package/runtime/gatewaysdk/environment/schema/data.py +60 -216
  78. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  79. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  80. package/runtime/gatewaysdk/environment/schema/database/base.py +936 -0
  81. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  82. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  83. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  84. package/runtime/gatewaysdk/environment/schema/database/guard.py +215 -0
  85. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  86. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  87. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  88. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  89. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  90. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  91. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +393 -0
  92. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  93. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  94. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  95. package/runtime/gatewaysdk/environment/schema/envelope.py +227 -0
  96. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  97. package/runtime/gatewaysdk/environment/schema/grading.py +90 -103
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +163 -12
  99. package/runtime/gatewaysdk/environment/schema/host.py +237 -1795
  100. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  101. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  102. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  103. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  104. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  105. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  106. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  107. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  108. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  109. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  110. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  111. package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
  112. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  113. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  114. package/runtime/gatewaysdk/environment/schema/local.py +58 -170
  115. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  116. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  117. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  118. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  119. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  120. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  121. package/runtime/gatewaysdk/environment/schema/platform.py +137 -187
  122. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  123. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  124. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  125. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  126. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  127. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  128. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  129. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  130. package/runtime/gatewaysdk/environment/schema/runtime.py +178 -308
  131. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  132. package/runtime/gatewaysdk/environment/schema/session_files.py +275 -0
  133. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  134. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  135. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +10 -11
  136. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +49 -16
  137. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +39 -9
  138. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +27 -27
  139. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +33 -33
  140. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  141. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +49 -1
  142. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  143. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  144. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  145. package/runtime/gatewaysdk/environment/schema/snapshot.py +516 -140
  146. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  147. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  148. package/runtime/gatewaysdk/environment/schema/tasks.py +267 -276
  149. package/runtime/gatewaysdk/environment/schema/tools_world.py +146 -242
  150. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  151. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  152. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  153. package/runtime/gatewaysdk/environment/schema/validation.py +235 -41
  154. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  155. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  156. package/runtime/gatewaysdk/environment/schema/workers.py +345 -96
  157. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  158. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  159. package/runtime/gatewaysdk/environment/schema/world_tests.py +80 -50
  160. package/runtime/gatewaysdk/environment/score.py +57 -0
  161. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  162. package/runtime/gatewaysdk/environment/world.py +43 -4
  163. package/runtime/gatewaysdk/environment/world_session_contract.py +46 -5
  164. package/skills/agents/connector-template-author.md +5 -1
  165. package/skills/benchmarks-getting-started/SKILL.md +10 -11
  166. package/skills/connector-schema-authoring/SKILL.md +49 -16
  167. package/skills/connector-schema-authoring/connector-worlds.md +142 -11
  168. package/skills/connector-schema-authoring/world-schema.md +103 -51
  169. package/skills/world-data-ingestion/ROWS.md +39 -9
  170. package/skills/world-data-ingestion/SKILL.md +27 -27
  171. package/skills/worlds-getting-started/SKILL.md +33 -33
  172. package/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  173. package/skills/worlds-getting-started/references/gotchas.md +49 -1
  174. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
  175. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  176. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -0,0 +1,437 @@
1
+ """Bodies are what the ledger stored, redacted when captured: never re-read from anywhere else."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import uuid
7
+ from collections.abc import Callable, Iterable, Iterator, Mapping
8
+ from contextlib import contextmanager
9
+ from dataclasses import dataclass
10
+ from pathlib import Path
11
+ from typing import TYPE_CHECKING, Any
12
+
13
+ from .._toml import tomllib
14
+ from .call_redaction import REDACTED, CallRedaction
15
+ from .database.base import SideTable
16
+ from .tasks import JOURNAL, JOURNAL_META, WITHHELD_FIELD
17
+ from .validation import fail
18
+
19
+ if TYPE_CHECKING:
20
+ from .connector import Spec
21
+ from .database import WorldDatabase
22
+
23
+ JOURNAL_KEYS = (JOURNAL, JOURNAL_META)
24
+ JOURNAL_SCHEMA = "_gateway_journal"
25
+ JOURNAL_TABLES = frozenset(JOURNAL_KEYS)
26
+ MAX_JOURNAL_REQUESTS = 20_000
27
+ NOT_RECORDED = "not recorded: only a World Host session records the requests its world receives"
28
+ LINKED_NOT_RECORDED = "not recorded for a linked world: the root world's verifiers and the task's checks read it"
29
+ VIAS = ("api", "ui", "tool")
30
+ JSON_HINTS = ("json",)
31
+ WITHHELD_ROUTE_BODY = ["body", "selectors"]
32
+ WITHHELD_TOOL_ARGS = ["args", "selectors"]
33
+ NONE = type(None)
34
+ NUMBER = (int, float)
35
+
36
+
37
+ def _is(value: Any, kinds: tuple[type, ...]) -> bool:
38
+ """A bool is never an int here, as it is not in JSON."""
39
+ return type(value) in kinds or (float in kinds and type(value) is int)
40
+
41
+
42
+ def _check(entry: Mapping, field: str, kinds: tuple[type, ...], at: str) -> None:
43
+ if not _is(entry.get(field), kinds):
44
+ fail("journal", f"a journal request's {field} is {' or '.join(k.__name__ for k in kinds)}", f"{at}/{field}")
45
+
46
+
47
+ ENTRY_SHAPE: dict[str, tuple[type, ...]] = {
48
+ "id": (str,),
49
+ "seq": (int,),
50
+ "at": (str,),
51
+ "operation": (str, NONE),
52
+ "method": (str, NONE),
53
+ "path": (str, NONE),
54
+ "via": (str, NONE),
55
+ "rows": (int, NONE),
56
+ "found": (bool, NONE),
57
+ "durationMs": (float, NONE),
58
+ "query": (dict,),
59
+ "request": (dict,),
60
+ "response": (dict,),
61
+ }
62
+ BODY_SHAPE: dict[str, tuple[type, ...]] = {
63
+ "body": (str, NONE),
64
+ "bodyBytes": (int, NONE),
65
+ "truncated": (bool,),
66
+ "contentType": (str, NONE),
67
+ }
68
+
69
+
70
+ def _strings_in(node: Any) -> list[str]:
71
+ found: dict[str, None] = {}
72
+ stack = [node]
73
+ while stack:
74
+ item = stack.pop()
75
+ if isinstance(item, str) and item != REDACTED:
76
+ found[item] = None
77
+ if isinstance(item, dict):
78
+ stack.extend(reversed(list(item.values())))
79
+ if isinstance(item, list):
80
+ stack.extend(reversed(item))
81
+ return list(found)
82
+
83
+
84
+ @dataclass(frozen=True)
85
+ class JournalBody:
86
+ value: Any
87
+ whole: bool
88
+
89
+ @classmethod
90
+ def of(cls, part: Mapping) -> JournalBody:
91
+ text = part.get("body")
92
+ whole = part.get("truncated") is not True and (text is not None or not part.get("bodyBytes"))
93
+ return cls(None if text is None else cls._read(text, part.get("contentType")), whole)
94
+
95
+ @staticmethod
96
+ def _read(text: str, content_type: Any) -> Any:
97
+ typed = isinstance(content_type, str) and any(hint in content_type.lower() for hint in JSON_HINTS)
98
+ if not typed and not text.lstrip().startswith(("{", "[")):
99
+ return text
100
+ try:
101
+ return json.loads(text)
102
+ except (ValueError, RecursionError):
103
+ return text
104
+
105
+
106
+ @dataclass(frozen=True)
107
+ class JournalEntry:
108
+ """Checked: the host trusts the platform no more than the platform trusts it."""
109
+
110
+ raw: dict
111
+
112
+ @classmethod
113
+ def parse(cls, value: Any, at: str) -> JournalEntry:
114
+ if not isinstance(value, dict):
115
+ fail("journal", "a journal request is an object", at)
116
+ for field, kinds in ENTRY_SHAPE.items():
117
+ _check(value, field, kinds, at)
118
+ for side in ("request", "response"):
119
+ cls._part(value[side], f"{at}/{side}")
120
+ _check(value["response"], "status", (int,), f"{at}/response")
121
+ if value["via"] is not None and value["via"] not in VIAS:
122
+ fail("journal", f"a journal request came in by one of {', '.join(VIAS)}", f"{at}/via")
123
+ withheld = value.get(WITHHELD_FIELD, [])
124
+ if not isinstance(withheld, list) or any(not isinstance(path, str) for path in withheld):
125
+ fail("journal", "withheld lists the paths of a request the platform did not send", f"{at}/withheld")
126
+ return cls(value)
127
+
128
+ @staticmethod
129
+ def _part(part: dict, at: str) -> None:
130
+ for field, kinds in BODY_SHAPE.items():
131
+ _check(part, field, kinds, at)
132
+ headers = part.get("headers", {})
133
+ if not isinstance(headers, dict) or any(not isinstance(v, str) for v in headers.values()):
134
+ fail("journal", "headers are {name: value}", f"{at}/headers")
135
+
136
+ @property
137
+ def seq(self) -> int:
138
+ return self.raw["seq"]
139
+
140
+ @property
141
+ def operation(self) -> str | None:
142
+ return self.raw["operation"]
143
+
144
+ @property
145
+ def request(self) -> JournalBody:
146
+ return JournalBody.of(self.raw["request"])
147
+
148
+ def row(self) -> dict:
149
+ raw, request, response = self.raw, self.raw["request"], self.raw["response"]
150
+ out = {
151
+ key: raw[key]
152
+ for key in ("seq", "id", "at", "durationMs", "via", "operation", "method", "path", "query", "rows", "found")
153
+ }
154
+ out["request"] = {"headers": dict(request.get("headers") or {}), **self._shown(request)}
155
+ out["response"] = {"status": response["status"], **self._shown(response)}
156
+ if raw.get(WITHHELD_FIELD):
157
+ out[WITHHELD_FIELD] = list(raw[WITHHELD_FIELD])
158
+ return out
159
+
160
+ @staticmethod
161
+ def _shown(part: dict) -> dict:
162
+ return {
163
+ "body": JournalBody.of(part).value,
164
+ "bodyBytes": part.get("bodyBytes"),
165
+ "truncated": part.get("truncated") is True,
166
+ "contentType": part.get("contentType"),
167
+ }
168
+
169
+ def cut(self, columns: frozenset[str]) -> bool:
170
+ withheld = set(self.raw.get(WITHHELD_FIELD) or ())
171
+ parts = {BODY_COLUMNS[column] for column in columns if column in BODY_COLUMNS}
172
+ return any(part in withheld or self._truncated(part) for part in parts)
173
+
174
+ def _truncated(self, part: str) -> bool:
175
+ side = part.partition(".")[0]
176
+ return part.endswith(".body") and self.raw[side].get("truncated") is True
177
+
178
+ def answered(self) -> dict:
179
+ raw = self.raw
180
+ return {
181
+ "via": raw["via"],
182
+ "status": raw["response"]["status"],
183
+ "rows": raw["rows"],
184
+ "found": raw["found"],
185
+ "elapsed_ms": raw["durationMs"],
186
+ }
187
+
188
+
189
+ @dataclass(frozen=True)
190
+ class WorldJournal:
191
+ entries: tuple[JournalEntry, ...]
192
+ complete: bool
193
+ reason: str | None = None
194
+ recorded: bool = True
195
+
196
+ @classmethod
197
+ def unrecorded(cls, reason: str = NOT_RECORDED) -> WorldJournal:
198
+ return cls((), False, reason, recorded=False)
199
+
200
+ @classmethod
201
+ def of(cls, value: Any) -> WorldJournal | None:
202
+ return None if value is None else cls.parse(value)
203
+
204
+ @classmethod
205
+ def parse(cls, value: Any, at: str = "/journal") -> WorldJournal:
206
+ if not isinstance(value, dict) or set(value) - {"complete", "reason", "requests"}:
207
+ fail("journal", "a journal is {complete, reason?, requests: [request, ...]}", at)
208
+ requests = value.get("requests")
209
+ if not isinstance(requests, list) or len(requests) > MAX_JOURNAL_REQUESTS:
210
+ fail("journal", f"a journal's requests are a list of at most {MAX_JOURNAL_REQUESTS}", f"{at}/requests")
211
+ if not isinstance(value.get("complete"), bool):
212
+ fail("journal", "complete is true or false", f"{at}/complete")
213
+ if not _is(value.get("reason"), (str, NONE)):
214
+ fail("journal", "reason is text", f"{at}/reason")
215
+ entries = tuple(JournalEntry.parse(entry, f"{at}/requests/{i}") for i, entry in enumerate(requests))
216
+ if any(later.seq <= earlier.seq for earlier, later in zip(entries, entries[1:])):
217
+ fail("journal", "a journal's requests come in increasing seq", f"{at}/requests")
218
+ return cls(entries, value["complete"], value.get("reason"))
219
+
220
+ def rows(self) -> list[dict]:
221
+ return [entry.row() for entry in self.entries]
222
+
223
+ def meta(self) -> dict:
224
+ return {
225
+ "complete": self.complete,
226
+ "reason": self.reason,
227
+ "requests": len(self.entries),
228
+ "withheld": sum(1 for entry in self.entries if entry.raw.get(WITHHELD_FIELD)),
229
+ }
230
+
231
+ def gap(self, use: JournalUse) -> str | None:
232
+ if not use.tables:
233
+ return None
234
+ if not self.complete:
235
+ return f"journal incomplete ({self.reason or 'it may be missing requests'})"
236
+ cut = sum(1 for entry in self.entries if entry.cut(use.columns))
237
+ return f"the bodies of {cut} requests it reads were withheld or cut short" if cut else None
238
+
239
+ def into_state(self, state: dict, calls: list[dict]) -> dict:
240
+ return {**state, JOURNAL: self.rows(), JOURNAL_META: self.meta(), "calls": calls}
241
+
242
+
243
+ LINKED_JOURNAL = WorldJournal.unrecorded(LINKED_NOT_RECORDED)
244
+
245
+
246
+ class CallsView:
247
+ """A request no route took and a tool call the door refused are the journal's alone: they never were calls."""
248
+
249
+ def __init__(self, spec: Spec | None, redaction: CallRedaction, admitted: Callable[[str], bool]) -> None:
250
+ self.spec = spec
251
+ self.redaction = redaction
252
+ self.admitted = admitted
253
+
254
+ def rows(self, journal: WorldJournal) -> list[dict]:
255
+ return [call for call in map(self._call, journal.entries) if call is not None]
256
+
257
+ def _call(self, entry: JournalEntry) -> dict | None:
258
+ if entry.operation is None:
259
+ return None
260
+ if entry.raw["via"] == "tool" and entry.raw["method"] is None:
261
+ return self._tool(entry) if self.admitted(entry.operation) else None
262
+ return self._route(entry)
263
+
264
+ def _tool(self, entry: JournalEntry) -> dict:
265
+ body = entry.request
266
+ args = body.value if body.whole else REDACTED
267
+ withheld = {} if body.whole else {WITHHELD_FIELD: list(WITHHELD_TOOL_ARGS)}
268
+ return {
269
+ **self._heading(entry),
270
+ "method": None,
271
+ "path": None,
272
+ "args": args,
273
+ "query": {},
274
+ "body": None,
275
+ "selectors": _strings_in(args) if body.whole else [],
276
+ **entry.answered(),
277
+ **withheld,
278
+ }
279
+
280
+ def _route(self, entry: JournalEntry) -> dict:
281
+ body = entry.request
282
+ kept = body.value if body.whole and isinstance(body.value, (dict, list)) and body.value else None
283
+ args = self._args(entry)
284
+ query = entry.raw["query"]
285
+ withheld = {} if body.whole else {WITHHELD_FIELD: list(WITHHELD_ROUTE_BODY)}
286
+ return {
287
+ **self._heading(entry),
288
+ "method": entry.raw["method"],
289
+ "path": entry.raw["path"],
290
+ "args": args,
291
+ "query": query,
292
+ "body": kept,
293
+ "selectors": _strings_in([args, query, kept]) if body.whole else _strings_in([args, query]),
294
+ **entry.answered(),
295
+ **withheld,
296
+ }
297
+
298
+ @staticmethod
299
+ def _heading(entry: JournalEntry) -> dict:
300
+ return {"seq": entry.seq, "at": entry.raw["at"], "operation": entry.operation}
301
+
302
+ def _args(self, entry: JournalEntry) -> dict:
303
+ operations = self.spec.operations if self.spec is not None else {}
304
+ operation = operations.get(entry.operation or "")
305
+ path = entry.raw["path"]
306
+ if operation is None or not isinstance(path, str):
307
+ return {}
308
+ return self.redaction.value(operation.path_args(path))
309
+
310
+
311
+ JOURNAL_COLUMNS = (
312
+ ("seq", "INTEGER"),
313
+ ("id", "TEXT"),
314
+ ("at", "TEXT"),
315
+ ("duration_ms", "REAL"),
316
+ ("via", "TEXT"),
317
+ ("operation", "TEXT"),
318
+ ("method", "TEXT"),
319
+ ("path", "TEXT"),
320
+ ("query", "TEXT"),
321
+ ("status", "INTEGER"),
322
+ ("rows", "INTEGER"),
323
+ ("found", "INTEGER"),
324
+ ("request_headers", "TEXT"),
325
+ ("request_body", "TEXT"),
326
+ ("request_body_bytes", "INTEGER"),
327
+ ("request_truncated", "INTEGER"),
328
+ ("request_content_type", "TEXT"),
329
+ ("response_body", "TEXT"),
330
+ ("response_body_bytes", "INTEGER"),
331
+ ("response_truncated", "INTEGER"),
332
+ ("response_content_type", "TEXT"),
333
+ ("withheld", "TEXT"),
334
+ )
335
+ JOURNAL_META_COLUMNS = (("complete", "INTEGER"), ("reason", "TEXT"), ("requests", "INTEGER"), ("withheld", "INTEGER"))
336
+ BODY_COLUMNS = {
337
+ "request_headers": "request.headers",
338
+ "request_body": "request.body",
339
+ "response_body": "response.body",
340
+ }
341
+
342
+
343
+ @dataclass(frozen=True)
344
+ class JournalUse:
345
+ tables: bool
346
+ columns: frozenset[str] = frozenset()
347
+
348
+ @classmethod
349
+ def none(cls) -> JournalUse:
350
+ return cls(False)
351
+
352
+
353
+ def _flag(value: Any) -> int | None:
354
+ return None if value is None else int(bool(value))
355
+
356
+
357
+ def _table_row(entry: JournalEntry) -> tuple:
358
+ raw, request, response = entry.raw, entry.raw["request"], entry.raw["response"]
359
+ return (
360
+ raw["seq"],
361
+ raw["id"],
362
+ raw["at"],
363
+ raw["durationMs"],
364
+ raw["via"],
365
+ raw["operation"],
366
+ raw["method"],
367
+ raw["path"],
368
+ json.dumps(raw["query"], ensure_ascii=False),
369
+ response["status"],
370
+ raw["rows"],
371
+ _flag(raw["found"]),
372
+ json.dumps(request.get("headers") or {}, ensure_ascii=False),
373
+ request.get("body"),
374
+ request.get("bodyBytes"),
375
+ _flag(request.get("truncated")),
376
+ request.get("contentType"),
377
+ response.get("body"),
378
+ response.get("bodyBytes"),
379
+ _flag(response.get("truncated")),
380
+ response.get("contentType"),
381
+ json.dumps(raw[WITHHELD_FIELD]) if raw.get(WITHHELD_FIELD) else None,
382
+ )
383
+
384
+
385
+ class JournalDatabase:
386
+ """A read the store's authorizer does not report (a NATURAL or USING join's count) still counts when a statement
387
+ names a journal table or body column, so the verifier still fails closed."""
388
+
389
+ def __init__(self, journal: WorldJournal, scratch: Path) -> None:
390
+ self.journal = journal
391
+ self.scratch = Path(scratch)
392
+
393
+ def tables(self) -> tuple[SideTable, ...]:
394
+ meta = self.journal.meta()
395
+ summary = (int(meta["complete"]), meta["reason"], meta["requests"], meta["withheld"])
396
+ return (
397
+ SideTable(JOURNAL, JOURNAL_COLUMNS, tuple(map(_table_row, self.journal.entries))),
398
+ SideTable(JOURNAL_META, JOURNAL_META_COLUMNS, (summary,)),
399
+ )
400
+
401
+ @contextmanager
402
+ def attached(self, store: WorldDatabase) -> Iterator[Callable[[list[str]], JournalUse]]:
403
+ self.scratch.mkdir(parents=True, exist_ok=True)
404
+ path = self.scratch / f"journal-{uuid.uuid4().hex}"
405
+ try:
406
+ store.write_side_tables(path, self.tables())
407
+ store.attach(JOURNAL_SCHEMA, path, JOURNAL_TABLES, bare=True)
408
+ except BaseException:
409
+ path.unlink(missing_ok=True)
410
+ raise
411
+ try:
412
+ yield lambda statements: self._use(store, statements)
413
+ finally:
414
+ try:
415
+ store.detach(JOURNAL_SCHEMA)
416
+ finally:
417
+ path.unlink(missing_ok=True)
418
+
419
+ @staticmethod
420
+ def _use(store: WorldDatabase, statements: list[str]) -> JournalUse:
421
+ named = frozenset().union(*(store.identifiers(statement) for statement in statements))
422
+ tables = store.reads_of(JOURNAL_SCHEMA) > 0 or bool(named & JOURNAL_TABLES)
423
+ return JournalUse(tables, store.columns_read_of(JOURNAL_SCHEMA) | (named & frozenset(BODY_COLUMNS)))
424
+
425
+
426
+ def accepting_incomplete(bundle: Path) -> frozenset[str]:
427
+ try:
428
+ manifest = tomllib.loads((Path(bundle) / "gateway-env.toml").read_text(encoding="utf-8"))
429
+ except (OSError, tomllib.TOMLDecodeError):
430
+ return frozenset()
431
+ table = manifest.get("verifiers")
432
+ entries: Iterable[tuple[str, Any]] = table.items() if isinstance(table, dict) else ()
433
+ return frozenset(
434
+ name
435
+ for name, policy in entries
436
+ if isinstance(policy, dict) and policy.get("accepts_incomplete_journal") is True
437
+ )
@@ -0,0 +1,53 @@
1
+ """``Lanes``: one holder at a time per key, served in the order they arrived.
2
+
3
+ The World Host keys them by version: a version is built once while its other
4
+ opens wait, and its sessions open one after another, so a burst of opens queues
5
+ instead of running together in the version's one worker.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import threading
11
+ from collections.abc import Iterator
12
+ from contextlib import contextmanager
13
+ from dataclasses import dataclass
14
+
15
+
16
+ @dataclass
17
+ class _Lane:
18
+ changed: threading.Condition
19
+ issued: int = 0
20
+ serving: int = 0
21
+
22
+
23
+ class Lanes:
24
+ """One holder at a time per key, first come first served; another key never
25
+ waits. A key is forgotten once nobody holds it or waits on it."""
26
+
27
+ def __init__(self) -> None:
28
+ self._lock = threading.Lock()
29
+ self._lanes: dict[str, _Lane] = {}
30
+
31
+ @contextmanager
32
+ def turn(self, key: str) -> Iterator[None]:
33
+ with self._lock:
34
+ lane = self._lanes.get(key)
35
+ if lane is None:
36
+ lane = self._lanes[key] = _Lane(threading.Condition(self._lock))
37
+ ticket = lane.issued
38
+ lane.issued += 1
39
+ lane.changed.wait_for(lambda: lane.serving == ticket)
40
+ try:
41
+ yield
42
+ finally:
43
+ with self._lock:
44
+ lane.serving += 1
45
+ if lane.serving == lane.issued:
46
+ del self._lanes[key]
47
+ else:
48
+ lane.changed.notify_all()
49
+
50
+ def held(self) -> list[str]:
51
+ """The keys someone holds or waits on now."""
52
+ with self._lock:
53
+ return sorted(self._lanes)