@withgateway/sdk 0.6.0 → 0.9.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 (150) hide show
  1. package/dist/agents/index.d.mts +581 -0
  2. package/dist/agents/index.d.ts +581 -0
  3. package/dist/agents/index.js +1473 -0
  4. package/dist/agents/index.js.map +1 -0
  5. package/dist/agents/index.mjs +1424 -0
  6. package/dist/agents/index.mjs.map +1 -0
  7. package/dist/apiError-DHpfbmdx.d.mts +17 -0
  8. package/dist/apiError-DHpfbmdx.d.ts +17 -0
  9. package/dist/cli.js +11611 -6845
  10. package/dist/cli.js.map +1 -1
  11. package/dist/cli.mjs +10090 -5325
  12. package/dist/cli.mjs.map +1 -1
  13. package/dist/files/index.d.mts +3 -1
  14. package/dist/files/index.d.ts +3 -1
  15. package/dist/files/index.js +371 -102
  16. package/dist/files/index.js.map +1 -1
  17. package/dist/files/index.mjs +371 -102
  18. package/dist/files/index.mjs.map +1 -1
  19. package/dist/hooks/index.js +346 -136
  20. package/dist/hooks/index.js.map +1 -1
  21. package/dist/hooks/index.mjs +346 -136
  22. package/dist/hooks/index.mjs.map +1 -1
  23. package/dist/{index-LA-PMRJT.d.ts → index-DIN14Lhg.d.ts} +1 -1
  24. package/dist/{index-Di9nNqOY.d.mts → index-DuB-eQ0Z.d.mts} +1 -1
  25. package/dist/index.d.mts +7 -4
  26. package/dist/index.d.ts +7 -4
  27. package/dist/index.js +3177 -748
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +2987 -590
  30. package/dist/index.mjs.map +1 -1
  31. package/dist/media-CQUC7TkS.d.mts +39 -0
  32. package/dist/media-DQnBloaX.d.ts +39 -0
  33. package/dist/traces/index.d.mts +3 -1
  34. package/dist/traces/index.d.ts +3 -1
  35. package/dist/traces/index.js +371 -102
  36. package/dist/traces/index.js.map +1 -1
  37. package/dist/traces/index.mjs +371 -102
  38. package/dist/traces/index.mjs.map +1 -1
  39. package/dist/tracing/index.d.mts +3 -2
  40. package/dist/tracing/index.d.ts +3 -2
  41. package/dist/tracing/index.js +257 -16
  42. package/dist/tracing/index.js.map +1 -1
  43. package/dist/tracing/index.mjs +257 -16
  44. package/dist/tracing/index.mjs.map +1 -1
  45. package/dist/transport-CpRe7zgd.d.mts +123 -0
  46. package/dist/transport-CpRe7zgd.d.ts +123 -0
  47. package/dist/worlds/index.d.mts +1986 -1746
  48. package/dist/worlds/index.d.ts +1986 -1746
  49. package/dist/worlds/index.js +1470 -290
  50. package/dist/worlds/index.js.map +1 -1
  51. package/dist/worlds/index.mjs +1465 -286
  52. package/dist/worlds/index.mjs.map +1 -1
  53. package/package.json +6 -1
  54. package/runtime/gatewaysdk/environment/bundle_manifest.py +531 -0
  55. package/runtime/gatewaysdk/environment/factory_documents.py +670 -0
  56. package/runtime/gatewaysdk/environment/factory_rules.py +973 -0
  57. package/runtime/gatewaysdk/environment/factory_shapes.py +253 -0
  58. package/runtime/gatewaysdk/environment/factory_spine.py +1155 -0
  59. package/runtime/gatewaysdk/environment/factory_spine_shapes.py +480 -0
  60. package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
  61. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
  62. package/runtime/gatewaysdk/environment/schema/admission.py +61 -59
  63. package/runtime/gatewaysdk/environment/schema/api.py +3 -4
  64. package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
  65. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +20 -0
  67. package/runtime/gatewaysdk/environment/schema/cast.py +133 -67
  68. package/runtime/gatewaysdk/environment/schema/compiler.py +16 -17
  69. package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
  70. package/runtime/gatewaysdk/environment/schema/handler_errors.py +58 -4
  71. package/runtime/gatewaysdk/environment/schema/host.py +94 -12
  72. package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
  73. package/runtime/gatewaysdk/environment/schema/host_control.py +35 -2
  74. package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
  75. package/runtime/gatewaysdk/environment/schema/host_loops.py +27 -4
  76. package/runtime/gatewaysdk/environment/schema/host_metrics.py +69 -0
  77. package/runtime/gatewaysdk/environment/schema/host_requests.py +35 -0
  78. package/runtime/gatewaysdk/environment/schema/host_session.py +20 -2
  79. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
  80. package/runtime/gatewaysdk/environment/schema/host_versions.py +100 -19
  81. package/runtime/gatewaysdk/environment/schema/host_workers.py +172 -50
  82. package/runtime/gatewaysdk/environment/schema/ingest.py +12 -3
  83. package/runtime/gatewaysdk/environment/schema/journal.py +7 -2
  84. package/runtime/gatewaysdk/environment/schema/local.py +32 -7
  85. package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
  86. package/runtime/gatewaysdk/environment/schema/measured_tests.py +187 -0
  87. package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
  88. package/runtime/gatewaysdk/environment/schema/platform.py +80 -270
  89. package/runtime/gatewaysdk/environment/schema/platform_query.py +4 -3
  90. package/runtime/gatewaysdk/environment/schema/platform_templates.py +420 -0
  91. package/runtime/gatewaysdk/environment/schema/process_memory.py +76 -0
  92. package/runtime/gatewaysdk/environment/schema/redaction.py +13 -0
  93. package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
  94. package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
  95. package/runtime/gatewaysdk/environment/schema/runtime.py +57 -5
  96. package/runtime/gatewaysdk/environment/schema/scaffold.py +386 -219
  97. package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
  98. package/runtime/gatewaysdk/environment/schema/shape_catalog.py +493 -0
  99. package/runtime/gatewaysdk/environment/schema/shape_declarations.py +219 -0
  100. package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
  101. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
  102. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +2 -2
  103. package/runtime/gatewaysdk/environment/schema/skills/factory-orchestrator/SKILL.md +147 -0
  104. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +5 -1
  105. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +8 -6
  106. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
  107. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
  108. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +6 -6
  109. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
  110. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  111. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  112. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
  113. package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
  114. package/runtime/gatewaysdk/environment/schema/snapshot.py +28 -2
  115. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
  116. package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
  117. package/runtime/gatewaysdk/environment/schema/tools_world.py +7 -5
  118. package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
  119. package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
  120. package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
  121. package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
  122. package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
  123. package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
  124. package/runtime/gatewaysdk/environment/schema/validation.py +24 -1
  125. package/runtime/gatewaysdk/environment/schema/worker.py +12 -5
  126. package/runtime/gatewaysdk/environment/schema/worker_key.py +38 -0
  127. package/runtime/gatewaysdk/environment/schema/worker_peaks.py +38 -0
  128. package/runtime/gatewaysdk/environment/schema/worker_watch.py +50 -0
  129. package/runtime/gatewaysdk/environment/schema/workers.py +245 -69
  130. package/runtime/gatewaysdk/environment/schema/world_host.py +96 -73
  131. package/runtime/gatewaysdk/environment/schema/world_tests.py +3 -1
  132. package/runtime/gatewaysdk/environment/secret_values.py +1 -1
  133. package/runtime/gatewaysdk/environment/world.py +34 -43
  134. package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
  135. package/skills/benchmarks-getting-started/SKILL.md +1 -1
  136. package/skills/connector-schema-authoring/SKILL.md +2 -2
  137. package/skills/connector-schema-authoring/connector-worlds.md +3 -2
  138. package/skills/connector-schema-authoring/world-schema.md +36 -23
  139. package/skills/factory-orchestrator/SKILL.md +147 -0
  140. package/skills/world-data-ingestion/ROWS.md +5 -1
  141. package/skills/world-data-ingestion/SKILL.md +8 -6
  142. package/skills/worlds-getting-started/SKILL.md +9 -9
  143. package/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
  144. package/skills/worlds-getting-started/references/gotchas.md +6 -6
  145. package/skills/worlds-getting-started/references/journal-checks.md +17 -2
  146. package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  147. package/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  148. package/skills/worlds-getting-started/references/ui-map.md +3 -2
  149. package/dist/media-BIApiPzS.d.mts +0 -102
  150. package/dist/media-BIApiPzS.d.ts +0 -102
