flux-sim-engine 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (165) hide show
  1. flux_engine/__init__.py +22 -0
  2. flux_engine/_links.py +55 -0
  3. flux_engine/_vendor/__init__.py +5 -0
  4. flux_engine/_vendor/flux_spec/NOTICE +19 -0
  5. flux_engine/_vendor/flux_spec/VENDOR-NOTES.md +104 -0
  6. flux_engine/_vendor/flux_spec/__init__.py +9 -0
  7. flux_engine/_vendor/flux_spec/bundle.py +410 -0
  8. flux_engine/_vendor/flux_spec/enforce.py +316 -0
  9. flux_engine/_vendor/flux_spec/schema/flux-enforcement-0.5.0.json +121 -0
  10. flux_engine/_vendor/flux_spec/schema/flux-manifest-0.5.0.json +153 -0
  11. flux_engine/_vendor/flux_spec/schema/flux-schema-0.2.0.json +465 -0
  12. flux_engine/_vendor/flux_spec/schema/flux-schema-0.3.0.json +876 -0
  13. flux_engine/_vendor/flux_spec/schema/flux-schema-0.4.0.json +1601 -0
  14. flux_engine/_vendor/flux_spec/schema/flux-schema-0.4.1.json +1668 -0
  15. flux_engine/_vendor/flux_spec/schema/flux-schema-0.5.0.json +1669 -0
  16. flux_engine/_vendor/flux_spec/schema/flux-schema-latest.json +1669 -0
  17. flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.4.0.json +795 -0
  18. flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.4.1.json +852 -0
  19. flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.5.0.json +852 -0
  20. flux_engine/_vendor/flux_spec/validate.py +537 -0
  21. flux_engine/_vendor/flux_spec/vectors/enforcement-vectors.json +935 -0
  22. flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.3.json +5234 -0
  23. flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.4.json +5437 -0
  24. flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.5.json +5498 -0
  25. flux_engine/_vocabulary.py +141 -0
  26. flux_engine/accuracy/__init__.py +5 -0
  27. flux_engine/accuracy/_scoring/__init__.py +24 -0
  28. flux_engine/accuracy/accuracy_record.py +96 -0
  29. flux_engine/accuracy/policy.py +158 -0
  30. flux_engine/accuracy/records.py +264 -0
  31. flux_engine/accuracy/store.py +169 -0
  32. flux_engine/api/__init__.py +163 -0
  33. flux_engine/api/accuracy.py +209 -0
  34. flux_engine/api/agentic.py +134 -0
  35. flux_engine/api/calibration.py +125 -0
  36. flux_engine/api/claims.py +93 -0
  37. flux_engine/api/digests.py +73 -0
  38. flux_engine/api/emit.py +78 -0
  39. flux_engine/api/expressions.py +72 -0
  40. flux_engine/api/fidelity.py +110 -0
  41. flux_engine/api/lineage.py +78 -0
  42. flux_engine/api/stages.py +242 -0
  43. flux_engine/api/verdict.py +108 -0
  44. flux_engine/calibrate/__init__.py +5 -0
  45. flux_engine/calibrate/declared.py +253 -0
  46. flux_engine/calibrate/provenance.py +113 -0
  47. flux_engine/cli/__init__.py +2146 -0
  48. flux_engine/cli/__main__.py +17 -0
  49. flux_engine/cli/_documents.py +226 -0
  50. flux_engine/cli/_hints.py +118 -0
  51. flux_engine/cli/_init.py +152 -0
  52. flux_engine/cli/_progress.py +124 -0
  53. flux_engine/concordance/__init__.py +127 -0
  54. flux_engine/concordance/boundary/__init__.py +78 -0
  55. flux_engine/concordance/boundary/merkle.py +287 -0
  56. flux_engine/concordance/boundary/slice.py +429 -0
  57. flux_engine/concordance/boundary/statistic.py +561 -0
  58. flux_engine/concordance/boundary/store.py +334 -0
  59. flux_engine/concordance/boundary/vault.py +357 -0
  60. flux_engine/concordance/compiler.py +542 -0
  61. flux_engine/concordance/errors.py +189 -0
  62. flux_engine/concordance/gate.py +525 -0
  63. flux_engine/concordance/predicate.py +1217 -0
  64. flux_engine/concordance/record.py +554 -0
  65. flux_engine/concordance/verifier.py +583 -0
  66. flux_engine/core/__init__.py +5 -0
  67. flux_engine/core/artifact.py +99 -0
  68. flux_engine/core/canonical.py +369 -0
  69. flux_engine/core/clock.py +437 -0
  70. flux_engine/core/digest.py +288 -0
  71. flux_engine/core/errors.py +277 -0
  72. flux_engine/core/fixedpoint.py +929 -0
  73. flux_engine/core/lrm.py +158 -0
  74. flux_engine/core/rng.py +736 -0
  75. flux_engine/core/seedtree.py +891 -0
  76. flux_engine/core/trace.py +423 -0
  77. flux_engine/describe.py +207 -0
  78. flux_engine/engine.py +257 -0
  79. flux_engine/evidence/__init__.py +5 -0
  80. flux_engine/evidence/pack.py +411 -0
  81. flux_engine/evidence/report.py +243 -0
  82. flux_engine/expr/__init__.py +133 -0
  83. flux_engine/expr/ast.py +312 -0
  84. flux_engine/expr/attrs.py +386 -0
  85. flux_engine/expr/check.py +278 -0
  86. flux_engine/expr/compile.py +322 -0
  87. flux_engine/expr/errors.py +256 -0
  88. flux_engine/expr/lexer.py +297 -0
  89. flux_engine/expr/parser.py +313 -0
  90. flux_engine/expr/types.py +177 -0
  91. flux_engine/generator/__init__.py +97 -0
  92. flux_engine/generator/families.py +325 -0
  93. flux_engine/generator/paths.py +227 -0
  94. flux_engine/generator/rows.py +918 -0
  95. flux_engine/generator/statistics.py +524 -0
  96. flux_engine/governance/__init__.py +87 -0
  97. flux_engine/governance/audit.py +307 -0
  98. flux_engine/governance/gate.py +334 -0
  99. flux_engine/governance/skills.py +220 -0
  100. flux_engine/governance/sovereignty.py +251 -0
  101. flux_engine/lineage/__init__.py +5 -0
  102. flux_engine/lineage/emitter.py +398 -0
  103. flux_engine/py.typed +0 -0
  104. flux_engine/runtime/__init__.py +153 -0
  105. flux_engine/runtime/campaign.py +407 -0
  106. flux_engine/runtime/cast.py +283 -0
  107. flux_engine/runtime/detector.py +222 -0
  108. flux_engine/runtime/errors.py +58 -0
  109. flux_engine/runtime/experiment.py +311 -0
  110. flux_engine/runtime/journey.py +383 -0
  111. flux_engine/runtime/jurisdiction.py +72 -0
  112. flux_engine/runtime/payloads.py +124 -0
  113. flux_engine/runtime/signals.py +334 -0
  114. flux_engine/runtime/temperature.py +156 -0
  115. flux_engine/seam/__init__.py +5 -0
  116. flux_engine/seam/attest.py +290 -0
  117. flux_engine/seam/conform.py +448 -0
  118. flux_engine/seam/contract.py +605 -0
  119. flux_engine/seam/emit.py +488 -0
  120. flux_engine/seam/mapping.py +299 -0
  121. flux_engine/seam/resolve.py +1087 -0
  122. flux_engine/seam/sinks.py +157 -0
  123. flux_engine/spec/__init__.py +134 -0
  124. flux_engine/spec/bundle.py +25 -0
  125. flux_engine/spec/enforce.py +31 -0
  126. flux_engine/spec/validate.py +28 -0
  127. flux_engine/stages/__init__.py +30 -0
  128. flux_engine/stages/apply.py +447 -0
  129. flux_engine/stages/errors.py +315 -0
  130. flux_engine/stages/layout.py +292 -0
  131. flux_engine/stages/pipeline.py +600 -0
  132. flux_engine/stages/plan.py +241 -0
  133. flux_engine/stages/replay.py +83 -0
  134. flux_engine/stages/run.py +208 -0
  135. flux_engine/stages/ship.py +934 -0
  136. flux_engine/stages/validate.py +93 -0
  137. flux_engine/stages/verify.py +1129 -0
  138. flux_engine/starter/__init__.py +161 -0
  139. flux_engine/starter/bundle/detector.flux.yml +15 -0
  140. flux_engine/starter/bundle/journey.flux.yml +23 -0
  141. flux_engine/starter/bundle/module.flux.yml +16 -0
  142. flux_engine/starter/bundle/payment-recovery.fluid.yml +30 -0
  143. flux_engine/starter/bundle/persona.flux.yml +26 -0
  144. flux_engine/starter/bundle/signal.flux.yml +13 -0
  145. flux_engine/starter/bundle/simulation.flux.yml +29 -0
  146. flux_engine/starter/bundle/taxonomy.flux.yml +17 -0
  147. flux_engine/starter/bundle/treatment.flux.yml +13 -0
  148. flux_engine/starter/bundle/world.flux.yml +20 -0
  149. flux_engine/verticals/__init__.py +85 -0
  150. flux_engine/verticals/telco.py +89 -0
  151. flux_engine/world/__init__.py +89 -0
  152. flux_engine/world/derived.py +195 -0
  153. flux_engine/world/errors.py +41 -0
  154. flux_engine/world/families.py +260 -0
  155. flux_engine/world/population.py +602 -0
  156. flux_engine/world/tracing.py +66 -0
  157. flux_engine/world/values.py +121 -0
  158. flux_sim_engine-0.2.0.dist-info/METADATA +108 -0
  159. flux_sim_engine-0.2.0.dist-info/RECORD +165 -0
  160. flux_sim_engine-0.2.0.dist-info/WHEEL +5 -0
  161. flux_sim_engine-0.2.0.dist-info/entry_points.txt +2 -0
  162. flux_sim_engine-0.2.0.dist-info/licenses/LICENSE +202 -0
  163. flux_sim_engine-0.2.0.dist-info/licenses/NOTICE +10 -0
  164. flux_sim_engine-0.2.0.dist-info/licenses/flux_engine/_vendor/flux_spec/NOTICE +19 -0
  165. flux_sim_engine-0.2.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,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,5 @@
1
+ # Copyright 2026 Agentics Transformation Limited
2
+ #
3
+ # SPDX-License-Identifier: Apache-2.0
4
+
5
+ """Kernel numerics: canonicalisation, seed tree, fixed-point grid, LRM, clock, trace, artifact writer."""
@@ -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