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,297 @@
1
+ # Copyright 2026 Agentics Transformation Limited
2
+ #
3
+ # SPDX-License-Identifier: Apache-2.0
4
+
5
+ """Hand-written tokenizer for ``flux-expr/1`` (EXPR-SPEC §1, §4).
6
+
7
+ The grammar is closed: "anything not derivable is a parse error
8
+ (``FLX-6001``), never an extension point". This module is therefore written
9
+ to reject rather than to recover -- there is no error node, no skipped
10
+ character and no lookahead beyond one character.
11
+
12
+ Three rules resolved here that the EBNF leaves open, each in the restrictive
13
+ direction the closed-grammar policy calls for:
14
+
15
+ * **NFC first.** The source is normalised to NFC before a single character is
16
+ read, so the composed and decomposed spellings of an identifier name the
17
+ same path (EXPR-SPEC §5, "NFC/NFD identifier equivalence"). Every offset a
18
+ token or an error reports indexes the *normalised* text.
19
+ * **Backslash.** ``string = "'" , { char - "'" | "\\'" } , "'"`` does not say
20
+ what a bare backslash means. Resolved: a backslash is legal only as the
21
+ two-character escape ``\\'``; any other backslash is ``FLX-6001``. A string
22
+ value therefore never contains a backslash, which is what makes
23
+ ``unparse`` total and a fixed point.
24
+ * **Control characters.** A character below U+0020 (a newline included) is
25
+ ``FLX-6001`` anywhere in the source, including inside a string literal:
26
+ EXPR-SPEC §1 lists space and tab as the whole of the whitespace set, and a
27
+ canonical form that can carry a raw newline is not a single line of
28
+ ``plan.json``.
29
+ """
30
+
31
+ from __future__ import annotations
32
+
33
+ from dataclasses import dataclass
34
+ from decimal import Decimal
35
+ from enum import Enum
36
+ from typing import List, Tuple
37
+
38
+ from flux_engine.expr.errors import ParseError, ReservedWordError
39
+ from flux_engine.expr.types import nfc
40
+
41
+ __all__ = ["Token", "TokenKind", "RESERVED_WORDS", "tokenize"]
42
+
43
+ #: Words held for ``flux-expr/2``. EXPR-SPEC §1: "``matches`` is a **reserved
44
+ #: word** that parses to ``FLX-6002`` naming flux-expr/2". Reserved in every
45
+ #: position -- as a bare name, as a path segment and as a method name -- so
46
+ #: that the word cannot acquire a meaning by accident in flux-expr/1.
47
+ RESERVED_WORDS: frozenset = frozenset({"matches"})
48
+
49
+ #: EXPR-SPEC §1: "Whitespace: space, tab."
50
+ _WHITESPACE = " \t"
51
+
52
+
53
+ class TokenKind(str, Enum):
54
+ """Every token flux-expr/1 has. Closed."""
55
+
56
+ IDENT = "ident"
57
+ NUMBER = "number"
58
+ STRING = "string"
59
+ TRUE = "true"
60
+ FALSE = "false"
61
+ NULL = "null"
62
+ IN = "in"
63
+ LPAREN = "("
64
+ RPAREN = ")"
65
+ LBRACKET = "["
66
+ RBRACKET = "]"
67
+ COMMA = ","
68
+ DOT = "."
69
+ BANG = "!"
70
+ AND = "&&"
71
+ OR = "||"
72
+ EQ = "=="
73
+ NE = "!="
74
+ LT = "<"
75
+ LE = "<="
76
+ GT = ">"
77
+ GE = ">="
78
+ EOF = "<end of expression>"
79
+
80
+
81
+ #: ``ident``s that are keywords rather than names. ``matches`` is handled
82
+ #: separately because it raises rather than producing a token.
83
+ _KEYWORDS = {
84
+ "true": TokenKind.TRUE,
85
+ "false": TokenKind.FALSE,
86
+ "null": TokenKind.NULL,
87
+ "in": TokenKind.IN,
88
+ }
89
+
90
+ #: Operators that are exactly one character and have no two-character form.
91
+ _SINGLES = {
92
+ "(": TokenKind.LPAREN,
93
+ ")": TokenKind.RPAREN,
94
+ "[": TokenKind.LBRACKET,
95
+ "]": TokenKind.RBRACKET,
96
+ ",": TokenKind.COMMA,
97
+ ".": TokenKind.DOT,
98
+ }
99
+
100
+ #: Comparison operator kinds, consumed by the parser as ``cmp_op``.
101
+ COMPARISON_KINDS = (
102
+ TokenKind.EQ,
103
+ TokenKind.NE,
104
+ TokenKind.LT,
105
+ TokenKind.LE,
106
+ TokenKind.GT,
107
+ TokenKind.GE,
108
+ )
109
+
110
+
111
+ @dataclass(frozen=True)
112
+ class Token:
113
+ """One token: its kind, the exact text consumed, and its start offset.
114
+
115
+ ``value`` carries the decoded payload for the three literal kinds -- a
116
+ ``Decimal`` for ``NUMBER`` (never a ``float``; KERNEL-SPEC §2.1), the
117
+ unescaped NFC string for ``STRING``, the identifier for ``IDENT`` -- and
118
+ is the empty string for every operator.
119
+ """
120
+
121
+ kind: TokenKind
122
+ text: str
123
+ position: int
124
+ value: object = ""
125
+
126
+ def __str__(self) -> str:
127
+ return self.text or self.kind.value
128
+
129
+
130
+ def _is_ident_start(char: str) -> bool:
131
+ """``ident = ( letter | "_" ) , ...`` -- ``letter`` is any Unicode letter."""
132
+ return char == "_" or char.isalpha()
133
+
134
+
135
+ def _is_ident_part(char: str) -> bool:
136
+ """``... , { letter | digit | "_" }``."""
137
+ return char == "_" or char.isalpha() or char.isdecimal()
138
+
139
+
140
+ def _read_string(source: str, start: int) -> Tuple[str, int]:
141
+ """Read a single-quoted string starting at the quote; return (value, end)."""
142
+ index = start + 1
143
+ chars: List[str] = []
144
+ while index < len(source):
145
+ char = source[index]
146
+ if char == "'":
147
+ return "".join(chars), index + 1
148
+ if char == "\\":
149
+ if index + 1 < len(source) and source[index + 1] == "'":
150
+ chars.append("'")
151
+ index += 2
152
+ continue
153
+ raise ParseError(
154
+ "a backslash is only legal as the escape \\' inside a string",
155
+ position=index,
156
+ )
157
+ if char < " ":
158
+ raise ParseError(
159
+ f"control character U+{ord(char):04X} is not legal in a string literal",
160
+ position=index,
161
+ )
162
+ chars.append(char)
163
+ index += 1
164
+ raise ParseError("unterminated string literal", position=start)
165
+
166
+
167
+ def _read_number(source: str, start: int) -> Tuple[Decimal, int]:
168
+ """Read ``[ "-" ] , digit , { digit } , [ "." , digit , { digit } ]``.
169
+
170
+ Parsed as ``Decimal`` with the literal's declared scale preserved
171
+ (``0.50`` stays ``0.50``) -- EXPR-SPEC §2: "Numeric literals are parsed as
172
+ ``Decimal``, never ``float``."
173
+ """
174
+ index = start
175
+ if source[index] == "-":
176
+ index += 1
177
+ digits_start = index
178
+ while index < len(source) and source[index].isdecimal():
179
+ index += 1
180
+ if index == digits_start:
181
+ raise ParseError(
182
+ "a '-' must be followed by a digit; there is no arithmetic", position=start
183
+ )
184
+ if index < len(source) and source[index] == ".":
185
+ fraction_start = index + 1
186
+ index = fraction_start
187
+ while index < len(source) and source[index].isdecimal():
188
+ index += 1
189
+ if index == fraction_start:
190
+ raise ParseError("a decimal point must be followed by a digit", position=start)
191
+ text = source[start:index]
192
+ # ``isdecimal`` accepts non-ASCII decimal digits, which ``Decimal`` would
193
+ # then accept too; the grammar's ``digit`` is ASCII, so reject the rest
194
+ # rather than silently admitting U+0660 and friends.
195
+ if any(char not in "-.0123456789" for char in text):
196
+ raise ParseError("a number is written with ASCII digits", position=start)
197
+ return Decimal(text), index
198
+
199
+
200
+ def tokenize(source: str) -> Tuple[Token, ...]:
201
+ """Tokenize *source*, ending with a single ``EOF`` token.
202
+
203
+ Raises :class:`~flux_engine.expr.errors.ParseError` (``FLX-6001``) for any
204
+ character or character sequence the grammar cannot derive, and
205
+ :class:`~flux_engine.expr.errors.ReservedWordError` (``FLX-6002``) for a
206
+ word held for ``flux-expr/2``.
207
+ """
208
+ text = nfc(source)
209
+ tokens: List[Token] = []
210
+ index = 0
211
+ length = len(text)
212
+ while index < length:
213
+ char = text[index]
214
+ if char in _WHITESPACE:
215
+ index += 1
216
+ continue
217
+ if char < " " or char == "\x7f":
218
+ raise ParseError(
219
+ f"control character U+{ord(char):04X} is not whitespace in flux-expr/1",
220
+ position=index,
221
+ )
222
+ if _is_ident_start(char):
223
+ start = index
224
+ index += 1
225
+ while index < length and _is_ident_part(text[index]):
226
+ index += 1
227
+ word = text[start:index]
228
+ if word in RESERVED_WORDS:
229
+ raise ReservedWordError(
230
+ f"'{word}' is reserved for flux-expr/2 and has no meaning in flux-expr/1",
231
+ position=start,
232
+ )
233
+ keyword = _KEYWORDS.get(word)
234
+ if keyword is not None:
235
+ tokens.append(Token(keyword, word, start))
236
+ else:
237
+ tokens.append(Token(TokenKind.IDENT, word, start, word))
238
+ continue
239
+ if char.isdecimal() or char == "-":
240
+ value, end = _read_number(text, index)
241
+ tokens.append(Token(TokenKind.NUMBER, text[index:end], index, value))
242
+ index = end
243
+ continue
244
+ if char == "'":
245
+ value_str, end = _read_string(text, index)
246
+ tokens.append(Token(TokenKind.STRING, text[index:end], index, value_str))
247
+ index = end
248
+ continue
249
+ if char in _SINGLES:
250
+ tokens.append(Token(_SINGLES[char], char, index))
251
+ index += 1
252
+ continue
253
+ nxt = text[index + 1] if index + 1 < length else ""
254
+ if char == "&":
255
+ if nxt != "&":
256
+ raise ParseError("'&' is not an operator; conjunction is '&&'", position=index)
257
+ tokens.append(Token(TokenKind.AND, "&&", index))
258
+ index += 2
259
+ continue
260
+ if char == "|":
261
+ if nxt != "|":
262
+ raise ParseError("'|' is not an operator; disjunction is '||'", position=index)
263
+ tokens.append(Token(TokenKind.OR, "||", index))
264
+ index += 2
265
+ continue
266
+ if char == "=":
267
+ if nxt != "=":
268
+ raise ParseError("'=' is not an operator; equality is '=='", position=index)
269
+ tokens.append(Token(TokenKind.EQ, "==", index))
270
+ index += 2
271
+ continue
272
+ if char == "!":
273
+ if nxt == "=":
274
+ tokens.append(Token(TokenKind.NE, "!=", index))
275
+ index += 2
276
+ else:
277
+ tokens.append(Token(TokenKind.BANG, "!", index))
278
+ index += 1
279
+ continue
280
+ if char == "<":
281
+ kind, size = (TokenKind.LE, 2) if nxt == "=" else (TokenKind.LT, 1)
282
+ tokens.append(Token(kind, text[index : index + size], index))
283
+ index += size
284
+ continue
285
+ if char == ">":
286
+ kind, size = (TokenKind.GE, 2) if nxt == "=" else (TokenKind.GT, 1)
287
+ tokens.append(Token(kind, text[index : index + size], index))
288
+ index += size
289
+ continue
290
+ if char == '"':
291
+ raise ParseError(
292
+ "flux-expr/1 has no double-quoted strings; use single quotes",
293
+ position=index,
294
+ )
295
+ raise ParseError(f"unexpected character {char!r}", position=index)
296
+ tokens.append(Token(TokenKind.EOF, "", length))
297
+ return tuple(tokens)
@@ -0,0 +1,313 @@
1
+ # Copyright 2026 Agentics Transformation Limited
2
+ #
3
+ # SPDX-License-Identifier: Apache-2.0
4
+
5
+ """Pratt parser for ``flux-expr/1`` (EXPR-SPEC §1, §4).
6
+
7
+ The EBNF is reproduced here because the code is written against it clause by
8
+ clause::
9
+
10
+ expr = or_expr ;
11
+ or_expr = and_expr , { "||" , and_expr } ;
12
+ and_expr = not_expr , { "&&" , not_expr } ;
13
+ not_expr = [ "!" ] , primary ;
14
+ primary = "(" , expr , ")" | comparison | membership | method | bool_lit ;
15
+ comparison = operand , cmp_op , operand ;
16
+ membership = operand , "in" , list_lit | operand , "in" , path ;
17
+ method = path , "." , method_name , "(" , [ literal , { "," , literal } ] , ")" ;
18
+ operand = path | literal ;
19
+
20
+ The binary operators ``||`` and ``&&`` are driven by the binding-power table
21
+ :data:`_BINDING_POWER` in one loop (the Pratt shape EXPR-SPEC §4 names);
22
+ ``!`` is the single prefix operator; everything tighter is a *primary*, which
23
+ this module parses with one token of lookahead.
24
+
25
+ Two consequences of taking the EBNF literally are worth stating, because both
26
+ are commonly assumed otherwise:
27
+
28
+ * **A bare path is not an expression.** ``primary`` offers ``bool_lit`` but
29
+ not ``operand``, so a boolean attribute is written ``flag == true``, and
30
+ ``products`` on its own is ``FLX-6001``.
31
+ * **``!`` applies to a primary, not to an operand.** ``!a > 1`` therefore
32
+ derives as ``!(a > 1)``: ``not_expr = [ "!" ] , primary`` and ``primary``
33
+ includes ``comparison``. The precedence line in EXPR-SPEC §1 lists ``!`` as
34
+ tighter than comparison, but the grammar gives ``!`` nothing tighter to
35
+ apply to, so the ordering is unobservable and the EBNF decides. ``!!x`` is
36
+ not derivable and is ``FLX-6001``.
37
+ * **A method is not an operand.** ``a == b.has('x')`` is ``FLX-6001``; the
38
+ method production stands alone as a primary.
39
+ """
40
+
41
+ from __future__ import annotations
42
+
43
+ from decimal import Decimal
44
+ from typing import Dict, List, Sequence, Tuple, Union
45
+
46
+ from flux_engine.expr.ast import (
47
+ METHOD_NAMES,
48
+ And,
49
+ BoolLit,
50
+ Compare,
51
+ Expr,
52
+ In,
53
+ ListLit,
54
+ Literal,
55
+ Method,
56
+ Not,
57
+ NullLit,
58
+ NumberLit,
59
+ Operand,
60
+ Or,
61
+ Path,
62
+ StringLit,
63
+ )
64
+ from flux_engine.expr.errors import ParseError
65
+ from flux_engine.expr.lexer import COMPARISON_KINDS, Token, TokenKind, tokenize
66
+
67
+ __all__ = ["parse", "parse_tokens"]
68
+
69
+ #: Left binding power of the two infix boolean operators. ``&&`` binds
70
+ #: tighter than ``||``; both are left-associative, which the parse loop gets
71
+ #: by recursing at ``bp + 1``.
72
+ _BINDING_POWER: Dict[TokenKind, int] = {
73
+ TokenKind.OR: 1,
74
+ TokenKind.AND: 2,
75
+ }
76
+
77
+ #: Token kinds that can begin an ``operand``.
78
+ _OPERAND_STARTS = (
79
+ TokenKind.IDENT,
80
+ TokenKind.STRING,
81
+ TokenKind.NUMBER,
82
+ TokenKind.TRUE,
83
+ TokenKind.FALSE,
84
+ TokenKind.NULL,
85
+ )
86
+
87
+
88
+ class _Parser:
89
+ """One parse. Holds the token stream and the cursor; never backtracks."""
90
+
91
+ def __init__(self, tokens: Sequence[Token]) -> None:
92
+ self._tokens = tokens
93
+ self._index = 0
94
+
95
+ # --- cursor -----------------------------------------------------------
96
+
97
+ def at_end(self) -> bool:
98
+ """True when the whole token stream has been consumed."""
99
+ return self._peek().kind is TokenKind.EOF
100
+
101
+ def trailing(self) -> Token:
102
+ """The token the parse stopped at (``EOF`` on a complete parse)."""
103
+ return self._peek()
104
+
105
+ def _peek(self, offset: int = 0) -> Token:
106
+ index = min(self._index + offset, len(self._tokens) - 1)
107
+ return self._tokens[index]
108
+
109
+ def _advance(self) -> Token:
110
+ token = self._tokens[self._index]
111
+ if token.kind is not TokenKind.EOF:
112
+ self._index += 1
113
+ return token
114
+
115
+ def _expect(self, kind: TokenKind, what: str) -> Token:
116
+ token = self._peek()
117
+ if token.kind is not kind:
118
+ raise ParseError(f"expected {what}, found {token}", position=token.position)
119
+ return self._advance()
120
+
121
+ # --- expr / or_expr / and_expr ----------------------------------------
122
+
123
+ def parse_expr(self, min_bp: int = 1) -> Expr:
124
+ """``expr = or_expr`` -- the Pratt loop over ``||`` and ``&&``."""
125
+ node: Expr = self.parse_not()
126
+ while True:
127
+ token = self._peek()
128
+ bp = _BINDING_POWER.get(token.kind)
129
+ if bp is None or bp < min_bp:
130
+ return node
131
+ self._advance()
132
+ right = self.parse_expr(bp + 1)
133
+ node = Or(node, right) if token.kind is TokenKind.OR else And(node, right)
134
+
135
+ # --- not_expr ---------------------------------------------------------
136
+
137
+ def parse_not(self) -> Expr:
138
+ """``not_expr = [ "!" ] , primary``. One ``!`` only; ``!!`` is FLX-6001."""
139
+ if self._peek().kind is TokenKind.BANG:
140
+ self._advance()
141
+ if self._peek().kind is TokenKind.BANG:
142
+ raise ParseError(
143
+ "'!' applies to one primary; '!!' is not derivable",
144
+ position=self._peek().position,
145
+ )
146
+ return Not(self.parse_primary())
147
+ return self.parse_primary()
148
+
149
+ # --- primary ----------------------------------------------------------
150
+
151
+ def parse_primary(self) -> Expr:
152
+ """``primary = "(" expr ")" | comparison | membership | method | bool_lit``."""
153
+ token = self._peek()
154
+ if token.kind is TokenKind.LPAREN:
155
+ self._advance()
156
+ inner = self.parse_expr()
157
+ self._expect(TokenKind.RPAREN, "')'")
158
+ return inner
159
+ if token.kind not in _OPERAND_STARTS:
160
+ raise ParseError(f"expected a predicate, found {token}", position=token.position)
161
+
162
+ left = self._parse_operand_or_method(allow_method=True)
163
+ after = self._peek()
164
+
165
+ if after.kind in COMPARISON_KINDS:
166
+ if isinstance(left, Method):
167
+ raise ParseError(
168
+ "a method call is not an operand of a comparison",
169
+ position=after.position,
170
+ )
171
+ self._advance()
172
+ right = self._parse_operand_or_method(allow_method=False)
173
+ assert not isinstance(right, Method) # allow_method=False
174
+ return Compare(after.text, left, right)
175
+
176
+ if after.kind is TokenKind.IN:
177
+ if isinstance(left, Method):
178
+ raise ParseError(
179
+ "a method call is not an operand of 'in'",
180
+ position=after.position,
181
+ )
182
+ self._advance()
183
+ return In(left, self._parse_membership_right())
184
+
185
+ if isinstance(left, Method):
186
+ return left
187
+ if isinstance(left, BoolLit):
188
+ return left
189
+ raise ParseError(
190
+ "a bare operand is not a predicate; primary is a comparison, a "
191
+ "membership test, a method call, a boolean literal or a "
192
+ "parenthesised expression",
193
+ position=after.position,
194
+ )
195
+
196
+ # --- operand / path / method ------------------------------------------
197
+
198
+ def _parse_operand_or_method(self, *, allow_method: bool) -> Union[Operand, Method]:
199
+ """``operand = path | literal``, or -- when *allow_method* -- a ``method``."""
200
+ token = self._peek()
201
+ if token.kind is TokenKind.IDENT:
202
+ return self._parse_path_or_method(allow_method=allow_method)
203
+ return self._parse_literal()
204
+
205
+ def _parse_literal(self) -> Literal:
206
+ """``literal = string | number | bool_lit | null_lit``."""
207
+ token = self._peek()
208
+ if token.kind is TokenKind.STRING:
209
+ self._advance()
210
+ return StringLit(str(token.value))
211
+ if token.kind is TokenKind.NUMBER:
212
+ self._advance()
213
+ value = token.value
214
+ assert isinstance(value, Decimal) # the lexer decodes NUMBER to Decimal
215
+ return NumberLit(value)
216
+ if token.kind in (TokenKind.TRUE, TokenKind.FALSE):
217
+ self._advance()
218
+ return BoolLit(token.kind is TokenKind.TRUE)
219
+ if token.kind is TokenKind.NULL:
220
+ self._advance()
221
+ return NullLit()
222
+ raise ParseError(f"expected a literal, found {token}", position=token.position)
223
+
224
+ def _parse_path_or_method(self, *, allow_method: bool) -> Union[Path, Method]:
225
+ """Read ``path`` and, on the method lookahead, the whole ``method``.
226
+
227
+ ``path`` and ``method`` share their prefix, so the dotted segments are
228
+ consumed greedily until a segment is both a declared ``method_name``
229
+ and immediately followed by ``(`` -- the one-token lookahead that
230
+ separates ``products.has`` (a path) from ``products.has('tv')`` (a
231
+ method call).
232
+ """
233
+ parts: List[str] = [str(self._expect(TokenKind.IDENT, "an identifier").value)]
234
+ while self._peek().kind is TokenKind.DOT:
235
+ segment = self._peek(1)
236
+ if segment.kind is not TokenKind.IDENT:
237
+ raise ParseError(
238
+ f"expected an identifier after '.', found {segment}",
239
+ position=segment.position,
240
+ )
241
+ is_call = segment.text in METHOD_NAMES and self._peek(2).kind is TokenKind.LPAREN
242
+ if is_call:
243
+ if not allow_method:
244
+ raise ParseError(
245
+ "a method call is not an operand here",
246
+ position=segment.position,
247
+ )
248
+ self._advance() # '.'
249
+ self._advance() # method_name
250
+ args = self._parse_arguments()
251
+ return Method(Path(tuple(parts)), segment.text, args)
252
+ self._advance() # '.'
253
+ self._advance() # segment
254
+ parts.append(str(segment.value))
255
+ return Path(tuple(parts))
256
+
257
+ def _parse_arguments(self) -> Tuple[Literal, ...]:
258
+ """``"(" , [ literal , { "," , literal } ] , ")"`` -- literals only."""
259
+ self._expect(TokenKind.LPAREN, "'('")
260
+ args: List[Literal] = []
261
+ if self._peek().kind is not TokenKind.RPAREN:
262
+ args.append(self._parse_literal())
263
+ while self._peek().kind is TokenKind.COMMA:
264
+ self._advance()
265
+ args.append(self._parse_literal())
266
+ self._expect(TokenKind.RPAREN, "')'")
267
+ return tuple(args)
268
+
269
+ def _parse_membership_right(self) -> Union[ListLit, Path]:
270
+ """The right side of ``in``: a list literal or a path (``set<string>``)."""
271
+ token = self._peek()
272
+ if token.kind is TokenKind.LBRACKET:
273
+ self._advance()
274
+ items: List[Literal] = []
275
+ if self._peek().kind is not TokenKind.RBRACKET:
276
+ items.append(self._parse_literal())
277
+ while self._peek().kind is TokenKind.COMMA:
278
+ self._advance()
279
+ items.append(self._parse_literal())
280
+ self._expect(TokenKind.RBRACKET, "']'")
281
+ return ListLit(tuple(items))
282
+ if token.kind is TokenKind.IDENT:
283
+ right = self._parse_path_or_method(allow_method=False)
284
+ assert isinstance(right, Path) # allow_method=False
285
+ return right
286
+ raise ParseError(
287
+ f"the right side of 'in' is a list literal or a path, found {token}",
288
+ position=token.position,
289
+ )
290
+
291
+
292
+ def parse_tokens(tokens: Sequence[Token]) -> Expr:
293
+ """Parse an already-tokenized expression; the stream must end at ``EOF``."""
294
+ parser = _Parser(tokens)
295
+ node = parser.parse_expr()
296
+ if not parser.at_end():
297
+ rest = parser.trailing()
298
+ raise ParseError(f"unexpected {rest} after the expression", position=rest.position)
299
+ return node
300
+
301
+
302
+ def parse(source: str) -> Expr:
303
+ """Tokenize and parse *source* into a frozen AST.
304
+
305
+ Raises ``FLX-6001`` for anything the closed grammar cannot derive and
306
+ ``FLX-6002`` for a word reserved for ``flux-expr/2``. No type checking
307
+ happens here -- that is :func:`flux_engine.expr.check.check`, which needs
308
+ the attribute model.
309
+ """
310
+ tokens = tokenize(source)
311
+ if len(tokens) == 1:
312
+ raise ParseError("an expression is not empty", position=0)
313
+ return parse_tokens(tokens)