@@ -0,0 +1,670 @@
1
+ """Stdlib only: the runner vendors this package."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import re
7
+ from collections.abc import Callable, Iterable, Mapping
8
+ from dataclasses import dataclass
9
+ from functools import cached_property
10
+ from types import MappingProxyType
11
+ from typing import Any
12
+
13
+ from .factory_shapes import (
14
+ _KIND,
15
+ _REF,
16
+ _REFS,
17
+ _TEXT,
18
+ FACTORY_LIMITS,
19
+ FACTORY_NODE_ID,
20
+ Check,
21
+ _any_of,
22
+ _array,
23
+ _json,
24
+ _literal,
25
+ _node_id,
26
+ _node_shape,
27
+ _one_of,
28
+ _record,
29
+ _slug,
30
+ _source,
31
+ _strict,
32
+ _string,
33
+ _tagged,
34
+ canonical,
35
+ )
36
+ from .factory_spine_shapes import (
37
+ SPINE_DOCUMENT_ISSUE_CODES,
38
+ SPINE_ISSUE_TEXT,
39
+ SPINE_NODE,
40
+ SpineIndex,
41
+ SpineRowEntries,
42
+ spine_findings,
43
+ spine_sources,
44
+ spine_table,
45
+ spine_table_refs,
46
+ table_head,
47
+ )
48
+
49
+ __all__ = [
50
+ "FACTORY_DOCS",
51
+ "FACTORY_INSTANT",
52
+ "FACTORY_ISSUE_CODES",
53
+ "FACTORY_LIMITS",
54
+ "FACTORY_NODE_ID",
55
+ "FactoryDocuments",
56
+ "FactoryIssue",
57
+ "canonical",
58
+ "hook_matcher_patterns",
59
+ ]
60
+
61
+ FACTORY_DOCS = ("ontology", "graph", "rules", "tests", "spine")
62
+ FACTORY_ISSUE_CODES = (
63
+ "node_invalid",
64
+ "edits_invalid",
65
+ "id_duplicate",
66
+ "id_mismatch",
67
+ "node_too_large",
68
+ "factory_too_large",
69
+ "relation_target_missing",
70
+ "ref_node_missing",
71
+ "test_attach_missing",
72
+ "hook_rule_missing",
73
+ "hook_test_missing",
74
+ "remove_missing",
75
+ "ref_world_missing",
76
+ "ref_schema_missing",
77
+ "test_spec_invalid",
78
+ "test_rule_missing",
79
+ "hook_matcher_invalid",
80
+ "hook_handler_event",
81
+ "hook_guard_missing",
82
+ *SPINE_DOCUMENT_ISSUE_CODES,
83
+ )
84
+ FACTORY_INSTANT = re.compile(
85
+ r"^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]"
86
+ r"(:[0-5][0-9](\.[0-9]+)?)?(Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])$"
87
+ )
88
+ RULE_UNIT_MAX_CASES = 50
89
+
90
+ _ENTRY_PATH = re.compile(r"^(ontology|graph|rules|tests|spine)/([a-z0-9][a-z0-9_-]{0,63})\.json$")
91
+
92
+ _HANDLER = _tagged(
93
+ "type",
94
+ {
95
+ "context": _strict({"type": _literal("context"), "text": _TEXT}),
96
+ "guard": _strict({"type": _literal("guard"), "rule": _node_id}),
97
+ "test": _strict({"type": _literal("test"), "test": _node_id}),
98
+ "record": _strict({"type": _literal("record")}),
99
+ },
100
+ )
101
+ _HOOK = _strict(
102
+ {
103
+ "event": _one_of("pre_tool_call", "post_tool_call"),
104
+ "handlers": _array(_HANDLER, min_items=1),
105
+ },
106
+ {"matcher": _TEXT, "for": _array(_TEXT), "scope": _REFS},
107
+ )
108
+
109
+ _NODE = _tagged(
110
+ "doc",
111
+ {
112
+ "ontology": _node_shape(
113
+ "ontology",
114
+ {"kind": _KIND},
115
+ {
116
+ "relations": _array(
117
+ _strict({"type": _KIND, "to": _node_id}),
118
+ max_items=FACTORY_LIMITS["relationsPerNode"],
119
+ )
120
+ },
121
+ ),
122
+ "graph": _node_shape(
123
+ "graph",
124
+ {"kind": _literal("entity")},
125
+ {
126
+ "entity": _strict({"world": _slug, "entity": _TEXT}),
127
+ "cardinality": _TEXT,
128
+ "createdIn": _slug,
129
+ "mergeKinds": _record(_one_of("set", "append", "counter"), _TEXT),
130
+ },
131
+ ),
132
+ "rules": _node_shape(
133
+ "rules",
134
+ {"kind": _literal("rule")},
135
+ {
136
+ "code": _strict({}, {"guard": _source, "derive": _source}),
137
+ "hooks": _array(_HOOK),
138
+ },
139
+ ),
140
+ "tests": _node_shape(
141
+ "tests",
142
+ {
143
+ "kind": _literal("test"),
144
+ "attaches": _array(_node_id, min_items=1),
145
+ "testKind": _one_of(
146
+ "rule_unit",
147
+ "chronicle",
148
+ "row",
149
+ "distribution",
150
+ "coverage",
151
+ "judged",
152
+ ),
153
+ "when": _array(_one_of("generate", "verify"), min_items=1),
154
+ "severity": _one_of("block", "warn"),
155
+ },
156
+ {"spec": _json},
157
+ ),
158
+ "spine": SPINE_NODE,
159
+ },
160
+ )
161
+
162
+ _DAYS_IN_MONTH = (31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31)
163
+
164
+
165
+ def _leap(year: int) -> bool:
166
+ return year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)
167
+
168
+
169
+ def _instant(value: Any) -> bool:
170
+ if not isinstance(value, str) or FACTORY_INSTANT.fullmatch(value) is None:
171
+ return False
172
+ year, month, day = int(value[0:4]), int(value[5:7]), int(value[8:10])
173
+ missing_leap_day = 1 if month == 2 and not _leap(year) else 0
174
+ return day <= _DAYS_IN_MONTH[month - 1] - missing_leap_day
175
+
176
+
177
+ def _rows_key(key: Any) -> bool:
178
+ world, dot, entity = key.partition(".") if isinstance(key, str) else ("", "", "")
179
+ return bool(dot) and _slug(world) and entity != ""
180
+
181
+
182
+ def _true(value: Any) -> bool:
183
+ return value is True
184
+
185
+
186
+ def _nullable(check: Check) -> Check:
187
+ return lambda value: value is None or check(value)
188
+
189
+
190
+ _ROW = _record(_json)
191
+ _ABOUT = _array(_node_id, min_items=1)
192
+ _CHANGE = _strict(
193
+ {},
194
+ {
195
+ "world": _slug,
196
+ "entity": _TEXT,
197
+ "op": _one_of("insert", "update", "delete"),
198
+ "row": _ROW,
199
+ "before": _nullable(_ROW),
200
+ "at": _instant,
201
+ "tool": _TEXT,
202
+ "input": _ROW,
203
+ "by": _strict({"principal": _TEXT, "unit": _nullable(_TEXT)}),
204
+ },
205
+ )
206
+ _STATEMENT = _strict(
207
+ {"id": _TEXT, "about": _array(_node_id), "says": _TEXT},
208
+ {"at": _instant, "causes": _array(_TEXT), "links": _array(_REF)},
209
+ )
210
+ _RULE_UNIT_CASE_SHAPE = _strict(
211
+ {"name": _TEXT, "change": _CHANGE},
212
+ {
213
+ "rows": _record(_array(_ROW), _rows_key),
214
+ "spine": _record(_ROW, _node_id),
215
+ "statements": _array(_STATEMENT),
216
+ "expect": _one_of("ok", "deny"),
217
+ "reason": _string(),
218
+ "derived": _array(_ROW),
219
+ },
220
+ )
221
+
222
+
223
+ def _rule_unit_case(value: Any) -> bool:
224
+ return _RULE_UNIT_CASE_SHAPE(value) and ("expect" in value or "derived" in value)
225
+
226
+
227
+ _RULE_UNIT_SPEC = _strict({"rule": _node_id, "cases": _array(_rule_unit_case, 1, RULE_UNIT_MAX_CASES)})
228
+ _CHRONICLE_SPEC = _strict(
229
+ {
230
+ "each": _strict({"about": _ABOUT}),
231
+ "require": _array(
232
+ _any_of(
233
+ _strict({"cause": _strict({"about": _ABOUT})}),
234
+ _strict({"at": _true}),
235
+ _strict({"causeBefore": _true}),
236
+ _strict({"link": _strict({}, {"world": _slug, "entity": _TEXT})}),
237
+ ),
238
+ min_items=1,
239
+ ),
240
+ },
241
+ {"cases": _array(_strict({"name": _TEXT, "statements": _array(_STATEMENT), "expect": _one_of("pass", "fail")}))},
242
+ )
243
+ _CODE_NEEDS = (("derive", "derived"), ("guard", "expect"))
244
+
245
+ _ISSUE_TEXT: Mapping[str, str] = MappingProxyType(
246
+ {
247
+ "node_invalid": "Node {node} does not match its document's shape.",
248
+ "edits_invalid": "The edit is malformed at {subject}.",
249
+ "id_duplicate": "Node id {node} is used more than once; ids are unique across all documents.",
250
+ "id_mismatch": "The node stored as {node} carries the id {subject}.",
251
+ "node_too_large": f"Node {{node}} is larger than {FACTORY_LIMITS['nodeBytes']} bytes as canonical JSON.",
252
+ "factory_too_large": (
253
+ f"A factory holds at most {FACTORY_LIMITS['nodesPerFactory']} nodes "
254
+ f"and {FACTORY_LIMITS['factoryBytes']} bytes of canonical JSON."
255
+ ),
256
+ "relation_target_missing": "Node {node} relates to {subject}, which is not a node of this factory.",
257
+ "ref_node_missing": "Node {node} refers to node {subject}, which is not a node of this factory.",
258
+ "test_attach_missing": "Test {node} attaches to {subject}, which is not a node of this factory.",
259
+ "hook_rule_missing": "A hook on {node} guards with {subject}, which is not a rule of this factory.",
260
+ "hook_test_missing": "A hook on {node} runs {subject}, which is not a test of this factory.",
261
+ "remove_missing": "The edit removes {node}, which the base revision does not hold.",
262
+ "ref_world_missing": "Node {node} refers to the world {subject}, which this project does not have.",
263
+ "ref_schema_missing": "Node {node} refers to {subject}, which that world's contract does not declare.",
264
+ "test_spec_invalid": "Test {node}'s spec does not match the grammar of its kind.",
265
+ "test_rule_missing": "Test {node} needs {subject}, which the rules of this factory do not define.",
266
+ "hook_matcher_invalid": "A hook on {node} has the matcher {subject}, which does not parse.",
267
+ "hook_handler_event": (
268
+ "A hook on {node} guards with {subject} on post_tool_call; a call that already ran cannot be refused, "
269
+ "so a guard belongs on pre_tool_call."
270
+ ),
271
+ "hook_guard_missing": (
272
+ "A hook on {node} guards with {subject}, which has no guard code; "
273
+ "a guard without code would refuse every matching call."
274
+ ),
275
+ **SPINE_ISSUE_TEXT,
276
+ }
277
+ )
278
+
279
+
280
+ @dataclass(frozen=True)
281
+ class FactoryIssue:
282
+ code: str
283
+ node: str | None
284
+ subject: str | None = None
285
+
286
+ @property
287
+ def message(self) -> str:
288
+ return _ISSUE_TEXT[self.code].format(node=self.node or "(no id)", subject=self.subject or "(root)")
289
+
290
+ def to_json(self) -> dict[str, str | None]:
291
+ return {"code": self.code, "node": self.node, "subject": self.subject}
292
+
293
+ @staticmethod
294
+ def sorted(issues: Iterable[FactoryIssue]) -> list[FactoryIssue]:
295
+ return sorted(set(issues), key=lambda i: (i.node or "", i.code, i.subject or ""))
296
+
297
+
298
+ @dataclass(frozen=True)
299
+ class _Link:
300
+ code: str
301
+ target: str
302
+ doc: str | None = None
303
+ table: bool = False
304
+ key: str | None = None
305
+
306
+ @property
307
+ def row_subject(self) -> str:
308
+ return self.target if self.key is None else f"{self.target}/{self.key}"
309
+
310
+
311
+ def _table_link(target: str, key: str | None) -> _Link:
312
+ return _Link("ref_node_missing", target, table=True, key=key)
313
+
314
+
315
+ _REF_LINKS: Mapping[str, Callable[[dict[str, Any]], list[_Link]]] = MappingProxyType(
316
+ {
317
+ "node": lambda ref: [_Link("ref_node_missing", ref["id"])],
318
+ "row": lambda ref: [_table_link(ref["node"], ref["key"])],
319
+ }
320
+ )
321
+
322
+
323
+ def _ref_links(refs: Iterable[dict[str, Any]]) -> list[_Link]:
324
+ return [link for ref in refs for link in _REF_LINKS.get(ref["kind"], lambda ref: [])(ref)]
325
+
326
+
327
+ def _ontology_links(node: dict[str, Any]) -> list[_Link]:
328
+ return [_Link("relation_target_missing", relation["to"]) for relation in node.get("relations", [])]
329
+
330
+
331
+ _HANDLER_LINKS: Mapping[str, Callable[[dict[str, Any]], list[_Link]]] = MappingProxyType(
332
+ {
333
+ "context": lambda handler: [],
334
+ "guard": lambda handler: [_Link("hook_rule_missing", handler["rule"], "rules")],
335
+ "test": lambda handler: [_Link("hook_test_missing", handler["test"], "tests")],
336
+ "record": lambda handler: [],
337
+ }
338
+ )
339
+
340
+
341
+ def _rule_links(node: dict[str, Any]) -> list[_Link]:
342
+ hooks = node.get("hooks", [])
343
+ scopes = _ref_links(ref for hook in hooks for ref in hook.get("scope", []))
344
+ handlers = [handler for hook in hooks for handler in hook["handlers"]]
345
+ return [
346
+ *scopes,
347
+ *(link for handler in handlers for link in _HANDLER_LINKS[handler["type"]](handler)),
348
+ ]
349
+
350
+
351
+ _DOC_LINKS: Mapping[str, Callable[[dict[str, Any]], list[_Link]]] = MappingProxyType(
352
+ {
353
+ "ontology": _ontology_links,
354
+ "graph": lambda node: [],
355
+ "rules": _rule_links,
356
+ "tests": lambda node: [_Link("test_attach_missing", target) for target in node["attaches"]],
357
+ "spine": lambda node: [
358
+ *_ref_links(spine_sources(node)),
359
+ *(_table_link(target, None) for target in spine_table_refs(node)),
360
+ ],
361
+ }
362
+ )
363
+
364
+
365
+ def _links(node: dict[str, Any]) -> list[_Link]:
366
+ return [*_ref_links(node.get("refs", [])), *_DOC_LINKS[node["doc"]](node)]
367
+
368
+
369
+ _DEPTH_STEP: Mapping[str, int] = MappingProxyType({"(": 1, ")": -1})
370
+
371
+
372
+ class _TopLevelSplit:
373
+ def __init__(self) -> None:
374
+ self._parts: list[str] = []
375
+ self._current: list[str] = []
376
+ self._depth = 0
377
+ self._escaped = False
378
+ self._in_class = False
379
+
380
+ @classmethod
381
+ def of(cls, text: str) -> list[str]:
382
+ split = cls()
383
+ for char in text:
384
+ split._take(char)
385
+ return [*split._parts, "".join(split._current)]
386
+
387
+ def _take(self, char: str) -> None:
388
+ if self._escaped:
389
+ self._escaped = False
390
+ self._current.append(char)
391
+ return
392
+ if char == "\\":
393
+ self._escaped = True
394
+ self._current.append(char)
395
+ return
396
+ if self._in_class:
397
+ self._in_class = char != "]"
398
+ self._current.append(char)
399
+ return
400
+ if char == "|" and self._depth == 0:
401
+ self._parts.append("".join(self._current))
402
+ self._current = []
403
+ return
404
+ self._in_class = char == "["
405
+ self._depth = max(0, self._depth + _DEPTH_STEP.get(char, 0))
406
+ self._current.append(char)
407
+
408
+
409
+ def hook_matcher_patterns(text: str | None) -> tuple[str, ...]:
410
+ """The matcher grammar of gatewaysdk.hooks.matchers, which this vendored package cannot import;
411
+ conformance/hook-contract.json pins the two together. Raises ValueError for a matcher that does not parse."""
412
+ patterns = tuple(part for part in (raw.strip() for raw in _TopLevelSplit.of(text or "")) if part)
413
+ if "*" in patterns:
414
+ return ()
415
+ for pattern in patterns:
416
+ try:
417
+ re.compile(pattern)
418
+ except re.error as error:
419
+ raise ValueError(f"matcher {pattern!r} is not a regular expression: {error}") from None
420
+ return patterns
421
+
422
+
423
+ def _matcher_issues(node_id: str, hook: dict[str, Any]) -> list[FactoryIssue]:
424
+ if "matcher" not in hook:
425
+ return []
426
+ try:
427
+ hook_matcher_patterns(hook["matcher"])
428
+ except ValueError:
429
+ return [FactoryIssue("hook_matcher_invalid", node_id, hook["matcher"])]
430
+ return []
431
+
432
+
433
+ _GUARDED_RULES: Mapping[str, Callable[[dict[str, Any]], list[str]]] = MappingProxyType(
434
+ {
435
+ "context": lambda handler: [],
436
+ "guard": lambda handler: [handler["rule"]],
437
+ "test": lambda handler: [],
438
+ "record": lambda handler: [],
439
+ }
440
+ )
441
+
442
+
443
+ def _guarded_rules(hook: dict[str, Any]) -> list[str]:
444
+ return [rule for handler in hook["handlers"] for rule in _GUARDED_RULES[handler["type"]](handler)]
445
+
446
+
447
+ def _handler_event_issues(node_id: str, hook: dict[str, Any]) -> list[FactoryIssue]:
448
+ if hook["event"] == "pre_tool_call":
449
+ return []
450
+ return [FactoryIssue("hook_handler_event", node_id, rule) for rule in _guarded_rules(hook)]
451
+
452
+
453
+ def _lacks_guard(rule: dict[str, Any] | None) -> bool:
454
+ return rule is not None and rule.get("doc") == "rules" and not rule.get("code", {}).get("guard")
455
+
456
+
457
+ def _guard_code_issues(node_id: str, hook: dict[str, Any], documents: FactoryDocuments) -> list[FactoryIssue]:
458
+ return [
459
+ FactoryIssue("hook_guard_missing", node_id, rule)
460
+ for rule in _guarded_rules(hook)
461
+ if _lacks_guard(documents.node(rule))
462
+ ]
463
+
464
+
465
+ def _rule_checks(node: dict[str, Any], documents: FactoryDocuments) -> list[FactoryIssue]:
466
+ return [
467
+ issue
468
+ for hook in node.get("hooks", [])
469
+ for issue in (
470
+ *_matcher_issues(node["id"], hook),
471
+ *_handler_event_issues(node["id"], hook),
472
+ *_guard_code_issues(node["id"], hook, documents),
473
+ )
474
+ ]
475
+
476
+
477
+ def _rule_unit_issues(test: dict[str, Any], documents: FactoryDocuments) -> list[FactoryIssue]:
478
+ spec: Any = test.get("spec")
479
+ if not _RULE_UNIT_SPEC(spec):
480
+ return [FactoryIssue("test_spec_invalid", test["id"])]
481
+ rule = documents.node(spec["rule"]) or {}
482
+ if rule.get("doc") != "rules":
483
+ return [FactoryIssue("test_rule_missing", test["id"], spec["rule"])]
484
+ code = rule.get("code", {})
485
+ return [
486
+ FactoryIssue("test_rule_missing", test["id"], f"{spec['rule']}.{part}")
487
+ for part, field in _CODE_NEEDS
488
+ if any(field in case for case in spec["cases"]) and not code.get(part)
489
+ ]
490
+
491
+
492
+ def _chronicle_issues(test: dict[str, Any], documents: FactoryDocuments) -> list[FactoryIssue]:
493
+ return [] if _CHRONICLE_SPEC(test.get("spec")) else [FactoryIssue("test_spec_invalid", test["id"])]
494
+
495
+
496
+ def _no_checks(node: dict[str, Any], documents: FactoryDocuments) -> list[FactoryIssue]:
497
+ return []
498
+
499
+
500
+ _SPEC_CHECKS: Mapping[str, Callable[[dict[str, Any], FactoryDocuments], list[FactoryIssue]]] = MappingProxyType(
501
+ {
502
+ "rule_unit": _rule_unit_issues,
503
+ "chronicle": _chronicle_issues,
504
+ "row": _no_checks,
505
+ "distribution": _no_checks,
506
+ "coverage": _no_checks,
507
+ "judged": _no_checks,
508
+ }
509
+ )
510
+
511
+ _DOC_CHECKS: Mapping[str, Callable[[dict[str, Any], FactoryDocuments], list[FactoryIssue]]] = MappingProxyType(
512
+ {
513
+ "ontology": _no_checks,
514
+ "graph": _no_checks,
515
+ "rules": _rule_checks,
516
+ "tests": lambda node, documents: _SPEC_CHECKS[node["testKind"]](node, documents),
517
+ "spine": lambda node, documents: [
518
+ FactoryIssue(code, node["id"], subject) for code, subject in spine_findings(node, documents.spine_index)
519
+ ],
520
+ }
521
+ )
522
+
523
+
524
+ def _raw_id(value: Any) -> str | None:
525
+ node_id = value.get("id") if isinstance(value, dict) else None
526
+ return node_id if isinstance(node_id, str) else None
527
+
528
+
529
+ class FactoryDocuments:
530
+ def __init__(self, nodes: Mapping[str, dict[str, Any]]) -> None:
531
+ self._nodes: dict[str, dict[str, Any]] = dict(nodes)
532
+
533
+ @classmethod
534
+ def read(cls, raw: Iterable[Any]) -> FactoryDocuments | list[FactoryIssue]:
535
+ issues: list[FactoryIssue] = []
536
+ nodes: dict[str, dict[str, Any]] = {}
537
+ duplicated: set[str] = set()
538
+ for value in raw:
539
+ if not _NODE(value):
540
+ issues.append(FactoryIssue("node_invalid", _raw_id(value)))
541
+ continue
542
+ if value["id"] in nodes:
543
+ duplicated.add(value["id"])
544
+ nodes[value["id"]] = value
545
+ issues.extend(FactoryIssue("id_duplicate", node_id) for node_id in duplicated)
546
+ return FactoryIssue.sorted(issues) if issues else cls(nodes)
547
+
548
+ @classmethod
549
+ def from_entries(cls, entries: Mapping[str, bytes | str]) -> FactoryDocuments | list[FactoryIssue]:
550
+ issues: list[FactoryIssue] = []
551
+ raw: list[Any] = []
552
+ rows = SpineRowEntries()
553
+ for path, data in entries.items():
554
+ if rows.take(path, data):
555
+ continue
556
+ read = _read_entry(path, data)
557
+ if isinstance(read, FactoryIssue):
558
+ issues.append(read)
559
+ continue
560
+ raw.append(read)
561
+ nodes, failures = rows.join(raw)
562
+ issues.extend(FactoryIssue("node_invalid", node_id) for node_id in failures)
563
+ reading = cls.read(nodes)
564
+ if not issues:
565
+ return reading
566
+ return FactoryIssue.sorted([*issues, *(reading if isinstance(reading, list) else [])])
567
+
568
+ def __len__(self) -> int:
569
+ return len(self._nodes)
570
+
571
+ def ids(self) -> list[str]:
572
+ return sorted(self._nodes)
573
+
574
+ def node(self, node_id: str) -> dict[str, Any] | None:
575
+ return self._nodes.get(node_id)
576
+
577
+ def all(self) -> list[dict[str, Any]]:
578
+ return [self._nodes[node_id] for node_id in self.ids()]
579
+
580
+ def by_doc(self, doc: str) -> list[dict[str, Any]]:
581
+ return [node for node in self.all() if node["doc"] == doc]
582
+
583
+ @cached_property
584
+ def spine_index(self) -> SpineIndex:
585
+ return SpineIndex(table for node in self._valid if (table := spine_table(node)) is not None)
586
+
587
+ @cached_property
588
+ def _checked(self) -> list[tuple[dict[str, Any], bool]]:
589
+ return [(node, _NODE(node)) for node in self.all()]
590
+
591
+ @cached_property
592
+ def _valid(self) -> list[dict[str, Any]]:
593
+ return [node for node, ok in self._checked if ok]
594
+
595
+ def issues(self) -> list[FactoryIssue]:
596
+ valid = self._valid
597
+ invalid = [FactoryIssue("node_invalid", node.get("id")) for node, ok in self._checked if not ok]
598
+ return FactoryIssue.sorted(
599
+ [
600
+ *self._limit_issues(),
601
+ *self._identity_issues(),
602
+ *invalid,
603
+ *self._link_issues(valid),
604
+ *(issue for node in valid for issue in _DOC_CHECKS[node["doc"]](node, self)),
605
+ ]
606
+ )
607
+
608
+ def _limit_issues(self) -> list[FactoryIssue]:
609
+ sizes = [(node["id"], *_sizes(node)) for node in self.all()]
610
+ too_large_factory = (
611
+ len(self._nodes) > FACTORY_LIMITS["nodesPerFactory"]
612
+ or sum(size for _, size, _ in sizes) > FACTORY_LIMITS["factoryBytes"]
613
+ )
614
+ too_large_nodes = [
615
+ FactoryIssue("node_too_large", node_id) for node_id, _, head in sizes if head > FACTORY_LIMITS["nodeBytes"]
616
+ ]
617
+ return [*([FactoryIssue("factory_too_large", None)] if too_large_factory else []), *too_large_nodes]
618
+
619
+ def _identity_issues(self) -> list[FactoryIssue]:
620
+ counts: dict[str, int] = {}
621
+ for node in self._nodes.values():
622
+ counts[node.get("id")] = counts.get(node.get("id"), 0) + 1
623
+ mismatched = [
624
+ FactoryIssue("id_mismatch", key, node.get("id"))
625
+ for key, node in self._nodes.items()
626
+ if key != node.get("id")
627
+ ]
628
+ return [
629
+ *mismatched,
630
+ *(FactoryIssue("id_duplicate", node_id) for node_id, count in counts.items() if count > 1),
631
+ ]
632
+
633
+ def _link_issues(self, valid: list[dict[str, Any]]) -> list[FactoryIssue]:
634
+ return [issue for node in valid for link in _links(node) for issue in self._link_issue(node["id"], link)]
635
+
636
+ def _link_issue(self, node_id: str, link: _Link) -> list[FactoryIssue]:
637
+ target = self._nodes.get(link.target)
638
+ if target is None or (link.doc is not None and target["doc"] != link.doc):
639
+ return [FactoryIssue(link.code, node_id, link.target)]
640
+ if not link.table or self.spine_index.holds(link.target, link.key):
641
+ return []
642
+ return [FactoryIssue("ref_row_missing", node_id, link.row_subject)]
643
+
644
+
645
+ def _bytes(value: Any) -> int:
646
+ return len(canonical(value).encode("utf-8"))
647
+
648
+
649
+ def _sizes(node: dict[str, Any]) -> tuple[int, int]:
650
+ total = _bytes(node)
651
+ table = spine_table(node)
652
+ return total, total if table is None else _bytes(table_head(table))
653
+
654
+
655
+ def _refuse_constant(name: str) -> Any:
656
+ raise ValueError(f"{name} is not JSON")
657
+
658
+
659
+ def _read_entry(path: str, data: bytes | str) -> Any:
660
+ match = _ENTRY_PATH.fullmatch(path)
661
+ if match is None:
662
+ return FactoryIssue("node_invalid", None)
663
+ doc, node_id = match.groups()
664
+ try:
665
+ value = json.loads(data, parse_constant=_refuse_constant)
666
+ except ValueError:
667
+ return FactoryIssue("node_invalid", node_id)
668
+ if _raw_id(value) != node_id or value.get("doc") != doc:
669
+ return FactoryIssue("node_invalid", node_id)
670
+ return value