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.
- flux_engine/__init__.py +22 -0
- flux_engine/_links.py +55 -0
- flux_engine/_vendor/__init__.py +5 -0
- flux_engine/_vendor/flux_spec/NOTICE +19 -0
- flux_engine/_vendor/flux_spec/VENDOR-NOTES.md +104 -0
- flux_engine/_vendor/flux_spec/__init__.py +9 -0
- flux_engine/_vendor/flux_spec/bundle.py +410 -0
- flux_engine/_vendor/flux_spec/enforce.py +316 -0
- flux_engine/_vendor/flux_spec/schema/flux-enforcement-0.5.0.json +121 -0
- flux_engine/_vendor/flux_spec/schema/flux-manifest-0.5.0.json +153 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.2.0.json +465 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.3.0.json +876 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.4.0.json +1601 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.4.1.json +1668 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.5.0.json +1669 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-latest.json +1669 -0
- flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.4.0.json +795 -0
- flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.4.1.json +852 -0
- flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.5.0.json +852 -0
- flux_engine/_vendor/flux_spec/validate.py +537 -0
- flux_engine/_vendor/flux_spec/vectors/enforcement-vectors.json +935 -0
- flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.3.json +5234 -0
- flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.4.json +5437 -0
- flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.5.json +5498 -0
- flux_engine/_vocabulary.py +141 -0
- flux_engine/accuracy/__init__.py +5 -0
- flux_engine/accuracy/_scoring/__init__.py +24 -0
- flux_engine/accuracy/accuracy_record.py +96 -0
- flux_engine/accuracy/policy.py +158 -0
- flux_engine/accuracy/records.py +264 -0
- flux_engine/accuracy/store.py +169 -0
- flux_engine/api/__init__.py +163 -0
- flux_engine/api/accuracy.py +209 -0
- flux_engine/api/agentic.py +134 -0
- flux_engine/api/calibration.py +125 -0
- flux_engine/api/claims.py +93 -0
- flux_engine/api/digests.py +73 -0
- flux_engine/api/emit.py +78 -0
- flux_engine/api/expressions.py +72 -0
- flux_engine/api/fidelity.py +110 -0
- flux_engine/api/lineage.py +78 -0
- flux_engine/api/stages.py +242 -0
- flux_engine/api/verdict.py +108 -0
- flux_engine/calibrate/__init__.py +5 -0
- flux_engine/calibrate/declared.py +253 -0
- flux_engine/calibrate/provenance.py +113 -0
- flux_engine/cli/__init__.py +2146 -0
- flux_engine/cli/__main__.py +17 -0
- flux_engine/cli/_documents.py +226 -0
- flux_engine/cli/_hints.py +118 -0
- flux_engine/cli/_init.py +152 -0
- flux_engine/cli/_progress.py +124 -0
- flux_engine/concordance/__init__.py +127 -0
- flux_engine/concordance/boundary/__init__.py +78 -0
- flux_engine/concordance/boundary/merkle.py +287 -0
- flux_engine/concordance/boundary/slice.py +429 -0
- flux_engine/concordance/boundary/statistic.py +561 -0
- flux_engine/concordance/boundary/store.py +334 -0
- flux_engine/concordance/boundary/vault.py +357 -0
- flux_engine/concordance/compiler.py +542 -0
- flux_engine/concordance/errors.py +189 -0
- flux_engine/concordance/gate.py +525 -0
- flux_engine/concordance/predicate.py +1217 -0
- flux_engine/concordance/record.py +554 -0
- flux_engine/concordance/verifier.py +583 -0
- flux_engine/core/__init__.py +5 -0
- flux_engine/core/artifact.py +99 -0
- flux_engine/core/canonical.py +369 -0
- flux_engine/core/clock.py +437 -0
- flux_engine/core/digest.py +288 -0
- flux_engine/core/errors.py +277 -0
- flux_engine/core/fixedpoint.py +929 -0
- flux_engine/core/lrm.py +158 -0
- flux_engine/core/rng.py +736 -0
- flux_engine/core/seedtree.py +891 -0
- flux_engine/core/trace.py +423 -0
- flux_engine/describe.py +207 -0
- flux_engine/engine.py +257 -0
- flux_engine/evidence/__init__.py +5 -0
- flux_engine/evidence/pack.py +411 -0
- flux_engine/evidence/report.py +243 -0
- flux_engine/expr/__init__.py +133 -0
- flux_engine/expr/ast.py +312 -0
- flux_engine/expr/attrs.py +386 -0
- flux_engine/expr/check.py +278 -0
- flux_engine/expr/compile.py +322 -0
- flux_engine/expr/errors.py +256 -0
- flux_engine/expr/lexer.py +297 -0
- flux_engine/expr/parser.py +313 -0
- flux_engine/expr/types.py +177 -0
- flux_engine/generator/__init__.py +97 -0
- flux_engine/generator/families.py +325 -0
- flux_engine/generator/paths.py +227 -0
- flux_engine/generator/rows.py +918 -0
- flux_engine/generator/statistics.py +524 -0
- flux_engine/governance/__init__.py +87 -0
- flux_engine/governance/audit.py +307 -0
- flux_engine/governance/gate.py +334 -0
- flux_engine/governance/skills.py +220 -0
- flux_engine/governance/sovereignty.py +251 -0
- flux_engine/lineage/__init__.py +5 -0
- flux_engine/lineage/emitter.py +398 -0
- flux_engine/py.typed +0 -0
- flux_engine/runtime/__init__.py +153 -0
- flux_engine/runtime/campaign.py +407 -0
- flux_engine/runtime/cast.py +283 -0
- flux_engine/runtime/detector.py +222 -0
- flux_engine/runtime/errors.py +58 -0
- flux_engine/runtime/experiment.py +311 -0
- flux_engine/runtime/journey.py +383 -0
- flux_engine/runtime/jurisdiction.py +72 -0
- flux_engine/runtime/payloads.py +124 -0
- flux_engine/runtime/signals.py +334 -0
- flux_engine/runtime/temperature.py +156 -0
- flux_engine/seam/__init__.py +5 -0
- flux_engine/seam/attest.py +290 -0
- flux_engine/seam/conform.py +448 -0
- flux_engine/seam/contract.py +605 -0
- flux_engine/seam/emit.py +488 -0
- flux_engine/seam/mapping.py +299 -0
- flux_engine/seam/resolve.py +1087 -0
- flux_engine/seam/sinks.py +157 -0
- flux_engine/spec/__init__.py +134 -0
- flux_engine/spec/bundle.py +25 -0
- flux_engine/spec/enforce.py +31 -0
- flux_engine/spec/validate.py +28 -0
- flux_engine/stages/__init__.py +30 -0
- flux_engine/stages/apply.py +447 -0
- flux_engine/stages/errors.py +315 -0
- flux_engine/stages/layout.py +292 -0
- flux_engine/stages/pipeline.py +600 -0
- flux_engine/stages/plan.py +241 -0
- flux_engine/stages/replay.py +83 -0
- flux_engine/stages/run.py +208 -0
- flux_engine/stages/ship.py +934 -0
- flux_engine/stages/validate.py +93 -0
- flux_engine/stages/verify.py +1129 -0
- flux_engine/starter/__init__.py +161 -0
- flux_engine/starter/bundle/detector.flux.yml +15 -0
- flux_engine/starter/bundle/journey.flux.yml +23 -0
- flux_engine/starter/bundle/module.flux.yml +16 -0
- flux_engine/starter/bundle/payment-recovery.fluid.yml +30 -0
- flux_engine/starter/bundle/persona.flux.yml +26 -0
- flux_engine/starter/bundle/signal.flux.yml +13 -0
- flux_engine/starter/bundle/simulation.flux.yml +29 -0
- flux_engine/starter/bundle/taxonomy.flux.yml +17 -0
- flux_engine/starter/bundle/treatment.flux.yml +13 -0
- flux_engine/starter/bundle/world.flux.yml +20 -0
- flux_engine/verticals/__init__.py +85 -0
- flux_engine/verticals/telco.py +89 -0
- flux_engine/world/__init__.py +89 -0
- flux_engine/world/derived.py +195 -0
- flux_engine/world/errors.py +41 -0
- flux_engine/world/families.py +260 -0
- flux_engine/world/population.py +602 -0
- flux_engine/world/tracing.py +66 -0
- flux_engine/world/values.py +121 -0
- flux_sim_engine-0.2.0.dist-info/METADATA +108 -0
- flux_sim_engine-0.2.0.dist-info/RECORD +165 -0
- flux_sim_engine-0.2.0.dist-info/WHEEL +5 -0
- flux_sim_engine-0.2.0.dist-info/entry_points.txt +2 -0
- flux_sim_engine-0.2.0.dist-info/licenses/LICENSE +202 -0
- flux_sim_engine-0.2.0.dist-info/licenses/NOTICE +10 -0
- flux_sim_engine-0.2.0.dist-info/licenses/flux_engine/_vendor/flux_spec/NOTICE +19 -0
- 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()
|