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,583 @@
|
|
|
1
|
+
# Copyright 2026 Agentics Transformation Limited
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
4
|
+
|
|
5
|
+
"""The verifier -- SEAM-FIDELITY-SPEC §5.
|
|
6
|
+
|
|
7
|
+
Inputs: the contract set (recomputes ``H``, ``G``), ``S``, ``C1``,
|
|
8
|
+
``C2``, and D′ (recomputes D′'s statistics on the same grid and D′'s
|
|
9
|
+
digest = ``outputDigest``). Evaluates each property in the integer
|
|
10
|
+
cross-multiplied form [...]. Fail-closed conditions: ``k = 0``, count
|
|
11
|
+
outside ``records``, group below ``records.min``, a value outside its
|
|
12
|
+
range, a column absent, ``ε ≥ τ``. **No proof is generated in v0.1**;
|
|
13
|
+
the ``ProofSystem`` port has one implementation, ``none``, and the
|
|
14
|
+
record says so.
|
|
15
|
+
|
|
16
|
+
Three properties this module is shaped to keep.
|
|
17
|
+
|
|
18
|
+
**Nothing here divides.** Every comparison is one of
|
|
19
|
+
:mod:`flux_engine.core.fixedpoint`'s integer cross-multiplied forms, over
|
|
20
|
+
integers both sides formed with the same function on the same grid. There
|
|
21
|
+
is no floating point on the path and no place for one to appear.
|
|
22
|
+
|
|
23
|
+
**A refusal is not a verdict.** §5's fail-closed conditions become
|
|
24
|
+
:class:`Refusal` entries, and an evaluation carrying any refusal is not
|
|
25
|
+
within its margins whatever its property outcomes say. The two are
|
|
26
|
+
separate fields; nothing collapses them into a single boolean that could
|
|
27
|
+
be read as "the check ran and passed" when it did not run.
|
|
28
|
+
|
|
29
|
+
**The backend states what it is.** ``proofSystem`` is ``"none"`` and says
|
|
30
|
+
so in the record, because an omitted field reads as an unremarkable
|
|
31
|
+
default and a stated ``"none"`` reads as what it is.
|
|
32
|
+
"""
|
|
33
|
+
|
|
34
|
+
from __future__ import annotations
|
|
35
|
+
|
|
36
|
+
from dataclasses import dataclass
|
|
37
|
+
from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple
|
|
38
|
+
|
|
39
|
+
from flux_engine.concordance.boundary.slice import CommittedState
|
|
40
|
+
from flux_engine.concordance.boundary.statistic import (
|
|
41
|
+
GroupStatistic,
|
|
42
|
+
Row,
|
|
43
|
+
compute_property_statistic,
|
|
44
|
+
require_record_count,
|
|
45
|
+
)
|
|
46
|
+
from flux_engine.concordance.compiler import CompiledFidelity, CompiledProperty, render_exact
|
|
47
|
+
from flux_engine.concordance.errors import FLX_5011
|
|
48
|
+
from flux_engine.concordance.predicate import PropertyKind, ToleranceKind
|
|
49
|
+
from flux_engine.core.canonical import canonical_bytes
|
|
50
|
+
from flux_engine.core.digest import DigestRef, digest_of_stream
|
|
51
|
+
from flux_engine.core.errors import FluxError
|
|
52
|
+
from flux_engine.core.fixedpoint import (
|
|
53
|
+
FLX_5005,
|
|
54
|
+
correlation_within,
|
|
55
|
+
mean_within_absolute,
|
|
56
|
+
mean_within_relative,
|
|
57
|
+
quantile_rank_ok,
|
|
58
|
+
quantile_within,
|
|
59
|
+
support_within,
|
|
60
|
+
total_variation_within,
|
|
61
|
+
)
|
|
62
|
+
|
|
63
|
+
__all__ = [
|
|
64
|
+
"ClearStatistic",
|
|
65
|
+
"EMIT_STREAM_PREFIX",
|
|
66
|
+
"FidelityEvaluation",
|
|
67
|
+
"GroupOutcome",
|
|
68
|
+
"NoProofSystem",
|
|
69
|
+
"Outcome",
|
|
70
|
+
"PropertyOutcome",
|
|
71
|
+
"Refusal",
|
|
72
|
+
"emit_stream_digest",
|
|
73
|
+
]
|
|
74
|
+
|
|
75
|
+
#: The two words §6's ``properties[].outcome`` takes. A closed pair: there
|
|
76
|
+
#: is no third value meaning "could not tell", because that case is a
|
|
77
|
+
#: :class:`Refusal` and belongs in a different field.
|
|
78
|
+
Outcome = str
|
|
79
|
+
WITHIN: Outcome = "within"
|
|
80
|
+
OUTSIDE: Outcome = "outside"
|
|
81
|
+
|
|
82
|
+
#: KERNEL-SPEC §8's framing label for the emit stream.
|
|
83
|
+
EMIT_STREAM_PREFIX = b"flux-emit/1\x00"
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
@dataclass(frozen=True)
|
|
87
|
+
class NoProofSystem:
|
|
88
|
+
"""The v0.1 proof system: there is none, and the record says so."""
|
|
89
|
+
|
|
90
|
+
name: str = "none"
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
# ---------------------------------------------------------------------------
|
|
94
|
+
# D-prime's digest
|
|
95
|
+
# ---------------------------------------------------------------------------
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def emit_stream_digest(
|
|
99
|
+
*,
|
|
100
|
+
header: Mapping[str, Any],
|
|
101
|
+
rows: Sequence[Sequence[Any]],
|
|
102
|
+
subject: str,
|
|
103
|
+
) -> DigestRef:
|
|
104
|
+
"""Recompute ``outputDigest`` over an emit stream (KERNEL-SPEC §8).
|
|
105
|
+
|
|
106
|
+
``outputDigest = "sha256:" + hex(sha256(b"flux-emit/1\\x00" +
|
|
107
|
+
JCS(header) + b"\\x00" + concat(line(row) for row in rows)))``
|
|
108
|
+
|
|
109
|
+
with each line ``JCS([v1, v2, ...]) + b"\\n"`` -- arrays aligned to the
|
|
110
|
+
header's column order, because JCS sorts object keys and objects would
|
|
111
|
+
erase that order.
|
|
112
|
+
|
|
113
|
+
The rule belongs to the seam (``seam/emit.py``), which computes the
|
|
114
|
+
digest above the sink so the sink cannot influence it. It is
|
|
115
|
+
implemented here because the gate has to recompute the digest "from
|
|
116
|
+
the rows actually placed in the pack" (§7) and the seam module does
|
|
117
|
+
not exist yet; :func:`~flux_engine.concordance.gate.run_gate` takes
|
|
118
|
+
the recomputation as an injectable callable so the seam's own
|
|
119
|
+
implementation replaces this one without a change at the call site.
|
|
120
|
+
"""
|
|
121
|
+
body = EMIT_STREAM_PREFIX + canonical_bytes(header) + b"\x00"
|
|
122
|
+
body += b"".join(canonical_bytes(list(row)) + b"\n" for row in rows)
|
|
123
|
+
return digest_of_stream(body, subject=subject)
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
# ---------------------------------------------------------------------------
|
|
127
|
+
# Outcomes and refusals
|
|
128
|
+
# ---------------------------------------------------------------------------
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
@dataclass(frozen=True)
|
|
132
|
+
class GroupOutcome:
|
|
133
|
+
"""One property's outcome inside one group.
|
|
134
|
+
|
|
135
|
+
``group`` is the empty string for an ungrouped property. The two
|
|
136
|
+
counts travel with the outcome because they are what a reader needs to
|
|
137
|
+
tell a comparison over a thousand records from one over the
|
|
138
|
+
``records.min`` floor.
|
|
139
|
+
"""
|
|
140
|
+
|
|
141
|
+
group: str
|
|
142
|
+
committed_count: int
|
|
143
|
+
synthetic_count: int
|
|
144
|
+
outcome: Outcome
|
|
145
|
+
|
|
146
|
+
@property
|
|
147
|
+
def within(self) -> bool:
|
|
148
|
+
"""Whether this group's comparison landed inside the margin."""
|
|
149
|
+
return self.outcome == WITHIN
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
@dataclass(frozen=True)
|
|
153
|
+
class PropertyOutcome:
|
|
154
|
+
"""One declared property's outcome, as §6's record row carries it."""
|
|
155
|
+
|
|
156
|
+
property_id: str
|
|
157
|
+
kind: PropertyKind
|
|
158
|
+
columns: Tuple[str, ...]
|
|
159
|
+
group_by: Optional[str]
|
|
160
|
+
tolerance: Mapping[str, str]
|
|
161
|
+
margin: Optional[str]
|
|
162
|
+
epsilon: str
|
|
163
|
+
outcome: Outcome
|
|
164
|
+
groups: Tuple[GroupOutcome, ...] = ()
|
|
165
|
+
|
|
166
|
+
@property
|
|
167
|
+
def within(self) -> bool:
|
|
168
|
+
"""Whether every group of this property landed inside the margin."""
|
|
169
|
+
return self.outcome == WITHIN
|
|
170
|
+
|
|
171
|
+
def to_record_row(self) -> Dict[str, Any]:
|
|
172
|
+
"""The property row of the fidelity record (§6).
|
|
173
|
+
|
|
174
|
+
Exactly §6's keys. A single-column property spells its column as
|
|
175
|
+
``column``; a correlation spells its pair as ``columns``. The
|
|
176
|
+
per-group detail stays on the evaluation: §6 fixes one row per
|
|
177
|
+
declared property, and adding a group list here would make a
|
|
178
|
+
record that a reader of the specification cannot parse.
|
|
179
|
+
"""
|
|
180
|
+
row: Dict[str, Any] = {"property": self.kind.value}
|
|
181
|
+
if len(self.columns) == 1:
|
|
182
|
+
row["column"] = self.columns[0]
|
|
183
|
+
else:
|
|
184
|
+
row["columns"] = list(self.columns)
|
|
185
|
+
if self.group_by is not None:
|
|
186
|
+
row["groupBy"] = self.group_by
|
|
187
|
+
row["tolerance"] = dict(sorted(self.tolerance.items()))
|
|
188
|
+
row["margin"] = self.margin
|
|
189
|
+
row["epsilon"] = self.epsilon
|
|
190
|
+
row["outcome"] = self.outcome
|
|
191
|
+
return row
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
@dataclass(frozen=True)
|
|
195
|
+
class Refusal:
|
|
196
|
+
"""One fail-closed condition of §5, with the code that names it.
|
|
197
|
+
|
|
198
|
+
``reason`` names a column, a row index, a property or a count -- never
|
|
199
|
+
a value (KERNEL-SPEC §9), because a refusal that quoted the record it
|
|
200
|
+
tripped on would be a record leaving the boundary by another route.
|
|
201
|
+
"""
|
|
202
|
+
|
|
203
|
+
code: str
|
|
204
|
+
reason: str
|
|
205
|
+
property_id: Optional[str] = None
|
|
206
|
+
|
|
207
|
+
def to_document(self) -> Dict[str, Any]:
|
|
208
|
+
"""The canonical form carried in a gate decision."""
|
|
209
|
+
return {
|
|
210
|
+
"code": self.code,
|
|
211
|
+
"reason": self.reason,
|
|
212
|
+
"propertyId": self.property_id,
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
@dataclass(frozen=True)
|
|
217
|
+
class FidelityEvaluation:
|
|
218
|
+
"""What the verifier found. Two fields, and no boolean that merges them."""
|
|
219
|
+
|
|
220
|
+
expose_id: str
|
|
221
|
+
outcomes: Tuple[PropertyOutcome, ...]
|
|
222
|
+
refusals: Tuple[Refusal, ...] = ()
|
|
223
|
+
synthetic_rows: int = 0
|
|
224
|
+
|
|
225
|
+
@property
|
|
226
|
+
def refused(self) -> bool:
|
|
227
|
+
"""Whether any fail-closed condition of §5 was met."""
|
|
228
|
+
return bool(self.refusals)
|
|
229
|
+
|
|
230
|
+
@property
|
|
231
|
+
def within(self) -> bool:
|
|
232
|
+
"""Whether the check ran to completion and every property is within.
|
|
233
|
+
|
|
234
|
+
A refusal makes this ``False`` whatever the outcomes say: §5's
|
|
235
|
+
conditions are the cases where the verifier declines to answer,
|
|
236
|
+
and an unanswered question is not an answer of yes.
|
|
237
|
+
"""
|
|
238
|
+
return not self.refusals and all(entry.within for entry in self.outcomes)
|
|
239
|
+
|
|
240
|
+
@property
|
|
241
|
+
def outside(self) -> Tuple[PropertyOutcome, ...]:
|
|
242
|
+
"""The properties that landed outside their compiled margin."""
|
|
243
|
+
return tuple(entry for entry in self.outcomes if not entry.within)
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
# ---------------------------------------------------------------------------
|
|
247
|
+
# The backend
|
|
248
|
+
# ---------------------------------------------------------------------------
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
def _group_outcome(
|
|
252
|
+
compiled: CompiledProperty,
|
|
253
|
+
committed: GroupStatistic,
|
|
254
|
+
synthetic: GroupStatistic,
|
|
255
|
+
) -> bool:
|
|
256
|
+
declaration = compiled.declaration
|
|
257
|
+
kind = declaration.kind
|
|
258
|
+
|
|
259
|
+
if kind is PropertyKind.MEAN:
|
|
260
|
+
if declaration.tolerance.kind is ToleranceKind.ABSOLUTE:
|
|
261
|
+
assert compiled.margin_units is not None
|
|
262
|
+
return mean_within_absolute(
|
|
263
|
+
sum_a=synthetic.sum_x,
|
|
264
|
+
count_a=synthetic.k,
|
|
265
|
+
sum_b=committed.sum_x,
|
|
266
|
+
count_b=committed.k,
|
|
267
|
+
tolerance_units=compiled.margin_units,
|
|
268
|
+
)
|
|
269
|
+
assert compiled.margin is not None
|
|
270
|
+
return mean_within_relative(
|
|
271
|
+
sum_a=synthetic.sum_x,
|
|
272
|
+
count_a=synthetic.k,
|
|
273
|
+
sum_b=committed.sum_x,
|
|
274
|
+
count_b=committed.k,
|
|
275
|
+
tolerance=compiled.margin,
|
|
276
|
+
)
|
|
277
|
+
|
|
278
|
+
if kind is PropertyKind.MARGINAL_HISTOGRAM:
|
|
279
|
+
assert compiled.margin is not None
|
|
280
|
+
return total_variation_within(
|
|
281
|
+
counts_a=synthetic.bin_counts,
|
|
282
|
+
count_a=synthetic.k,
|
|
283
|
+
counts_b=committed.bin_counts,
|
|
284
|
+
count_b=committed.k,
|
|
285
|
+
tolerance=compiled.margin,
|
|
286
|
+
)
|
|
287
|
+
|
|
288
|
+
if kind is PropertyKind.SUPPORT:
|
|
289
|
+
assert compiled.max_non_members is not None
|
|
290
|
+
members = set(committed.support)
|
|
291
|
+
# §5's "count of non-members" is counted in RECORDS, not in
|
|
292
|
+
# distinct strange values. Counting distinct values would let a
|
|
293
|
+
# dataset every one of whose records carries one undeclared level
|
|
294
|
+
# count as a single non-member and pass under any ``max >= 1``,
|
|
295
|
+
# so the tolerance would bound the size of the strange set rather
|
|
296
|
+
# than how much of the dataset is strange.
|
|
297
|
+
strangers = sum(
|
|
298
|
+
occurrences
|
|
299
|
+
for value, occurrences in zip(synthetic.support, synthetic.support_counts, strict=True)
|
|
300
|
+
if value not in members
|
|
301
|
+
)
|
|
302
|
+
return support_within(
|
|
303
|
+
non_member_count=strangers,
|
|
304
|
+
max_non_members=compiled.max_non_members,
|
|
305
|
+
)
|
|
306
|
+
|
|
307
|
+
if kind is PropertyKind.CORRELATION:
|
|
308
|
+
assert compiled.margin is not None and declaration.min_variance is not None
|
|
309
|
+
return correlation_within(
|
|
310
|
+
moments_a=synthetic.moments,
|
|
311
|
+
moments_b=committed.moments,
|
|
312
|
+
tolerance=compiled.margin,
|
|
313
|
+
min_variance=declaration.min_variance,
|
|
314
|
+
)
|
|
315
|
+
|
|
316
|
+
# QUANTILE
|
|
317
|
+
assert declaration.level is not None and compiled.margin_units is not None
|
|
318
|
+
for side, statistic in (("committed", committed), ("synthetic", synthetic)):
|
|
319
|
+
if statistic.quantile_witness is None:
|
|
320
|
+
raise FluxError(
|
|
321
|
+
FLX_5005, f"{side} side offers no quantile witness for {declaration.property_id}"
|
|
322
|
+
)
|
|
323
|
+
if not quantile_rank_ok(
|
|
324
|
+
count=statistic.k,
|
|
325
|
+
level=declaration.level,
|
|
326
|
+
count_strictly_below=statistic.quantile_below,
|
|
327
|
+
count_at_or_below=statistic.quantile_at_or_below,
|
|
328
|
+
):
|
|
329
|
+
raise FluxError(
|
|
330
|
+
FLX_5005,
|
|
331
|
+
f"the {side} side's quantile witness for {declaration.property_id} does not "
|
|
332
|
+
"carry the ranks the order statistic requires",
|
|
333
|
+
)
|
|
334
|
+
assert committed.quantile_witness is not None and synthetic.quantile_witness is not None
|
|
335
|
+
return quantile_within(
|
|
336
|
+
witness_a=synthetic.quantile_witness,
|
|
337
|
+
witness_b=committed.quantile_witness,
|
|
338
|
+
tolerance_units=compiled.margin_units,
|
|
339
|
+
)
|
|
340
|
+
|
|
341
|
+
|
|
342
|
+
@dataclass(frozen=True)
|
|
343
|
+
class ClearStatistic:
|
|
344
|
+
"""The v0.1 verifier: it recomputes the aggregates and compares them.
|
|
345
|
+
|
|
346
|
+
Holds what §5 says a verifier takes -- the compiled contract set, the
|
|
347
|
+
committed state's published quantities, and D′'s rows -- and nothing
|
|
348
|
+
that would let it see a committed record.
|
|
349
|
+
|
|
350
|
+
Satisfies :class:`flux_engine.api.fidelity.FidelityVerifier`
|
|
351
|
+
structurally: :attr:`proof_system` names the backend and
|
|
352
|
+
:meth:`check` returns the claim the evaluation supports.
|
|
353
|
+
"""
|
|
354
|
+
|
|
355
|
+
compiled: CompiledFidelity
|
|
356
|
+
committed: CommittedState
|
|
357
|
+
synthetic_rows: Sequence[Row]
|
|
358
|
+
proof_system: NoProofSystem = NoProofSystem()
|
|
359
|
+
|
|
360
|
+
def evaluate(self) -> FidelityEvaluation:
|
|
361
|
+
"""Re-evaluate every declared property, fail-closed.
|
|
362
|
+
|
|
363
|
+
Recomputes ``G`` from the compiled contract set and refuses
|
|
364
|
+
(``FLX-5011``) a committed state formed under a different one;
|
|
365
|
+
recomputes D′'s statistics on the declared grid; then compares
|
|
366
|
+
each property in its integer cross-multiplied form. Every
|
|
367
|
+
fail-closed condition becomes a :class:`Refusal` rather than an
|
|
368
|
+
exception, so one call reports every reason the check declined
|
|
369
|
+
instead of only the first.
|
|
370
|
+
"""
|
|
371
|
+
refusals: List[Refusal] = []
|
|
372
|
+
if self.committed.g != self.compiled.g.value:
|
|
373
|
+
refusals.append(
|
|
374
|
+
Refusal(
|
|
375
|
+
code=FLX_5011.code,
|
|
376
|
+
reason=(
|
|
377
|
+
"the committed state was formed under different declarations; "
|
|
378
|
+
"a new committed state is required"
|
|
379
|
+
),
|
|
380
|
+
)
|
|
381
|
+
)
|
|
382
|
+
if self.committed.expose_id != self.compiled.block.expose_id:
|
|
383
|
+
refusals.append(
|
|
384
|
+
Refusal(
|
|
385
|
+
code=FLX_5005.code,
|
|
386
|
+
reason="the committed state answers for a different expose",
|
|
387
|
+
)
|
|
388
|
+
)
|
|
389
|
+
if refusals:
|
|
390
|
+
return FidelityEvaluation(
|
|
391
|
+
expose_id=self.compiled.block.expose_id,
|
|
392
|
+
outcomes=(),
|
|
393
|
+
refusals=tuple(refusals),
|
|
394
|
+
synthetic_rows=len(self.synthetic_rows),
|
|
395
|
+
)
|
|
396
|
+
|
|
397
|
+
try:
|
|
398
|
+
require_record_count(
|
|
399
|
+
self.synthetic_rows, self.compiled.block, subject="synthetic dataset"
|
|
400
|
+
)
|
|
401
|
+
except FluxError as error:
|
|
402
|
+
return FidelityEvaluation(
|
|
403
|
+
expose_id=self.compiled.block.expose_id,
|
|
404
|
+
outcomes=(),
|
|
405
|
+
refusals=(Refusal(code=error.code.code, reason=error.detail),),
|
|
406
|
+
synthetic_rows=len(self.synthetic_rows),
|
|
407
|
+
)
|
|
408
|
+
|
|
409
|
+
outcomes: List[PropertyOutcome] = []
|
|
410
|
+
for entry in self.compiled.properties:
|
|
411
|
+
outcome, property_refusals = self._evaluate_property(entry)
|
|
412
|
+
refusals.extend(property_refusals)
|
|
413
|
+
outcomes.append(outcome)
|
|
414
|
+
return FidelityEvaluation(
|
|
415
|
+
expose_id=self.compiled.block.expose_id,
|
|
416
|
+
outcomes=tuple(outcomes),
|
|
417
|
+
refusals=tuple(refusals),
|
|
418
|
+
synthetic_rows=len(self.synthetic_rows),
|
|
419
|
+
)
|
|
420
|
+
|
|
421
|
+
def _evaluate_property(self, entry: CompiledProperty) -> Tuple[PropertyOutcome, List[Refusal]]:
|
|
422
|
+
"""Compare one property, refusing only that property on a fail-closed.
|
|
423
|
+
|
|
424
|
+
The synthetic side's quantities are formed here rather than for the
|
|
425
|
+
whole dataset at once, so a value outside its range on one column
|
|
426
|
+
refuses the properties over that column and leaves the rest
|
|
427
|
+
answerable.
|
|
428
|
+
"""
|
|
429
|
+
declaration = entry.declaration
|
|
430
|
+
property_id = entry.property_id
|
|
431
|
+
refusals: List[Refusal] = []
|
|
432
|
+
base = PropertyOutcome(
|
|
433
|
+
property_id=property_id,
|
|
434
|
+
kind=declaration.kind,
|
|
435
|
+
columns=declaration.columns,
|
|
436
|
+
group_by=declaration.group_by,
|
|
437
|
+
tolerance=declaration.tolerance.declared,
|
|
438
|
+
margin=render_exact(entry.margin) if entry.margin is not None else None,
|
|
439
|
+
epsilon=render_exact(entry.epsilon),
|
|
440
|
+
outcome=OUTSIDE,
|
|
441
|
+
)
|
|
442
|
+
committed_statistic = self.committed.statistic.properties.get(property_id)
|
|
443
|
+
if committed_statistic is None:
|
|
444
|
+
refusals.append(
|
|
445
|
+
Refusal(
|
|
446
|
+
code=FLX_5005.code,
|
|
447
|
+
reason="the committed state carries no statistic for this property",
|
|
448
|
+
property_id=property_id,
|
|
449
|
+
)
|
|
450
|
+
)
|
|
451
|
+
return base, refusals
|
|
452
|
+
try:
|
|
453
|
+
synthetic_statistic = compute_property_statistic(
|
|
454
|
+
self.synthetic_rows,
|
|
455
|
+
entry,
|
|
456
|
+
self.compiled.block,
|
|
457
|
+
subject="synthetic dataset",
|
|
458
|
+
)
|
|
459
|
+
except FluxError as error:
|
|
460
|
+
refusals.append(
|
|
461
|
+
Refusal(code=error.code.code, reason=error.detail, property_id=property_id)
|
|
462
|
+
)
|
|
463
|
+
return base, refusals
|
|
464
|
+
|
|
465
|
+
committed_groups = {group.group: group for group in committed_statistic.groups}
|
|
466
|
+
synthetic_groups = {group.group: group for group in synthetic_statistic.groups}
|
|
467
|
+
if set(committed_groups) != set(synthetic_groups):
|
|
468
|
+
# Naming the differing keys would name category values, which
|
|
469
|
+
# KERNEL-SPEC §9 keeps out of diagnostics. The counts are
|
|
470
|
+
# enough to act on.
|
|
471
|
+
refusals.append(
|
|
472
|
+
Refusal(
|
|
473
|
+
code=FLX_5005.code,
|
|
474
|
+
reason=(
|
|
475
|
+
f"the two sides group into different sets: "
|
|
476
|
+
f"{len(committed_groups)} committed and {len(synthetic_groups)} "
|
|
477
|
+
"synthetic"
|
|
478
|
+
),
|
|
479
|
+
property_id=property_id,
|
|
480
|
+
)
|
|
481
|
+
)
|
|
482
|
+
return base, refusals
|
|
483
|
+
|
|
484
|
+
group_outcomes: List[GroupOutcome] = []
|
|
485
|
+
for key in sorted(committed_groups):
|
|
486
|
+
try:
|
|
487
|
+
within = _group_outcome(entry, committed_groups[key], synthetic_groups[key])
|
|
488
|
+
except FluxError as error:
|
|
489
|
+
refusals.append(
|
|
490
|
+
Refusal(code=error.code.code, reason=error.detail, property_id=property_id)
|
|
491
|
+
)
|
|
492
|
+
within = False
|
|
493
|
+
group_outcomes.append(
|
|
494
|
+
GroupOutcome(
|
|
495
|
+
group=key,
|
|
496
|
+
committed_count=committed_groups[key].k,
|
|
497
|
+
synthetic_count=synthetic_groups[key].k,
|
|
498
|
+
outcome=WITHIN if within else OUTSIDE,
|
|
499
|
+
)
|
|
500
|
+
)
|
|
501
|
+
every = all(group.within for group in group_outcomes)
|
|
502
|
+
return (
|
|
503
|
+
PropertyOutcome(
|
|
504
|
+
property_id=base.property_id,
|
|
505
|
+
kind=base.kind,
|
|
506
|
+
columns=base.columns,
|
|
507
|
+
group_by=base.group_by,
|
|
508
|
+
tolerance=base.tolerance,
|
|
509
|
+
margin=base.margin,
|
|
510
|
+
epsilon=base.epsilon,
|
|
511
|
+
outcome=WITHIN if every else OUTSIDE,
|
|
512
|
+
groups=tuple(group_outcomes),
|
|
513
|
+
),
|
|
514
|
+
refusals,
|
|
515
|
+
)
|
|
516
|
+
|
|
517
|
+
def check(self, statement: Any, attestation: Optional[bytes] = None) -> Any:
|
|
518
|
+
"""Re-evaluate *statement* and return the claim it supports.
|
|
519
|
+
|
|
520
|
+
Implements :class:`flux_engine.api.fidelity.FidelityVerifier`.
|
|
521
|
+
The claim's sentence names the outcome -- it never says agreement
|
|
522
|
+
for an evaluation that refused or that found a property outside
|
|
523
|
+
its margin -- and its basis is ``none`` because a fidelity check
|
|
524
|
+
measures the synthetic dataset against a committed state, not
|
|
525
|
+
against the world.
|
|
526
|
+
|
|
527
|
+
*attestation* must be ``None``: the ``"none"`` backend produces no
|
|
528
|
+
artefact, so a caller handing one over has confused this backend
|
|
529
|
+
for another and is told so rather than having it ignored.
|
|
530
|
+
"""
|
|
531
|
+
from flux_engine.api.claims import Claim, ClaimBasis, ClaimType
|
|
532
|
+
|
|
533
|
+
if attestation is not None:
|
|
534
|
+
raise FluxError(
|
|
535
|
+
FLX_5005,
|
|
536
|
+
"the 'none' backend produces and accepts no attestation artefact",
|
|
537
|
+
)
|
|
538
|
+
expose_id = getattr(statement, "expose_id", None)
|
|
539
|
+
if expose_id is not None and expose_id != self.compiled.block.expose_id:
|
|
540
|
+
raise FluxError(
|
|
541
|
+
FLX_5005,
|
|
542
|
+
f"the statement answers for expose {expose_id!r}, this backend for "
|
|
543
|
+
f"{self.compiled.block.expose_id!r}",
|
|
544
|
+
)
|
|
545
|
+
evaluation = self.evaluate()
|
|
546
|
+
if evaluation.refused:
|
|
547
|
+
sentence = (
|
|
548
|
+
f"the fidelity check declined to answer for expose "
|
|
549
|
+
f"{self.compiled.block.expose_id!r}: {len(evaluation.refusals)} fail-closed "
|
|
550
|
+
"conditions were met"
|
|
551
|
+
)
|
|
552
|
+
elif evaluation.within:
|
|
553
|
+
sentence = (
|
|
554
|
+
f"every one of the {len(evaluation.outcomes)} declared properties of expose "
|
|
555
|
+
f"{self.compiled.block.expose_id!r} is within its compiled margin against the "
|
|
556
|
+
f"committed state at ordinal {self.committed.ordinal}"
|
|
557
|
+
)
|
|
558
|
+
else:
|
|
559
|
+
sentence = (
|
|
560
|
+
f"{len(evaluation.outside)} of the {len(evaluation.outcomes)} declared "
|
|
561
|
+
f"properties of expose {self.compiled.block.expose_id!r} are outside their "
|
|
562
|
+
"compiled margin"
|
|
563
|
+
)
|
|
564
|
+
return Claim(
|
|
565
|
+
claim_type=ClaimType.FIDELITY,
|
|
566
|
+
statement=sentence,
|
|
567
|
+
basis=ClaimBasis.NONE,
|
|
568
|
+
evidence=(self.compiled.h, self.compiled.g),
|
|
569
|
+
verifier=f"{type(self).__name__}/{self.proof_system.name}",
|
|
570
|
+
)
|
|
571
|
+
|
|
572
|
+
|
|
573
|
+
# The extension contract this backend targets is
|
|
574
|
+
# ``flux_engine.api.fidelity.FidelityVerifier``. It is satisfied at runtime
|
|
575
|
+
# (``isinstance(backend, FidelityVerifier)`` holds, and a test pins that),
|
|
576
|
+
# but not yet as a *static* assertion: that Protocol spells
|
|
577
|
+
# ``proof_system`` and ``ProofSystem.name`` as settable variables, and mypy
|
|
578
|
+
# refuses a frozen dataclass against a settable protocol member. Every
|
|
579
|
+
# dataclass on that API surface is frozen by its own doctrine, so the
|
|
580
|
+
# spelling excludes the implementations it is written for. The fix belongs
|
|
581
|
+
# in ``flux_engine/api/fidelity.py`` (read-only properties, which a mutable
|
|
582
|
+
# attribute also satisfies) and is filed as a request rather than worked
|
|
583
|
+
# around here by unfreezing a value object.
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# Copyright 2026 Agentics Transformation Limited
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
4
|
+
|
|
5
|
+
"""The choke point for the enveloped artifacts flux_engine writes to disk.
|
|
6
|
+
|
|
7
|
+
Mirrors ``fluid_build.cli.artifact_writer`` / ``artifact_envelope``: one
|
|
8
|
+
place, one envelope shape, so every generated file -- plan output, run
|
|
9
|
+
attestation, fidelity record, evidence manifest -- is instantly
|
|
10
|
+
recognisable and carries a stable schema_version a future migration can
|
|
11
|
+
key off.
|
|
12
|
+
|
|
13
|
+
**Which kinds go through it today.** ``RunAttestation``
|
|
14
|
+
(:mod:`flux_engine.seam.attest`), ``AccuracyRecord``
|
|
15
|
+
(:mod:`flux_engine.accuracy.accuracy_record`) and ``GoldenSnapshot``
|
|
16
|
+
(:mod:`flux_engine.stages.verify`) are written by this function. The
|
|
17
|
+
remaining kinds in :data:`EnvelopeKind` are still written by their own
|
|
18
|
+
producers -- ``PlanArtifact`` in ``stages/plan.py``, the fidelity record in
|
|
19
|
+
``stages/ship.py``, the manifest in ``evidence/pack.py``, and
|
|
20
|
+
``calibrate/provenance.py``, which says in its own docstring that it
|
|
21
|
+
mirrors this envelope's byte shape and then re-implements it. That is a
|
|
22
|
+
real gap, not a design: a fifth envelope field or a different indent would
|
|
23
|
+
desynchronise those files from the rest. ``tests/stages`` pins the list of
|
|
24
|
+
producers that bypass this function, so it can shrink and cannot silently
|
|
25
|
+
grow.
|
|
26
|
+
|
|
27
|
+
Kernel modules (see the "kernel packages" import-linter contract in
|
|
28
|
+
pyproject.toml) may not call the wall clock, so ``generated_at`` is always
|
|
29
|
+
supplied by the caller -- the actual ``datetime.now()`` read happens at
|
|
30
|
+
the CLI / engine-facade layer, never inside ``flux_engine.core``. That
|
|
31
|
+
keeps this module itself free of non-deterministic calls while still
|
|
32
|
+
producing a real wall-clock timestamp in every artifact.
|
|
33
|
+
"""
|
|
34
|
+
|
|
35
|
+
from __future__ import annotations
|
|
36
|
+
|
|
37
|
+
import json
|
|
38
|
+
from pathlib import Path
|
|
39
|
+
from typing import Any, Dict, Literal, Union
|
|
40
|
+
|
|
41
|
+
__all__ = ["ENVELOPE_NON_DIGEST_FIELDS", "EnvelopeKind", "write_artifact"]
|
|
42
|
+
|
|
43
|
+
#: Every artifact kind flux_engine writes. Kept closed (a Literal, not a
|
|
44
|
+
#: bare ``str``) so a typo in a caller is a type-check failure, not a
|
|
45
|
+
#: silently-accepted new kind nothing downstream recognises.
|
|
46
|
+
EnvelopeKind = Literal[
|
|
47
|
+
"PlanArtifact",
|
|
48
|
+
"RunAttestation",
|
|
49
|
+
"FidelityRecord",
|
|
50
|
+
"AccuracyRecord",
|
|
51
|
+
"EvidenceManifest",
|
|
52
|
+
"GoldenSnapshot",
|
|
53
|
+
"CalibrationProvenance",
|
|
54
|
+
]
|
|
55
|
+
|
|
56
|
+
#: Fields present in every envelope that must be excluded from any
|
|
57
|
+
#: content-addressed digest computed over an artifact's bytes. Both are
|
|
58
|
+
#: wall-clock / identity fields that would otherwise make two runs over
|
|
59
|
+
#: identical inputs produce different digests -- this is the envelope-only
|
|
60
|
+
#: subset; ``flux_engine.core.canonical.NON_DIGEST_FIELDS`` is the
|
|
61
|
+
#: five-member superset the digest mask actually uses, and nothing outside
|
|
62
|
+
#: this module reads the constant below. Two constants under one name is
|
|
63
|
+
#: how a reader comes to believe the envelope mask is the digest mask.
|
|
64
|
+
ENVELOPE_NON_DIGEST_FIELDS = frozenset({"generated_at", "generated_by"})
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def write_artifact(
|
|
68
|
+
path: Union[str, Path],
|
|
69
|
+
obj: Dict[str, Any],
|
|
70
|
+
*,
|
|
71
|
+
kind: EnvelopeKind,
|
|
72
|
+
schema_version: str,
|
|
73
|
+
generated_at: str,
|
|
74
|
+
generated_by: str = "flux-engine",
|
|
75
|
+
) -> Path:
|
|
76
|
+
"""Write *obj* to *path* as sorted-key JSON with the standard envelope.
|
|
77
|
+
|
|
78
|
+
The envelope has exactly four fields: ``schema_version``, ``kind``,
|
|
79
|
+
``generated_at``, ``generated_by``. Payload keys from *obj* follow.
|
|
80
|
+
The file is written with ``sort_keys=True`` and a trailing newline so
|
|
81
|
+
two runs over identical inputs (modulo
|
|
82
|
+
:data:`ENVELOPE_NON_DIGEST_FIELDS`) produce
|
|
83
|
+
byte-identical output.
|
|
84
|
+
|
|
85
|
+
``generated_at`` is a required keyword, not defaulted internally --
|
|
86
|
+
see the module docstring for why the wall-clock read lives at the
|
|
87
|
+
call site rather than in this kernel module.
|
|
88
|
+
"""
|
|
89
|
+
envelope: Dict[str, Any] = {
|
|
90
|
+
"schema_version": schema_version,
|
|
91
|
+
"kind": kind,
|
|
92
|
+
"generated_at": generated_at,
|
|
93
|
+
"generated_by": generated_by,
|
|
94
|
+
}
|
|
95
|
+
merged: Dict[str, Any] = {**envelope, **obj}
|
|
96
|
+
p = Path(path)
|
|
97
|
+
p.parent.mkdir(parents=True, exist_ok=True)
|
|
98
|
+
p.write_text(json.dumps(merged, sort_keys=True, indent=2) + "\n", encoding="utf-8")
|
|
99
|
+
return p
|