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,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
|
+
)
|