@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,973 @@
1
+ """Copied into the rule sandbox with ``factory_spine.py`` beside it, so both import only the
2
+ standard library and nothing relative."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import ast
7
+ import builtins
8
+ import copy
9
+ import decimal
10
+ import hashlib
11
+ import importlib.util
12
+ import json
13
+ import os
14
+ import random
15
+ import signal
16
+ import sys
17
+ import time
18
+ import types
19
+ from typing import Any, Callable, Iterable
20
+
21
+ try:
22
+ import resource
23
+ except ImportError:
24
+ resource = None # type: ignore[assignment]
25
+
26
+ import zoneinfo
27
+
28
+ VERSION = 1
29
+ ALLOWED_IMPORTS = frozenset("math statistics decimal datetime re json collections itertools zoneinfo".split())
30
+ BANNED_NAMES = frozenset(
31
+ "open exec eval compile __import__ globals locals vars input breakpoint getattr setattr delattr "
32
+ "hasattr type object dir super memoryview __build_class__ exit quit hash id BaseException print".split()
33
+ )
34
+ INTROSPECTION_ATTRS = frozenset(
35
+ "gi_frame gi_code gi_yieldfrom gi_suspended cr_frame cr_code cr_await ag_frame ag_code ag_await "
36
+ "f_back f_globals f_locals f_builtins f_code f_trace tb_frame tb_next co_code co_consts co_names "
37
+ "cell_contents func_globals func_code mro".split()
38
+ )
39
+ HOST_READS = {"now": "the clock", "utcnow": "the clock", "today": "the clock", "samples": "unseeded randomness"}
40
+ UNEXPORTED = frozenset({"DefaultContext", "BasicContext", "ExtendedContext", "reset_tzpath"})
41
+ DEFAULT_BY = {"principal": "user:fixture", "unit": None}
42
+ DEFAULT_JOB_SECONDS = 2.0
43
+ MAX_JOB_SECONDS = 60
44
+ MIB = 1024 * 1024
45
+ RESULT_CAP_BYTES = 4 * MIB
46
+ RESULT_CAPS = {"spine": 32 * MIB, "generate": 16 * MIB}
47
+ ADDRESS_SPACE_BYTES = 1 << 30
48
+ REFUSED_AUDIT_EXACT = frozenset(
49
+ "subprocess.Popen os.system os.fork os.kill os.remove os.rename os.rmdir os.mkdir os.truncate "
50
+ "os.chmod os.chown os.symlink os.link os.utime os.listdir os.scandir os.chdir os.putenv os.unsetenv".split()
51
+ )
52
+ REFUSED_AUDIT_PREFIX = ("socket.", "os.exec", "os.posix_spawn", "os.spawn", "shutil.", "ctypes.", "subprocess.")
53
+
54
+
55
+ def _tz_roots() -> tuple[str, ...]:
56
+ roots = [str(path) for path in zoneinfo.TZPATH]
57
+ try:
58
+ import tzdata # type: ignore[import-not-found]
59
+
60
+ roots.append(os.path.dirname(tzdata.__file__))
61
+ except Exception:
62
+ pass
63
+ return tuple(roots)
64
+
65
+
66
+ TZ_ROOTS = _tz_roots()
67
+
68
+
69
+ def _internal_deps() -> frozenset[str]:
70
+ """The stdlib modules an allow-list module pulls in itself (``datetime`` needs
71
+ ``time`` for ``strftime``); allowing only these keeps internals working while a
72
+ fresh off-list import still fails (D-46). ``socket``/``subprocess`` are not among them."""
73
+ import importlib
74
+
75
+ before = set(sys.modules)
76
+ for name in ALLOWED_IMPORTS:
77
+ importlib.import_module(name)
78
+ delta = {module.split(".")[0] for module in set(sys.modules) - before}
79
+ return frozenset(delta | {"time"})
80
+
81
+
82
+ INTERNAL_DEPS = _internal_deps()
83
+
84
+
85
+ class _Module:
86
+ """A read-only stand-in carrying only an allow-list module's public, non-module attributes, so a rule
87
+ cannot hop through ``re.enum`` or ``collections.abc`` to ``sys``/``os``. Every job shares it, so it refuses
88
+ writes; the process-wide setters in ``UNEXPORTED`` stay out of it for the same reason."""
89
+
90
+ def __init__(self, exported: dict[str, Any]) -> None:
91
+ self.__dict__.update(exported)
92
+
93
+ def __getattr__(self, attr: str) -> Any:
94
+ raise RuleRefused("escape_refused", f"attribute {attr} is not available to a rule")
95
+
96
+ def __setattr__(self, attr: str, _value: Any) -> None:
97
+ raise RuleRefused("escape_refused", f"attribute {attr} is read-only to a rule")
98
+
99
+ def __delattr__(self, attr: str) -> None:
100
+ self.__setattr__(attr, None)
101
+
102
+
103
+ def _module_proxies() -> dict[str, _Module]:
104
+ proxies = {}
105
+ for name in ALLOWED_IMPORTS:
106
+ exported = {
107
+ key: value
108
+ for key, value in vars(sys.modules[name]).items()
109
+ if not key.startswith("_") and key not in UNEXPORTED and not isinstance(value, types.ModuleType)
110
+ }
111
+ proxies[name] = _Module(exported)
112
+ return proxies
113
+
114
+
115
+ _MODULE_PROXIES = _module_proxies()
116
+
117
+
118
+ def _load_spine() -> types.ModuleType:
119
+ """By file location, before the sentry arms, so the script and the package load the same sibling."""
120
+ path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "factory_spine.py")
121
+ spec = importlib.util.spec_from_file_location("gateway_factory_spine", path)
122
+ module = importlib.util.module_from_spec(spec)
123
+ spec.loader.exec_module(module)
124
+ return module
125
+
126
+
127
+ _SPINE = _load_spine()
128
+
129
+
130
+ class _CanonicalEncoder(json.JSONEncoder):
131
+ """Bound at import, before any rule runs, so the executor frames and measures every result with methods
132
+ no rule can reach, whatever a rule did to ``json.JSONEncoder``."""
133
+
134
+ encode = json.JSONEncoder.encode
135
+ iterencode = json.JSONEncoder.iterencode
136
+ default = json.JSONEncoder.default
137
+
138
+
139
+ _CANONICAL = _CanonicalEncoder(sort_keys=True, separators=(",", ":"), ensure_ascii=False)
140
+ _DECIMAL_CONTEXT = decimal.getcontext().copy()
141
+
142
+
143
+ def canonical(value: Any) -> str:
144
+ return _CANONICAL.encode(value)
145
+
146
+
147
+ class RuleRefused(Exception):
148
+ def __init__(self, type: str, message: str, line: int | None = None) -> None:
149
+ super().__init__(message)
150
+ self.type = type
151
+ self.message = message
152
+ self.line = line
153
+
154
+ def as_error(self) -> dict[str, Any]:
155
+ error: dict[str, Any] = {"type": self.type, "message": self.message}
156
+ if self.line is not None:
157
+ error["line"] = self.line
158
+ return error
159
+
160
+
161
+ class InputInvalid(Exception):
162
+ def __init__(self, message: str) -> None:
163
+ super().__init__(message)
164
+ self.message = message
165
+
166
+
167
+ class SandboxViolation(Exception):
168
+ def __init__(self, event: str) -> None:
169
+ super().__init__(event)
170
+ self.event = event
171
+
172
+
173
+ class JobTimeout(BaseException):
174
+ """A ``BaseException`` so a rule's ``except Exception`` cannot swallow its budget."""
175
+
176
+
177
+ class StaticGuard:
178
+ """The earliest refusal in the source wins, so its line number is stable."""
179
+
180
+ def __init__(self, source: str, mode: str = "exec") -> None:
181
+ self._source = source
182
+ self._mode = mode
183
+
184
+ def check(self) -> None:
185
+ refusals = sorted(self._refusals(), key=lambda r: (r.line or 0, r.type))
186
+ if refusals:
187
+ raise refusals[0]
188
+
189
+ def _refusals(self) -> Iterable[RuleRefused]:
190
+ tree = self._parse()
191
+ for node in ast.walk(tree):
192
+ yield from self._refuse(node)
193
+
194
+ def _parse(self) -> ast.AST:
195
+ try:
196
+ return ast.parse(self._source, mode=self._mode)
197
+ except SyntaxError as error:
198
+ raise RuleRefused("syntax_invalid", f"the rule does not parse: {error.msg}", error.lineno)
199
+
200
+ def _refuse(self, node: ast.AST) -> Iterable[RuleRefused]:
201
+ handler = _STATIC_HANDLERS.get(type(node))
202
+ if handler is None:
203
+ return ()
204
+ return handler(node)
205
+
206
+
207
+ def _refuse_import(node: ast.Import) -> Iterable[RuleRefused]:
208
+ bad = [alias.name for alias in node.names if alias.name.split(".")[0] not in ALLOWED_IMPORTS]
209
+ return _import_refusal(bad, node.lineno)
210
+
211
+
212
+ def _refuse_import_from(node: ast.ImportFrom) -> Iterable[RuleRefused]:
213
+ root = (node.module or "").split(".")[0]
214
+ bad = [] if root in ALLOWED_IMPORTS else [node.module or ""]
215
+ return _import_refusal(bad, node.lineno)
216
+
217
+
218
+ def _import_refusal(bad: list[str], line: int) -> Iterable[RuleRefused]:
219
+ if not bad:
220
+ return ()
221
+ return (RuleRefused("import_refused", f"{bad[0]} is not on the rule allow-list", line),)
222
+
223
+
224
+ def _refuse_name(node: ast.Name) -> Iterable[RuleRefused]:
225
+ if node.id not in BANNED_NAMES and not node.id.startswith("__"):
226
+ return ()
227
+ return (RuleRefused("escape_refused", f"{node.id} is not available to a rule", node.lineno),)
228
+
229
+
230
+ def _refuse_attribute(node: ast.Attribute) -> Iterable[RuleRefused]:
231
+ if node.attr in HOST_READS:
232
+ return (RuleRefused("clock_refused", f"{HOST_READS[node.attr]} is not available: {node.attr}()", node.lineno),)
233
+ if node.attr.startswith("_") or node.attr in INTROSPECTION_ATTRS:
234
+ return (RuleRefused("escape_refused", f"attribute {node.attr} is not available to a rule", node.lineno),)
235
+ if isinstance(node.ctx, ast.Load):
236
+ return ()
237
+ return (RuleRefused("escape_refused", f"attribute {node.attr} is read-only to a rule", node.lineno),)
238
+
239
+
240
+ def _refuse_bare_except(node: ast.ExceptHandler) -> Iterable[RuleRefused]:
241
+ if node.type is not None:
242
+ return ()
243
+ return (RuleRefused("escape_refused", "a bare except is not available to a rule", node.lineno),)
244
+
245
+
246
+ _JUMPS = (ast.Return, ast.Break, ast.Continue)
247
+
248
+
249
+ def _refuse_finally_jump(node: ast.Try) -> Iterable[RuleRefused]:
250
+ """A ``return``, ``break`` or ``continue`` in a ``finally`` discards the job's ``JobTimeout`` as a bare
251
+ ``except`` would."""
252
+ jumps = [inner for statement in node.finalbody for inner in ast.walk(statement) if isinstance(inner, _JUMPS)]
253
+ return [RuleRefused("escape_refused", "a finally cannot return, break or continue", jump.lineno) for jump in jumps]
254
+
255
+
256
+ _STATIC_HANDLERS: dict[type, Callable[[Any], Iterable[RuleRefused]]] = {
257
+ ast.Import: _refuse_import,
258
+ ast.ImportFrom: _refuse_import_from,
259
+ ast.Name: _refuse_name,
260
+ ast.Attribute: _refuse_attribute,
261
+ ast.ExceptHandler: _refuse_bare_except,
262
+ ast.Try: _refuse_finally_jump,
263
+ getattr(ast, "TryStar", ast.Try): _refuse_finally_jump,
264
+ }
265
+
266
+
267
+ def _realpath(path: Any) -> str:
268
+ try:
269
+ return os.path.realpath(path)
270
+ except (TypeError, ValueError, OSError):
271
+ return ""
272
+
273
+
274
+ class AuditSentry:
275
+ """The process audit hook, armed once and never disarmed: the flag lives in a
276
+ closure the hook and ``arm`` share, so no attribute a rule could flip exists even
277
+ after a reflection escape. A read is allowed only under the realpath-normalised tz
278
+ database; every other file, directory, process, socket, ctypes and env event is refused."""
279
+
280
+ def __init__(self, tz_roots: tuple[str, ...] = TZ_ROOTS) -> None:
281
+ self._tz_roots = tuple(sorted({_realpath(root) for root in tz_roots if _realpath(root)}))
282
+ armed = [False]
283
+
284
+ def hook(event: str, args: tuple[Any, ...]) -> None:
285
+ if armed[0] and self.refuses(event, args):
286
+ raise SandboxViolation(event)
287
+
288
+ self._arm = lambda: armed.__setitem__(0, True)
289
+ sys.addaudithook(hook)
290
+
291
+ def arm(self) -> None:
292
+ self._arm()
293
+
294
+ def refuses(self, event: str, args: tuple[Any, ...]) -> bool:
295
+ if event == "open":
296
+ return not self._tz_read(args)
297
+ if event in REFUSED_AUDIT_EXACT:
298
+ return True
299
+ return event.startswith(REFUSED_AUDIT_PREFIX)
300
+
301
+ def _tz_read(self, args: tuple[Any, ...]) -> bool:
302
+ if not args or not self._tz_roots:
303
+ return False
304
+ return _realpath(args[0]).startswith(self._tz_roots)
305
+
306
+
307
+ _SENTRY = AuditSentry()
308
+
309
+
310
+ class RuleRuntime:
311
+ """Compiles and runs one rule function with scrubbed builtins; the executor
312
+ arms the audit sentry for the whole run, so a rule syscall becomes a refusal here."""
313
+
314
+ def call(self, name: str, source: str, view: "View", change: dict[str, Any]) -> Any:
315
+ StaticGuard(source).check()
316
+ return self.compile_and_run(name, source, view, change)
317
+
318
+ def compile_and_run(self, name: str, source: str, view: "View", change: dict[str, Any]) -> Any:
319
+ fn = self.bind(name, compile(source, "<rule>", "exec"))
320
+ return self.invoke(fn, view, change)
321
+
322
+ def bind(self, name: str, code: types.CodeType) -> Callable[..., Any]:
323
+ scope: dict[str, Any] = {"__name__": "__rule__", "__builtins__": self.scrubbed_builtins()}
324
+ exec(code, scope) # noqa: S102 - scrubbed builtins + armed audit hook
325
+ fn = scope.get(name)
326
+ if not callable(fn):
327
+ raise RuleRefused("rule_missing", f"the rule defines no {name}()")
328
+ return fn
329
+
330
+ def invoke(self, fn: Callable[..., Any], *args: Any) -> Any:
331
+ try:
332
+ return fn(*args)
333
+ except SandboxViolation as violation:
334
+ raise RuleRefused("sandbox_refused", f"{violation.event} is not available to a rule")
335
+
336
+ def scrubbed_builtins(self) -> dict[str, Any]:
337
+ scrubbed = {name: value for name, value in vars(builtins).items() if name not in BANNED_NAMES}
338
+ scrubbed["__import__"] = self._import
339
+ return scrubbed
340
+
341
+ def _import(self, name: str, globals: Any = None, locals: Any = None, fromlist: Any = (), level: int = 0) -> Any:
342
+ top = name.split(".")[0]
343
+ if top in ALLOWED_IMPORTS:
344
+ return _MODULE_PROXIES[top]
345
+ if top in INTERNAL_DEPS:
346
+ return builtins.__import__(name, globals, locals, fromlist, level)
347
+ raise RuleRefused("import_refused", f"{name} is not on the rule allow-list")
348
+
349
+
350
+ class SpineRuntime:
351
+ """factory_spine's only door to the sandbox: what it runs gets a rule's static guard, scrubbed builtins
352
+ and armed sentry. Guarded code is kept per source, so an owner runs over every row on one guard."""
353
+
354
+ def __init__(self) -> None:
355
+ self._rules = RuleRuntime()
356
+ self._codes: dict[tuple[str, str], types.CodeType | RuleRefused] = {}
357
+
358
+ def evaluate(self, expression: str, names: dict[str, Any]) -> Any:
359
+ return self._as_spine(self._evaluate, expression, names)
360
+
361
+ def call(self, function: str, source: str, *args: Any) -> Any:
362
+ return self._as_spine(self._call, function, source, *args)
363
+
364
+ def _evaluate(self, expression: str, names: dict[str, Any]) -> Any:
365
+ code = self._guarded(expression, "eval")
366
+ scope = {**names, "__builtins__": self._rules.scrubbed_builtins()}
367
+ return self._rules.invoke(eval, code, scope) # noqa: S307 - guarded, scrubbed builtins + armed audit hook
368
+
369
+ def _call(self, function: str, source: str, *args: Any) -> Any:
370
+ code = self._guarded(source, "exec")
371
+ return self._rules.invoke(lambda: self._rules.bind(function, code)(*args))
372
+
373
+ def _guarded(self, source: str, mode: str) -> types.CodeType:
374
+ known = self._codes.get((mode, source))
375
+ if known is None:
376
+ known = self._codes[(mode, source)] = self._compile(source, mode)
377
+ if isinstance(known, RuleRefused):
378
+ raise RuleRefused(known.type, known.message, known.line)
379
+ return known
380
+
381
+ @staticmethod
382
+ def _compile(source: str, mode: str) -> types.CodeType | RuleRefused:
383
+ try:
384
+ StaticGuard(source, mode).check()
385
+ except RuleRefused as refused:
386
+ return refused
387
+ return compile(source, "<spine>", mode)
388
+
389
+ @staticmethod
390
+ def _as_spine(work: Callable[..., Any], *args: Any) -> Any:
391
+ try:
392
+ return work(*args)
393
+ except RuleRefused as refused:
394
+ raise _SPINE.SpineRefused(refused.type, refused.message, refused.line) from None
395
+
396
+
397
+ class View:
398
+ """The read-only view a rule reads rows, spine nodes and statements through.
399
+ Every reader returns copies, so a rule cannot mutate the fixture."""
400
+
401
+ def __init__(
402
+ self,
403
+ rows: dict[str, list[dict[str, Any]]],
404
+ spine: dict[str, Any],
405
+ statements: list[dict[str, Any]],
406
+ seed: str,
407
+ rule_id: str,
408
+ ) -> None:
409
+ self._rows = rows
410
+ self._spine = spine
411
+ self._statements = statements
412
+ self._seed = seed
413
+ self._rule_id = rule_id
414
+
415
+ @classmethod
416
+ def of(cls, payload: dict[str, Any], seed: str, rule_id: str) -> "View":
417
+ return cls(
418
+ dict(payload.get("rows") or {}),
419
+ dict(payload.get("spine") or {}),
420
+ list(payload.get("statements") or []),
421
+ seed,
422
+ rule_id,
423
+ )
424
+
425
+ @classmethod
426
+ def empty(cls, seed: str, rule_id: str) -> "View":
427
+ return cls({}, {}, [], seed, rule_id)
428
+
429
+ def rows(self, world: str, entity: str, **where: Any) -> list[dict[str, Any]]:
430
+ table = self._rows.get(f"{world}.{entity}", [])
431
+ matched = [row for row in table if _matches(row, where)]
432
+ return copy.deepcopy(matched)
433
+
434
+ def one(self, world: str, entity: str, **where: Any) -> dict[str, Any] | None:
435
+ found = self.rows(world, entity, **where)
436
+ return found[0] if found else None
437
+
438
+ def spine(self, node_id: str) -> dict[str, Any]:
439
+ if node_id not in self._spine:
440
+ raise RuleRefused("spine_missing", f"no spine node {node_id}")
441
+ return copy.deepcopy(self._spine[node_id])
442
+
443
+ def statements(self, about: str | None = None) -> list[dict[str, Any]]:
444
+ selected = [s for s in self._statements if about is None or about in (s.get("about") or [])]
445
+ return copy.deepcopy(selected)
446
+
447
+ def rng(self, name: str) -> random.Random:
448
+ digest = hashlib.sha256("\u0000".join([self._seed, self._rule_id, name]).encode("utf-8")).hexdigest()
449
+ return _SPINE.SeededStream(digest)
450
+
451
+
452
+ def _matches(row: dict[str, Any], where: dict[str, Any]) -> bool:
453
+ return all(row.get(key) == value for key, value in where.items())
454
+
455
+
456
+ class Verdict:
457
+ """A guard's answer: ``ok`` or ``deny(reason)``. Anything that is not ``True``
458
+ or a non-empty string is refused as ``verdict_invalid`` (D-53)."""
459
+
460
+ def __init__(self, status: str, reason: str | None) -> None:
461
+ self.status = status
462
+ self.reason = reason
463
+
464
+ @classmethod
465
+ def of(cls, result: Any) -> "Verdict":
466
+ if result is True:
467
+ return cls("ok", None)
468
+ if isinstance(result, str) and result:
469
+ return cls("deny", result)
470
+ raise RuleRefused("verdict_invalid", f"a guard returns True or a reason string, got {result!r}")
471
+
472
+ def result(self) -> dict[str, Any]:
473
+ if self.status == "ok":
474
+ return {"status": "ok"}
475
+ return {"status": "deny", "reason": self.reason}
476
+
477
+
478
+ class Rule:
479
+ def __init__(self, rule_id: str, code: dict[str, Any]) -> None:
480
+ self.id = rule_id
481
+ self._guard = code.get("guard")
482
+ self._derive = code.get("derive")
483
+ self._runtime = RuleRuntime()
484
+
485
+ def guard_source(self) -> str | None:
486
+ return self._guard
487
+
488
+ def derive_source(self) -> str | None:
489
+ return self._derive
490
+
491
+ def guard(self, view: View, change: dict[str, Any], source: str | None = None) -> Verdict:
492
+ return Verdict.of(self._runtime.call("guard", self._need(source or self._guard, "guard"), view, change))
493
+
494
+ def derive(self, view: View, change: dict[str, Any], source: str | None = None) -> list[dict[str, Any]]:
495
+ rows = self._runtime.call("derive", self._need(source or self._derive, "derive"), view, change)
496
+ return _as_rows(rows)
497
+
498
+ def _need(self, source: str | None, name: str) -> str:
499
+ if source is None:
500
+ raise RuleRefused("rule_missing", f"the rule has no {name} code")
501
+ return source
502
+
503
+
504
+ def _as_rows(rows: Any) -> list[dict[str, Any]]:
505
+ if not isinstance(rows, list) or not all(isinstance(row, dict) for row in rows):
506
+ raise RuleRefused("derive_invalid", "a derive returns a list of JSON objects")
507
+ try:
508
+ [canonical(row) for row in rows]
509
+ except TypeError:
510
+ raise RuleRefused("derive_invalid", "a derived row is not JSON-serialisable")
511
+ return rows
512
+
513
+
514
+ class Change:
515
+ @staticmethod
516
+ def of(raw: Any) -> dict[str, Any]:
517
+ change = dict(raw or {})
518
+ change.setdefault("by", dict(DEFAULT_BY))
519
+ return change
520
+
521
+
522
+ class Batch:
523
+ def __init__(self, jobs: list["Job"], job_seconds: float) -> None:
524
+ self.jobs = jobs
525
+ self.job_seconds = job_seconds
526
+
527
+ @classmethod
528
+ def parse(cls, payload: Any) -> "Batch":
529
+ cls._require(isinstance(payload, dict), "the input is not an object")
530
+ cls._require(payload.get("version") == VERSION, "unsupported input version")
531
+ cls._require(isinstance(payload.get("rules", {}), dict), "rules is not an object")
532
+ cls._require(isinstance(payload.get("spine", {}), dict), "spine is not an object")
533
+ cls._require(isinstance(payload.get("jobs"), list), "jobs is not a list")
534
+ codes = payload.get("rules") or {}
535
+ cls._require(all(isinstance(code, dict) for code in codes.values()), "a rule is not an object")
536
+ seed = str(payload.get("seed", ""))
537
+ rules = {rid: Rule(rid, code) for rid, code in codes.items()}
538
+ context = BatchContext(seed, rules, dict(payload.get("spine") or {}))
539
+ jobs = [Job.of(job, context) for job in payload["jobs"]]
540
+ return cls(jobs, cls._seconds(payload.get("limits")))
541
+
542
+ @staticmethod
543
+ def _require(ok: bool, message: str) -> None:
544
+ if not ok:
545
+ raise InputInvalid(message)
546
+
547
+ @staticmethod
548
+ def _seconds(limits: Any) -> float:
549
+ wanted = (limits or {}).get("jobSeconds") if isinstance(limits, dict) else None
550
+ return float(wanted) if isinstance(wanted, (int, float)) and wanted > 0 else DEFAULT_JOB_SECONDS
551
+
552
+
553
+ class BatchContext:
554
+ def __init__(self, seed: str, rules: dict[str, Rule], spine: dict[str, Any]) -> None:
555
+ self.seed = seed
556
+ self._rules = rules
557
+ self.spine = spine
558
+
559
+ def rule(self, rule_id: Any) -> Rule:
560
+ rule = self._rules.get(rule_id)
561
+ if rule is None:
562
+ raise RuleRefused("rule_missing", f"no rule {rule_id} in this factory")
563
+ return rule
564
+
565
+ def view(self, payload: Any, rule_id: str) -> View:
566
+ merged = dict(payload or {})
567
+ merged["spine"] = {**self.spine, **(merged.get("spine") or {})}
568
+ return View.of(merged, self.seed, rule_id)
569
+
570
+
571
+ class Job:
572
+ """Every job starts from the decimal context the executor started with, so no job reads another's."""
573
+
574
+ def __init__(self, spec: dict[str, Any], context: BatchContext) -> None:
575
+ self._spec = spec
576
+ self._context = context
577
+ self.id = spec.get("id")
578
+ self.result_cap = RESULT_CAPS.get(spec.get("kind"), RESULT_CAP_BYTES)
579
+
580
+ @classmethod
581
+ def of(cls, spec: Any, context: BatchContext) -> "Job":
582
+ if not isinstance(spec, dict):
583
+ raise InputInvalid("a job is not an object")
584
+ subclass = _JOB_KINDS.get(spec.get("kind"))
585
+ if subclass is None:
586
+ raise InputInvalid(f"unknown job kind {spec.get('kind')!r}")
587
+ if not _seconds_valid(spec.get("seconds")):
588
+ raise InputInvalid(f"a job's seconds is a number above 0 and at most {MAX_JOB_SECONDS}")
589
+ return subclass(spec, context)
590
+
591
+ def budget(self, batch_seconds: float) -> float:
592
+ seconds = self._spec.get("seconds")
593
+ return batch_seconds if seconds is None else float(seconds)
594
+
595
+ def run(self, seconds: float) -> dict[str, Any]:
596
+ decimal.setcontext(_DECIMAL_CONTEXT.copy())
597
+ try:
598
+ with _deadline(seconds):
599
+ result = self._run()
600
+ except RuleRefused as refused:
601
+ return {"id": self.id, "status": "error", "error": refused.as_error()}
602
+ return {"id": self.id, **self._extend(result, seconds)}
603
+
604
+ def _run(self) -> dict[str, Any]:
605
+ raise NotImplementedError
606
+
607
+ def _extend(self, result: dict[str, Any], _seconds: float) -> dict[str, Any]:
608
+ return result
609
+
610
+
611
+ def _seconds_valid(seconds: Any) -> bool:
612
+ if seconds is None:
613
+ return True
614
+ return isinstance(seconds, (int, float)) and not isinstance(seconds, bool) and 0 < seconds <= MAX_JOB_SECONDS
615
+
616
+
617
+ class GuardJob(Job):
618
+ def _run(self) -> dict[str, Any]:
619
+ rule = self._context.rule(self._spec.get("rule"))
620
+ view = self._context.view(self._spec.get("view"), rule.id)
621
+ change = Change.of(self._spec.get("change"))
622
+ return rule.guard(view, change).result()
623
+
624
+
625
+ class DeriveJob(Job):
626
+ def _run(self) -> dict[str, Any]:
627
+ rule = self._context.rule(self._spec.get("rule"))
628
+ view = self._context.view(self._spec.get("view"), rule.id)
629
+ change = Change.of(self._spec.get("change"))
630
+ return {"status": "ok", "rows": rule.derive(view, change)}
631
+
632
+
633
+ class RuleUnitJob(Job):
634
+ """The cases run under the job's budget; the mutants under a budget of their
635
+ own, so a mutant can never turn a passing test into a failure."""
636
+
637
+ def _run(self) -> dict[str, Any]:
638
+ rule = self._context.rule(self._test().get("rule"))
639
+ reports = [self._case(rule, case) for case in self._cases()]
640
+ passed = all(report["status"] == "pass" for report in reports)
641
+ return {"status": "passed" if passed else "failed", "cases": reports}
642
+
643
+ def _extend(self, result: dict[str, Any], seconds: float) -> dict[str, Any]:
644
+ if not self._spec.get("mutants") or result["status"] != "passed":
645
+ return result
646
+ rule = self._context.rule(self._test().get("rule"))
647
+ mutation = MutationRun(rule, self._cases(), self._passes)
648
+ return {**result, "mutants": mutation.within(seconds)}
649
+
650
+ def _test(self) -> dict[str, Any]:
651
+ return self._spec.get("spec") or {}
652
+
653
+ def _cases(self) -> list[dict[str, Any]]:
654
+ return self._test().get("cases") or []
655
+
656
+ def _case(self, rule: Rule, case: dict[str, Any]) -> dict[str, Any]:
657
+ try:
658
+ return {"name": case.get("name"), "status": "pass" if self._passes(rule, case) else "fail"}
659
+ except RuleRefused as refused:
660
+ return {"name": case.get("name"), "status": "fail", "detail": refused.as_error()}
661
+
662
+ def _passes(self, rule: Rule, case: dict[str, Any], sources: dict[str, str] | None = None) -> bool:
663
+ view = self._context.view(case, rule.id)
664
+ change = Change.of(case.get("change"))
665
+ checker = self._checker(case)
666
+ return checker(rule, view, change, case, sources or {})
667
+
668
+ def _checker(self, case: dict[str, Any]) -> Callable[..., bool]:
669
+ if "expect" in case:
670
+ return _check_guard
671
+ if "derived" in case:
672
+ return _check_derive
673
+ raise RuleRefused("case_empty", "a case has neither expect nor derived")
674
+
675
+
676
+ def _check_guard(rule: Rule, view: View, change: dict[str, Any], case: dict[str, Any], sources: dict[str, str]) -> bool:
677
+ verdict = rule.guard(view, change, sources.get("guard"))
678
+ if case["expect"] == "ok":
679
+ return verdict.status == "ok"
680
+ return verdict.status == "deny" and _reason_matches(verdict.reason, case.get("reason"))
681
+
682
+
683
+ def _check_derive(
684
+ rule: Rule, view: View, change: dict[str, Any], case: dict[str, Any], sources: dict[str, str]
685
+ ) -> bool:
686
+ produced = rule.derive(view, change, sources.get("derive"))
687
+ return _multiset(produced) == _multiset(case["derived"])
688
+
689
+
690
+ def _reason_matches(reason: str | None, needle: str | None) -> bool:
691
+ return needle is None or (reason is not None and needle in reason)
692
+
693
+
694
+ def _multiset(rows: list[dict[str, Any]]) -> list[str]:
695
+ return sorted(canonical(row) for row in rows)
696
+
697
+
698
+ _CMP = {
699
+ ast.Lt: ("<", ast.LtE, "<="),
700
+ ast.LtE: ("<=", ast.Lt, "<"),
701
+ ast.Gt: (">", ast.GtE, ">="),
702
+ ast.GtE: (">=", ast.Gt, ">"),
703
+ ast.Eq: ("==", ast.NotEq, "!="),
704
+ ast.NotEq: ("!=", ast.Eq, "=="),
705
+ }
706
+ _BOOL = {ast.And: ("and", ast.Or, "or"), ast.Or: ("or", ast.And, "and")}
707
+ _BIN = {ast.Add: ("+", ast.Sub, "-"), ast.Sub: ("-", ast.Add, "+")}
708
+ _MUTANT_CAP = 12
709
+
710
+
711
+ class MutationRun:
712
+ def __init__(self, rule: Rule, cases: list[dict[str, Any]], passes: Callable[..., bool]) -> None:
713
+ self._rule = rule
714
+ self._cases = cases
715
+ self._passes = passes
716
+ self._completed = 0
717
+ self._survived: list[dict[str, Any]] = []
718
+
719
+ def within(self, seconds: float) -> dict[str, Any]:
720
+ try:
721
+ with _deadline(seconds):
722
+ self._evaluate()
723
+ except JobTimeout:
724
+ return {"run": self._completed, "survived": self._survived, "incomplete": True}
725
+ return {"run": self._completed, "survived": self._survived}
726
+
727
+ def _evaluate(self) -> None:
728
+ for mutant in self._mutants():
729
+ survived = self._survives(mutant)
730
+ self._completed += 1
731
+ if survived:
732
+ self._survived.append(mutant["survived"])
733
+
734
+ def _mutants(self) -> Iterable[dict[str, Any]]:
735
+ planned = [
736
+ (name, source, index) for name, source in self._exercised() for index in range(len(_mutation_sites(source)))
737
+ ]
738
+ return (self._mutant(*site) for site in planned[:_MUTANT_CAP])
739
+
740
+ def _exercised(self) -> list[tuple[str, str]]:
741
+ parts = (("expect", "guard", self._rule.guard_source()), ("derived", "derive", self._rule.derive_source()))
742
+ return [
743
+ (name, source)
744
+ for key, name, source in parts
745
+ if source is not None and any(key in case for case in self._cases)
746
+ ]
747
+
748
+ def _mutant(self, name: str, source: str, index: int) -> dict[str, Any]:
749
+ mutated, line, change = _apply_mutation(source, index)
750
+ return {"name": name, "source": mutated, "survived": {"rule": self._rule.id, "line": line, "change": change}}
751
+
752
+ def _survives(self, mutant: dict[str, Any]) -> bool:
753
+ sources = {mutant["name"]: mutant["source"]}
754
+ return all(self._passes_safely(case, sources) for case in self._cases)
755
+
756
+ def _passes_safely(self, case: dict[str, Any], sources: dict[str, str]) -> bool:
757
+ try:
758
+ return self._passes(self._rule, case, sources)
759
+ except RuleRefused:
760
+ return False
761
+
762
+
763
+ def _mutation_sites(source: str) -> list[tuple[ast.AST, str, int | None]]:
764
+ return list(_ops(ast.parse(source)))
765
+
766
+
767
+ def _ops(tree: ast.AST) -> Iterable[tuple[ast.AST, str, int | None]]:
768
+ for node in ast.walk(tree):
769
+ yield from _node_ops(node)
770
+
771
+
772
+ def _node_ops(node: ast.AST) -> Iterable[tuple[ast.AST, str, int | None]]:
773
+ if isinstance(node, ast.Compare):
774
+ return [(node, "cmp", index) for index, op in enumerate(node.ops) if type(op) in _CMP]
775
+ if isinstance(node, ast.BoolOp) and type(node.op) in _BOOL:
776
+ return [(node, "bool", None)]
777
+ if isinstance(node, ast.BinOp) and type(node.op) in _BIN:
778
+ return [(node, "bin", None)]
779
+ return []
780
+
781
+
782
+ def _apply_mutation(source: str, index: int) -> tuple[str, int, str]:
783
+ tree = ast.parse(source)
784
+ node, kind, position = list(_ops(tree))[index]
785
+ change = _MUTATORS[kind](node, position)
786
+ ast.fix_missing_locations(tree)
787
+ return ast.unparse(tree), node.lineno, change
788
+
789
+
790
+ def _mutate_cmp(node: ast.Compare, position: int | None) -> str:
791
+ original, replacement, symbol = _CMP[type(node.ops[position])]
792
+ node.ops[position] = replacement()
793
+ return f"`{original}` → `{symbol}`"
794
+
795
+
796
+ def _mutate_bool(node: ast.BoolOp, _position: int | None) -> str:
797
+ original, replacement, symbol = _BOOL[type(node.op)]
798
+ node.op = replacement()
799
+ return f"`{original}` → `{symbol}`"
800
+
801
+
802
+ def _mutate_bin(node: ast.BinOp, _position: int | None) -> str:
803
+ original, replacement, symbol = _BIN[type(node.op)]
804
+ node.op = replacement()
805
+ return f"`{original}` → `{symbol}`"
806
+
807
+
808
+ _MUTATORS: dict[str, Callable[[Any, int | None], str]] = {
809
+ "cmp": _mutate_cmp,
810
+ "bool": _mutate_bool,
811
+ "bin": _mutate_bin,
812
+ }
813
+
814
+
815
+ class ChronicleJob(Job):
816
+ def _run(self) -> dict[str, Any]:
817
+ spec = self._spec.get("spec") or {}
818
+ if spec.get("cases"):
819
+ return self._cases(spec)
820
+ return self._against(spec, self._spec.get("statements") or [])
821
+
822
+ def _against(self, spec: dict[str, Any], statements: list[dict[str, Any]]) -> dict[str, Any]:
823
+ violations = _SPINE.Chronicle(spec).violations(statements)
824
+ return {"status": "passed" if not violations else "failed", "violations": violations}
825
+
826
+ def _cases(self, spec: dict[str, Any]) -> dict[str, Any]:
827
+ chronicle = _SPINE.Chronicle(spec)
828
+ reports = [self._case(chronicle, case) for case in spec["cases"]]
829
+ passed = all(report["status"] == "pass" for report in reports)
830
+ return {"status": "passed" if passed else "failed", "cases": reports}
831
+
832
+ def _case(self, chronicle: Any, case: dict[str, Any]) -> dict[str, Any]:
833
+ violated = bool(chronicle.violations(case.get("statements") or []))
834
+ expected_fail = case.get("expect") == "fail"
835
+ return {"name": case.get("name"), "status": "pass" if violated == expected_fail else "fail"}
836
+
837
+
838
+ class SpineJob(Job):
839
+ def _run(self) -> dict[str, Any]:
840
+ work = _SPINE.JOBS[self._spec.get("kind")]
841
+ try:
842
+ return work(self._spec, SpineRuntime(), self._context).run()
843
+ except _SPINE.SpineRefused as refused:
844
+ raise RuleRefused(refused.type, refused.message, refused.line) from None
845
+
846
+
847
+ _JOB_KINDS: dict[Any, type[Job]] = {
848
+ "guard": GuardJob,
849
+ "derive": DeriveJob,
850
+ "rule_unit": RuleUnitJob,
851
+ "chronicle": ChronicleJob,
852
+ **dict.fromkeys(_SPINE.JOBS, SpineJob),
853
+ }
854
+
855
+
856
+ class Executor:
857
+ def __init__(self, input_path: str, output_path: str) -> None:
858
+ self._input = input_path
859
+ self._output = output_path
860
+
861
+ def run(self) -> None:
862
+ _confine()
863
+ raw, error = self._read()
864
+ handle = open(self._output, "w", encoding="utf-8")
865
+ try:
866
+ _SENTRY.arm()
867
+ handle.write(canonical(self._outcome(raw, error)))
868
+ finally:
869
+ handle.close()
870
+
871
+ def _outcome(self, raw: Any, error: str | None) -> dict[str, Any]:
872
+ if error is not None:
873
+ return {"version": VERSION, "error": {"type": "input_invalid", "message": error}}
874
+ try:
875
+ batch = Batch.parse(raw)
876
+ except InputInvalid as invalid:
877
+ return {"version": VERSION, "error": {"type": "input_invalid", "message": invalid.message}}
878
+ return {"version": VERSION, "results": [self._result(job, job.budget(batch.job_seconds)) for job in batch.jobs]}
879
+
880
+ def _read(self) -> tuple[Any, str | None]:
881
+ try:
882
+ with open(self._input, encoding="utf-8") as handle:
883
+ return json.load(handle), None
884
+ except (OSError, ValueError) as error:
885
+ return None, f"the input is not readable JSON: {error}"
886
+
887
+ def _result(self, job: Job, seconds: float) -> dict[str, Any]:
888
+ return _capped(self._guarded(job, seconds), job.result_cap)
889
+
890
+ def _guarded(self, job: Job, seconds: float) -> dict[str, Any]:
891
+ try:
892
+ return job.run(seconds)
893
+ except JobTimeout:
894
+ return {
895
+ "id": job.id,
896
+ "status": "error",
897
+ "error": {"type": "timeout", "message": "the job exceeded its time budget"},
898
+ }
899
+ except BaseException as error: # noqa: BLE001 - SystemExit from a rule would leave the output file empty
900
+ return {"id": job.id, "status": "error", "error": {"type": "job_error", "message": str(error)[:500]}}
901
+
902
+
903
+ def _capped(result: dict[str, Any], cap: int) -> dict[str, Any]:
904
+ if len(canonical(result).encode("utf-8")) <= cap:
905
+ return result
906
+ return {
907
+ "id": result.get("id"),
908
+ "status": "error",
909
+ "error": {"type": "result_too_large", "message": f"the result exceeds {cap // MIB} MiB"},
910
+ }
911
+
912
+
913
+ class _deadline:
914
+ """A per-job wall-clock budget through ``SIGALRM``; a no-op where the signal is unavailable (a non-main
915
+ thread). Once it fires it fires again every ``REFIRE_SECONDS`` until the job unwinds, and a job that leaves
916
+ after it fired leaves with ``JobTimeout`` however its code handled the first one."""
917
+
918
+ REFIRE_SECONDS = 0.05
919
+
920
+ def __init__(self, seconds: float) -> None:
921
+ self._seconds = seconds
922
+ self.fired = False
923
+
924
+ def __enter__(self) -> "_deadline":
925
+ try:
926
+ signal.signal(signal.SIGALRM, self._fire)
927
+ signal.setitimer(signal.ITIMER_REAL, self._seconds, self.REFIRE_SECONDS)
928
+ except (ValueError, AttributeError):
929
+ pass
930
+ return self
931
+
932
+ def __exit__(self, exc_type: Any, *_exc: Any) -> None:
933
+ try:
934
+ signal.setitimer(signal.ITIMER_REAL, 0)
935
+ except (ValueError, AttributeError):
936
+ pass
937
+ if self.fired and exc_type is not JobTimeout:
938
+ raise JobTimeout()
939
+
940
+ def _fire(self, _signum: int, _frame: Any) -> None:
941
+ self.fired = True
942
+ raise JobTimeout()
943
+
944
+
945
+ def _confine() -> None:
946
+ os.environ["TZ"] = "UTC"
947
+ _call(time.tzset)
948
+ _limit_address_space()
949
+
950
+
951
+ def _limit_address_space() -> None:
952
+ if resource is None:
953
+ return
954
+ try:
955
+ resource.setrlimit(resource.RLIMIT_AS, (ADDRESS_SPACE_BYTES, ADDRESS_SPACE_BYTES))
956
+ except (ValueError, OSError):
957
+ pass
958
+
959
+
960
+ def _call(fn: Callable[[], Any]) -> None:
961
+ try:
962
+ fn()
963
+ except Exception:
964
+ pass
965
+
966
+
967
+ def main(argv: list[str]) -> int:
968
+ Executor(argv[1], argv[2]).run()
969
+ return 0
970
+
971
+
972
+ if __name__ == "__main__":
973
+ raise SystemExit(main(sys.argv))