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,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))
|
flux_engine/describe.py
ADDED
|
@@ -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
|
+
}
|