flux-sim-engine 0.2.0__py3-none-any.whl

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 (165) hide show
  1. flux_engine/__init__.py +22 -0
  2. flux_engine/_links.py +55 -0
  3. flux_engine/_vendor/__init__.py +5 -0
  4. flux_engine/_vendor/flux_spec/NOTICE +19 -0
  5. flux_engine/_vendor/flux_spec/VENDOR-NOTES.md +104 -0
  6. flux_engine/_vendor/flux_spec/__init__.py +9 -0
  7. flux_engine/_vendor/flux_spec/bundle.py +410 -0
  8. flux_engine/_vendor/flux_spec/enforce.py +316 -0
  9. flux_engine/_vendor/flux_spec/schema/flux-enforcement-0.5.0.json +121 -0
  10. flux_engine/_vendor/flux_spec/schema/flux-manifest-0.5.0.json +153 -0
  11. flux_engine/_vendor/flux_spec/schema/flux-schema-0.2.0.json +465 -0
  12. flux_engine/_vendor/flux_spec/schema/flux-schema-0.3.0.json +876 -0
  13. flux_engine/_vendor/flux_spec/schema/flux-schema-0.4.0.json +1601 -0
  14. flux_engine/_vendor/flux_spec/schema/flux-schema-0.4.1.json +1668 -0
  15. flux_engine/_vendor/flux_spec/schema/flux-schema-0.5.0.json +1669 -0
  16. flux_engine/_vendor/flux_spec/schema/flux-schema-latest.json +1669 -0
  17. flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.4.0.json +795 -0
  18. flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.4.1.json +852 -0
  19. flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.5.0.json +852 -0
  20. flux_engine/_vendor/flux_spec/validate.py +537 -0
  21. flux_engine/_vendor/flux_spec/vectors/enforcement-vectors.json +935 -0
  22. flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.3.json +5234 -0
  23. flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.4.json +5437 -0
  24. flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.5.json +5498 -0
  25. flux_engine/_vocabulary.py +141 -0
  26. flux_engine/accuracy/__init__.py +5 -0
  27. flux_engine/accuracy/_scoring/__init__.py +24 -0
  28. flux_engine/accuracy/accuracy_record.py +96 -0
  29. flux_engine/accuracy/policy.py +158 -0
  30. flux_engine/accuracy/records.py +264 -0
  31. flux_engine/accuracy/store.py +169 -0
  32. flux_engine/api/__init__.py +163 -0
  33. flux_engine/api/accuracy.py +209 -0
  34. flux_engine/api/agentic.py +134 -0
  35. flux_engine/api/calibration.py +125 -0
  36. flux_engine/api/claims.py +93 -0
  37. flux_engine/api/digests.py +73 -0
  38. flux_engine/api/emit.py +78 -0
  39. flux_engine/api/expressions.py +72 -0
  40. flux_engine/api/fidelity.py +110 -0
  41. flux_engine/api/lineage.py +78 -0
  42. flux_engine/api/stages.py +242 -0
  43. flux_engine/api/verdict.py +108 -0
  44. flux_engine/calibrate/__init__.py +5 -0
  45. flux_engine/calibrate/declared.py +253 -0
  46. flux_engine/calibrate/provenance.py +113 -0
  47. flux_engine/cli/__init__.py +2146 -0
  48. flux_engine/cli/__main__.py +17 -0
  49. flux_engine/cli/_documents.py +226 -0
  50. flux_engine/cli/_hints.py +118 -0
  51. flux_engine/cli/_init.py +152 -0
  52. flux_engine/cli/_progress.py +124 -0
  53. flux_engine/concordance/__init__.py +127 -0
  54. flux_engine/concordance/boundary/__init__.py +78 -0
  55. flux_engine/concordance/boundary/merkle.py +287 -0
  56. flux_engine/concordance/boundary/slice.py +429 -0
  57. flux_engine/concordance/boundary/statistic.py +561 -0
  58. flux_engine/concordance/boundary/store.py +334 -0
  59. flux_engine/concordance/boundary/vault.py +357 -0
  60. flux_engine/concordance/compiler.py +542 -0
  61. flux_engine/concordance/errors.py +189 -0
  62. flux_engine/concordance/gate.py +525 -0
  63. flux_engine/concordance/predicate.py +1217 -0
  64. flux_engine/concordance/record.py +554 -0
  65. flux_engine/concordance/verifier.py +583 -0
  66. flux_engine/core/__init__.py +5 -0
  67. flux_engine/core/artifact.py +99 -0
  68. flux_engine/core/canonical.py +369 -0
  69. flux_engine/core/clock.py +437 -0
  70. flux_engine/core/digest.py +288 -0
  71. flux_engine/core/errors.py +277 -0
  72. flux_engine/core/fixedpoint.py +929 -0
  73. flux_engine/core/lrm.py +158 -0
  74. flux_engine/core/rng.py +736 -0
  75. flux_engine/core/seedtree.py +891 -0
  76. flux_engine/core/trace.py +423 -0
  77. flux_engine/describe.py +207 -0
  78. flux_engine/engine.py +257 -0
  79. flux_engine/evidence/__init__.py +5 -0
  80. flux_engine/evidence/pack.py +411 -0
  81. flux_engine/evidence/report.py +243 -0
  82. flux_engine/expr/__init__.py +133 -0
  83. flux_engine/expr/ast.py +312 -0
  84. flux_engine/expr/attrs.py +386 -0
  85. flux_engine/expr/check.py +278 -0
  86. flux_engine/expr/compile.py +322 -0
  87. flux_engine/expr/errors.py +256 -0
  88. flux_engine/expr/lexer.py +297 -0
  89. flux_engine/expr/parser.py +313 -0
  90. flux_engine/expr/types.py +177 -0
  91. flux_engine/generator/__init__.py +97 -0
  92. flux_engine/generator/families.py +325 -0
  93. flux_engine/generator/paths.py +227 -0
  94. flux_engine/generator/rows.py +918 -0
  95. flux_engine/generator/statistics.py +524 -0
  96. flux_engine/governance/__init__.py +87 -0
  97. flux_engine/governance/audit.py +307 -0
  98. flux_engine/governance/gate.py +334 -0
  99. flux_engine/governance/skills.py +220 -0
  100. flux_engine/governance/sovereignty.py +251 -0
  101. flux_engine/lineage/__init__.py +5 -0
  102. flux_engine/lineage/emitter.py +398 -0
  103. flux_engine/py.typed +0 -0
  104. flux_engine/runtime/__init__.py +153 -0
  105. flux_engine/runtime/campaign.py +407 -0
  106. flux_engine/runtime/cast.py +283 -0
  107. flux_engine/runtime/detector.py +222 -0
  108. flux_engine/runtime/errors.py +58 -0
  109. flux_engine/runtime/experiment.py +311 -0
  110. flux_engine/runtime/journey.py +383 -0
  111. flux_engine/runtime/jurisdiction.py +72 -0
  112. flux_engine/runtime/payloads.py +124 -0
  113. flux_engine/runtime/signals.py +334 -0
  114. flux_engine/runtime/temperature.py +156 -0
  115. flux_engine/seam/__init__.py +5 -0
  116. flux_engine/seam/attest.py +290 -0
  117. flux_engine/seam/conform.py +448 -0
  118. flux_engine/seam/contract.py +605 -0
  119. flux_engine/seam/emit.py +488 -0
  120. flux_engine/seam/mapping.py +299 -0
  121. flux_engine/seam/resolve.py +1087 -0
  122. flux_engine/seam/sinks.py +157 -0
  123. flux_engine/spec/__init__.py +134 -0
  124. flux_engine/spec/bundle.py +25 -0
  125. flux_engine/spec/enforce.py +31 -0
  126. flux_engine/spec/validate.py +28 -0
  127. flux_engine/stages/__init__.py +30 -0
  128. flux_engine/stages/apply.py +447 -0
  129. flux_engine/stages/errors.py +315 -0
  130. flux_engine/stages/layout.py +292 -0
  131. flux_engine/stages/pipeline.py +600 -0
  132. flux_engine/stages/plan.py +241 -0
  133. flux_engine/stages/replay.py +83 -0
  134. flux_engine/stages/run.py +208 -0
  135. flux_engine/stages/ship.py +934 -0
  136. flux_engine/stages/validate.py +93 -0
  137. flux_engine/stages/verify.py +1129 -0
  138. flux_engine/starter/__init__.py +161 -0
  139. flux_engine/starter/bundle/detector.flux.yml +15 -0
  140. flux_engine/starter/bundle/journey.flux.yml +23 -0
  141. flux_engine/starter/bundle/module.flux.yml +16 -0
  142. flux_engine/starter/bundle/payment-recovery.fluid.yml +30 -0
  143. flux_engine/starter/bundle/persona.flux.yml +26 -0
  144. flux_engine/starter/bundle/signal.flux.yml +13 -0
  145. flux_engine/starter/bundle/simulation.flux.yml +29 -0
  146. flux_engine/starter/bundle/taxonomy.flux.yml +17 -0
  147. flux_engine/starter/bundle/treatment.flux.yml +13 -0
  148. flux_engine/starter/bundle/world.flux.yml +20 -0
  149. flux_engine/verticals/__init__.py +85 -0
  150. flux_engine/verticals/telco.py +89 -0
  151. flux_engine/world/__init__.py +89 -0
  152. flux_engine/world/derived.py +195 -0
  153. flux_engine/world/errors.py +41 -0
  154. flux_engine/world/families.py +260 -0
  155. flux_engine/world/population.py +602 -0
  156. flux_engine/world/tracing.py +66 -0
  157. flux_engine/world/values.py +121 -0
  158. flux_sim_engine-0.2.0.dist-info/METADATA +108 -0
  159. flux_sim_engine-0.2.0.dist-info/RECORD +165 -0
  160. flux_sim_engine-0.2.0.dist-info/WHEEL +5 -0
  161. flux_sim_engine-0.2.0.dist-info/entry_points.txt +2 -0
  162. flux_sim_engine-0.2.0.dist-info/licenses/LICENSE +202 -0
  163. flux_sim_engine-0.2.0.dist-info/licenses/NOTICE +10 -0
  164. flux_sim_engine-0.2.0.dist-info/licenses/flux_engine/_vendor/flux_spec/NOTICE +19 -0
  165. flux_sim_engine-0.2.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,322 @@
