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,423 @@
1
+ # Copyright 2026 Agentics Transformation Limited
2
+ #
3
+ # SPDX-License-Identifier: Apache-2.0
4
+
5
+ """``flux-trace/1``: the closed op vocabulary and the run digest document.
6
+
7
+ Implements KERNEL-SPEC §10. The trace is the closed list of *observable
8
+ decisions* a run makes -- what a reader of the run could have watched
9
+ happen -- and nothing else. Kernel internals are never traced: a draw
10
+ count, a heap operation or a cache hit is not an observable decision, and
11
+ tracing one would make an implementation detail part of the golden.
12
+
13
+ Two consequences the code enforces rather than documents:
14
+
15
+ * the op vocabulary is closed (``FLX-2103``) and each op's field set is
16
+ exact (``FLX-2104``). A new field is a ``kernelVersion`` bump, not a
17
+ quiet addition -- which is what makes the wall-clock negative kernel of
18
+ KERNEL-SPEC §14 detectable here rather than three layers downstream.
19
+ * component digests are taken over an envelope that names the component,
20
+ so two empty components do not share one digest and a golden failure
21
+ can name which component moved.
22
+ """
23
+
24
+ from __future__ import annotations
25
+
26
+ from dataclasses import dataclass
27
+ from enum import Enum
28
+ from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple
29
+
30
+ from flux_engine.core.canonical import canonicalise
31
+ from flux_engine.core.digest import (
32
+ DigestDomain,
33
+ DigestedDocument,
34
+ DigestRef,
35
+ digest_of_document,
36
+ require_domain,
37
+ )
38
+ from flux_engine.core.errors import FluxError, register
39
+
40
+ __all__ = [
41
+ "COMPONENT_OPS",
42
+ "EXTERNAL_COMPONENTS",
43
+ "FLX_2103",
44
+ "FLX_2104",
45
+ "FLX_2105",
46
+ "GOLDEN_CHANGELOG_FILENAME",
47
+ "GoldenUpdate",
48
+ "OP_FIELDS",
49
+ "RUN_FORMAT_VERSION",
50
+ "RunComponents",
51
+ "TRACE_VERSION",
52
+ "TraceOp",
53
+ "build_run_digest_document",
54
+ "check_golden_update",
55
+ "component_digest",
56
+ "component_digests",
57
+ "component_of",
58
+ "golden_changelog_row",
59
+ "moved_components",
60
+ "require_golden_update",
61
+ "trace_record",
62
+ ]
63
+
64
+ FLX_2103 = register(
65
+ "FLX-2103",
66
+ "trace op outside the flux-trace/1 vocabulary",
67
+ "The trace vocabulary is closed (KERNEL-SPEC §10). An op the golden "
68
+ "does not know about would move every component digest under it, so a "
69
+ "new op is a kernelVersion bump with a GOLDEN-CHANGELOG row, never an "
70
+ "addition a caller can make at run time.",
71
+ )
72
+
73
+ FLX_2104 = register(
74
+ "FLX-2104",
75
+ "trace op field set does not match flux-trace/1",
76
+ "Each op in KERNEL-SPEC §10 has an exact field set: a missing field "
77
+ "leaves the trace ambiguous and an extra one puts something in the "
78
+ "golden that the vocabulary never promised -- a wall-clock reading, "
79
+ "for example, which would make two identical runs disagree.",
80
+ )
81
+
82
+ FLX_2105 = register(
83
+ "FLX-2105",
84
+ "golden update without a reason and a changelog row",
85
+ "Moving a golden baseline is a deliberate act (KERNEL-SPEC §10): "
86
+ "--update-golden requires --reason, and the new baseline must be "
87
+ "recorded as a GOLDEN-CHANGELOG.md row naming the components that "
88
+ "moved. Without both, a silent regression and an intended change look "
89
+ "the same in the history.",
90
+ )
91
+
92
+ #: KERNEL-SPEC §1: the trace wire version, carried in the receipt and in
93
+ #: the run digest document.
94
+ TRACE_VERSION = "flux-trace/1"
95
+
96
+ #: KERNEL-SPEC §10: the shape version of ``run-digest.json``.
97
+ RUN_FORMAT_VERSION = 1
98
+
99
+ #: The file that records every deliberate golden move.
100
+ GOLDEN_CHANGELOG_FILENAME = "GOLDEN-CHANGELOG.md"
101
+
102
+
103
+ class TraceOp(str, Enum):
104
+ """The eleven observable decisions of KERNEL-SPEC §10."""
105
+
106
+ COHORT = "cohort"
107
+ MARKET = "market"
108
+ TRAIT = "trait"
109
+ SIGNAL = "signal"
110
+ DETECT = "detect"
111
+ TRANSITION = "transition"
112
+ DELIVER = "deliver"
113
+ SUPPRESS = "suppress"
114
+ ASSIGN = "assign"
115
+ EMIT = "emit"
116
+ DECISION = "decision"
117
+
118
+
119
+ #: The exact field set of each op, in the order KERNEL-SPEC §10's table
120
+ #: lists them. The order is documentation only -- JCS sorts object keys --
121
+ #: but it keeps this table readable next to the specification.
122
+ OP_FIELDS: Mapping[TraceOp, Tuple[str, ...]] = {
123
+ TraceOp.COHORT: ("worldId", "lifecycle", "count"),
124
+ TraceOp.MARKET: ("ordinal", "market"),
125
+ TraceOp.TRAIT: ("ordinal", "name", "value"),
126
+ TraceOp.SIGNAL: ("t", "signalId", "ordinal", "occurrence", "payloadDigest"),
127
+ TraceOp.DETECT: ("t", "detectorId", "ordinal", "firstT", "lastT", "eventCount"),
128
+ TraceOp.TRANSITION: (
129
+ "t",
130
+ "journeyId",
131
+ "ordinal",
132
+ "fromState",
133
+ "toState",
134
+ "outcome",
135
+ "success",
136
+ ),
137
+ TraceOp.DELIVER: ("t", "campaignId", "ordinal", "channelId"),
138
+ TraceOp.SUPPRESS: ("t", "campaignId", "ordinal", "reasonCode"),
139
+ TraceOp.ASSIGN: ("experimentId", "ordinal", "variant"),
140
+ TraceOp.EMIT: ("exposeId", "rowIndex"),
141
+ TraceOp.DECISION: ("seq", "policyDigest", "reasonCode", "allow"),
142
+ }
143
+
144
+ #: KERNEL-SPEC §10's component grouping. The five components whose digest
145
+ #: is taken over trace ops; ``emits`` and ``decisions`` are digested
146
+ #: elsewhere (see :data:`EXTERNAL_COMPONENTS`).
147
+ COMPONENT_OPS: Mapping[str, Tuple[TraceOp, ...]] = {
148
+ "population": (TraceOp.COHORT, TraceOp.MARKET, TraceOp.TRAIT),
149
+ "events": (TraceOp.SIGNAL, TraceOp.DETECT),
150
+ "journeys": (TraceOp.TRANSITION,),
151
+ "delivery": (TraceOp.DELIVER, TraceOp.SUPPRESS),
152
+ "assignment": (TraceOp.ASSIGN,),
153
+ }
154
+
155
+ #: The two components of the run digest that are **not** digests of trace
156
+ #: ops: ``emits`` carries the per-expose ``outputDigest`` of KERNEL-SPEC §8
157
+ #: (domain ``jcs-ndjson-stream``, computed above the sink) and
158
+ #: ``decisions`` is the raw bytes of ``decisions.ndjson``. The ``emit``
159
+ #: and ``decision`` trace ops still exist -- they are what a reader
160
+ #: watches -- but their digest comes from the artifact, not from the
161
+ #: trace, so the artifact and the trace cannot disagree unnoticed.
162
+ EXTERNAL_COMPONENTS: Tuple[str, ...] = ("emits", "decisions")
163
+
164
+ _OP_COMPONENT: Mapping[TraceOp, str] = {
165
+ op: component for component, ops in COMPONENT_OPS.items() for op in ops
166
+ }
167
+
168
+
169
+ def _as_op(op: Any) -> TraceOp:
170
+ if isinstance(op, TraceOp):
171
+ return op
172
+ try:
173
+ return TraceOp(op)
174
+ except ValueError:
175
+ raise FluxError(FLX_2103, f"op {op!r}") from None
176
+
177
+
178
+ def component_of(op: Any) -> Optional[str]:
179
+ """Return the component *op* belongs to, or ``None`` for emit/decision.
180
+
181
+ ``emit`` and ``decision`` are traced but their component digests come
182
+ from the emit stream and ``decisions.ndjson`` respectively -- see
183
+ :data:`EXTERNAL_COMPONENTS`.
184
+ """
185
+ return _OP_COMPONENT.get(_as_op(op))
186
+
187
+
188
+ def trace_record(op: Any, **fields: Any) -> Dict[str, Any]:
189
+ """Return one canonical ``flux-trace/1`` record.
190
+
191
+ Validates the op against the closed vocabulary (``FLX-2103``) and the
192
+ field set against KERNEL-SPEC §10's table (``FLX-2104``), then
193
+ canonicalises the values -- so a float, a ``datetime``, or any other
194
+ class with no canonical spelling is refused here rather than at the
195
+ digest, where the diagnostic would name a byte offset instead of a
196
+ field.
197
+ """
198
+ trace_op = _as_op(op)
199
+ expected = set(OP_FIELDS[trace_op])
200
+ given = set(fields)
201
+ if given != expected:
202
+ missing = sorted(expected - given)
203
+ unexpected = sorted(given - expected)
204
+ detail = f"op {trace_op.value!r}"
205
+ if missing:
206
+ detail += f", missing {missing}"
207
+ if unexpected:
208
+ detail += f", unexpected {unexpected}"
209
+ raise FluxError(FLX_2104, detail)
210
+ record: Dict[str, Any] = {"op": trace_op.value}
211
+ for name in OP_FIELDS[trace_op]:
212
+ record[name] = canonicalise(fields[name])
213
+ return record
214
+
215
+
216
+ def _records_for(component: str, records: Iterable[Mapping[str, Any]]) -> List[Dict[str, Any]]:
217
+ allowed = {op.value for op in COMPONENT_OPS[component]}
218
+ checked: List[Dict[str, Any]] = []
219
+ for index, record in enumerate(records):
220
+ op = record.get("op")
221
+ if op not in allowed:
222
+ raise FluxError(
223
+ FLX_2104,
224
+ f"record {index} carries op {op!r}, which is not part of the "
225
+ f"{component!r} component",
226
+ )
227
+ checked.append(dict(record))
228
+ return checked
229
+
230
+
231
+ def component_digest(component: str, records: Iterable[Mapping[str, Any]]) -> DigestRef:
232
+ """Digest one trace component (KERNEL-SPEC §10).
233
+
234
+ The digest is taken over an envelope that names the component and the
235
+ trace version, not over the bare op list: two components that are both
236
+ empty on a given run must not share one digest, or a golden failure
237
+ could not name which one moved.
238
+ """
239
+ if component not in COMPONENT_OPS:
240
+ raise FluxError(
241
+ FLX_2103,
242
+ f"component {component!r} is not one of {sorted(COMPONENT_OPS)}",
243
+ )
244
+ envelope = {
245
+ "traceVersion": TRACE_VERSION,
246
+ "component": component,
247
+ "ops": _records_for(component, records),
248
+ }
249
+ return digest_of_document(envelope, subject=f"{component}Digest")
250
+
251
+
252
+ def component_digests(records: Iterable[Mapping[str, Any]]) -> Dict[str, DigestRef]:
253
+ """Digest all five trace components of one run's *records*.
254
+
255
+ Records are partitioned by op into the components of
256
+ :data:`COMPONENT_OPS`, preserving their emission order within each
257
+ component -- the scheduler's order is part of what the golden pins.
258
+ ``emit`` and ``decision`` records are ignored here; their digests come
259
+ from the artifacts (see :data:`EXTERNAL_COMPONENTS`).
260
+ """
261
+ grouped: Dict[str, List[Mapping[str, Any]]] = {name: [] for name in COMPONENT_OPS}
262
+ for index, record in enumerate(records):
263
+ op = record.get("op")
264
+ if op is None:
265
+ raise FluxError(FLX_2104, f"record {index} has no 'op' field")
266
+ trace_op = _as_op(op)
267
+ component = _OP_COMPONENT.get(trace_op)
268
+ if component is not None:
269
+ grouped[component].append(record)
270
+ return {name: component_digest(name, grouped[name]) for name in sorted(grouped)}
271
+
272
+
273
+ @dataclass(frozen=True)
274
+ class RunComponents:
275
+ """The ``components`` block of the run digest document (KERNEL-SPEC §10)."""
276
+
277
+ population: DigestRef
278
+ events: DigestRef
279
+ journeys: DigestRef
280
+ delivery: DigestRef
281
+ assignment: DigestRef
282
+ emits: Mapping[str, DigestRef]
283
+ decisions: DigestRef
284
+
285
+ def as_document(self) -> Dict[str, Any]:
286
+ """Render as the canonical block, checking each reference's domain.
287
+
288
+ The domains are part of the claim: the five trace components are
289
+ ``jcs-document``, a per-expose ``outputDigest`` is the
290
+ ``jcs-ndjson-stream`` of KERNEL-SPEC §8, and ``decisions`` is the
291
+ raw bytes of ``decisions.ndjson``. A reference in the wrong domain
292
+ is ``FLX-1002`` here rather than a mismatch nobody can explain
293
+ later.
294
+ """
295
+ block: Dict[str, Any] = {
296
+ "population": require_domain(self.population, DigestDomain.JCS_DOCUMENT).value,
297
+ "events": require_domain(self.events, DigestDomain.JCS_DOCUMENT).value,
298
+ "journeys": require_domain(self.journeys, DigestDomain.JCS_DOCUMENT).value,
299
+ "delivery": require_domain(self.delivery, DigestDomain.JCS_DOCUMENT).value,
300
+ "assignment": require_domain(self.assignment, DigestDomain.JCS_DOCUMENT).value,
301
+ "emits": {
302
+ expose_id: require_domain(
303
+ self.emits[expose_id], DigestDomain.JCS_NDJSON_STREAM
304
+ ).value
305
+ for expose_id in sorted(self.emits)
306
+ },
307
+ "decisions": require_domain(self.decisions, DigestDomain.RAW_BYTES).value,
308
+ }
309
+ return block
310
+
311
+
312
+ def build_run_digest_document(
313
+ *,
314
+ kernel_version: str,
315
+ input_digest: DigestRef,
316
+ plan_digest: DigestRef,
317
+ components: RunComponents,
318
+ ) -> DigestedDocument:
319
+ """Build the run digest document and its digest (KERNEL-SPEC §10).
320
+
321
+ ``golden.baselineDigest`` is exactly the returned reference's value:
322
+ a golden comparison is one string comparison, and the component block
323
+ beneath it is what :func:`moved_components` reads to name what moved.
324
+ """
325
+ document: Dict[str, Any] = {
326
+ "runFormatVersion": RUN_FORMAT_VERSION,
327
+ "traceVersion": TRACE_VERSION,
328
+ "kernelVersion": kernel_version,
329
+ "inputDigest": require_domain(input_digest, DigestDomain.JCS_DOCUMENT).value,
330
+ "planDigest": require_domain(plan_digest, DigestDomain.JCS_DOCUMENT).value,
331
+ "components": components.as_document(),
332
+ }
333
+ return DigestedDocument(
334
+ document=document,
335
+ ref=digest_of_document(document, subject="runDigest"),
336
+ )
337
+
338
+
339
+ def moved_components(
340
+ previous: Mapping[str, Any],
341
+ current: Mapping[str, Any],
342
+ ) -> Tuple[str, ...]:
343
+ """Name the components that differ between two ``components`` blocks.
344
+
345
+ KERNEL-SPEC §10: "A golden failure names the component that moved."
346
+ Nested ``emits`` entries are reported as ``emits.<exposeId>``, and an
347
+ expose that appears on only one side is reported too -- an emit that
348
+ stopped being produced has moved as surely as one whose rows changed.
349
+ """
350
+ moved: List[str] = []
351
+ for name in sorted(set(previous) | set(current)):
352
+ before = previous.get(name)
353
+ after = current.get(name)
354
+ if isinstance(before, Mapping) or isinstance(after, Mapping):
355
+ before_map: Mapping[str, Any] = before if isinstance(before, Mapping) else {}
356
+ after_map: Mapping[str, Any] = after if isinstance(after, Mapping) else {}
357
+ for key in sorted(set(before_map) | set(after_map)):
358
+ if before_map.get(key) != after_map.get(key):
359
+ moved.append(f"{name}.{key}")
360
+ elif before != after:
361
+ moved.append(name)
362
+ return tuple(moved)
363
+
364
+
365
+ @dataclass(frozen=True)
366
+ class GoldenUpdate:
367
+ """One deliberate move of a golden baseline.
368
+
369
+ ``components`` names what moved (from :func:`moved_components`), so
370
+ the changelog row says which part of the run changed rather than only
371
+ that the digest did.
372
+ """
373
+
374
+ kernel_version: str
375
+ previous_digest: Optional[str]
376
+ new_digest: str
377
+ reason: str
378
+ components: Sequence[str] = ()
379
+
380
+
381
+ def golden_changelog_row(update: GoldenUpdate) -> str:
382
+ """Render *update* as the ``GOLDEN-CHANGELOG.md`` table row.
383
+
384
+ One row, one deliberate move: kernel version, the digest before and
385
+ after, the components that moved, and the reason the author gave.
386
+ """
387
+ components = ", ".join(update.components) if update.components else "-"
388
+ previous = update.previous_digest or "-"
389
+ reason = update.reason.strip().replace("|", "/").replace("\n", " ")
390
+ return (
391
+ f"| {update.kernel_version} | {previous} | {update.new_digest} | {components} | {reason} |"
392
+ )
393
+
394
+
395
+ def check_golden_update(update: GoldenUpdate, changelog: str) -> Tuple[str, ...]:
396
+ """Return the reasons *update* is not admissible, or an empty tuple.
397
+
398
+ Checks, in order: a non-empty reason of real content; a new digest
399
+ that differs from the previous one (a "move" that moves nothing is a
400
+ mistake, not a golden update); and a ``GOLDEN-CHANGELOG.md`` body that
401
+ already carries a row for the new digest.
402
+ """
403
+ problems: List[str] = []
404
+ reason = update.reason.strip()
405
+ if not reason:
406
+ problems.append("--reason is required and must say why the baseline moved")
407
+ elif len(reason) < 8:
408
+ problems.append(f"--reason {reason!r} is too short to explain a baseline move")
409
+ if update.previous_digest is not None and update.previous_digest == update.new_digest:
410
+ problems.append("the new baseline equals the previous one: nothing moved")
411
+ if update.new_digest not in changelog:
412
+ problems.append(
413
+ f"{GOLDEN_CHANGELOG_FILENAME} has no row for {update.new_digest}; "
414
+ "add the row emitted by golden_changelog_row()"
415
+ )
416
+ return tuple(problems)
417
+
418
+
419
+ def require_golden_update(update: GoldenUpdate, changelog: str) -> None:
420
+ """Raise ``FLX-2105`` unless *update* passes :func:`check_golden_update`."""
421
+ problems = check_golden_update(update, changelog)
422
+ if problems:
423
+ raise FluxError(FLX_2105, "; ".join(problems))
@@ -0,0 +1,207 @@
1
+ # Copyright 2026 Agentics Transformation Limited
2
+ #
3
+ # SPDX-License-Identifier: Apache-2.0
4
+
5
+ """Library-level self-description for the FLUX Simulation Engine.
6
+
7
+ Importable as: ``from flux_engine.describe import self_describe``.
8
+ Pattern adapted from ``pulumi about --json`` (flat object, top-level keys
9
+ per category) -- the same pattern ``fluid_build.describe.self_describe``
10
+ uses on the FLUID side, so a future host application's backend route can
11
+ treat both engines uniformly. ``commands`` follows
12
+ ``fluid_build.describe._command_tree``'s own port of that same
13
+ introspection idiom (see this repo's CLAUDE.md north star: "``fluid
14
+ describe --format=json`` returns the full command tree + flag list +
15
+ output schemas + provider capabilities, so CC can generate UI dynamically
16
+ and never lag the CLI" -- this module is that promise on the FLUX side).
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import argparse
22
+ import importlib.util
23
+ import sys
24
+ from typing import Any, Dict, List, Tuple
25
+
26
+ from flux_engine import __version__
27
+ from flux_engine.spec import SOURCE
28
+
29
+ __all__ = ["installed_spec_version", "self_describe"]
30
+
31
+ #: The FLUX spec version the **vendored** validator/enforcement copy in
32
+ #: ``flux_engine._vendor.flux_spec`` implements (RFC-04 + RFC-09, v0.5.0 per
33
+ #: the approved plan). It is the answer only while the vendored fallback is
34
+ #: what this installation runs on -- see :func:`installed_spec_version`.
35
+ VENDORED_SPEC_VERSION = "0.5.0"
36
+
37
+ #: The pre-0.2 spelling of :data:`VENDORED_SPEC_VERSION`, kept so a caller
38
+ #: that imported the old name still resolves.
39
+ SPEC_VERSION = VENDORED_SPEC_VERSION
40
+
41
+ #: The distribution :data:`flux_engine.spec.SOURCE` names when the public
42
+ #: package is installed. Its version, not a constant in this file, is what a
43
+ #: host is told it is talking to.
44
+ _SPEC_DISTRIBUTION = "flux-spec"
45
+
46
+
47
+ def installed_spec_version() -> str:
48
+ """The FLUX spec version this installation actually runs against.
49
+
50
+ Read from the installed ``flux-spec`` distribution's own metadata when
51
+ :data:`flux_engine.spec.SOURCE` says that distribution is what is in
52
+ use, so an environment holding a newer spec is reported as holding a
53
+ newer spec. Falls back to :data:`VENDORED_SPEC_VERSION` when the
54
+ vendored copy is what is running, and when the distribution is present
55
+ but declares no metadata this engine can read.
56
+ """
57
+ if SOURCE != "flux_spec":
58
+ return VENDORED_SPEC_VERSION
59
+ from importlib.metadata import PackageNotFoundError, version
60
+
61
+ try:
62
+ return version(_SPEC_DISTRIBUTION)
63
+ except PackageNotFoundError: # pragma: no cover - exercised once flux_spec ships
64
+ return VENDORED_SPEC_VERSION
65
+
66
+
67
+ #: Capabilities this engine implements itself. They are present in every
68
+ #: installation -- the code that provides them is inside ``flux_engine`` --
69
+ #: so probing for a third-party import to decide whether to report them
70
+ #: answered the wrong question. It reported ``lineage`` false on a build
71
+ #: whose every run writes OpenLineage RunEvents, and ``calibrate`` false on
72
+ #: a build that ships ``fluxsim calibrate``; a host application reading this
73
+ #: document would have hidden two working features.
74
+ _ENGINE_CAPABILITIES: Tuple[str, ...] = (
75
+ "accuracy",
76
+ "calibrate",
77
+ "evidence",
78
+ "expr",
79
+ "fidelity",
80
+ "gate",
81
+ "generator",
82
+ "lineage",
83
+ )
84
+
85
+ #: Optional *backends* -- distributions this engine can use when they are
86
+ #: installed and does without when they are not. These are the only names
87
+ #: an import probe can honestly answer, and each is named for the backend
88
+ #: rather than for the feature, so "the pyabc backend is absent" can never
89
+ #: again be read as "calibration is absent".
90
+ _CAPABILITY_MODULES: Dict[str, str] = {
91
+ "agentic": "flux_engine_agentic",
92
+ "calibrate_abc": "pyabc",
93
+ "lineage_transport": "openlineage",
94
+ "synth": "synthcity",
95
+ }
96
+
97
+
98
+ def _detect_capabilities() -> Dict[str, bool]:
99
+ detected: Dict[str, bool] = {name: True for name in _ENGINE_CAPABILITIES}
100
+ for name, module in _CAPABILITY_MODULES.items():
101
+ try:
102
+ detected[name] = importlib.util.find_spec(module) is not None
103
+ except (ImportError, ValueError, ModuleNotFoundError):
104
+ detected[name] = False
105
+ return detected
106
+
107
+
108
+ def _describe_action(action: "argparse.Action") -> Dict[str, Any]:
109
+ """One argparse option/positional -> a JSON-safe flag descriptor.
110
+
111
+ Ported from ``fluid_build.describe._describe_action`` verbatim (see
112
+ the module docstring's borrow-before-build note): the two engines'
113
+ downstream consumers read one shape.
114
+ """
115
+ default = action.default
116
+ if default is argparse.SUPPRESS or not isinstance(default, (str, int, float, bool, type(None))):
117
+ default = None if default is argparse.SUPPRESS else str(default)
118
+ return {
119
+ "names": list(action.option_strings), # [] for a positional
120
+ "dest": action.dest,
121
+ "positional": not action.option_strings,
122
+ "required": bool(getattr(action, "required", False)),
123
+ "help": action.help or "",
124
+ "choices": [str(c) for c in action.choices] if action.choices else None,
125
+ "default": default,
126
+ "metavar": action.metavar,
127
+ }
128
+
129
+
130
+ def _command_tree(parser: "argparse.ArgumentParser", _depth: int = 0) -> Dict[str, Any]:
131
+ """Introspect an argparse parser into a ``{options, subcommands}`` tree.
132
+
133
+ Ported from ``fluid_build.describe._command_tree``. Walks
134
+ ``parser._actions`` for flags and the ``_SubParsersAction`` for
135
+ subcommands -- the standard argparse-introspection idiom argparse
136
+ itself has no public API for, but that shtab and argparse-manpage
137
+ read the same private attributes to get. Read-only: no parsing, no
138
+ side effects. Aliases (several names -> one subparser) are
139
+ de-duplicated under ``aliases``.
140
+ """
141
+ options: List[Dict[str, Any]] = []
142
+ subcommands: Dict[str, Any] = {}
143
+ if _depth > 8: # defensive recursion guard
144
+ return {"options": options, "subcommands": subcommands}
145
+ for action in parser._actions:
146
+ if isinstance(action, argparse._SubParsersAction):
147
+ helps = {a.dest: (a.help or "") for a in (action._choices_actions or [])}
148
+ seen: Dict[int, str] = {}
149
+ for name, sub in action.choices.items():
150
+ if id(sub) in seen:
151
+ subcommands[seen[id(sub)]].setdefault("aliases", []).append(name)
152
+ continue
153
+ seen[id(sub)] = name
154
+ subcommands[name] = {
155
+ "help": helps.get(name, ""),
156
+ **_command_tree(sub, _depth + 1),
157
+ }
158
+ elif isinstance(action, argparse._HelpAction):
159
+ continue
160
+ else:
161
+ options.append(_describe_action(action))
162
+ return {"options": options, "subcommands": subcommands}
163
+
164
+
165
+ def self_describe() -> Dict[str, Any]:
166
+ """Return a machine-readable description of this flux_engine installation.
167
+
168
+ Returns a dict with stable keys:
169
+ - component: always "FLUX Simulation Engine" (the canon name)
170
+ - version: flux_engine's own version
171
+ - python_version: the running interpreter's version
172
+ - spec_source: "flux_spec" | "vendored" (see flux_engine.spec.SOURCE)
173
+ - spec_version: the FLUX spec version this installation runs
174
+ against -- the installed ``flux-spec`` distribution's own version
175
+ when that distribution is the source, the vendored copy's version
176
+ otherwise (:func:`installed_spec_version`)
177
+ - capabilities: dict[str, bool]. The engine's own capabilities
178
+ (:data:`_ENGINE_CAPABILITIES`) are always true -- the code that
179
+ provides them ships in this package. The optional backends
180
+ (:data:`_CAPABILITY_MODULES`) are derived by import probing, so
181
+ ``capabilities["agentic"]`` is False unless the separate
182
+ ``flux-engine-agentic`` distribution is installed.
183
+ - commands: dict -- the CLI's argparse command tree (per-command
184
+ options plus nested subcommands), so a consumer can render
185
+ command/flag UI dynamically and never lag the CLI. Never lets a
186
+ parser-construction issue crash ``describe`` itself: an import or
187
+ build failure degrades to ``{"options": [], "subcommands": {},
188
+ "error": "..."}`` rather than propagating.
189
+ """
190
+ try:
191
+ from flux_engine.cli import build_parser
192
+
193
+ commands = _command_tree(build_parser())
194
+ except Exception as exc: # describe must never crash on a parser-construction issue
195
+ commands = {"options": [], "subcommands": {}, "error": str(exc)[:160]}
196
+
197
+ return {
198
+ "component": "FLUX Simulation Engine",
199
+ "version": __version__,
200
+ "python_version": (
201
+ f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
202
+ ),
203
+ "spec_source": SOURCE,
204
+ "spec_version": installed_spec_version(),
205
+ "capabilities": _detect_capabilities(),
206
+ "commands": commands,
207
+ }