@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,1155 @@
1
+ """The spine's executor jobs and the chronicle's statement checks. Copied into the rule sandbox beside the rule
2
+ executor, so it imports only the standard library and nothing relative. It never compiles code itself: every formula
3
+ and function runs through the ``runtime`` it is handed (``evaluate(expression, names)``, ``call(function, source,
4
+ *args)``), which owns the sandbox. A job is built from its spec, that runtime and the batch (``seed``, ``spine``,
5
+ ``view(payload, rule_id)``)."""
6
+
7
+ # file limit exception: the sandbox loads this as the executor's one sibling; a split adds a loader and a file
8
+
9
+ from __future__ import annotations
10
+
11
+ import copy
12
+ import datetime
13
+ import hashlib
14
+ import json
15
+ import math
16
+ import random
17
+ import re
18
+ from fractions import Fraction
19
+ from typing import Any, Callable, Iterable
20
+
21
+ FORMS = ("copy", "formula", "literal", "from")
22
+ REF_KINDS = frozenset("node row world schema object statement file".split())
23
+ DEFAULT_WEEKEND = (5, 6)
24
+ WEEKDAYS = ("Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday")
25
+ DATE = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}")
26
+ INSTANT = re.compile(
27
+ 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]"
28
+ r"(:[0-5][0-9](\.[0-9]+)?)?(Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])"
29
+ )
30
+ ARRAY_INDEX = re.compile(r"0|[1-9][0-9]*")
31
+ SAFE_INTEGER = 2**53
32
+ SHORT = 120
33
+ MESSAGE = 500
34
+ WARN = frozenset({"copy_differs", "step_off_day"})
35
+ OWNER_BY = {"principal": "user:fixture", "unit": None}
36
+
37
+
38
+ class SeededStream(random.Random):
39
+ """The only randomness rule and spine code get: reseeding it without a value would draw from the host."""
40
+
41
+ def seed(self, a: Any = None, version: int = 2) -> None:
42
+ if a is None:
43
+ raise SpineRefused("clock_refused", "a stream reseeds only from a value it is given")
44
+ super().seed(a, version)
45
+
46
+
47
+ class SpineRefused(Exception):
48
+ def __init__(self, type: str, message: str, line: int | None = None) -> None:
49
+ super().__init__(message)
50
+ self.type = type
51
+ self.message = message
52
+ self.line = line
53
+
54
+ def as_error(self) -> dict[str, Any]:
55
+ error: dict[str, Any] = {"type": self.type, "message": self.message}
56
+ if self.line is not None:
57
+ error["line"] = self.line
58
+ return error
59
+
60
+
61
+ class Unresolved(Exception):
62
+ pass
63
+
64
+
65
+ class Shape(Exception):
66
+ pass
67
+
68
+
69
+ def canonical(value: Any) -> str:
70
+ return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
71
+
72
+
73
+ def short(value: Any) -> str:
74
+ text = canonical(value)
75
+ return text if len(text) <= SHORT else text[: SHORT - 1] + "…"
76
+
77
+
78
+ def as_json(value: Any) -> Any:
79
+ """A Python value as JavaScript reads it back, so both sides compare the same thing: 10 / 2 is 5."""
80
+ return json.loads(json.dumps(value, allow_nan=False), parse_float=_js_number)
81
+
82
+
83
+ def _js_number(text: str) -> Any:
84
+ number = float(text)
85
+ return int(number) if number.is_integer() and abs(number) < SAFE_INTEGER else number
86
+
87
+
88
+ _JS_STRINGS: dict[type, Callable[[Any], str]] = {
89
+ bool: lambda value: "true" if value else "false",
90
+ float: lambda value: str(int(value)) if value.is_integer() else repr(value),
91
+ type(None): lambda value: "null",
92
+ }
93
+
94
+
95
+ def js_string(value: Any) -> str:
96
+ """``String(value)`` as the TypeScript side computes it, so keys compare the same on both sides."""
97
+ return _JS_STRINGS.get(type(value), str)(value)
98
+
99
+
100
+ class Exact:
101
+ """Numbers as exact fractions of the decimals they were written as, so 0.1 + 0.2 closes against 0.3."""
102
+
103
+ @staticmethod
104
+ def is_number(value: Any) -> bool:
105
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
106
+ return False
107
+ return not isinstance(value, float) or math.isfinite(value)
108
+
109
+ @staticmethod
110
+ def of(value: Any) -> Fraction:
111
+ if not Exact.is_number(value):
112
+ raise TypeError(f"{short(value)} is not a number")
113
+ return Fraction(repr(value)) if isinstance(value, float) else Fraction(value)
114
+
115
+ @staticmethod
116
+ def number(value: Any, field: str) -> Fraction:
117
+ if not Exact.is_number(value):
118
+ raise Shape(f"{field} is not a number")
119
+ return Exact.of(value)
120
+
121
+ @staticmethod
122
+ def parts(value: Any, field: str, noun: str = "a list or a map of numbers") -> list[Fraction]:
123
+ items = list(value.values()) if isinstance(value, dict) else value
124
+ if not isinstance(items, list) or not all(Exact.is_number(item) for item in items):
125
+ raise Shape(f"{field} is not {noun}")
126
+ return [Exact.of(item) for item in items]
127
+
128
+
129
+ def show(number: Fraction) -> str:
130
+ return str(number.numerator) if number.denominator == 1 else repr(float(number))
131
+
132
+
133
+ class Calendar:
134
+ @staticmethod
135
+ def date(value: Any) -> datetime.date | None:
136
+ return Calendar._day(value, DATE)
137
+
138
+ @staticmethod
139
+ def instant(value: Any) -> datetime.date | None:
140
+ return Calendar._day(value, INSTANT)
141
+
142
+ @staticmethod
143
+ def day(value: Any) -> datetime.date | None:
144
+ return Calendar.date(value) or Calendar.instant(value)
145
+
146
+ @staticmethod
147
+ def _day(value: Any, pattern: re.Pattern[str]) -> datetime.date | None:
148
+ if not isinstance(value, str) or not pattern.fullmatch(value):
149
+ return None
150
+ try:
151
+ return datetime.date(int(value[:4]), int(value[5:7]), int(value[8:10]))
152
+ except ValueError:
153
+ return None
154
+
155
+
156
+ class Formulas:
157
+ @staticmethod
158
+ def largest_remainder(total: Any, weights: Any) -> Any:
159
+ keys, values = Formulas._weights(weights)
160
+ whole = Formulas._whole(total)
161
+ exact = [Exact.of(weight) for weight in values]
162
+ if any(weight < 0 for weight in exact):
163
+ raise ValueError("a weight is negative")
164
+ if sum(exact) == 0:
165
+ raise ValueError("the weights sum to zero")
166
+ shares = [whole * weight / sum(exact) for weight in exact]
167
+ split = [math.floor(share) for share in shares]
168
+ order = sorted(range(len(shares)), key=lambda i: (split[i] - shares[i], i))
169
+ for index in order[: whole - sum(split)]:
170
+ split[index] += 1
171
+ return split if keys is None else dict(zip(keys, split))
172
+
173
+ @staticmethod
174
+ def lookup(rows: Any, column: str, **where: Any) -> Any:
175
+ return next((row.get(column) for row in Formulas._matching(rows, where)), None)
176
+
177
+ @staticmethod
178
+ def count(rows: Any, **where: Any) -> int:
179
+ return sum(1 for _ in Formulas._matching(rows, where))
180
+
181
+ @staticmethod
182
+ def total(rows: Any, column: str, **where: Any) -> Any:
183
+ values = (row.get(column) for row in Formulas._matching(rows, where))
184
+ return sum(value for value in values if value is not None)
185
+
186
+ @staticmethod
187
+ def working_day(date: Any, holidays: Iterable[Any] = (), weekend: Iterable[int] = DEFAULT_WEEKEND) -> bool:
188
+ day = Calendar.day(date)
189
+ if day is None:
190
+ raise ValueError(f"{short(date)} is not a date")
191
+ return day.weekday() not in weekend and day not in {Calendar.day(holiday) for holiday in holidays}
192
+
193
+ @classmethod
194
+ def names(cls) -> dict[str, Callable[..., Any]]:
195
+ return {name: getattr(cls, name) for name in ("largest_remainder", "lookup", "count", "total", "working_day")}
196
+
197
+ @staticmethod
198
+ def _weights(weights: Any) -> tuple[list[str] | None, list[Any]]:
199
+ if isinstance(weights, dict):
200
+ return sorted(weights), [weights[key] for key in sorted(weights)]
201
+ if not isinstance(weights, (list, tuple)):
202
+ raise TypeError("the weights are a list or a map of numbers")
203
+ return None, list(weights)
204
+
205
+ @staticmethod
206
+ def _whole(total: Any) -> int:
207
+ exact = Exact.of(total)
208
+ if exact.denominator != 1:
209
+ raise ValueError(f"largest_remainder splits a whole total, not {short(total)}")
210
+ return exact.numerator
211
+
212
+ @staticmethod
213
+ def _matching(rows: Any, where: dict[str, Any]) -> Iterable[dict[str, Any]]:
214
+ listed = rows.get("rows") if isinstance(rows, dict) else rows
215
+ if not isinstance(listed, list):
216
+ raise TypeError("rows is a list of rows or a table")
217
+ return (row for row in listed if isinstance(row, dict) and all(row.get(k) == v for k, v in where.items()))
218
+
219
+
220
+ def _step_list(value: list[Any], token: str) -> Any:
221
+ if not ARRAY_INDEX.fullmatch(token):
222
+ raise LookupError(token)
223
+ return value[int(token)]
224
+
225
+
226
+ _POINTER_STEPS: dict[type, Callable[[Any, str], Any]] = {dict: lambda value, token: value[token], list: _step_list}
227
+
228
+
229
+ class Pointer:
230
+ def __init__(self, text: str) -> None:
231
+ if text and not text.startswith("/"):
232
+ raise Unresolved(f"{text} is not a JSON pointer")
233
+ self.text = text
234
+ self.tokens = [token.replace("~1", "/").replace("~0", "~") for token in text.split("/")[1:]]
235
+
236
+ def first(self) -> str | None:
237
+ return self.tokens[0] if self.tokens else None
238
+
239
+ def read(self, value: Any, label: str, skip: int = 0) -> Any:
240
+ try:
241
+ for token in self.tokens[skip:]:
242
+ value = _POINTER_STEPS[type(value)](value, token)
243
+ except LookupError:
244
+ raise Unresolved(f"{label} has nothing at {self.text}") from None
245
+ return value
246
+
247
+
248
+ class Outcome:
249
+ """A resolved value, and whether it stands: a value downstream of a failure is null, told once at its root."""
250
+
251
+ __slots__ = ("value", "ok")
252
+
253
+ def __init__(self, value: Any, ok: bool = True) -> None:
254
+ self.value = value
255
+ self.ok = ok
256
+
257
+ @staticmethod
258
+ def mapping(outcomes: dict[str, "Outcome"]) -> "Outcome":
259
+ return Outcome({key: o.value for key, o in outcomes.items()}, all(o.ok for o in outcomes.values()))
260
+
261
+ @staticmethod
262
+ def listing(outcomes: list["Outcome"]) -> "Outcome":
263
+ return Outcome([o.value for o in outcomes], all(o.ok for o in outcomes))
264
+
265
+
266
+ FAILED = Outcome(None, False)
267
+
268
+
269
+ class Place:
270
+ """Where a value lives, which is where its issues are told and how they sort."""
271
+
272
+ __slots__ = ("node", "check", "row", "key", "column", "rank")
273
+
274
+ def __init__(
275
+ self,
276
+ node: str,
277
+ check: int | None = None,
278
+ row: int = -1,
279
+ key: str | None = None,
280
+ column: str | None = None,
281
+ rank: int = -1,
282
+ ) -> None:
283
+ self.node = node
284
+ self.check = check
285
+ self.row = row
286
+ self.key = key
287
+ self.column = column
288
+ self.rank = rank
289
+
290
+ def at(self, row: int, key: str, column: str) -> "Place":
291
+ return Place(self.node, self.check, row, key, column)
292
+
293
+ def order(self) -> tuple[Any, ...]:
294
+ if self.check is None:
295
+ return (self.node, 0, self.row, self.rank)
296
+ return (self.node, 1, self.check, self.row)
297
+
298
+
299
+ class IssueLog:
300
+ def __init__(self) -> None:
301
+ self._issues: list[tuple[tuple[Any, ...], int, dict[str, Any]]] = []
302
+
303
+ def add(self, place: Place, type: str, code: str, message: str, severity: str | None = None) -> None:
304
+ issue: dict[str, Any] = {
305
+ "node": place.node,
306
+ "check": place.check,
307
+ "type": type,
308
+ "code": code,
309
+ "severity": severity or ("warn" if code in WARN else "block"),
310
+ "message": message[:MESSAGE],
311
+ }
312
+ if place.key is not None:
313
+ issue["key"] = place.key
314
+ if place.column is not None:
315
+ issue["column"] = place.column
316
+ self._issues.append((place.order(), len(self._issues), issue))
317
+
318
+ def json(self) -> list[dict[str, Any]]:
319
+ return [issue for _, _, issue in sorted(self._issues, key=lambda entry: entry[:2])]
320
+
321
+
322
+ class Target:
323
+ """What a read lands on: a unit to resolve or a value at hand, then the rest of its pointer."""
324
+
325
+ __slots__ = ("unit", "value", "pointer", "skip", "label")
326
+
327
+ def __init__(self, unit: tuple[Any, ...] | None, value: Any, pointer: Pointer, skip: int, label: str) -> None:
328
+ self.unit = unit
329
+ self.value = value
330
+ self.pointer = pointer
331
+ self.skip = skip
332
+ self.label = label
333
+
334
+ def outcome(self, resolver: "SpineResolver") -> Outcome:
335
+ found = resolver.unit(self.unit) if self.unit is not None else Outcome(self.value)
336
+ if not found.ok:
337
+ return found
338
+ return Outcome(self.pointer.read(found.value, self.label, self.skip))
339
+
340
+
341
+ class SpineTable:
342
+ def __init__(self, node_id: str, node: dict[str, Any]) -> None:
343
+ self.id = node_id
344
+ self._declared = node.get("columns") or []
345
+ self.columns = {column.get("name"): column for column in self._declared}
346
+ self._ranks = {name: rank for rank, name in enumerate(self.columns)}
347
+ self.key = node.get("key")
348
+ self.rows = sorted(node.get("rows") or [], key=self._key_of)
349
+ self.keys = [self._key_of(row) for row in self.rows]
350
+ self.index = {key: index for index, key in enumerate(self.keys)}
351
+ cells = enumerate(self.rows)
352
+ self.derived = [
353
+ (index, column) for index, row in cells for column, cell in row.items() if Derivation.form_of(cell)
354
+ ]
355
+ self.derived_set = set(self.derived)
356
+
357
+ def _key_of(self, row: dict[str, Any]) -> str:
358
+ return js_string(row.get(self.key))
359
+
360
+ def place(self, index: int, column: str) -> Place:
361
+ rank = self._ranks.get(column, len(self._ranks))
362
+ return Place(self.id, row=index, key=self.keys[index], column=column, rank=rank)
363
+
364
+ def read(self, rows: list[dict[str, Any]]) -> dict[str, Any]:
365
+ return {"columns": self._declared, "key": self.key, "rows": rows}
366
+
367
+ def cell_target(self, index: int, column: str, pointer: Pointer, label: str) -> Target:
368
+ if (index, column) in self.derived_set:
369
+ return Target(("cell", self.id, index, column), None, pointer, 1, label)
370
+ return Target(None, self.rows[index].get(column), pointer, 1, label)
371
+
372
+
373
+ class SpineDocument:
374
+ def __init__(self, nodes: dict[str, dict[str, Any]], sources: dict[str, Any]) -> None:
375
+ self.nodes = nodes
376
+ self.sources = sources
377
+ self.tables = {key: SpineTable(key, node) for key, node in sorted(nodes.items()) if node.get("kind") == "table"}
378
+
379
+ @classmethod
380
+ def of(cls, spec: dict[str, Any]) -> "SpineDocument":
381
+ nodes, sources = spec.get("nodes"), spec.get("sources") or {}
382
+ if not isinstance(nodes, dict) or not all(isinstance(node, dict) for node in nodes.values()):
383
+ raise SpineRefused("spine_invalid", "nodes is not an object of spine nodes")
384
+ if not isinstance(sources, dict):
385
+ raise SpineRefused("spine_invalid", "sources is not an object")
386
+ return cls(nodes, sources)
387
+
388
+ def ids(self) -> list[str]:
389
+ return sorted(self.nodes)
390
+
391
+ def facts(self) -> list[str]:
392
+ return [node_id for node_id in self.ids() if self.nodes[node_id].get("kind") == "fact"]
393
+
394
+ def kind(self, node_id: Any) -> str | None:
395
+ node = self.nodes.get(node_id)
396
+ if node is not None:
397
+ return node.get("kind")
398
+ return "source" if node_id in self.sources else None
399
+
400
+ def row_ref_resolves(self, ref: Any) -> bool:
401
+ if not isinstance(ref, dict) or ref.get("kind") != "row" or not isinstance(ref.get("key"), str):
402
+ return False
403
+ table = self.tables.get(ref.get("node"))
404
+ return table is not None and ref["key"] in table.index
405
+
406
+
407
+ def _row_label(source: dict[str, Any]) -> str:
408
+ return f"{source.get('node')}/{source.get('key')}"
409
+
410
+
411
+ def _node_label(source: dict[str, Any]) -> str:
412
+ return str(source.get("id"))
413
+
414
+
415
+ _SOURCE_LABELS: dict[Any, Callable[[dict[str, Any]], str]] = {"row": _row_label}
416
+
417
+
418
+ class SourceRead:
419
+ """One read a derivation makes: a node or a row, narrowed by a column or a pointer."""
420
+
421
+ def __init__(self, raw: dict[str, Any]) -> None:
422
+ source = raw.get("from")
423
+ self._source = source if isinstance(source, dict) else {}
424
+ self._path = raw.get("path") or ""
425
+ self._column = raw.get("column")
426
+
427
+ def label(self) -> str:
428
+ return _SOURCE_LABELS.get(self._source.get("kind"), _node_label)(self._source)
429
+
430
+ def describe(self) -> str:
431
+ at = f" at {self._path}" if self._path else ""
432
+ column = f" column {self._column}" if self._column is not None else ""
433
+ return f"{self.label()}{at}{column}"
434
+
435
+ def target_or_none(self, document: SpineDocument) -> Target | None:
436
+ try:
437
+ return self.target(document)
438
+ except Unresolved:
439
+ return None
440
+
441
+ def target(self, document: SpineDocument) -> Target:
442
+ reader = _SOURCE_TARGETS.get(self._source.get("kind"))
443
+ if reader is None:
444
+ raise Unresolved("the source is not a node or a row")
445
+ return reader(self, document)
446
+
447
+ def _node(self, document: SpineDocument) -> Target:
448
+ node_id = self._source.get("id")
449
+ kind = document.kind(node_id)
450
+ if kind is None:
451
+ raise Unresolved(f"there is no node {node_id}")
452
+ if self._column is not None and kind != "table":
453
+ raise Unresolved(f"{node_id} is not a table, so it has no column {self._column}")
454
+ return _NODE_TARGETS[kind](self, document, node_id)
455
+
456
+ def _table(self, document: SpineDocument, node_id: str) -> Target:
457
+ if self._column is None:
458
+ return self.at(("table", node_id))
459
+ if self._column not in document.tables[node_id].columns:
460
+ raise Unresolved(f"{node_id} has no column {self._column}")
461
+ return self.at(("column", node_id, self._column))
462
+
463
+ def _row(self, document: SpineDocument) -> Target:
464
+ node_id, key = self._source.get("node"), self._source.get("key")
465
+ table = document.tables.get(node_id)
466
+ if table is None:
467
+ raise Unresolved(f"{node_id} is not a table")
468
+ if key not in table.index:
469
+ raise Unresolved(f"{node_id} has no row {key}")
470
+ if self._column is not None:
471
+ raise Unresolved(f"{node_id}/{key} is a row, not a table")
472
+ pointer = Pointer(self._path)
473
+ if pointer.first() not in table.columns:
474
+ return Target(("row", node_id, table.index[key]), None, pointer, 0, self.label())
475
+ return table.cell_target(table.index[key], pointer.first(), pointer, self.label())
476
+
477
+ def at(self, unit: tuple[Any, ...] | None, value: Any = None) -> Target:
478
+ return Target(unit, value, Pointer(self._path), 0, self.label())
479
+
480
+
481
+ _SOURCE_TARGETS: dict[Any, Callable[[SourceRead, SpineDocument], Target]] = {
482
+ "node": SourceRead._node,
483
+ "row": SourceRead._row,
484
+ }
485
+ _NODE_TARGETS: dict[str, Callable[[SourceRead, SpineDocument, str], Target]] = {
486
+ "table": SourceRead._table,
487
+ "fact": lambda read, _document, node_id: read.at(("fact", node_id)),
488
+ "check": lambda read, _document, _node_id: read.at(None, {}),
489
+ "source": lambda read, document, node_id: read.at(None, document.sources[node_id]),
490
+ }
491
+
492
+
493
+ class Derivation:
494
+ """A Value: plain JSON or a derivation. The TypeScript grammar guarantees each form's exact shape, and
495
+ detects forms in this order."""
496
+
497
+ def __init__(self, raw: Any) -> None:
498
+ self.raw = raw
499
+
500
+ @staticmethod
501
+ def form_of(value: Any) -> str | None:
502
+ if not isinstance(value, dict):
503
+ return None
504
+ return next((form for form in FORMS if form in value), None)
505
+
506
+ @staticmethod
507
+ def of(value: Any) -> "Derivation":
508
+ return _DERIVATIONS[Derivation.form_of(value)](value)
509
+
510
+ def reads(self) -> list[SourceRead]:
511
+ return []
512
+
513
+ def resolve(self, resolver: "SpineResolver", place: Place) -> Outcome:
514
+ return Outcome(self.raw)
515
+
516
+
517
+ class LiteralValue(Derivation):
518
+ def resolve(self, resolver: "SpineResolver", place: Place) -> Outcome:
519
+ return Outcome(self.raw["literal"])
520
+
521
+
522
+ class FromValue(Derivation):
523
+ def reads(self) -> list[SourceRead]:
524
+ return [SourceRead(self.raw)]
525
+
526
+ def resolve(self, resolver: "SpineResolver", place: Place) -> Outcome:
527
+ return resolver.read(SourceRead(self.raw), place)
528
+
529
+
530
+ class CopyValue(FromValue):
531
+ def resolve(self, resolver: "SpineResolver", place: Place) -> Outcome:
532
+ read = SourceRead(self.raw)
533
+ source = resolver.read(read, place)
534
+ copied = self.raw["copy"]
535
+ if source.ok and canonical(source.value) != canonical(copied):
536
+ message = f"the copy is {short(copied)}, but {read.describe()} is {short(source.value)}"
537
+ resolver.log.add(place, "copy", "copy_differs", message)
538
+ return Outcome(copied)
539
+
540
+
541
+ class FormulaValue(Derivation):
542
+ def _names(self) -> dict[str, Derivation]:
543
+ names = self.raw.get("with") or {}
544
+ return {name: Derivation.of(names[name]) for name in sorted(names)}
545
+
546
+ def reads(self) -> list[SourceRead]:
547
+ return [read for derivation in self._names().values() for read in derivation.reads()]
548
+
549
+ def resolve(self, resolver: "SpineResolver", place: Place) -> Outcome:
550
+ names = Outcome.mapping({name: d.resolve(resolver, place) for name, d in self._names().items()})
551
+ if not names.ok:
552
+ return FAILED
553
+ return resolver.formula(self.raw["formula"], names.value, place)
554
+
555
+
556
+ _DERIVATIONS: dict[str | None, type[Derivation]] = {
557
+ None: Derivation,
558
+ "copy": CopyValue,
559
+ "formula": FormulaValue,
560
+ "literal": LiteralValue,
561
+ "from": FromValue,
562
+ }
563
+
564
+
565
+ class DependencyOrder:
566
+ """Tarjan's strongly connected components, without recursion: a running balance over 20 000 rows is a
567
+ chain as deep as the table. Components come out dependencies first."""
568
+
569
+ def __init__(self, edges: Callable[[Any], list[Any]]) -> None:
570
+ self._edges = edges
571
+ self._index: dict[Any, int] = {}
572
+ self._low: dict[Any, int] = {}
573
+ self._stack: list[Any] = []
574
+ self._on_stack: set[Any] = set()
575
+ self._components: list[list[Any]] = []
576
+
577
+ def components(self, root: Any) -> list[list[Any]]:
578
+ work = [self._open(root)]
579
+ while work:
580
+ self._step(work)
581
+ return self._components
582
+
583
+ def _open(self, unit: Any) -> tuple[Any, Any]:
584
+ self._index[unit] = self._low[unit] = len(self._index)
585
+ self._stack.append(unit)
586
+ self._on_stack.add(unit)
587
+ return unit, iter(self._edges(unit))
588
+
589
+ def _step(self, work: list[tuple[Any, Any]]) -> None:
590
+ unit, children = work[-1]
591
+ child = next(children, None)
592
+ if child is None:
593
+ work.pop()
594
+ self._close(unit, work)
595
+ return
596
+ if child not in self._index:
597
+ work.append(self._open(child))
598
+ return
599
+ if child in self._on_stack:
600
+ self._low[unit] = min(self._low[unit], self._index[child])
601
+
602
+ def _close(self, unit: Any, work: list[tuple[Any, Any]]) -> None:
603
+ if work:
604
+ parent = work[-1][0]
605
+ self._low[parent] = min(self._low[parent], self._low[unit])
606
+ if self._low[unit] == self._index[unit]:
607
+ self._components.append(self._pop(unit))
608
+
609
+ def _pop(self, unit: Any) -> list[Any]:
610
+ component: list[Any] = []
611
+ while not component or component[-1] != unit:
612
+ top = self._stack.pop()
613
+ self._on_stack.discard(top)
614
+ component.append(top)
615
+ return component
616
+
617
+
618
+ class SpineResolver:
619
+ """Resolves each unit once, lazily, in dependency order: a fact or a derived cell (a value at its place), or a
620
+ whole table, column or row. Every value on a cycle is told as one; a reader of a failed value inherits its
621
+ null silently."""
622
+
623
+ def __init__(self, document: SpineDocument, runtime: Any, log: IssueLog) -> None:
624
+ self.document = document
625
+ self.log = log
626
+ self._runtime = runtime
627
+ self._memo: dict[tuple[Any, ...], Outcome] = {}
628
+ facts = {("fact", key): document.nodes[key].get("value") for key in document.facts()}
629
+ cells = {
630
+ ("cell", table.id, index, column): table.rows[index][column]
631
+ for table in document.tables.values()
632
+ for index, column in table.derived
633
+ }
634
+ self._located = {**facts, **cells}
635
+ self._aggregates = {
636
+ "table": (self._table_deps, self._table_value),
637
+ "column": (self._column_deps, self._column_value),
638
+ "row": (self._row_deps, self._row_value),
639
+ }
640
+
641
+ def unit(self, unit: tuple[Any, ...]) -> Outcome:
642
+ if unit not in self._memo:
643
+ for component in DependencyOrder(self._open_deps).components(unit):
644
+ self._settle(component)
645
+ return self._memo[unit]
646
+
647
+ def cell(self, table_id: str, index: int, column: str) -> Outcome:
648
+ table = self.document.tables[table_id]
649
+ if (index, column) in table.derived_set:
650
+ return self.unit(("cell", table_id, index, column))
651
+ return Outcome(table.rows[index].get(column))
652
+
653
+ def resolve(self, value: Any, place: Place) -> Outcome:
654
+ return Derivation.of(value).resolve(self, place)
655
+
656
+ def read(self, read: SourceRead, place: Place) -> Outcome:
657
+ try:
658
+ return read.target(self.document).outcome(self)
659
+ except Unresolved as unresolved:
660
+ return self._failed(place, "value_unresolved", str(unresolved))
661
+
662
+ def formula(self, text: str, names: dict[str, Any], place: Place) -> Outcome:
663
+ scope = {**Formulas.names(), **{name: as_json(value) for name, value in names.items()}}
664
+ try:
665
+ result = self._runtime.evaluate(text, scope)
666
+ except SpineRefused as refused:
667
+ return self._failed(place, "formula_failed", f"{refused.type}: {refused.message}")
668
+ except Exception as error:
669
+ return self._failed(place, "formula_failed", f"{type(error).__name__}: {error}")
670
+ try:
671
+ return Outcome(as_json(result))
672
+ except (TypeError, ValueError, RecursionError) as error:
673
+ return self._failed(place, "formula_failed", f"the result is not JSON: {error}")
674
+
675
+ def _failed(self, place: Place, code: str, message: str) -> Outcome:
676
+ self.log.add(place, "value", code, message)
677
+ return FAILED
678
+
679
+ def _deps_of(self, unit: tuple[Any, ...]) -> list[tuple[Any, ...]]:
680
+ if unit in self._located:
681
+ targets = (read.target_or_none(self.document) for read in Derivation.of(self._located[unit]).reads())
682
+ return [target.unit for target in targets if target is not None and target.unit is not None]
683
+ return self._aggregates[unit[0]][0](*unit[1:])
684
+
685
+ def _open_deps(self, unit: tuple[Any, ...]) -> list[tuple[Any, ...]]:
686
+ return [dep for dep in self._deps_of(unit) if dep not in self._memo]
687
+
688
+ def _settle(self, component: list[tuple[Any, ...]]) -> None:
689
+ first = component[0]
690
+ if len(component) == 1 and first not in self._deps_of(first):
691
+ self._memo[first] = self._value_of(first)
692
+ return
693
+ for unit in component:
694
+ self._memo[unit] = FAILED
695
+ self._cycle(unit)
696
+
697
+ def _value_of(self, unit: tuple[Any, ...]) -> Outcome:
698
+ if unit in self._located:
699
+ return self.resolve(self._located[unit], self._place(unit))
700
+ return self._aggregates[unit[0]][1](*unit[1:])
701
+
702
+ def _cycle(self, unit: tuple[Any, ...]) -> None:
703
+ if unit in self._located:
704
+ self.log.add(self._place(unit), "value", "value_cycle", "the value depends on itself")
705
+
706
+ def _place(self, unit: tuple[Any, ...]) -> Place:
707
+ return _PLACES[unit[0]](self.document, *unit[1:])
708
+
709
+ def _table_deps(self, table_id: str) -> list[tuple[Any, ...]]:
710
+ return [("cell", table_id, index, column) for index, column in self.document.tables[table_id].derived]
711
+
712
+ def _column_deps(self, table_id: str, column: str) -> list[tuple[Any, ...]]:
713
+ cells = self.document.tables[table_id].derived
714
+ return [("cell", table_id, index, name) for index, name in cells if name == column]
715
+
716
+ def _row_deps(self, table_id: str, index: int) -> list[tuple[Any, ...]]:
717
+ row = self.document.tables[table_id].rows[index]
718
+ return [("cell", table_id, index, column) for column in row if Derivation.form_of(row[column])]
719
+
720
+ def _table_value(self, table_id: str) -> Outcome:
721
+ table = self.document.tables[table_id]
722
+ rows = Outcome.listing([self._row_value(table_id, index) for index in range(len(table.rows))])
723
+ return Outcome(table.read(rows.value), rows.ok)
724
+
725
+ def _column_value(self, table_id: str, column: str) -> Outcome:
726
+ rows = range(len(self.document.tables[table_id].rows))
727
+ return Outcome.listing([self.cell(table_id, index, column) for index in rows])
728
+
729
+ def _row_value(self, table_id: str, index: int) -> Outcome:
730
+ row = self.document.tables[table_id].rows[index]
731
+ return Outcome.mapping({column: self.cell(table_id, index, column) for column in row})
732
+
733
+
734
+ _PLACES: dict[str, Callable[..., Place]] = {
735
+ "fact": lambda _document, node_id: Place(node_id),
736
+ "cell": lambda document, table_id, index, column: document.tables[table_id].place(index, column),
737
+ }
738
+
739
+
740
+ def _is_ref(value: Any) -> bool:
741
+ return isinstance(value, dict) and isinstance(value.get("kind"), str) and value["kind"] in REF_KINDS
742
+
743
+
744
+ _CELL_TYPES: dict[Any, tuple[Callable[[Any], bool], str]] = {
745
+ "string": (lambda value: isinstance(value, str), "a string"),
746
+ "integer": (lambda value: Exact.is_number(value) and (isinstance(value, int) or value.is_integer()), "an integer"),
747
+ "number": (Exact.is_number, "a number"),
748
+ "boolean": (lambda value: isinstance(value, bool), "true or false"),
749
+ "date": (lambda value: Calendar.date(value) is not None, "a date"),
750
+ "instant": (lambda value: Calendar.instant(value) is not None, "an instant"),
751
+ "ref": (_is_ref, "a factory ref"),
752
+ }
753
+ _ANY_TYPE: tuple[Callable[[Any], bool], str] = (lambda _value: True, "")
754
+
755
+
756
+ class CellChecks:
757
+ """Every resolved cell against its column: its type, the row a ref names, and the table its column refers to."""
758
+
759
+ def __init__(self, resolver: SpineResolver) -> None:
760
+ self._resolver = resolver
761
+ self._document = resolver.document
762
+
763
+ def run(self) -> None:
764
+ for table in self._document.tables.values():
765
+ for index in range(len(table.rows)):
766
+ for column in table.columns:
767
+ self._cell(table, index, column)
768
+
769
+ def _cell(self, table: SpineTable, index: int, column: str) -> None:
770
+ outcome = self._resolver.cell(table.id, index, column)
771
+ if not outcome.ok or outcome.value is None:
772
+ return
773
+ problem = self._problem(table.columns[column], outcome.value, f"row {table.keys[index]}: {column}")
774
+ if problem is not None:
775
+ self._resolver.log.add(table.place(index, column), "cell", *problem)
776
+
777
+ def _problem(self, spec: dict[str, Any], value: Any, where: str) -> tuple[str, str] | None:
778
+ valid, noun = _CELL_TYPES.get(spec.get("type"), _ANY_TYPE)
779
+ if not valid(value):
780
+ return "cell_type", f"{where} is {short(value)}, not {noun}"
781
+ if spec.get("type") == "ref" and value.get("kind") == "row" and not self._document.row_ref_resolves(value):
782
+ return "cell_ref_missing", f"{where} names {_row_label(value)}, which is not a row"
783
+ return self._refers(spec.get("ref"), value, where)
784
+
785
+ def _refers(self, target: Any, value: Any, where: str) -> tuple[str, str] | None:
786
+ if not isinstance(target, dict):
787
+ return None
788
+ table = self._document.tables.get(target.get("id"))
789
+ if table is None:
790
+ return "cell_ref_missing", f"{where} refers to {target.get('id')}, which is not a table"
791
+ if js_string(value) in table.index:
792
+ return None
793
+ return "cell_ref_missing", f"{where} {short(value)} is not a row of {table.id}"
794
+
795
+
796
+ Failure = tuple[str, str, "Place | None"]
797
+
798
+
799
+ class Check:
800
+ """One check on a spine node: its values resolve at the check's place, then its kind judges them. A value
801
+ that failed upstream skips the check, since its own issue already says why."""
802
+
803
+ code = ""
804
+ fields: tuple[str, ...] = ()
805
+
806
+ def __init__(self, spec: dict[str, Any], place: Place, resolver: SpineResolver) -> None:
807
+ self.spec = spec
808
+ self.place = place
809
+ self.resolver = resolver
810
+
811
+ @staticmethod
812
+ def of(spec: dict[str, Any], place: Place, resolver: SpineResolver) -> "Check":
813
+ kind = _CHECKS.get(spec.get("type"))
814
+ if kind is None:
815
+ raise SpineRefused("spine_invalid", f"there is no check type {spec.get('type')!r}")
816
+ return kind(spec, place, resolver)
817
+
818
+ def run(self) -> None:
819
+ present = [field for field in self.fields if field in self.spec]
820
+ values = Outcome.mapping({field: self.resolver.resolve(self.spec[field], self.place) for field in present})
821
+ if not values.ok:
822
+ return
823
+ try:
824
+ failures = self.failures(values.value)
825
+ except Shape as shape:
826
+ failures = self.fail(str(shape))
827
+ for code, message, place in failures:
828
+ self.resolver.log.add(place or self.place, self.spec["type"], code, message, self.spec.get("severity"))
829
+
830
+ def failures(self, values: dict[str, Any]) -> list[Failure]:
831
+ raise NotImplementedError
832
+
833
+ def fail(self, message: str, code: str | None = None, place: Place | None = None) -> list[Failure]:
834
+ return [(code or self.code, message, place)]
835
+
836
+
837
+ class FlowCheck(Check):
838
+ code = "flow_open"
839
+ fields = ("start", "created", "closed", "end")
840
+
841
+ def failures(self, values: dict[str, Any]) -> list[Failure]:
842
+ start = Exact.number(values["start"], "start")
843
+ created = Exact.number(values["created"], "created")
844
+ closed = values["closed"]
845
+ listed = [closed] if Exact.is_number(closed) else closed
846
+ gone = sum(Exact.parts(listed, "closed", "a number, a list or a map of numbers"))
847
+ end = Exact.number(values["end"], "end")
848
+ opened = start + created - gone
849
+ if opened == end:
850
+ return []
851
+ sentence = f"open at start {show(start)} + created {show(created)} − closed {show(gone)} = {show(opened)}"
852
+ return self.fail(f"{sentence}, not {show(end)}")
853
+
854
+
855
+ class SumCheck(Check):
856
+ code = "sum_differs"
857
+ fields = ("parts", "total")
858
+
859
+ def failures(self, values: dict[str, Any]) -> list[Failure]:
860
+ parts = sum(Exact.parts(values["parts"], "parts"))
861
+ total = Exact.number(values["total"], "total")
862
+ if parts == total:
863
+ return []
864
+ return self.fail(f"the parts sum to {show(parts)}, not {show(total)}")
865
+
866
+
867
+ def _entries(value: Any) -> dict[Any, Any] | None:
868
+ if isinstance(value, dict):
869
+ return dict(value)
870
+ return dict(enumerate(value)) if isinstance(value, list) else None
871
+
872
+
873
+ class QuotaCheck(Check):
874
+ code = "quota_differs"
875
+ fields = ("total", "quotas", "weights")
876
+
877
+ def failures(self, values: dict[str, Any]) -> list[Failure]:
878
+ total = Exact.number(values["total"], "total")
879
+ quotas = values["quotas"]
880
+ summed = sum(Exact.parts(quotas, "quotas"))
881
+ if summed != total:
882
+ return self.fail(f"the quotas sum to {show(summed)}, not {show(total)}")
883
+ if "weights" not in values:
884
+ return []
885
+ expected = self._split(values["total"], quotas, values["weights"])
886
+ if {key: Exact.of(quota) for key, quota in _entries(quotas).items()} == _entries(expected):
887
+ return []
888
+ split = f"the largest-remainder split {short(expected)} of {show(total)}"
889
+ return self.fail(f"the quotas are {short(quotas)}, not {split}")
890
+
891
+ @staticmethod
892
+ def _split(total: Any, quotas: Any, weights: Any) -> Any:
893
+ shape = _entries(weights)
894
+ if (
895
+ shape is None
896
+ or isinstance(weights, dict) != isinstance(quotas, dict)
897
+ or set(shape) != set(_entries(quotas))
898
+ ):
899
+ raise Shape("the weights and the quotas differ in shape")
900
+ try:
901
+ return Formulas.largest_remainder(total, weights)
902
+ except (TypeError, ValueError) as error:
903
+ raise Shape(str(error)) from None
904
+
905
+
906
+ class FactCheck(Check):
907
+ code = "fact_differs"
908
+ fields = ("claims", "value")
909
+
910
+ def failures(self, values: dict[str, Any]) -> list[Failure]:
911
+ claims, value = values["claims"], values["value"]
912
+ if Exact.is_number(claims) and Exact.is_number(value):
913
+ return self._numbers(Exact.of(claims), Exact.of(value))
914
+ if canonical(claims) == canonical(value):
915
+ return []
916
+ return self.fail(f"claims {short(claims)}, but the value is {short(value)}")
917
+
918
+ def _numbers(self, claims: Fraction, value: Fraction) -> list[Failure]:
919
+ tolerance = Exact.of(self.spec.get("tolerance", 0))
920
+ if abs(claims - value) <= tolerance:
921
+ return []
922
+ apart = f", more than {show(tolerance)} apart" if tolerance else ""
923
+ return self.fail(f"claims {show(claims)}, but the value is {show(value)}{apart}")
924
+
925
+
926
+ class StepsCheck(Check):
927
+ code = "step_off_day"
928
+ fields = ("holidays",)
929
+
930
+ def failures(self, values: dict[str, Any]) -> list[Failure]:
931
+ table = self.resolver.document.tables.get(self.place.node)
932
+ if table is None:
933
+ return self.fail("a steps check reads a table", "step_unnamed")
934
+ holidays = self._holidays(values.get("holidays", []))
935
+ weekend = set(self.spec.get("weekend", DEFAULT_WEEKEND))
936
+ steps = range(len(table.rows))
937
+ return [f for i in steps for f in self._named(table, i) + self._dated(table, i, holidays, weekend)]
938
+
939
+ @staticmethod
940
+ def _holidays(value: Any) -> set[datetime.date | None]:
941
+ days = [Calendar.day(day) for day in value] if isinstance(value, list) else [None]
942
+ if None in days:
943
+ raise Shape("holidays is not a list of dates")
944
+ return set(days)
945
+
946
+ def _named(self, table: SpineTable, index: int) -> list[Failure]:
947
+ column = self.spec["names"]
948
+ names = self.resolver.cell(table.id, index, column)
949
+ if not names.ok or self.resolver.document.row_ref_resolves(names.value):
950
+ return []
951
+ key = table.keys[index]
952
+ return self.fail(f"step {key} names {_unnamed(names.value)}", "step_unnamed", self.place.at(index, key, column))
953
+
954
+ def _dated(self, table: SpineTable, index: int, holidays: set[Any], weekend: set[int]) -> list[Failure]:
955
+ column = self.spec["at"]
956
+ at = self.resolver.cell(table.id, index, column)
957
+ if not self._business(table, index) or not at.ok or at.value is None:
958
+ return []
959
+ key = table.keys[index]
960
+ place = self.place.at(index, key, column)
961
+ day = Calendar.day(at.value)
962
+ if day is None:
963
+ return self.fail(f"step {key}: {column} is {short(at.value)}, not a date", place=place)
964
+ if day.weekday() in weekend:
965
+ return self.fail(f"step {key} is on a {WEEKDAYS[day.weekday()]} ({day.isoformat()})", place=place)
966
+ if day in holidays:
967
+ return self.fail(f"step {key} is on the holiday {day.isoformat()}", place=place)
968
+ return []
969
+
970
+ def _business(self, table: SpineTable, index: int) -> bool:
971
+ column = self.spec.get("business")
972
+ if column is None:
973
+ return True
974
+ flag = self.resolver.cell(table.id, index, column)
975
+ return flag.ok and flag.value is True
976
+
977
+
978
+ def _unnamed(value: Any) -> str:
979
+ if isinstance(value, dict) and value.get("kind") == "row":
980
+ return f"{_row_label(value)}, which is not a row"
981
+ return "no row"
982
+
983
+
984
+ _CHECKS: dict[Any, type[Check]] = {
985
+ "flow": FlowCheck,
986
+ "sum": SumCheck,
987
+ "quota": QuotaCheck,
988
+ "fact": FactCheck,
989
+ "steps": StepsCheck,
990
+ }
991
+
992
+
993
+ class SpineRun:
994
+ def __init__(self, spec: dict[str, Any], runtime: Any, _batch: Any) -> None:
995
+ self._document = SpineDocument.of(spec)
996
+ self._log = IssueLog()
997
+ self._resolver = SpineResolver(self._document, runtime, self._log)
998
+
999
+ def run(self) -> dict[str, Any]:
1000
+ facts = {node_id: self._resolver.unit(("fact", node_id)).value for node_id in self._document.facts()}
1001
+ cells = self._derived_cells()
1002
+ CellChecks(self._resolver).run()
1003
+ for node_id in self._document.ids():
1004
+ for index, spec in enumerate(self._document.nodes[node_id].get("checks") or []):
1005
+ Check.of(spec, Place(node_id, check=index), self._resolver).run()
1006
+ return {"status": "ok", "values": {"facts": facts, "cells": cells}, "issues": self._log.json()}
1007
+
1008
+ def _derived_cells(self) -> dict[str, dict[str, dict[str, Any]]]:
1009
+ cells: dict[str, dict[str, dict[str, Any]]] = {}
1010
+ for table in self._document.tables.values():
1011
+ for index, column in table.derived:
1012
+ row = cells.setdefault(table.id, {}).setdefault(table.keys[index], {})
1013
+ row[column] = self._resolver.cell(table.id, index, column).value
1014
+ return cells
1015
+
1016
+
1017
+ class GenerateContext:
1018
+ """What a generator reads: the batch's spine, and one random stream per concept, so changing one roster
1019
+ never reshuffles another."""
1020
+
1021
+ def __init__(self, seed: str, spine: dict[str, Any]) -> None:
1022
+ self._seed = seed
1023
+ self._spine = spine
1024
+
1025
+ def rng(self, name: str) -> random.Random:
1026
+ return SeededStream(hashlib.sha256("\u0000".join([self._seed, "spine", name]).encode("utf-8")).hexdigest())
1027
+
1028
+ def spine(self, node_id: str) -> Any:
1029
+ if node_id not in self._spine:
1030
+ raise SpineRefused("spine_missing", f"no spine node {node_id}")
1031
+ return copy.deepcopy(self._spine[node_id])
1032
+
1033
+ def rows(self, node_id: str) -> list[dict[str, Any]]:
1034
+ node = self.spine(node_id)
1035
+ if not isinstance(node, dict) or not isinstance(node.get("rows"), list):
1036
+ raise SpineRefused("spine_missing", f"spine node {node_id} has no rows")
1037
+ return node["rows"]
1038
+
1039
+
1040
+ class GenerateRun:
1041
+ def __init__(self, spec: dict[str, Any], runtime: Any, batch: Any) -> None:
1042
+ self._code = spec.get("code")
1043
+ self._runtime = runtime
1044
+ self._context = GenerateContext(batch.seed, batch.spine)
1045
+
1046
+ def run(self) -> dict[str, Any]:
1047
+ if not isinstance(self._code, str):
1048
+ raise SpineRefused("rule_missing", "the table has no generate code")
1049
+ rows = self._runtime.call("generate", self._code, self._context)
1050
+ if not isinstance(rows, list) or not all(isinstance(row, dict) for row in rows):
1051
+ raise SpineRefused("derive_invalid", "a generator returns a list of JSON objects")
1052
+ try:
1053
+ return {"status": "ok", "rows": as_json(rows)}
1054
+ except (TypeError, ValueError, RecursionError) as error:
1055
+ raise SpineRefused("derive_invalid", f"a generated row is not JSON: {error}") from None
1056
+
1057
+
1058
+ class OwnerRun:
1059
+ """One unit per row; a refusal or an exception is that row's error, never the job's."""
1060
+
1061
+ def __init__(self, spec: dict[str, Any], runtime: Any, batch: Any) -> None:
1062
+ self._code = spec.get("code")
1063
+ self._rows = spec.get("rows")
1064
+ self._runtime = runtime
1065
+ self._view = batch.view({}, str(spec.get("node")))
1066
+
1067
+ def run(self) -> dict[str, Any]:
1068
+ if not isinstance(self._code, str):
1069
+ raise SpineRefused("rule_missing", "the partition has no owner code")
1070
+ if not isinstance(self._rows, list):
1071
+ raise SpineRefused("spine_invalid", "rows is not a list")
1072
+ return {"status": "ok", "units": [self._unit(entry) for entry in self._rows]}
1073
+
1074
+ def _unit(self, entry: dict[str, Any]) -> dict[str, Any]:
1075
+ change = {**{key: entry.get(key) for key in ("world", "entity", "row")}, "op": "insert", "by": dict(OWNER_BY)}
1076
+ try:
1077
+ unit = self._runtime.call("owner", self._code, self._view, change)
1078
+ return {"unit": None if unit is None else js_string(unit)}
1079
+ except SpineRefused as refused:
1080
+ return {"error": refused.as_error()}
1081
+ except Exception as error:
1082
+ return {"error": {"type": "owner_raised", "message": f"{type(error).__name__}: {error}"[:MESSAGE]}}
1083
+
1084
+
1085
+ class Chronicle:
1086
+ def __init__(self, spec: dict[str, Any]) -> None:
1087
+ self._about = set((spec.get("each") or {}).get("about") or [])
1088
+ self._requirements = spec.get("require") or []
1089
+
1090
+ def violations(self, statements: list[dict[str, Any]]) -> list[dict[str, Any]]:
1091
+ index = {s.get("id"): s for s in statements}
1092
+ subjects = [s for s in statements if self._about & set(s.get("about") or [])]
1093
+ return [v for s in subjects for v in self._unmet(s, index)]
1094
+
1095
+ def _unmet(self, statement: dict[str, Any], index: dict[Any, dict[str, Any]]) -> list[dict[str, Any]]:
1096
+ checks = [self._met(req, statement, index) for req in self._requirements]
1097
+ return [
1098
+ {"statement": statement.get("id"), "requirement": i, "detail": detail}
1099
+ for i, (ok, detail) in enumerate(checks)
1100
+ if not ok
1101
+ ]
1102
+
1103
+ def _met(
1104
+ self, req: dict[str, Any], statement: dict[str, Any], index: dict[Any, dict[str, Any]]
1105
+ ) -> tuple[bool, str]:
1106
+ kind = next((key for key in _CHRONICLE_REQS if key in req), None)
1107
+ if kind is None:
1108
+ return True, ""
1109
+ return _CHRONICLE_REQS[kind](req[kind], statement, index)
1110
+
1111
+
1112
+ def _req_cause(spec: Any, statement: dict[str, Any], index: dict[Any, dict[str, Any]]) -> tuple[bool, str]:
1113
+ wanted = set((spec or {}).get("about") or [])
1114
+ causes = [index.get(cid) for cid in statement.get("causes") or []]
1115
+ ok = any(cause and wanted & set(cause.get("about") or []) for cause in causes)
1116
+ return ok, "" if ok else f"no cause about {sorted(wanted)}"
1117
+
1118
+
1119
+ def _req_at(_spec: Any, statement: dict[str, Any], _index: dict[Any, dict[str, Any]]) -> tuple[bool, str]:
1120
+ ok = bool(statement.get("at"))
1121
+ return ok, "" if ok else "the statement is not dated"
1122
+
1123
+
1124
+ def _req_cause_before(_spec: Any, statement: dict[str, Any], index: dict[Any, dict[str, Any]]) -> tuple[bool, str]:
1125
+ at = statement.get("at")
1126
+ causes = [index.get(cid) for cid in statement.get("causes") or []]
1127
+ dated = [cause.get("at") for cause in causes if cause and cause.get("at")]
1128
+ ok = at is None or all(cause_at <= at for cause_at in dated)
1129
+ return ok, "" if ok else "a dated cause is later than the statement"
1130
+
1131
+
1132
+ def _req_link(spec: Any, statement: dict[str, Any], _index: dict[Any, dict[str, Any]]) -> tuple[bool, str]:
1133
+ wanted = spec or {}
1134
+ links = [link for link in statement.get("links") or [] if _link_matches(link, wanted)]
1135
+ ok = bool(links)
1136
+ return ok, "" if ok else "no matching object or schema link"
1137
+
1138
+
1139
+ def _link_matches(link: dict[str, Any], wanted: dict[str, Any]) -> bool:
1140
+ if link.get("kind") not in {"object", "schema"}:
1141
+ return False
1142
+ world_ok = "world" not in wanted or link.get("world") == wanted["world"]
1143
+ entity_ok = "entity" not in wanted or link.get("entity") == wanted["entity"]
1144
+ return world_ok and entity_ok
1145
+
1146
+
1147
+ _CHRONICLE_REQS: dict[str, Callable[[Any, dict[str, Any], dict[Any, dict[str, Any]]], tuple[bool, str]]] = {
1148
+ "cause": _req_cause,
1149
+ "at": _req_at,
1150
+ "causeBefore": _req_cause_before,
1151
+ "link": _req_link,
1152
+ }
1153
+
1154
+
1155
+ JOBS: dict[str, Any] = {"spine": SpineRun, "generate": GenerateRun, "owner": OwnerRun}