1
+ # Copyright 2026 Agentics Transformation Limited
2
+ #
3
+ # SPDX-License-Identifier: Apache-2.0
4
+
5
+ """Closure compiler for ``flux-expr/1`` (EXPR-SPEC §4).
6
+
7
+ ``compile(expr, scope_model) -> Callable[[View], bool]`` (closure tree)
8
+
9
+ A type-checked AST compiles to a tree of closures over pre-resolved canonical
10
+ paths: sugar is resolved once, at compile time, so evaluation is a dictionary
11
+ lookup and a comparison per node with no name resolution and no branching on
12
+ the model.
13
+
14
+ **Runtime totality** (EXPR-SPEC §2) is the invariant this module owes the
15
+ rest of the engine: "a type-checked expression never raises. A ``null``
16
+ operand makes every comparison and ``in`` evaluate to ``false``, ``!= null``
17
+ to ``true``, and ``isNull()`` to ``true``. Methods on ``null`` return
18
+ ``false``." A path missing from the view is null, so a view is never required
19
+ to be complete.
20
+
21
+ That sentence is ambiguous about ``x != null`` when ``x`` *is* null -- read
22
+ literally it would make ``null != null`` true while ``x.isNull()`` is also
23
+ true. Resolved here in the only self-consistent direction: the ``null``
24
+ literal makes the comparison a **null test**, so ``x == null`` is true when
25
+ ``x`` is null, ``x != null`` is true when it is not, and ``x != null`` is
26
+ exactly ``!x.isNull()``. Every *other* comparison or ``in`` with a null
27
+ operand is false. The checker enforces the same reading by accepting the
28
+ ``null`` literal only against a path.
29
+ """
30
+
31
+ from __future__ import annotations
32
+
33
+ from decimal import Decimal
34
+ from typing import AbstractSet, Any, Callable, Dict, FrozenSet, Mapping, Tuple, Union, cast
35
+
36
+ from flux_engine.expr.ast import (
37
+ And,
38
+ BoolLit,
39
+ Compare,
40
+ Expr,
41
+ In,
42
+ ListLit,
43
+ Method,
44
+ Node,
45
+ Not,
46
+ NullLit,
47
+ NumberLit,
48
+ Operand,
49
+ Or,
50
+ Path,
51
+ StringLit,
52
+ )
53
+ from flux_engine.expr.check import check
54
+ from flux_engine.expr.errors import TypeMismatchError, UnknownPathError
55
+ from flux_engine.expr.parser import parse
56
+ from flux_engine.expr.types import ScopeModel, Type, TypeKind, nfc
57
+
58
+ __all__ = ["Predicate", "View", "compile_expr", "compile_source", "make_view"]
59
+
60
+ #: One row presented to a compiled predicate: canonical path -> value.
61
+ #: ``number`` is ``Decimal``, ``string`` and ``enum`` are ``str``, ``bool`` is
62
+ #: ``bool``, ``set<string>`` is any set of ``str``, and a missing key or
63
+ #: ``None`` is null.
64
+ View = Mapping[str, Any]
65
+
66
+ #: What :func:`compile_expr` returns.
67
+ Predicate = Callable[[View], bool]
68
+
69
+ _Getter = Callable[[View], Any]
70
+
71
+
72
+ # --- views ------------------------------------------------------------------
73
+
74
+
75
+ def make_view(model: ScopeModel, values: Mapping[str, Any]) -> View:
76
+ """Build a checked view: resolve sugar, NFC the strings, reject ``float``.
77
+
78
+ This is a builder-side check, not part of evaluation: it runs once per row
79
+ at most and raises ``FLX-6004`` for a path the model does not declare and
80
+ ``FLX-6005`` for a value whose Python type does not match the declared
81
+ one. ``float`` is refused outright -- KERNEL-SPEC §2.1 keeps ``float`` out
82
+ of every hashed value, and a view feeds traced decisions. Errors name the
83
+ path and the value's **class**, never the value.
84
+ """
85
+ built: Dict[str, Any] = {}
86
+ for name in sorted(values, key=nfc):
87
+ canonical = model.resolve(name)
88
+ if canonical is None:
89
+ raise UnknownPathError(f"'{name}' is not an attribute of the {model.scope.value} scope")
90
+ built[canonical] = _coerce(canonical, model.attributes[canonical], values[name])
91
+ return built
92
+
93
+
94
+ def _coerce(path: str, declared: Type, value: Any) -> Any:
95
+ if value is None:
96
+ return None
97
+ if isinstance(value, float):
98
+ raise TypeMismatchError(f"'{path}': float is not a flux-expr/1 value; use Decimal")
99
+ if declared.kind is TypeKind.NUMBER:
100
+ if isinstance(value, bool) or not isinstance(value, (int, Decimal)):
101
+ raise TypeMismatchError(f"'{path}': number expected, got {type(value).__name__}")
102
+ return value if isinstance(value, Decimal) else Decimal(value)
103
+ if declared.kind is TypeKind.BOOL:
104
+ if not isinstance(value, bool):
105
+ raise TypeMismatchError(f"'{path}': bool expected, got {type(value).__name__}")
106
+ return value
107
+ if declared.kind in (TypeKind.STRING, TypeKind.ENUM):
108
+ if not isinstance(value, str):
109
+ raise TypeMismatchError(
110
+ f"'{path}': {declared.name} expected, got {type(value).__name__}"
111
+ )
112
+ return nfc(value)
113
+ if not isinstance(value, (set, frozenset)):
114
+ raise TypeMismatchError(f"'{path}': set<string> expected, got {type(value).__name__}")
115
+ members: AbstractSet[Any] = value
116
+ for member in members:
117
+ if not isinstance(member, str):
118
+ raise TypeMismatchError(
119
+ f"'{path}': set<string> member expected, got {type(member).__name__}"
120
+ )
121
+ return frozenset(nfc(member) for member in cast(AbstractSet[str], members))
122
+
123
+
124
+ # --- operand getters --------------------------------------------------------
125
+
126
+
127
+ def _getter(operand: Operand, model: ScopeModel) -> _Getter:
128
+ """Compile an operand into a value getter over the view."""
129
+ if isinstance(operand, Path):
130
+ canonical = model.resolve(operand.text)
131
+ if canonical is None: # pragma: no cover - the checker ran first
132
+ raise UnknownPathError(f"'{operand.text}' is not an attribute of this scope")
133
+ return lambda view: view.get(canonical)
134
+ if isinstance(operand, StringLit):
135
+ literal_str = nfc(operand.value)
136
+ return lambda view: literal_str
137
+ if isinstance(operand, NumberLit):
138
+ literal_num = operand.value
139
+ return lambda view: literal_num
140
+ if isinstance(operand, BoolLit):
141
+ literal_bool = operand.value
142
+ return lambda view: literal_bool
143
+ # ``NullLit`` never reaches here: the checker accepts the null literal only
144
+ # opposite a path, and _compile_compare turns that into a null test before
145
+ # compiling either side. The guard stays so a future operand kind fails
146
+ # loudly instead of compiling to something silently wrong.
147
+ raise TypeMismatchError( # pragma: no cover - unreachable after check()
148
+ f"not a value operand: {type(operand).__name__}"
149
+ )
150
+
151
+
152
+ def _literal_value(literal: Node) -> Any:
153
+ """The constant a literal denotes, with strings NFC-normalised."""
154
+ if isinstance(literal, StringLit):
155
+ return nfc(literal.value)
156
+ if isinstance(literal, NumberLit):
157
+ return literal.value
158
+ if isinstance(literal, BoolLit):
159
+ return literal.value
160
+ if isinstance(literal, NullLit): # pragma: no cover - the checker rejects it here
161
+ return None
162
+ raise TypeMismatchError( # pragma: no cover - unreachable after check()
163
+ f"not a literal: {type(literal).__name__}"
164
+ )
165
+
166
+
167
+ # --- comparison -------------------------------------------------------------
168
+
169
+ #: Total, null-free comparisons; the wrappers below own the null rules.
170
+ _OPERATIONS: Dict[str, Callable[[Any, Any], bool]] = {
171
+ "==": lambda a, b: bool(a == b),
172
+ "!=": lambda a, b: bool(a != b),
173
+ "<": lambda a, b: bool(a < b),
174
+ "<=": lambda a, b: bool(a <= b),
175
+ ">": lambda a, b: bool(a > b),
176
+ ">=": lambda a, b: bool(a >= b),
177
+ }
178
+
179
+
180
+ def _compile_compare(node: Compare, model: ScopeModel) -> Predicate:
181
+ if isinstance(node.left, NullLit) or isinstance(node.right, NullLit):
182
+ path = node.right if isinstance(node.left, NullLit) else node.left
183
+ assert isinstance(path, Path) # the checker requires a path opposite null
184
+ get = _getter(path, model)
185
+ if node.op == "==":
186
+ return lambda view: get(view) is None
187
+ return lambda view: get(view) is not None
188
+
189
+ left = _getter(node.left, model)
190
+ right = _getter(node.right, model)
191
+ operation = _OPERATIONS[node.op]
192
+
193
+ def run(view: View) -> bool:
194
+ a = left(view)
195
+ b = right(view)
196
+ if a is None or b is None:
197
+ return False
198
+ return operation(a, b)
199
+
200
+ return run
201
+
202
+
203
+ def _compile_in(node: In, model: ScopeModel) -> Predicate:
204
+ left = _getter(node.left, model)
205
+
206
+ if isinstance(node.right, Path):
207
+ right = _getter(node.right, model)
208
+
209
+ def run_path(view: View) -> bool:
210
+ value = left(view)
211
+ container = right(view)
212
+ if value is None or container is None:
213
+ return False
214
+ return value in cast(FrozenSet[str], container)
215
+
216
+ return run_path
217
+
218
+ assert isinstance(node.right, ListLit)
219
+ members: Tuple[Any, ...] = tuple(_literal_value(item) for item in node.right.items)
220
+
221
+ def run_list(view: View) -> bool:
222
+ value = left(view)
223
+ if value is None:
224
+ return False
225
+ return any(value == member for member in members)
226
+
227
+ return run_list
228
+
229
+
230
+ def _starts_with(haystack: str, needle: str) -> bool:
231
+ return haystack.startswith(needle)
232
+
233
+
234
+ def _ends_with(haystack: str, needle: str) -> bool:
235
+ return haystack.endswith(needle)
236
+
237
+
238
+ def _contains(haystack: str, needle: str) -> bool:
239
+ return needle in haystack
240
+
241
+
242
+ def _compile_method(node: Method, model: ScopeModel) -> Predicate:
243
+ canonical = model.resolve(node.target.text)
244
+ if canonical is None: # pragma: no cover - the checker ran first
245
+ raise UnknownPathError(f"'{node.target.text}' is not an attribute of this scope")
246
+
247
+ if node.name == "isNull":
248
+ return lambda view: view.get(canonical) is None
249
+
250
+ argument = nfc(cast(StringLit, node.args[0]).value)
251
+
252
+ if node.name == "has":
253
+
254
+ def run_has(view: View) -> bool:
255
+ container = view.get(canonical)
256
+ if container is None:
257
+ return False
258
+ return argument in cast(FrozenSet[str], container)
259
+
260
+ return run_has
261
+
262
+ operation: Callable[[str, str], bool]
263
+ if node.name == "startsWith":
264
+ operation = _starts_with
265
+ elif node.name == "endsWith":
266
+ operation = _ends_with
267
+ else:
268
+ operation = _contains
269
+
270
+ def run_string(view: View) -> bool:
271
+ value = view.get(canonical)
272
+ if value is None:
273
+ return False
274
+ return operation(cast(str, value), argument)
275
+
276
+ return run_string
277
+
278
+
279
+ # --- the compiler -----------------------------------------------------------
280
+
281
+
282
+ def _compile_node(node: Union[Expr, Node], model: ScopeModel) -> Predicate:
283
+ if isinstance(node, Or):
284
+ left = _compile_node(node.left, model)
285
+ right = _compile_node(node.right, model)
286
+ return lambda view: left(view) or right(view)
287
+ if isinstance(node, And):
288
+ left = _compile_node(node.left, model)
289
+ right = _compile_node(node.right, model)
290
+ return lambda view: left(view) and right(view)
291
+ if isinstance(node, Not):
292
+ inner = _compile_node(node.operand, model)
293
+ return lambda view: not inner(view)
294
+ if isinstance(node, Compare):
295
+ return _compile_compare(node, model)
296
+ if isinstance(node, In):
297
+ return _compile_in(node, model)
298
+ if isinstance(node, Method):
299
+ return _compile_method(node, model)
300
+ if isinstance(node, BoolLit):
301
+ constant = node.value
302
+ return lambda view: constant
303
+ raise TypeMismatchError( # pragma: no cover - check() rejects this first
304
+ f"{type(node).__name__} is not a predicate"
305
+ )
306
+
307
+
308
+ def compile_expr(node: Expr, model: ScopeModel) -> Predicate:
309
+ """Type-check *node* against *model* and return the compiled closure tree.
310
+
311
+ This is the ``compile(expr, scope_model)`` of EXPR-SPEC §4; it is spelled
312
+ ``compile_expr`` so it does not shadow the builtin at a call site. The
313
+ check is not optional: compiling an unchecked AST would put the totality
314
+ guarantee at the mercy of the caller.
315
+ """
316
+ check(node, model)
317
+ return _compile_node(node, model)
318
+
319
+
320
+ def compile_source(source: str, model: ScopeModel) -> Predicate:
321
+ """Parse, type-check and compile *source* in one call."""
322
+ return compile_expr(parse(source), model)
@@ -0,0 +1,256 @@
1
+ # Copyright 2026 Agentics Transformation Limited
2
+ #
3
+ # SPDX-License-Identifier: Apache-2.0
4
+
5
+ """Error catalog for ``flux-expr/1`` (the ``FLX-6nnn`` range).
6
+
7
+ KERNEL-SPEC §13 assigns the 6000 range to "expression language" and
8
+ requires ``fluxsim explain FLX-nnnn`` to print a catalog entry, so every code
9
+ raised by this package is declared here with a title and a hint rather
10
+ than being an ad-hoc string at the raise site.
11
+
12
+ The engine-wide registry is ``flux_engine.core.errors``, whose contract is
13
+ that "the catalog is populated at import time by the module that actually
14
+ raises the code, via ``register``". This module honours that: importing it
15
+ publishes all five ``FLX-6nnn`` entries into the shared catalog. It also
16
+ keeps :data:`CATALOG` as a local, self-contained copy, so the expression
17
+ package still works -- and still explains its codes -- when the shared
18
+ registry is not importable, which is the state ``flux_engine.core`` was in
19
+ when this package was written. See :func:`publish_to_core_catalog` and the
20
+ REQUEST in the build report (``core.errors._CORE_CODE_MODULES`` has to name
21
+ this module for ``fluxsim explain FLX-6nnn`` to work without an expression
22
+ having been parsed first).
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ import difflib
28
+ import re
29
+ from dataclasses import dataclass
30
+ from typing import Dict, Iterable, Mapping, Optional, Sequence, Tuple
31
+
32
+ __all__ = [
33
+ "CATALOG",
34
+ "PUBLISHED_TO_CORE_CATALOG",
35
+ "CatalogEntry",
36
+ "FluxExprError",
37
+ "ParseError",
38
+ "ReservedWordError",
39
+ "EnumLiteralError",
40
+ "UnknownPathError",
41
+ "TypeMismatchError",
42
+ "known_attributes_hint",
43
+ "publish_to_core_catalog",
44
+ "register_all",
45
+ "with_known_attributes",
46
+ ]
47
+
48
+
49
+ @dataclass(frozen=True)
50
+ class CatalogEntry:
51
+ """One row of the ``FLX-6nnn`` catalog: the code, its title and a hint."""
52
+
53
+ code: str
54
+ title: str
55
+ hint: str
56
+
57
+
58
+ #: The closed catalog for flux-expr/1. EXPR-SPEC §1-§3 name every one of
59
+ #: these; adding a code is a grammar change and therefore a
60
+ #: ``kernelVersion`` bump, not a patch.
61
+ CATALOG: Mapping[str, CatalogEntry] = {
62
+ entry.code: entry
63
+ for entry in (
64
+ CatalogEntry(
65
+ "FLX-6001",
66
+ "not derivable from the flux-expr/1 grammar",
67
+ "The grammar is closed: only the productions in EXPR-SPEC §1 parse. "
68
+ "There is no arithmetic, no lambda, no regex, no double-quoted string "
69
+ "and no user-defined function.",
70
+ ),
71
+ CatalogEntry(
72
+ "FLX-6002",
73
+ "reserved word held for flux-expr/2",
74
+ "This word is reserved and has no meaning in flux-expr/1. A grammar "
75
+ "that needs it is flux-expr/2; raise the request there.",
76
+ ),
77
+ CatalogEntry(
78
+ "FLX-6003",
79
+ "literal outside the declared closed set",
80
+ "The attribute is an enum whose levels come from the bundle. Compare "
81
+ "it against one of its declared levels.",
82
+ ),
83
+ CatalogEntry(
84
+ "FLX-6004",
85
+ "unknown path for this scope",
86
+ "Names are resolved against the attribute model derived at plan time. "
87
+ "Print the model with `fluxsim expr model` to see what this scope offers.",
88
+ ),
89
+ CatalogEntry(
90
+ "FLX-6005",
91
+ "type mismatch",
92
+ "flux-expr/1 has no coercion: the two sides of a comparison must have "
93
+ "the same type, and each method is declared on one type only.",
94
+ ),
95
+ )
96
+ }
97
+
98
+
99
+ class FluxExprError(Exception):
100
+ """Base class for every ``FLX-6nnn`` failure raised by this package.
101
+
102
+ Carries the machine-readable ``code`` alongside the human message and,
103
+ where the failure has a source location, the 0-based character offset
104
+ into the **NFC-normalised** expression text (the lexer normalises its
105
+ input first, so offsets index the normalised string -- see
106
+ :mod:`flux_engine.expr.lexer`).
107
+ """
108
+
109
+ #: Subclasses set this; the catalog is keyed on it.
110
+ code: str = "FLX-6001"
111
+
112
+ def __init__(self, message: str, *, position: Optional[int] = None) -> None:
113
+ self.message = message
114
+ self.position = position
115
+ super().__init__(str(self))
116
+
117
+ def __str__(self) -> str:
118
+ where = "" if self.position is None else f" (at offset {self.position})"
119
+ return f"{self.code}: {self.message}{where}"
120
+
121
+ @property
122
+ def entry(self) -> CatalogEntry:
123
+ """The catalog row for this error's code."""
124
+ return CATALOG[self.code]
125
+
126
+
127
+ class ParseError(FluxExprError):
128
+ """FLX-6001 -- the text is not derivable from the closed grammar."""
129
+
130
+ code = "FLX-6001"
131
+
132
+
133
+ class ReservedWordError(FluxExprError):
134
+ """FLX-6002 -- a word reserved for ``flux-expr/2`` was used."""
135
+
136
+ code = "FLX-6002"
137
+
138
+
139
+ class EnumLiteralError(FluxExprError):
140
+ """FLX-6003 -- a string literal falls outside an enum's declared levels."""
141
+
142
+ code = "FLX-6003"
143
+
144
+
145
+ class UnknownPathError(FluxExprError):
146
+ """FLX-6004 -- a path the scope's attribute model does not declare."""
147
+
148
+ code = "FLX-6004"
149
+
150
+
151
+ class TypeMismatchError(FluxExprError):
152
+ """FLX-6005 -- operand or argument types do not line up; no coercion."""
153
+
154
+ code = "FLX-6005"
155
+
156
+
157
+ #: The name an ``FLX-6004`` raise site quotes in its message (``'arpu' is
158
+ #: not an attribute of the subject scope``). Read back by
159
+ #: :func:`with_known_attributes` so the suggestion can be computed for the
160
+ #: name that actually failed, without every raise site having to hand the
161
+ #: attribute model down to the error.
162
+ _QUOTED_NAME = re.compile(r"'([^']+)'")
163
+
164
+ #: How many attributes an FLX-6004 message lists before it stops. A scope
165
+ #: with hundreds of attributes would otherwise turn one error into a wall
166
+ #: of text; the count that was elided is still reported.
167
+ _MAX_LISTED_ATTRIBUTES = 40
168
+
169
+
170
+ def known_attributes_hint(known: Iterable[str], *, name: Optional[str] = None) -> str:
171
+ """The attributes a scope declares, and the closest match to *name*.
172
+
173
+ The engine holds the whole attribute model in memory at the moment it
174
+ raises ``FLX-6004``, and the one list that fixes the error in a single
175
+ keystroke was being withheld from the reader. Returns the empty string
176
+ when the scope declares nothing, so a caller can append it
177
+ unconditionally.
178
+ """
179
+ attributes: Sequence[str] = sorted(set(known))
180
+ if not attributes:
181
+ return ""
182
+ parts = []
183
+ if name:
184
+ close = difflib.get_close_matches(name, attributes, n=1, cutoff=0.6)
185
+ if close:
186
+ parts.append(f"did you mean {close[0]!r}?")
187
+ listed: Tuple[str, ...] = tuple(attributes[:_MAX_LISTED_ATTRIBUTES])
188
+ elided = len(attributes) - len(listed)
189
+ known_text = "known attributes: " + ", ".join(listed)
190
+ if elided:
191
+ known_text = f"{known_text} (+{elided} more; `fluxsim expr model` prints them all)"
192
+ parts.append(known_text)
193
+ return " -- " + "; ".join(parts)
194
+
195
+
196
+ def with_known_attributes(error: "UnknownPathError", known: Iterable[str]) -> "UnknownPathError":
197
+ """Return *error* again, with the scope's attribute list appended to its message.
198
+
199
+ For the caller that has the attribute model to hand (the CLI's ``expr
200
+ eval``) and can therefore answer the question the bare error only
201
+ asks. The unknown name is read back from the message the raise site
202
+ composed; when it cannot be read, the list is still appended, without
203
+ a suggestion.
204
+ """
205
+ match = _QUOTED_NAME.search(error.message)
206
+ hint = known_attributes_hint(known, name=match.group(1) if match else None)
207
+ if not hint:
208
+ return error
209
+ return UnknownPathError(error.message + hint, position=error.position)
210
+
211
+
212
+ def register_all(registry: Dict[str, CatalogEntry]) -> None:
213
+ """Copy this catalog into a plain ``code -> entry`` *registry*.
214
+
215
+ The mapping-shaped counterpart to :func:`publish_to_core_catalog`, for a
216
+ consumer that keeps its own table (a documentation generator, a test)
217
+ rather than the engine-wide catalog. Idempotent, and it refuses to
218
+ shadow a differing entry for the same code, so a collision is loud
219
+ rather than silent.
220
+ """
221
+ for code, entry in sorted(CATALOG.items()):
222
+ existing = registry.get(code)
223
+ if existing is not None and existing != entry:
224
+ raise ValueError(f"{code} is already registered with a different entry")
225
+ registry[code] = entry
226
+
227
+
228
+ def publish_to_core_catalog() -> bool:
229
+ """Publish this catalog into ``flux_engine.core.errors``; return whether it landed.
230
+
231
+ The shared catalog's rule is that the module which raises a code
232
+ registers it at import time, so this runs on import (see
233
+ :data:`PUBLISHED_TO_CORE_CATALOG`). A missing or older
234
+ ``flux_engine.core.errors`` is not an error -- the local
235
+ :data:`CATALOG` is authoritative inside this package either way -- but a
236
+ *conflicting* registration is: two subsystems must not share one number,
237
+ so a ``ValueError`` from the shared registry propagates rather than
238
+ being swallowed.
239
+ """
240
+ try:
241
+ from flux_engine.core import errors as core_errors
242
+ except ImportError: # pragma: no cover - depends on the installed tree
243
+ return False
244
+ register = getattr(core_errors, "register", None)
245
+ if register is None: # pragma: no cover - depends on the installed tree
246
+ return False
247
+ for code in sorted(CATALOG):
248
+ entry = CATALOG[code]
249
+ register(entry.code, entry.title, entry.hint)
250
+ return True
251
+
252
+
253
+ #: Whether the five ``FLX-6nnn`` entries reached the engine-wide catalog on
254
+ #: import. False means ``flux_engine.core.errors`` was not importable; the
255
+ #: local :data:`CATALOG` is unaffected.
256
+ PUBLISHED_TO_CORE_CATALOG = publish_to_core_catalog()