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,1129 @@
1
+ # Copyright 2026 Agentics Transformation Limited
2
+ #
3
+ # SPDX-License-Identifier: Apache-2.0
4
+
5
+ """``fluxsim verify``: artifact re-derivation, golden regression, rows, RFC-04, fidelity.
6
+
7
+ Five independent checks over an already-applied run directory, each
8
+ answerable without re-running the simulation:
9
+
10
+ 0. **The bundle, and the artifacts.** Before anything else, three
11
+ re-derivations that decide whether the run directory still describes
12
+ the bundle it was given and still holds the bytes its digest was taken
13
+ over:
14
+
15
+ * ``plan.json`` is read back and confirmed to belong to the directory
16
+ holding it (:func:`~flux_engine.stages.apply.load_recorded_plan`,
17
+ ``FLX-2113``). ``apply`` and ``ship`` both did this; ``verify`` read
18
+ no plan at all, so ``cp -R runs/<real> runs/<other>`` and ``fluxsim
19
+ verify --run-id <other>`` exited 0 over a directory whose plan names
20
+ a different run -- every file in the copy agreeing with every other
21
+ file in the copy is exactly why the internal checks passed.
22
+ * the bundle's ``inputDigest`` is recomputed from the directory named
23
+ on the command line and compared with the receipt's (``FLX-2101``).
24
+ ``bundle`` is a required argument of this command, and until this
25
+ check existed the stage never read it: any path at all -- a typo, a
26
+ deleted directory, a different bundle -- produced the same verdict.
27
+ * every entry of KERNEL-SPEC §10's ``components`` map is recomputed
28
+ from the artifacts on disk (:func:`recompute_components`) and
29
+ compared with ``run-digest.json`` (``FLX-2110``). The golden leg
30
+ below hashes the *document*; this leg hashes what the document
31
+ claims to describe. Without it, an emit stream edited after ``apply``
32
+ wrote it -- the shipped data itself -- passed every leg of this
33
+ stage and shipped inside a signed evidence archive.
34
+
35
+ 1. **Golden regression** -- the run's ``runDigest`` against the recorded
36
+ baseline for this Simulation. No baseline yet is
37
+ :attr:`~flux_engine.api.verdict.Reproducibility.NOT_CHECKED`, not a
38
+ silent pass; a moved digest names the components that moved
39
+ (:func:`flux_engine.core.trace.moved_components`). A moved digest whose
40
+ component map is nevertheless identical -- the edit was one no part of
41
+ the simulation reads -- is reported as such (``outputsIdentical``,
42
+ :data:`INPUT_ONLY_DETAIL`) rather than as an unexplained mismatch.
43
+ 2. **Row conformance** -- every emitted stream's row count matches its
44
+ receipt and every row's width matches the column count its seam
45
+ attestation declares. Not merely that the rows agree with *each
46
+ other*: a stream whose every row is uniformly the wrong width agrees
47
+ with itself and matches nothing that was declared. A line that is not
48
+ JSON at all is a named problem here (``<exposeId>: line N is not
49
+ JSON``), never an uncaught ``JSONDecodeError`` that aborts the stage
50
+ and suppresses the remaining legs. (The stronger per-value check
51
+ already ran once, inside :class:`~flux_engine.seam.emit.EmitWriter`,
52
+ at ``apply`` time -- a row that violated KERNEL-SPEC §9 was never
53
+ written. This is a second, independent read of what actually landed on
54
+ disk.)
55
+ 3. **RFC-04 vector replay** -- :func:`flux_engine.governance.gate.run_conformance_vectors`
56
+ against the bundled enforcement vectors.
57
+ 4. **Fidelity** -- SEAM-FIDELITY-SPEC §2-§8, per emit. An emit with no
58
+ declared ``fidelity`` block in its ``extensions`` entry reports
59
+ ``"not declared"``.
60
+ One that declares a block but was given no ``--committed-slice`` on the
61
+ command line reports ``"declared, not checked"`` -- this build has no
62
+ pipeline that produces a committed real-data slice on its own (see the
63
+ REQUEST in this stage's build report), so the boundary state a check
64
+ needs has to come from the caller. Given a slice, the full commit ->
65
+ verify pipeline of :mod:`flux_engine.concordance` runs and the result is
66
+ ``"passed"``/``"failed"``.
67
+
68
+ When a prior ``ship`` left a ``fidelity-record-<exposeId>.json`` in the
69
+ run directory, this leg also checks that record's signature against the
70
+ anchor ``--trust-key``/``--signing-key`` supplied
71
+ (:func:`trust_anchor_for`, :func:`_record_signature_leg`). ``ship``
72
+ prints ``fluxsim verify`` as the command a reader outside the process runs
73
+ to reach the same conclusion from the pack, and ``verify`` could not be
74
+ given a trust anchor at all -- so the one signature state that says
75
+ *who* signed was reachable from ``ship`` and from nowhere else. With no
76
+ anchor the check reports itself ``"not checked"``: a record's own key is
77
+ never promoted to a trust anchor.
78
+
79
+ The headline (:meth:`~flux_engine.api.verdict.VerifyVerdict.headline`)
80
+ never conflates any of this with **validity**: nothing in this engine
81
+ measures a predicted outcome against the world, so ``validity`` is always
82
+ :attr:`~flux_engine.api.verdict.Validity.NOT_ASSERTED`.
83
+ """
84
+
85
+ from __future__ import annotations
86
+
87
+ import json
88
+ from pathlib import Path
89
+ from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple, Union
90
+
91
+ from flux_engine.api.stages import StageResult
92
+ from flux_engine.api.verdict import Reproducibility, Validity, VerifyVerdict
93
+ from flux_engine.concordance.gate import PackedEmit
94
+ from flux_engine.core.artifact import write_artifact
95
+ from flux_engine.core.canonical import canonical_bytes
96
+ from flux_engine.core.digest import digest_of_bytes, digest_of_document, digest_of_stream
97
+ from flux_engine.core.errors import FluxError
98
+ from flux_engine.core.trace import (
99
+ COMPONENT_OPS,
100
+ GoldenUpdate,
101
+ check_golden_update,
102
+ component_digest,
103
+ golden_changelog_row,
104
+ moved_components,
105
+ )
106
+ from flux_engine.governance.gate import run_conformance_vectors
107
+ from flux_engine.seam.emit import EMIT_LABEL
108
+ from flux_engine.spec import default_vectors_path
109
+ from flux_engine.stages import pipeline as _pipeline
110
+ from flux_engine.stages.apply import load_recorded_plan
111
+ from flux_engine.stages.errors import (
112
+ FLX_2114,
113
+ InputDigestMoved,
114
+ NoAppliedRun,
115
+ RunArtifactsMoved,
116
+ UnknownCommittedSliceExpose,
117
+ )
118
+ from flux_engine.stages.layout import (
119
+ EVENTS_LEDGER_COMPONENTS,
120
+ POPULATION_LEDGER_COMPONENTS,
121
+ RunLayout,
122
+ )
123
+
124
+ __all__ = [
125
+ "GOLDEN_REMEDY",
126
+ "GOLDEN_SNAPSHOT_SCHEMA_VERSION",
127
+ "INPUT_ONLY_DETAIL",
128
+ "component_mismatches",
129
+ "packed_emit",
130
+ "recompute_components",
131
+ "recompute_input_digest",
132
+ "require_known_slice_exposes",
133
+ "trust_anchor_for",
134
+ "verify",
135
+ ]
136
+
137
+ #: Said when the golden regression moved but every entry of the run
138
+ #: digest's own ``components`` map is identical (KERNEL-SPEC §10's
139
+ #: "a golden failure names the component that moved" -- here it names
140
+ #: none). KERNEL-SPEC §11 builds ``inputDigest`` from the *raw bytes* of
141
+ #: every bundle document, with no exemption for a comment or a metadata
142
+ #: annotation, and ``inputDigest`` is a field of the run digest document
143
+ #: (§10), so an edit that no part of the simulation reads still moves the
144
+ #: top-level ``runDigest``. Distinguishing that case from a real drift is
145
+ #: the difference between "someone retitled a document" and "the
146
+ #: generator changed", and a reader must never have to guess which.
147
+ #: Envelope version of the ``<state_dir>/golden/<simulationId>.json``
148
+ #: snapshot ``--update-golden`` writes.
149
+ GOLDEN_SNAPSHOT_SCHEMA_VERSION = "flux-golden/1"
150
+
151
+ INPUT_ONLY_DETAIL = (
152
+ "moved: no component -- every entry of run-digest.json's `components` map "
153
+ "is identical to the baseline's, so the edit was one the simulation never "
154
+ "reads (KERNEL-SPEC §11 digests the raw bytes of every bundle document, so "
155
+ "a comment, a metadata annotation or a reordered key still moves "
156
+ "inputDigest and with it the run digest)"
157
+ )
158
+
159
+ #: The remedy, said once. It used to be the closing sentence of BOTH the
160
+ #: regression line and :data:`INPUT_ONLY_DETAIL`, so the one failure printed
161
+ #: it twice, in two spellings, inside one run-on line.
162
+ GOLDEN_REMEDY = (
163
+ 're-record the baseline with `--update-golden --reason "<why>"` if the ' "move was intended"
164
+ )
165
+
166
+
167
+ def _read_json(path: Path) -> Dict[str, Any]:
168
+ return json.loads(path.read_text(encoding="utf-8"))
169
+
170
+
171
+ def _now() -> str:
172
+ """The wall clock, read here at the stage layer.
173
+
174
+ ``core.artifact.write_artifact`` takes ``generated_at`` as a required
175
+ argument precisely so the clock read happens outside the kernel; this
176
+ is the stage that supplies it.
177
+ """
178
+ from datetime import datetime, timezone
179
+
180
+ return datetime.now(timezone.utc).isoformat(timespec="seconds")
181
+
182
+
183
+ # ---------------------------------------------------------------------------
184
+ # Re-derivation: the bundle's inputDigest, and every run-digest component
185
+ # ---------------------------------------------------------------------------
186
+
187
+
188
+ def recompute_input_digest(bundle_directory: Union[str, Path]) -> str:
189
+ """Recompute KERNEL-SPEC §11's ``inputDigest`` for the bundle at *bundle_directory*.
190
+
191
+ Loads and validates the bundle and digests its declared document
192
+ bytes: the cheap half of the pipeline, with no population
193
+ materialised and no row emitted, because ``inputDigest`` is a fact
194
+ about the bundle's documents and its lockfile, and about nothing else
195
+ in the directory. A file a pack wrote beside those documents is a
196
+ product of packing the bundle rather than an input to running it, and
197
+ does not move this value.
198
+
199
+ The selection is not restated here.
200
+ :func:`flux_engine.stages.pipeline.input_digest_of` makes it, and
201
+ :func:`flux_engine.stages.pipeline.execute` calls that same function
202
+ while running, so verify time and apply time cannot drift into a
203
+ second opinion. ``tests/stages`` pins them to one code path.
204
+ """
205
+ from flux_engine.seam.resolve import load_bundle
206
+
207
+ return _pipeline.input_digest_of(load_bundle(Path(bundle_directory))).ref.value
208
+
209
+
210
+ def _emit_component_digest(layout: RunLayout, expose_id: str) -> Optional[str]:
211
+ """Recompute one emit stream's ``outputDigest`` from the bytes on disk (§8).
212
+
213
+ ``outputDigest = sha256(b"flux-emit/1\\x00" + JCS(header) + b"\\x00" +
214
+ rows)`` where *rows* is the framed row block -- which is exactly what
215
+ ``emits/<exposeId>.ndjson`` holds, byte for byte, because ``apply``
216
+ writes :meth:`~flux_engine.seam.emit.EmitWriter.stream_bytes` into it
217
+ unchanged. The header is the one the emit's seam attestation records.
218
+
219
+ ``None`` when either file is missing: the caller reports that as a
220
+ component that does not reproduce, not as a component that agrees.
221
+ """
222
+ attestation_path = layout.seam_attestation_path(expose_id)
223
+ emit_path = layout.emit_path(expose_id)
224
+ if not attestation_path.is_file() or not emit_path.is_file():
225
+ return None
226
+ try:
227
+ attestation = _read_json(attestation_path)
228
+ header = {
229
+ "exposeId": expose_id,
230
+ "columns": list(attestation["columns"]),
231
+ "types": list(attestation["types"]),
232
+ "contractDigest": attestation["reference"]["contractDigest"],
233
+ }
234
+ except (json.JSONDecodeError, KeyError, TypeError):
235
+ return None
236
+ material = EMIT_LABEL + b"\x00" + canonical_bytes(header) + b"\x00" + emit_path.read_bytes()
237
+ return digest_of_stream(material, subject=f"outputDigest:{expose_id}").value
238
+
239
+
240
+ def _ledger_records(
241
+ path: Path, components: Sequence[str]
242
+ ) -> Optional[Dict[str, List[Dict[str, Any]]]]:
243
+ """One ledger's ops, grouped by component, in file order.
244
+
245
+ ``None`` -- which the caller reads as "no component of this ledger
246
+ reproduces" -- when the file is missing, holds a line that is not
247
+ JSON, or carries an op that does not belong in it. That last case is
248
+ the reason the grouping happens here rather than per component: a
249
+ record filtered out for being the wrong op would let anything at all
250
+ be appended to a ledger without moving a digest.
251
+ """
252
+ if not path.is_file():
253
+ return None
254
+ grouped: Dict[str, List[Dict[str, Any]]] = {name: [] for name in components}
255
+ of_op = {op.value: name for name in components for op in COMPONENT_OPS[name]}
256
+ for line in path.read_text(encoding="utf-8").splitlines():
257
+ if not line:
258
+ continue
259
+ try:
260
+ record = json.loads(line)
261
+ except json.JSONDecodeError:
262
+ return None
263
+ if not isinstance(record, dict):
264
+ return None
265
+ op = record.get("op")
266
+ component = of_op.get(op) if isinstance(op, str) else None
267
+ if component is None:
268
+ return None
269
+ grouped[component].append(record)
270
+ return grouped
271
+
272
+
273
+ def recompute_components(layout: RunLayout, receipt: Mapping[str, Any]) -> Dict[str, Any]:
274
+ """Recompute KERNEL-SPEC §10's whole ``components`` map from the run directory.
275
+
276
+ One entry per component, derived from the artifact that component's
277
+ digest was taken over and from nothing else:
278
+
279
+ * ``emits.<exposeId>`` -- the framed stream digest over
280
+ ``emits/<exposeId>.ndjson`` (§8);
281
+ * ``decisions`` -- the raw bytes of ``decisions.ndjson``;
282
+ * the five trace components -- :func:`~flux_engine.core.trace.component_digest`
283
+ over their ops as the ledgers hold them (:data:`~flux_engine.stages.layout.COMPONENT_LEDGER`),
284
+ which ``apply`` writes in the emission order the digest was computed in.
285
+
286
+ A component whose artifact is missing or unreadable is ``None``: the
287
+ comparison below treats that as "does not reproduce", never as a pass.
288
+ """
289
+ components: Dict[str, Any] = {}
290
+ for ledger in (POPULATION_LEDGER_COMPONENTS, EVENTS_LEDGER_COMPONENTS):
291
+ grouped = _ledger_records(layout.ledger_path(ledger[0]), ledger)
292
+ for name in ledger:
293
+ components[name] = (
294
+ None if grouped is None else component_digest(name, grouped[name]).value
295
+ )
296
+ decisions_path = layout.decisions_path
297
+ components["decisions"] = (
298
+ digest_of_bytes(decisions_path.read_bytes(), subject="decisionsDigest").value
299
+ if decisions_path.is_file()
300
+ else None
301
+ )
302
+ components["emits"] = {
303
+ expose_id: _emit_component_digest(layout, expose_id)
304
+ for expose_id in sorted(receipt.get("emits", {}))
305
+ }
306
+ return components
307
+
308
+
309
+ def component_mismatches(
310
+ layout: RunLayout, receipt: Mapping[str, Any], recorded: Mapping[str, Any]
311
+ ) -> Tuple[str, ...]:
312
+ """Name every component of *recorded* the run directory no longer reproduces.
313
+
314
+ ``recorded`` is ``run-digest.json``'s own ``components`` block. Names
315
+ are the ones KERNEL-SPEC §10 uses, with a per-expose stream reported
316
+ as ``emits.<exposeId>`` -- the same spelling
317
+ :func:`~flux_engine.core.trace.moved_components` gives a golden
318
+ failure, so one vocabulary covers both.
319
+ """
320
+ recomputed = recompute_components(layout, receipt)
321
+ return moved_components(dict(recorded), recomputed)
322
+
323
+
324
+ def require_known_slice_exposes(
325
+ receipt: Mapping[str, Any], committed_slice: Mapping[str, str]
326
+ ) -> None:
327
+ """Refuse (``FLX-2111``) a ``--committed-slice`` naming an expose the run has no emit for.
328
+
329
+ Slices are consumed by lookup (``slices.get(expose_id)``), so a
330
+ mistyped id was never looked up, never warned about and never
331
+ reported: the flag silently vanished and the emit it was meant for was
332
+ reported as having no slice, telling the caller to pass an argument
333
+ they had just passed.
334
+ """
335
+ known = sorted(receipt.get("emits", {}))
336
+ unknown = sorted(set(committed_slice) - set(known))
337
+ if unknown:
338
+ raise UnknownCommittedSliceExpose(unknown=unknown, known=known)
339
+
340
+
341
+ def _decoded_rows(emit_path: Path, expose_id: str) -> Tuple[List[List[Any]], List[str]]:
342
+ """Decode every row of an emit stream; a bad line is a problem, not an exception."""
343
+ rows: List[List[Any]] = []
344
+ problems: List[str] = []
345
+ for index, line in enumerate(emit_path.read_text(encoding="utf-8").splitlines()):
346
+ if not line:
347
+ continue
348
+ try:
349
+ rows.append(json.loads(line))
350
+ except json.JSONDecodeError:
351
+ problems.append(f"{expose_id}: line {index + 1} is not JSON")
352
+ return rows, problems
353
+
354
+
355
+ def _declared_columns(layout: RunLayout, expose_id: str) -> Optional[List[str]]:
356
+ """The column names the emit's seam attestation declares, or ``None``."""
357
+ path = layout.seam_attestation_path(expose_id)
358
+ if not path.is_file():
359
+ return None
360
+ try:
361
+ return [str(name) for name in _read_json(path)["columns"]]
362
+ except (json.JSONDecodeError, KeyError, TypeError):
363
+ return None
364
+
365
+
366
+ def _row_conformance(layout: RunLayout, receipt: Dict[str, Any]) -> List[str]:
367
+ problems: List[str] = []
368
+ for expose_id, entry in sorted(receipt.get("emits", {}).items()):
369
+ emit_path = layout.emit_path(expose_id)
370
+ if not emit_path.is_file():
371
+ problems.append(f"{expose_id}: no emit file at {emit_path}")
372
+ continue
373
+ rows, decode_problems = _decoded_rows(emit_path, expose_id)
374
+ problems.extend(decode_problems)
375
+ if decode_problems:
376
+ continue
377
+ if len(rows) != entry["rows"]:
378
+ problems.append(
379
+ f"{expose_id}: receipt declares {entry['rows']} rows, file has {len(rows)}"
380
+ )
381
+ continue
382
+ # The declared width, not merely a shared one. Rows that all carry
383
+ # the same wrong number of values agree with each other and match
384
+ # nothing the contract declared, which is exactly the corruption
385
+ # this leg exists to catch.
386
+ columns = _declared_columns(layout, expose_id)
387
+ if columns is None:
388
+ problems.append(f"{expose_id}: no readable seam attestation to check row width against")
389
+ continue
390
+ widths = {len(row) for row in rows}
391
+ wrong = sorted(width for width in widths if width != len(columns))
392
+ if wrong:
393
+ problems.append(
394
+ f"{expose_id}: rows carry {wrong} values where the attestation "
395
+ f"declares {len(columns)} columns"
396
+ )
397
+ return problems
398
+
399
+
400
+ def _golden(
401
+ layout: RunLayout,
402
+ simulation_id: str,
403
+ run_digest: str,
404
+ run_components: Dict[str, Any],
405
+ *,
406
+ update: bool,
407
+ reason: Optional[str],
408
+ declared_baseline: Optional[str],
409
+ generated_at: str,
410
+ ) -> Dict[str, Any]:
411
+ """Compare against ``<state_dir>/golden/<simulationId>.json``, the record
412
+ ``--update-golden`` maintains (bundle directories are frequently read-only
413
+ checkouts -- the FLUX examples repo included -- so this build never writes
414
+ into the bundle itself).
415
+
416
+ The Simulation's own ``spec.golden.baselineDigest`` -- the schema's
417
+ golden-regression anchor ($defs/golden) -- is reported alongside as
418
+ ``specGoldenMatch`` for a reader's information, but it is not this
419
+ function's pass/fail signal: an example or a fixture ships whatever
420
+ placeholder its author typed (the FLUX spec repo's own telco example
421
+ ships one no run has ever actually produced), and gating the whole loop
422
+ on that would make "the bundle happens to carry an old string" and "the
423
+ simulation is not reproducible" the same failure. Once an owner has run
424
+ ``--update-golden`` and committed the resulting digest into the bundle's
425
+ ``spec.golden`` block, this and that become the same check.
426
+ """
427
+ golden_path = layout.golden_path(simulation_id)
428
+ changelog_path = layout.golden_changelog_path
429
+ existing = _read_json(golden_path) if golden_path.is_file() else None
430
+ previous_digest = existing["baselineDigest"] if existing else None
431
+ spec_golden_match = None if declared_baseline is None else declared_baseline == run_digest
432
+ # KERNEL-SPEC section 10: `golden.baselineDigest === runDigest`. This
433
+ # function's pass/fail signal is deliberately the out-of-band
434
+ # `<state_dir>/golden/` record, not the bundle's own declared value
435
+ # (see this function's docstring) -- but a reader must still be told
436
+ # when the two disagree, never left to notice a silent gap on their
437
+ # own.
438
+ spec_golden_mismatch = declared_baseline is not None and spec_golden_match is False
439
+
440
+ if update:
441
+ changed = tuple(
442
+ moved_components(existing.get("components", {}), run_components) if existing else ()
443
+ )
444
+ golden_update = GoldenUpdate(
445
+ kernel_version=_pipeline.KERNEL_VERSION,
446
+ previous_digest=previous_digest,
447
+ new_digest=run_digest,
448
+ reason=reason or "",
449
+ components=changed,
450
+ )
451
+ row = golden_changelog_row(golden_update)
452
+ changelog_path.parent.mkdir(parents=True, exist_ok=True)
453
+ changelog_text = (
454
+ changelog_path.read_text(encoding="utf-8")
455
+ if changelog_path.is_file()
456
+ else (
457
+ "| kernelVersion | previous | new | components | reason |\n|---|---|---|---|---|\n"
458
+ )
459
+ )
460
+ changelog_text += row + "\n"
461
+ problems = check_golden_update(golden_update, changelog_text)
462
+ if problems:
463
+ return {"updated": False, "problems": problems}
464
+ changelog_path.write_text(changelog_text, encoding="utf-8")
465
+ # Through the one artifact writer, not a hand-rolled `json.dumps`
466
+ # beside it: `GoldenSnapshot` is a declared envelope kind, and a
467
+ # kind with no producer is a choke point in the docstring only.
468
+ write_artifact(
469
+ golden_path,
470
+ {
471
+ "kernelVersion": _pipeline.KERNEL_VERSION,
472
+ "baselineDigest": run_digest,
473
+ "components": run_components,
474
+ },
475
+ kind="GoldenSnapshot",
476
+ schema_version=GOLDEN_SNAPSHOT_SCHEMA_VERSION,
477
+ generated_at=generated_at,
478
+ )
479
+ return {
480
+ "updated": True,
481
+ "baselineDigest": run_digest,
482
+ "movedComponents": list(changed),
483
+ "specGoldenMatch": spec_golden_match,
484
+ "specGoldenMismatch": spec_golden_mismatch,
485
+ }
486
+
487
+ if existing is None:
488
+ return {
489
+ "reproducibility": Reproducibility.NOT_CHECKED,
490
+ "reason": "no golden baseline recorded yet",
491
+ "outputsIdentical": None,
492
+ "detail": None,
493
+ "specGoldenMatch": spec_golden_match,
494
+ "specGoldenMismatch": spec_golden_mismatch,
495
+ }
496
+ if existing["baselineDigest"] == run_digest:
497
+ return {
498
+ "reproducibility": Reproducibility.REPRODUCIBLE,
499
+ "movedComponents": [],
500
+ "outputsIdentical": True,
501
+ "detail": None,
502
+ "specGoldenMatch": spec_golden_match,
503
+ "specGoldenMismatch": spec_golden_mismatch,
504
+ }
505
+ moved = moved_components(existing.get("components", {}), run_components)
506
+ return {
507
+ "reproducibility": Reproducibility.NOT_REPRODUCIBLE,
508
+ "baselineDigest": existing["baselineDigest"],
509
+ "runDigest": run_digest,
510
+ "movedComponents": list(moved),
511
+ "outputsIdentical": not moved,
512
+ "detail": None if moved else INPUT_ONLY_DETAIL,
513
+ "specGoldenMatch": spec_golden_match,
514
+ "specGoldenMismatch": spec_golden_mismatch,
515
+ }
516
+
517
+
518
+ def trust_anchor_for(
519
+ signing_key: Optional[bytes], trust_key: Optional[bytes]
520
+ ) -> Tuple[Optional[bytes], bool]:
521
+ """The public key a record's signature is checked against, and whether it is self-attested.
522
+
523
+ One derivation, called by both stages -- ``ship`` passes the key
524
+ material it is about to sign with, ``verify`` passes whatever
525
+ ``--signing-key`` it was given -- so ``fluxsim ship --signing-key k`` and
526
+ ``fluxsim verify --signing-key k`` cannot reach different verdicts about
527
+ one record:
528
+
529
+ * ``--trust-key`` is the anchor. It came from outside this process, so
530
+ a signature that verifies against it is a statement about *who*
531
+ signed, and ``self_attested`` is false.
532
+ * A signing key alone yields the public half of that seed. The
533
+ signature check is then a statement about internal consistency and
534
+ nothing else, which is what ``self_attested`` records.
535
+ * Neither leaves the anchor ``None``. A record's own key is never
536
+ promoted to a trust anchor, so a caller with no key at all gets no
537
+ anchor and the check reports itself unchecked rather than green.
538
+ (``ship`` never reaches that case: it always has key material, an
539
+ ephemeral one when the caller supplied none.)
540
+ """
541
+ if trust_key is not None:
542
+ return trust_key, False
543
+ if signing_key is None:
544
+ return None, False
545
+ from flux_engine.concordance.record import Ed25519Signer
546
+
547
+ return Ed25519Signer(private_key=signing_key, key_id="_").public_key, True
548
+
549
+
550
+ def _record_signature_leg(
551
+ layout: RunLayout,
552
+ expose_id: str,
553
+ *,
554
+ trust_anchor: Optional[bytes],
555
+ self_attested: bool,
556
+ ) -> Optional[Dict[str, Any]]:
557
+ """Check the ``fidelity-record-<expose>.json`` a prior ``ship`` left, if any.
558
+
559
+ ``ship`` prints ``fluxsim verify`` as the command a reader outside this
560
+ process runs to reach the same conclusion from the pack alone, and
561
+ ``verify`` had no way to be given a trust anchor at all -- so the one
562
+ signature state that is a statement about *who* signed was reachable
563
+ from ``ship`` and from nowhere else. Returns ``None`` when this run
564
+ holds no record for the expose: there is nothing to say, and an
565
+ outcome key that always appeared would say "not checked" about a file
566
+ that does not exist.
567
+ """
568
+ record_path = layout.fidelity_record_path(expose_id)
569
+ if not record_path.is_file():
570
+ return None
571
+ if trust_anchor is None:
572
+ return {
573
+ "status": "not checked",
574
+ "detail": (
575
+ f"{record_path.name} is present; pass --trust-key <file> (the "
576
+ "`publicKey` the record prints) to check its signature"
577
+ ),
578
+ }
579
+ from flux_engine.concordance.record import verify_record
580
+
581
+ reasons = verify_record(
582
+ json.loads(record_path.read_text(encoding="utf-8")), trusted_keys=trust_anchor
583
+ )
584
+ if reasons:
585
+ return {"status": "not trusted", "detail": "; ".join(reasons)}
586
+ return {
587
+ "status": "self-attested" if self_attested else "trusted",
588
+ "detail": (
589
+ "the signature verifies against the public half of the key this "
590
+ "invocation was given, which says the record is internally "
591
+ "consistent and nothing about who signed it"
592
+ if self_attested
593
+ else None
594
+ ),
595
+ }
596
+
597
+
598
+ def _fidelity_leg(
599
+ layout: RunLayout,
600
+ receipt: Dict[str, Any],
601
+ committed_slice: Dict[str, str],
602
+ *,
603
+ trust_anchor: Optional[bytes] = None,
604
+ self_attested: bool = False,
605
+ ) -> Dict[str, Any]:
606
+ outcomes: Dict[str, Any] = {}
607
+ for expose_id, entry in sorted(receipt.get("emits", {}).items()):
608
+ if not entry.get("declaresFidelity"):
609
+ outcomes[expose_id] = {"status": "not declared"}
610
+ continue
611
+ slice_uri = committed_slice.get(expose_id)
612
+ if slice_uri is None:
613
+ outcome: Dict[str, Any] = {
614
+ "status": "declared, not checked",
615
+ "detail": "declares a fidelity block; pass --committed-slice "
616
+ f"{expose_id}=file://<path> to run the check",
617
+ }
618
+ else:
619
+ outcome = _run_fidelity_check(layout, expose_id, slice_uri)
620
+ signature = _record_signature_leg(
621
+ layout, expose_id, trust_anchor=trust_anchor, self_attested=self_attested
622
+ )
623
+ if signature is not None:
624
+ outcome["record"] = signature
625
+ # A record on disk that does not verify against the anchor the
626
+ # caller supplied is a failure of this leg, not a footnote to
627
+ # it: the artifact a ship published is not the one the reader
628
+ # trusts. The detail moves with the status -- leaving "pass
629
+ # --committed-slice to run the check" beside the word `failed`
630
+ # would name a check that did not run as the reason.
631
+ if signature["status"] == "not trusted":
632
+ was_failure = outcome["status"] == "failed"
633
+ outcome["status"] = "failed"
634
+ details = [f"{layout.fidelity_record_path(expose_id).name}: {signature['detail']}"]
635
+ if was_failure and outcome.get("detail"):
636
+ details.append(str(outcome["detail"]))
637
+ outcome["detail"] = "; ".join(details)
638
+ outcomes[expose_id] = outcome
639
+ return outcomes
640
+
641
+
642
+ #: What dates a committed state this leg forms itself. `verify` takes no
643
+ #: `--committed-at`, and stamping the host clock would date one record set
644
+ #: differently on every call; the owner's own declaration reaches a state
645
+ #: through `fluxsim ship --committed-at`.
646
+ _UNDECLARED_COMMITMENT_TIME = "2026-01-01T00:00:00.000Z"
647
+
648
+
649
+ def _run_fidelity_check(layout: RunLayout, expose_id: str, slice_uri: str) -> Dict[str, Any]:
650
+ from flux_engine.concordance.boundary.slice import read_slice
651
+ from flux_engine.concordance.boundary.store import BoundaryStore
652
+ from flux_engine.concordance.compiler import compile_fidelity
653
+ from flux_engine.concordance.predicate import expose_from_contract
654
+ from flux_engine.concordance.verifier import ClearStatistic
655
+
656
+ attestation = _read_json(layout.seam_attestation_path(expose_id))
657
+ fidelity_input_path = layout.fidelity_input_path(expose_id)
658
+ if not fidelity_input_path.is_file():
659
+ return {
660
+ "status": "declared, not checked",
661
+ "detail": f"no {fidelity_input_path.name} recorded for this run",
662
+ }
663
+ fidelity_input = _read_json(fidelity_input_path)
664
+ contract_document = fidelity_input["contract"]
665
+ emit_entry = fidelity_input["emit"]
666
+ expose = expose_from_contract(contract_document, expose_id)
667
+ compiled = compile_fidelity(contract=contract_document, emit=emit_entry, expose=expose)
668
+
669
+ rows, reference = read_slice(slice_uri, maximum=compiled.block.records.maximum)
670
+ # The same boundary store `ship` commits through, so a slice checked
671
+ # here and then shipped is one committed state with one blinding value
672
+ # and one C2 -- not two states that happen to hold the same records.
673
+ # This leg declares no commitment time of its own: `stamped_at` dates
674
+ # only a state being formed for the first time, and it is a fixed
675
+ # instant rather than the host clock because this leg reports a
676
+ # comparison of two datasets and never measures a state's age (that is
677
+ # `ship`'s gate, against the owner's own `--committed-at`).
678
+ store = BoundaryStore.for_state_dir(
679
+ layout.state_dir, max_checks_per_state=compiled.block.budget.max_checks_per_state
680
+ )
681
+ state = store.commit(
682
+ rows=rows,
683
+ compiled=compiled,
684
+ slice_reference=reference,
685
+ stamped_at=_UNDECLARED_COMMITMENT_TIME,
686
+ )
687
+
688
+ emit_path = layout.emit_path(expose_id)
689
+ emitted_rows, decode_problems = _decoded_rows(emit_path, expose_id)
690
+ if decode_problems:
691
+ return {"status": "failed", "refusals": [], "detail": "; ".join(decode_problems)}
692
+ # Through the catalogued guard, never a bare `zip(..., strict=True)`:
693
+ # a row whose width does not match the header is `FLX-8001` naming the
694
+ # row, the width and the declared column count, not a ValueError with
695
+ # no code that aborts the stage and suppresses every other leg.
696
+ try:
697
+ synthetic_rows = packed_emit(attestation, expose_id, emitted_rows).as_mappings()
698
+ except FluxError as error:
699
+ return {"status": "failed", "refusals": [], "detail": str(error)}
700
+
701
+ evaluation = ClearStatistic(
702
+ compiled=compiled, committed=state, synthetic_rows=synthetic_rows
703
+ ).evaluate()
704
+ return {
705
+ "status": "passed" if evaluation.within else "failed",
706
+ "refusals": [refusal.to_document() for refusal in evaluation.refusals],
707
+ }
708
+
709
+
710
+ def packed_emit(
711
+ attestation: Mapping[str, Any], expose_id: str, rows: Sequence[Sequence[Any]]
712
+ ) -> "PackedEmit":
713
+ """Build the §8 header and rows one emit is read back as.
714
+
715
+ Shared by ``verify``'s fidelity leg and ``ship``'s gate so both read
716
+ the pack the same way and both get
717
+ :meth:`~flux_engine.concordance.gate.PackedEmit.as_mappings`' width
718
+ refusal (``FLX-8001``) instead of an uncatalogued ``ValueError`` from
719
+ a bare ``zip(..., strict=True)``.
720
+ """
721
+ header = {
722
+ "exposeId": expose_id,
723
+ "columns": list(attestation["columns"]),
724
+ "types": list(attestation["types"]),
725
+ "contractDigest": attestation["reference"]["contractDigest"],
726
+ }
727
+ return PackedEmit(header=header, rows=tuple(tuple(row) for row in rows))
728
+
729
+
730
+ def _leg_lines(
731
+ golden: Mapping[str, Any],
732
+ *,
733
+ artifact_mismatches: Sequence[str],
734
+ row_problems: Sequence[str],
735
+ vector_failures: int,
736
+ fidelity_outcomes: Mapping[str, Any],
737
+ ) -> List[str]:
738
+ """One human line per leg, under the headline.
739
+
740
+ This command runs five independent checks and used to tell a person
741
+ six words about them, while the same invocation's ``--json`` envelope
742
+ carried the reason each leg said what it said and the exact flag that
743
+ turns "not checked" into a result. The human was given strictly less
744
+ than the machine, and no next step. Both now come from the same
745
+ values, so neither can quietly say more than the other.
746
+ """
747
+ lines: List[str] = []
748
+
749
+ reproducibility = golden.get("reproducibility", Reproducibility.NOT_CHECKED)
750
+ if reproducibility is Reproducibility.NOT_CHECKED:
751
+ lines.append(
752
+ f" golden: not checked ({golden.get('reason', 'no baseline recorded yet')} "
753
+ '-- record one with `--update-golden --reason "<why>"`)'
754
+ )
755
+ elif reproducibility is Reproducibility.REPRODUCIBLE:
756
+ lines.append(" golden: reproducible (this run matches the recorded baseline)")
757
+ else:
758
+ moved = ", ".join(golden.get("movedComponents") or ()) or "no component"
759
+ lines.append(f" golden: NOT reproducible (moved: {moved})")
760
+
761
+ lines.append(
762
+ " artifacts: every run-digest component reproduces"
763
+ if not artifact_mismatches
764
+ else f" artifacts: {len(artifact_mismatches)} component(s) do not reproduce: "
765
+ + ", ".join(artifact_mismatches)
766
+ )
767
+ lines.append(
768
+ " rows: ok"
769
+ if not row_problems
770
+ else f" rows: {len(row_problems)} problem(s) -- {row_problems[0]}"
771
+ )
772
+ lines.append(f" rfc-04 vectors: {vector_failures} failure(s)")
773
+ for expose_id, outcome in sorted(fidelity_outcomes.items()):
774
+ status = outcome.get("status", "unknown")
775
+ detail = outcome.get("detail")
776
+ lines.append(f" fidelity {expose_id}: {status}" + (f" -- {detail}" if detail else ""))
777
+ record = outcome.get("record")
778
+ if record:
779
+ record_detail = record.get("detail")
780
+ lines.append(
781
+ f" fidelity {expose_id} record signature: {record.get('status', 'unknown')}"
782
+ + (f" -- {record_detail}" if record_detail else "")
783
+ )
784
+ return lines
785
+
786
+
787
+ def verify(
788
+ bundle_directory: Union[str, Path],
789
+ *,
790
+ run_id: str,
791
+ state_dir: Union[str, Path, None] = None,
792
+ update_golden: bool = False,
793
+ reason: Optional[str] = None,
794
+ committed_slice: Optional[Dict[str, str]] = None,
795
+ vectors_path: Optional[Union[str, Path]] = None,
796
+ allow_declared_baseline_drift: bool = False,
797
+ signing_key: Optional[bytes] = None,
798
+ trust_key: Optional[bytes] = None,
799
+ ) -> StageResult:
800
+ """Verify the run recorded at ``<state_dir>/runs/<run_id>/``.
801
+
802
+ *trust_key* is the 32-byte raw ed25519 **public** key any fidelity
803
+ record this run already holds is checked against, and *signing_key* is
804
+ the seed whose public half stands in for it when the caller has only
805
+ that -- the same derivation ``ship`` performs, shared through
806
+ :func:`trust_anchor_for` so the two stages cannot disagree about one
807
+ record.
808
+ """
809
+ state = Path(state_dir) if state_dir is not None else Path(".flux")
810
+ layout = RunLayout.for_state_dir(state, run_id)
811
+
812
+ if not layout.receipt_path.is_file() or not layout.run_digest_path.is_file():
813
+ missing = NoAppliedRun(run_dir=layout.run_dir)
814
+ return StageResult(
815
+ stage="verify",
816
+ exit_code=1,
817
+ _artifacts={"code": missing.code.code},
818
+ stderr=str(missing),
819
+ error_code=missing.code.code,
820
+ )
821
+
822
+ receipt = _read_json(layout.receipt_path)
823
+ # A run directory is named by the run id derived from its plan's own
824
+ # planDigest; when the two disagree the directory was copied or
825
+ # renamed, and every later comparison is between files that travelled
826
+ # together (FLX-2113). `apply` and `ship` both check this through
827
+ # `load_recorded_plan`; `verify` never read plan.json at all, so it
828
+ # was the one stage that accepted a copied run directory.
829
+ if layout.plan_path.is_file():
830
+ try:
831
+ load_recorded_plan(layout)
832
+ except FluxError as error:
833
+ return StageResult(
834
+ stage="verify",
835
+ exit_code=1,
836
+ _artifacts={"code": error.code.code},
837
+ stderr=str(error),
838
+ error_code=error.code.code,
839
+ )
840
+ run_digest_document = _read_json(layout.run_digest_path)
841
+ run_digest = digest_of_document(run_digest_document, subject="runDigest").value
842
+
843
+ # Leg 0a. A mistyped --committed-slice key is a refusal, not a
844
+ # silently dropped flag (see `require_known_slice_exposes`). Checked
845
+ # before anything expensive: the caller's next command is the same one
846
+ # with the id spelled right.
847
+ try:
848
+ require_known_slice_exposes(receipt, committed_slice or {})
849
+ except FluxError as error:
850
+ return StageResult(
851
+ stage="verify",
852
+ exit_code=2,
853
+ _artifacts={"code": error.code.code},
854
+ stderr=str(error),
855
+ error_code=error.code.code,
856
+ )
857
+
858
+ # Leg 0b. The bundle argument. `verify`'s own signature took a bundle
859
+ # directory and never read it, so `fluxsim verify /etc --run-id <id>`
860
+ # reported the same verdict as the real bundle would. KERNEL-SPEC §11's
861
+ # inputDigest is what binds a run to the documents it was given, and
862
+ # recomputing it here is the whole content of "verify this run against
863
+ # this bundle".
864
+ try:
865
+ current_input_digest = recompute_input_digest(bundle_directory)
866
+ except FluxError as error:
867
+ return StageResult(
868
+ stage="verify",
869
+ exit_code=1,
870
+ _artifacts={"code": error.code.code},
871
+ stderr=str(error),
872
+ error_code=error.code.code,
873
+ )
874
+ except OSError as error:
875
+ moved = InputDigestMoved(planned=str(receipt.get("inputDigest")), current="unreadable")
876
+ return StageResult(
877
+ stage="verify",
878
+ exit_code=1,
879
+ _artifacts={"code": moved.code.code},
880
+ stderr=f"{moved.code.code}: {bundle_directory} could not be read as a bundle: {error}",
881
+ error_code=moved.code.code,
882
+ )
883
+ recorded_input_digest = str(receipt.get("inputDigest"))
884
+ if current_input_digest != recorded_input_digest:
885
+ moved = InputDigestMoved(planned=recorded_input_digest, current=current_input_digest)
886
+ return StageResult(
887
+ stage="verify",
888
+ exit_code=1,
889
+ _artifacts={
890
+ "code": moved.code.code,
891
+ "inputDigest": {
892
+ "recorded": recorded_input_digest,
893
+ "recomputed": current_input_digest,
894
+ },
895
+ },
896
+ stderr=f"{moved.code.code}: {moved.detail} -- this run was not produced from "
897
+ f"{Path(bundle_directory)}",
898
+ error_code=moved.code.code,
899
+ )
900
+
901
+ # The legs that do not touch the golden record run first, all of them,
902
+ # unconditionally -- including when `--update-golden` was passed. A
903
+ # `--update-golden` invocation that never evaluated row conformance,
904
+ # RFC-04 or fidelity would let `fluxsim run --verify --update-golden`
905
+ # report success having verified nothing but the golden write itself.
906
+ # None of them returns early either: one invocation says everything it
907
+ # found, so an operator fixing a corrupted run directory is not told
908
+ # about it one leg per command.
909
+ artifact_mismatches = component_mismatches(
910
+ layout, receipt, run_digest_document.get("components", {})
911
+ )
912
+ artifact_detail = (
913
+ str(RunArtifactsMoved(components=artifact_mismatches)) if artifact_mismatches else ""
914
+ )
915
+
916
+ row_problems = _row_conformance(layout, receipt)
917
+
918
+ vectors = vectors_path or default_vectors_path()
919
+ vector_failures, vector_messages = run_conformance_vectors(vectors)
920
+
921
+ trust_anchor, self_attested = trust_anchor_for(signing_key, trust_key)
922
+ fidelity_outcomes = _fidelity_leg(
923
+ layout,
924
+ receipt,
925
+ committed_slice or {},
926
+ trust_anchor=trust_anchor,
927
+ self_attested=self_attested,
928
+ )
929
+ fidelity_failed = [
930
+ expose_id
931
+ for expose_id, outcome in fidelity_outcomes.items()
932
+ if outcome.get("status") == "failed"
933
+ ]
934
+ artifacts_leg = {
935
+ "ok": not artifact_mismatches,
936
+ "movedComponents": list(artifact_mismatches),
937
+ }
938
+ legs_ok = (
939
+ not artifact_mismatches
940
+ and not row_problems
941
+ and vector_failures == 0
942
+ and not fidelity_failed
943
+ )
944
+ # FLX-2110 outranks the rest as the reported code: a run directory
945
+ # that no longer reproduces its own digest makes every other leg a
946
+ # statement about bytes nothing in the run produced.
947
+ leg_error_code = RunArtifactsMoved(components=()).code.code if artifact_mismatches else None
948
+
949
+ if update_golden:
950
+ if not legs_ok:
951
+ problems = [
952
+ *([artifact_detail] if artifact_detail else []),
953
+ *row_problems,
954
+ *vector_messages[:5],
955
+ *(f"{expose_id}: fidelity check failed" for expose_id in fidelity_failed),
956
+ ]
957
+ return StageResult(
958
+ stage="verify",
959
+ exit_code=1,
960
+ _artifacts={
961
+ "golden": {"updated": False, "problems": problems},
962
+ "artifactComponents": artifacts_leg,
963
+ "rowConformance": {"ok": not row_problems, "problems": row_problems},
964
+ "rfc04": {"failures": vector_failures, "messages": vector_messages},
965
+ "fidelity": fidelity_outcomes,
966
+ },
967
+ stderr="refusing to update the golden baseline -- a leg failed: "
968
+ + "; ".join(problems),
969
+ error_code=leg_error_code,
970
+ )
971
+ golden = _golden(
972
+ layout,
973
+ receipt["simulationId"],
974
+ run_digest,
975
+ run_digest_document["components"],
976
+ update=True,
977
+ reason=reason,
978
+ declared_baseline=receipt.get("declaredGoldenBaseline"),
979
+ generated_at=_now(),
980
+ )
981
+ exit_code = 0 if golden.get("updated") else 1
982
+ if golden.get("updated"):
983
+ golden["pasteIntoBundle"] = f'spec:\n golden:\n baselineDigest: "{run_digest}"'
984
+ return StageResult(
985
+ stage="verify",
986
+ exit_code=exit_code,
987
+ _artifacts={
988
+ "golden": golden,
989
+ "declaredBaselineDrift": bool(golden.get("specGoldenMismatch")),
990
+ "artifactComponents": artifacts_leg,
991
+ "rowConformance": {"ok": True, "problems": []},
992
+ "rfc04": {"failures": 0, "messages": []},
993
+ "fidelity": fidelity_outcomes,
994
+ },
995
+ stdout="golden baseline updated" if golden.get("updated") else "",
996
+ stderr="; ".join(golden.get("problems", [])) if not golden.get("updated") else "",
997
+ )
998
+
999
+ golden = _golden(
1000
+ layout,
1001
+ receipt["simulationId"],
1002
+ run_digest,
1003
+ run_digest_document["components"],
1004
+ update=False,
1005
+ reason=reason,
1006
+ declared_baseline=receipt.get("declaredGoldenBaseline"),
1007
+ generated_at=_now(),
1008
+ )
1009
+
1010
+ reproducibility = golden.get("reproducibility", Reproducibility.NOT_CHECKED)
1011
+ verdict = VerifyVerdict(reproducibility=reproducibility, validity=Validity.NOT_ASSERTED)
1012
+
1013
+ # KERNEL-SPEC §10 makes `golden.baselineDigest === runDigest` a
1014
+ # normative equality. A stage that prints the mismatch and still exits
1015
+ # 0 hands a CI gate -- and the --json envelope's own `"ok": true` --
1016
+ # a green light over a violated declaration, with the one fact that
1017
+ # matters buried three levels down in `artifacts.golden`. The verdict
1018
+ # is the exit code, so the mismatch belongs in it. A caller that has
1019
+ # decided a stale declared baseline is acceptable says so explicitly
1020
+ # with `--allow-declared-baseline-drift`.
1021
+ declared_baseline_drift = bool(golden.get("specGoldenMismatch"))
1022
+ ok = (
1023
+ reproducibility != Reproducibility.NOT_REPRODUCIBLE
1024
+ and legs_ok
1025
+ and (allow_declared_baseline_drift or not declared_baseline_drift)
1026
+ )
1027
+
1028
+ headline = verdict.headline()
1029
+ stderr_parts: List[str] = []
1030
+ if not ok:
1031
+ if artifact_detail:
1032
+ stderr_parts.append(artifact_detail)
1033
+ stderr_parts.extend(row_problems)
1034
+ stderr_parts.extend(vector_messages[:5])
1035
+ stderr_parts.extend(fidelity_failed)
1036
+ # **The regression names what moved, to a human.** `movedComponents`
1037
+ # is the answer to the only question a red `reproducible: no` raises,
1038
+ # and it used to reach `--json` callers alone: the human output was
1039
+ # the bare headline, with no baseline digest, no run digest and no
1040
+ # component name anywhere. This stage exists to say "this stopped
1041
+ # reproducing, and here is what moved"; saying it only in JSON is not
1042
+ # saying it.
1043
+ if reproducibility is Reproducibility.NOT_REPRODUCIBLE:
1044
+ moved_names = tuple(golden.get("movedComponents") or ())
1045
+ stderr_parts.append(
1046
+ f"golden regression: baseline {golden.get('baselineDigest')} -> this run "
1047
+ f"{golden.get('runDigest')}"
1048
+ )
1049
+ # One line for what moved -- the component list, or the explanation
1050
+ # of how a digest moves with no component behind it (see
1051
+ # INPUT_ONLY_DETAIL). Never both, and never the remedy twice.
1052
+ stderr_parts.append(
1053
+ f"moved: {', '.join(moved_names)}" if moved_names else INPUT_ONLY_DETAIL
1054
+ )
1055
+ stderr_parts.append(GOLDEN_REMEDY)
1056
+ # A moved digest over an unmoved run: say so in the headline, not only
1057
+ # in the artifacts. See INPUT_ONLY_DETAIL.
1058
+ if reproducibility is Reproducibility.NOT_REPRODUCIBLE and golden.get("outputsIdentical"):
1059
+ headline += " | inputs moved, every component identical"
1060
+ # KERNEL-SPEC section 10 makes `golden.baselineDigest === runDigest` a
1061
+ # normative equality; this stage's own pass/fail signal is the
1062
+ # out-of-band <state_dir>/golden/ record (see `_golden`'s docstring),
1063
+ # but a declared-vs-actual mismatch must still reach the reader,
1064
+ # regardless of exit code -- silence here would let "the bundle
1065
+ # carries a stale placeholder" and "this run is not reproducible"
1066
+ # look identical.
1067
+ if declared_baseline_drift:
1068
+ headline += " | declared baseline: does not match"
1069
+ stderr_parts.append(
1070
+ "declared baseline: does not match -- the bundle's Simulation "
1071
+ "spec.golden.baselineDigest is "
1072
+ f"{receipt.get('declaredGoldenBaseline')}, this run's runDigest is "
1073
+ f"{run_digest}"
1074
+ # The recovery hint used to be appended only when the flag was
1075
+ # already passed -- so the one invocation that actually failed
1076
+ # over this was the one told nothing about how to proceed.
1077
+ + (
1078
+ " (allowed by --allow-declared-baseline-drift)"
1079
+ if allow_declared_baseline_drift
1080
+ else ' -- re-record it with `--update-golden --reason "<why>"` and paste the '
1081
+ "printed digest into the bundle's spec.golden, or accept the drift for this "
1082
+ "run with `--allow-declared-baseline-drift`"
1083
+ )
1084
+ )
1085
+
1086
+ # A golden regression is a catalogued failure like any other, and it
1087
+ # used to report `"code": null` -- the one leg of this stage whose
1088
+ # `--json` envelope told a caller nothing it could branch on, and the
1089
+ # one whose remedy (`--update-golden --reason`) is a specific command.
1090
+ # FLX-2110 still outranks it: a run directory that no longer
1091
+ # reproduces its own digest makes the baseline comparison a statement
1092
+ # about bytes nothing in the run produced.
1093
+ error_code = leg_error_code
1094
+ if error_code is None and reproducibility is Reproducibility.NOT_REPRODUCIBLE:
1095
+ error_code = FLX_2114.code
1096
+
1097
+ return StageResult(
1098
+ stage="verify",
1099
+ exit_code=0 if ok else 1,
1100
+ _artifacts={
1101
+ "headline": headline,
1102
+ "reproducibility": reproducibility.value,
1103
+ "validity": verdict.validity.value,
1104
+ "verdict": {
1105
+ "reproducibility": reproducibility.value,
1106
+ "validity": verdict.validity.value,
1107
+ },
1108
+ "golden": golden,
1109
+ "declaredBaselineDrift": declared_baseline_drift,
1110
+ "artifactComponents": artifacts_leg,
1111
+ "rowConformance": {"ok": not row_problems, "problems": row_problems},
1112
+ "rfc04": {"failures": vector_failures, "messages": vector_messages},
1113
+ "fidelity": fidelity_outcomes,
1114
+ },
1115
+ stdout="\n".join(
1116
+ [
1117
+ headline,
1118
+ *_leg_lines(
1119
+ golden,
1120
+ artifact_mismatches=artifact_mismatches,
1121
+ row_problems=row_problems,
1122
+ vector_failures=vector_failures,
1123
+ fidelity_outcomes=fidelity_outcomes,
1124
+ ),
1125
+ ]
1126
+ ),
1127
+ stderr="\n".join(stderr_parts),
1128
+ error_code=error_code,
1129
+ )