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,1087 @@
1
+ # Copyright 2026 Agentics Transformation Limited
2
+ #
3
+ # SPDX-License-Identifier: Apache-2.0
4
+
5
+ """Resolving the FLUID seam: which contract, which expose, which bytes.
6
+
7
+ Implements the resolution half of KERNEL-SPEC §8: "``contractDigest`` is
8
+ recomputed from the in-bundle ``.fluid.yml`` (``jcs-document``) and
9
+ compared with the declared ``provenance.contractDigest`` (``FLX-3101`` on
10
+ mismatch)."
11
+
12
+ **The validator is borrowed, not rebuilt.** Every cross-document rule the
13
+ seam depends on -- ``productRef`` resolves to a ``.fluid.yml`` in the
14
+ bundle, ``exposeId`` is a member of its ``exposes[]``, the pinned
15
+ ``fluidVersion`` is satisfied, the emitted contract is at least as strict
16
+ as every consent profile gating the simulation -- is already implemented
17
+ in the FLUX reference validator, and this module delegates to it
18
+ (``flux_engine.spec.validate.Bundle``) rather than restating it. What this
19
+ module adds is the part the offline validator cannot do: it hands back the
20
+ resolved documents, the file bytes, and a recomputed digest in the
21
+ engine's own canonical domain, so the run has one object to bind to.
22
+
23
+ **The two digests are computed by two implementations, on purpose.** The
24
+ validator's own ``canonical_digest`` and the engine's
25
+ :func:`flux_engine.core.digest.digest_of_document` both claim to be "sha256
26
+ over the RFC 8785 canonicalisation", and a bundle that satisfies one and
27
+ not the other would be a bundle whose seam means two things.
28
+ :func:`resolve_emit` recomputes with the engine's canonicaliser --
29
+ the one every other digest in the run goes through -- and
30
+ ``test_resolve.py`` pins the two against each other on the shipped
31
+ example.
32
+
33
+ **The seam's own declarations live in the extension namespace.** FLUX
34
+ 0.5.0 closes ``Simulation.spec.emits[]`` (``additionalProperties: false``)
35
+ and opens exactly one door for a dialect: RFC-02's document-level
36
+ ``extensions`` map, keyed by ``reverse-dns/major``. So the fidelity block
37
+ (SEAM-FIDELITY-SPEC §2), the declared row count (§1) and the column
38
+ mapping live at::
39
+
40
+ extensions:
41
+ com.agentics.flux/1:
42
+ emits:
43
+ <exposeId>:
44
+ rows: 64
45
+ mapping: { <column>: <source path> }
46
+ fidelity: { ... }
47
+
48
+ :data:`EXTENSION_NAMESPACE` is that key. Every bundle stays valid against
49
+ the unmodified published schema -- the public ``scripts/validate.py`` and
50
+ ``scripts/bundle.py verify`` accept it with no tolerance, no stripping and
51
+ no engine-specific relaxation -- and :func:`resolve_emit` hands the block
52
+ back beside the emit entry so ``H`` can quote both (KERNEL-SPEC §8,
53
+ SEAM-FIDELITY-SPEC §3).
54
+
55
+ :data:`ADDITIVE_SEAM_FIELDS` is consequently **empty**. The enumeration
56
+ stays because it is the one place a future additive ``emits[]`` field
57
+ would have to be named, and because a test can prove it is empty; with
58
+ nothing in it the tolerance :class:`SeamBundle` applies is a no-op and the
59
+ schema sees every document exactly as authored.
60
+ """
61
+
62
+ from __future__ import annotations
63
+
64
+ import importlib
65
+ import json
66
+ from dataclasses import dataclass
67
+ from decimal import Decimal, InvalidOperation
68
+ from pathlib import Path
69
+ from typing import AbstractSet, Any, Dict, FrozenSet, List, Mapping, Optional, Sequence, Tuple
70
+
71
+ import yaml
72
+ from jsonschema import Draft202012Validator, FormatChecker
73
+
74
+ from flux_engine.core.canonical import nfc
75
+ from flux_engine.core.digest import DigestRef, digest_of_bytes, digest_of_document
76
+ from flux_engine.core.errors import FluxError, register
77
+ from flux_engine.seam.contract import CompiledExpose, compile_expose, find_expose
78
+ from flux_engine.spec.bundle import MANIFEST_NAME
79
+ from flux_engine.spec.validate import Bundle, canonical_digest, load_yaml_docs, semver_satisfies
80
+
81
+ __all__ = [
82
+ "ADDITIVE_SEAM_FIELDS",
83
+ "BUNDLE_PACK_PRODUCTS",
84
+ "BundleDigestInputs",
85
+ "EXTENSION_NAMESPACE",
86
+ "ExactLoader",
87
+ "FLUID_DOCUMENT_GLOBS",
88
+ "FLUX_DOCUMENT_GLOBS",
89
+ "LOCK_FILE_NAME",
90
+ "load_documents_exact",
91
+ "FLX_3101",
92
+ "FLX_3102",
93
+ "FLX_3103",
94
+ "FLX_3104",
95
+ "FLX_3105",
96
+ "FLX_3107",
97
+ "FLX_3108",
98
+ "LoadedBundle",
99
+ "ResolvedEmit",
100
+ "SeamBundle",
101
+ "extension_block",
102
+ "flux_schema_validator",
103
+ "load_bundle",
104
+ "resolve_all_emits",
105
+ "resolve_emit",
106
+ "strip_additive_seam_fields",
107
+ ]
108
+
109
+ FLX_3101 = register(
110
+ "FLX-3101",
111
+ "declared contractDigest does not match the in-bundle contract",
112
+ "KERNEL-SPEC §8 recomputes the referenced FLUID document's digest from "
113
+ "the bytes actually in the bundle and compares it with the digest the "
114
+ "emit declares. A mismatch means the contract that was reviewed is not "
115
+ "the contract that would ship, which is the one thing the seam exists "
116
+ "to make impossible. Re-run plan to refresh the declared digest, or "
117
+ "restore the contract the digest was taken over.",
118
+ )
119
+
120
+ FLX_3102 = register(
121
+ "FLX-3102",
122
+ "emit productRef resolves to no FLUID document in the bundle",
123
+ "An emit names the FLUID data product it fulfils by id, and that "
124
+ "document travels in the bundle so the proven bytes are the shipped "
125
+ "bytes. No document in the bundle declares this id.",
126
+ )
127
+
128
+ FLX_3103 = register(
129
+ "FLX-3103",
130
+ "emit exposeId is not an expose of the referenced product",
131
+ "The emit names which interface of the data product this stream "
132
+ "fulfils. The referenced product declares no expose with that id, so "
133
+ "there is no column set to emit against.",
134
+ )
135
+
136
+ FLX_3104 = register(
137
+ "FLX-3104",
138
+ "referenced contract does not satisfy the pinned fluidVersion",
139
+ "The emit pins the FLUID version it was written against, exactly or as "
140
+ "a semver range. The referenced document declares a version outside "
141
+ "that pin, so the schema the emit was checked under is not the schema "
142
+ "the contract is written in.",
143
+ )
144
+
145
+ FLX_3105 = register(
146
+ "FLX-3105",
147
+ "bundle does not validate, so its seam cannot be resolved",
148
+ "Resolution delegates to the FLUX offline reference validator: every "
149
+ "reference resolves, every id is unique, every weight sums, and every "
150
+ "in-bundle FLUID document is valid for its declared version. A bundle "
151
+ "that fails those checks has no seam to resolve, and repairing it here "
152
+ "would mean the engine ran against something the validator refused.",
153
+ )
154
+
155
+ FLX_3107 = register(
156
+ "FLX-3107",
157
+ "bundle directory not found",
158
+ "Every command that takes a bundle takes the path of a *directory* "
159
+ "holding the bundle's `.flux.yml` documents (and the `.fluid.yml` "
160
+ "contract they reference). Nothing at the path given is a directory -- "
161
+ "a typo, a path relative to a different working directory, or the path "
162
+ "of one document inside the bundle rather than the bundle itself. "
163
+ "Check the path and re-run the same command; nothing was read and "
164
+ "nothing was written.",
165
+ )
166
+
167
+ FLX_3108 = register(
168
+ "FLX-3108",
169
+ "the bundle directory holds a file this engine does not recognise",
170
+ "A bundle directory holds two classes of file and no third. Its "
171
+ "inputs are the documents the loader reads: `*.flux.yml`, "
172
+ "`*.flux.yaml`, `*.fluid.yml`, `*.fluid.yaml` and `flux.lock`. Its "
173
+ "products are the files a pack writes beside those documents, "
174
+ "`flux-manifest.json` and its detached signature, which are "
175
+ "recognised and left out of `inputDigest` because their content is a "
176
+ "function of the inputs. Any other regular file ends the command "
177
+ "here, naming the file, before a digest is taken. KERNEL-SPEC "
178
+ "section 11 makes `inputDigest` the value `apply` and `verify` bind a "
179
+ "run to, so a file that arrives beside the documents must neither "
180
+ "move that value quietly nor be hashed as an input without anyone "
181
+ "deciding it is one. Delete the file, or keep it outside the bundle "
182
+ "directory. If it is a document kind a newer FLUX version defines, "
183
+ "this engine is too old to read the bundle and the fix is to upgrade "
184
+ "the engine rather than to delete the document.",
185
+ )
186
+
187
+ #: The filename patterns a bundle's documents are named by, and the one
188
+ #: exact name its lockfile carries. The loader globs the directory with
189
+ #: these and nothing else, and every later decision about which files an
190
+ #: `inputDigest` covers reads the loader's result rather than matching the
191
+ #: directory a second time: two matchers that agree today are how the
192
+ #: original defect was written.
193
+ FLUX_DOCUMENT_GLOBS: Tuple[str, ...] = ("*.flux.yml", "*.flux.yaml")
194
+ FLUID_DOCUMENT_GLOBS: Tuple[str, ...] = ("*.fluid.yml", "*.fluid.yaml")
195
+ LOCK_FILE_NAME = "flux.lock"
196
+
197
+ #: What packing a bundle writes into the directory it packs. The manifest
198
+ #: carries the digests of the very files beside it, so hashing it into
199
+ #: `inputDigest` would fold a bundle's digest back into itself, and the
200
+ #: FLUX bundle format already excludes the manifest from its own file map
201
+ #: and Merkle root for that reason. The signature is the detached
202
+ #: signature `ssh-keygen -Y sign` writes next to the manifest it signs.
203
+ #:
204
+ #: Two exact names, never a suffix class: a wildcard over `*.sig` would
205
+ #: let a file called `evil.sig` sit beside the documents uncovered by any
206
+ #: digest, which is the case the bundle format's own verifier refuses.
207
+ #: The names are built from the bundler this engine links against, so an
208
+ #: upstream rename carries here with no edit.
209
+ BUNDLE_PACK_PRODUCTS: FrozenSet[str] = frozenset({MANIFEST_NAME, f"{MANIFEST_NAME}.sig"})
210
+
211
+ #: This engine's RFC-02 extension namespace. ``reverse-dns/major``, the
212
+ #: shape the published schema's ``propertyNames`` pattern requires, so a
213
+ #: bundle carrying it validates unmodified.
214
+ EXTENSION_NAMESPACE = "com.agentics.flux/1"
215
+
216
+ #: The key under :data:`EXTENSION_NAMESPACE` that holds the per-expose
217
+ #: blocks, and the three keys one block may carry.
218
+ _EMITS_KEY = "emits"
219
+ _ROWS_KEY = "rows"
220
+ _MAPPING_KEY = "mapping"
221
+
222
+ #: The one key SEAM-FIDELITY-SPEC §2 declares the block under. There is
223
+ #: no second spelling: two spellings of one declaration would be two
224
+ #: digests of one contract (§2's own reason for refusing a bare support
225
+ #: list), and a name only this engine's internals use has no business in
226
+ #: a document an author writes.
227
+ _FIDELITY_BLOCK_KEY: str = "fidelity"
228
+
229
+ #: Every key an extension block for one expose may carry. Closed: an
230
+ #: unknown key is a declaration this engine would silently ignore, and the
231
+ #: whole point of moving the block into ``extensions`` was to stop the
232
+ #: seam from tolerating declarations nothing reads.
233
+ _BLOCK_KEYS: FrozenSet[str] = frozenset({_ROWS_KEY, _MAPPING_KEY, _FIDELITY_BLOCK_KEY})
234
+
235
+ #: Additive FLUX RFC fields on an ``emits[]`` entry that the published
236
+ #: schema does not carry. **Empty**: everything this engine declares about
237
+ #: an emit now lives under :data:`EXTENSION_NAMESPACE` (see the module
238
+ #: docstring), so there is nothing left to tolerate and the schema sees
239
+ #: every document exactly as authored. The enumeration survives as the one
240
+ #: place a future additive field would be named.
241
+ ADDITIVE_SEAM_FIELDS: FrozenSet[str] = frozenset()
242
+
243
+
244
+ class ExactLoader(yaml.SafeLoader):
245
+ """A YAML loader that produces no ``float`` and no ``datetime``.
246
+
247
+ A bundle is read twice, for two incompatible consumers.
248
+
249
+ * **The JSON Schema validator** needs real JSON types: ``unitInterval``
250
+ is ``{"type": "number"}``, and a ``Decimal`` is not a number to
251
+ ``jsonschema``. That read is the reference validator's own, through
252
+ :func:`flux_engine.spec.validate.load_yaml_docs`.
253
+ * **The digests** must contain no float at all (KERNEL-SPEC §2.1), and
254
+ the shipped telco example declares ``minCredibility: 0.7`` -- a YAML
255
+ float in the very ``emits[]`` entry ``H`` is taken over. This loader
256
+ is that read: it constructs a float scalar as
257
+ ``Decimal(<the source text>)``, so the number that gets hashed is the
258
+ number the author wrote, exactly, and no binary float is ever
259
+ created.
260
+
261
+ Reading the source text rather than converting a parsed float is the
262
+ whole point: ``Decimal(0.7)`` is 0.69999999999999995559..., while
263
+ ``Decimal("0.7")`` is 0.7. Only the second is what the contract says.
264
+
265
+ Timestamps stay strings, matching the reference validator's loader and
266
+ the RFC 3339 grammar the schema declares.
267
+ """
268
+
269
+
270
+ def _construct_exact_float(loader: yaml.SafeLoader, node: yaml.Node) -> Decimal:
271
+ """Construct a YAML float scalar as an exact :class:`~decimal.Decimal`."""
272
+ text = str(loader.construct_scalar(node)).replace("_", "")
273
+ if ":" in text:
274
+ raise FluxError(
275
+ FLX_3105,
276
+ "YAML sexagesimal numbers have no canonical decimal spelling; write "
277
+ "the number in plain decimal notation",
278
+ )
279
+ try:
280
+ value = Decimal(text)
281
+ except InvalidOperation as exc:
282
+ raise FluxError(FLX_3105, f"{text!r} is not a decimal number") from exc
283
+ if not value.is_finite(): # pragma: no cover - see below
284
+ # Defence in depth, and today unreachable: YAML 1.1 spells every
285
+ # infinity and not-a-number with a leading dot (``.inf``, ``.nan``),
286
+ # and Decimal refuses all of those at the constructor above. The
287
+ # guard stays because the loader that decides which scalars reach
288
+ # here is the one thing about this function most likely to change,
289
+ # and a NaN in a digest pre-image is not a failure mode worth
290
+ # discovering downstream.
291
+ raise FluxError(
292
+ FLX_3105,
293
+ "an infinite or not-a-number value has no digest and no ordering",
294
+ )
295
+ return value
296
+
297
+
298
+ ExactLoader.add_constructor("tag:yaml.org,2002:float", _construct_exact_float)
299
+ ExactLoader.add_constructor(
300
+ "tag:yaml.org,2002:timestamp",
301
+ lambda loader, node: loader.construct_scalar(node),
302
+ )
303
+
304
+
305
+ def _with_yaml_mark(path: Path, message: str) -> str:
306
+ """Append ``(line L, column C)`` to a YAML load error when the parser knows it.
307
+
308
+ The reader this engine loads bundles through reports only the first
309
+ line of the parser's message, which is the sentence *without* the
310
+ position -- so a broken document said what was wrong and never where.
311
+ The position is re-derived by parsing the file again here, on the
312
+ failure path only, and the message is returned unchanged when the
313
+ second parse finds nothing to report.
314
+ """
315
+ try:
316
+ with Path(path).open(encoding="utf-8") as handle:
317
+ list(yaml.compose_all(handle))
318
+ except yaml.MarkedYAMLError as error:
319
+ mark = error.problem_mark or error.context_mark
320
+ if mark is not None:
321
+ return f"{message} (line {mark.line + 1}, column {mark.column + 1})"
322
+ except (yaml.YAMLError, OSError):
323
+ return message
324
+ return message
325
+
326
+
327
+ def load_documents_exact(path: Path) -> Tuple[Dict[str, Any], ...]:
328
+ """Load every YAML document in *path* with no float and no datetime.
329
+
330
+ The read the digests are taken over. Raises ``FLX-3105`` on unreadable
331
+ YAML, so a caller never has to tell "no documents" from "a broken
332
+ file".
333
+ """
334
+ try:
335
+ with Path(path).open(encoding="utf-8") as handle:
336
+ documents = list(yaml.load_all(handle, Loader=ExactLoader))
337
+ except (yaml.YAMLError, OSError) as exc:
338
+ raise FluxError(
339
+ FLX_3105, f"{Path(path).name}: unreadable YAML ({type(exc).__name__})"
340
+ ) from exc
341
+ return tuple(document for document in documents if isinstance(document, dict))
342
+
343
+
344
+ def flux_schema_validator() -> Draft202012Validator:
345
+ """Build the FLUX schema validator :class:`Bundle` expects.
346
+
347
+ The schema ships with whichever ``flux_spec`` provided :class:`Bundle`
348
+ -- the published distribution when it is installed, the vendored
349
+ fallback otherwise -- so it is read from that module rather than from
350
+ a path this repository would have to keep in step.
351
+ """
352
+ provider = importlib.import_module(Bundle.__module__)
353
+ schema_path = Path(provider.FLUX_SCHEMA_PATH)
354
+ schema = json.loads(schema_path.read_text())
355
+ Draft202012Validator.check_schema(schema)
356
+ return Draft202012Validator(schema, format_checker=FormatChecker())
357
+
358
+
359
+ def strip_additive_seam_fields(
360
+ document: Mapping[str, Any], *, fields: FrozenSet[str] = ADDITIVE_SEAM_FIELDS
361
+ ) -> Tuple[Dict[str, Any], Tuple[str, ...]]:
362
+ """Return a copy of *document* with the additive emit fields removed.
363
+
364
+ :data:`ADDITIVE_SEAM_FIELDS` is empty (see the module docstring), so
365
+ the default call returns the document unchanged and reports nothing
366
+ removed. The function keeps its shape because it is where a future
367
+ additive field would be handled, and because passing an explicit
368
+ *fields* set is how a test exercises the removal.
369
+
370
+ Only ``spec.emits[]`` entries are touched: the additive fields are
371
+ declared there and nowhere else, so a key of the same name anywhere
372
+ else in the document is left exactly where the author put it. The
373
+ second element names what was removed, as ``spec.emits[i].<field>``,
374
+ so a caller can report the tolerance rather than merely benefit from
375
+ it.
376
+ """
377
+ removed: List[str] = []
378
+ copy: Dict[str, Any] = dict(document)
379
+ spec = copy.get("spec")
380
+ if not isinstance(spec, Mapping):
381
+ return copy, ()
382
+ emits = spec.get("emits")
383
+ if not isinstance(emits, Sequence) or isinstance(emits, (str, bytes)):
384
+ return copy, ()
385
+
386
+ new_emits: List[Any] = []
387
+ for index, entry in enumerate(emits):
388
+ if not isinstance(entry, Mapping):
389
+ new_emits.append(entry)
390
+ continue
391
+ trimmed = {key: value for key, value in entry.items() if key not in fields}
392
+ removed.extend(f"spec.emits[{index}].{key}" for key in sorted(entry) if key in fields)
393
+ new_emits.append(trimmed)
394
+ if not removed:
395
+ return copy, ()
396
+ new_spec = dict(spec)
397
+ new_spec["emits"] = new_emits
398
+ copy["spec"] = new_spec
399
+ return copy, tuple(removed)
400
+
401
+
402
+ class SeamBundle(Bundle):
403
+ """A :class:`Bundle` that validates documents modulo the additive fields.
404
+
405
+ Overrides exactly one method. :meth:`Bundle.load` reads the directory,
406
+ validates each document against the FLUX schema and keeps only the
407
+ schema-valid ones; this subclass performs the same walk but hands the
408
+ schema a copy with :data:`ADDITIVE_SEAM_FIELDS` removed, while storing
409
+ the document **as authored**. Every cross-document check the base class
410
+ runs afterwards therefore sees the real document, and only the schema's
411
+ ``additionalProperties: false`` is relaxed, only on ``emits[]``, only
412
+ for the enumerated fields.
413
+
414
+ :attr:`tolerated` records what was removed from which document, so the
415
+ relaxation appears in the resolution result instead of vanishing --
416
+ and with :data:`ADDITIVE_SEAM_FIELDS` empty it is always empty, which
417
+ is the observable form of "this engine validates against the published
418
+ schema with nothing relaxed".
419
+ """
420
+
421
+ def __init__(
422
+ self,
423
+ directory: Path,
424
+ flux_validator: Draft202012Validator,
425
+ *,
426
+ tolerate_additive: bool = True,
427
+ ) -> None:
428
+ super().__init__(directory, flux_validator)
429
+ self.tolerate_additive = tolerate_additive
430
+ self.tolerated: Dict[str, Tuple[str, ...]] = {}
431
+ #: Every error raised while *reading and schema-checking* the
432
+ #: documents, as opposed to the cross-document checks that run
433
+ #: afterwards over whatever loaded. Empty until :meth:`load` runs.
434
+ self.load_errors: Tuple[str, ...] = ()
435
+
436
+ def load(self) -> None:
437
+ """Load and schema-check every document in the bundle directory.
438
+
439
+ Records where the load phase ended (:attr:`load_errors`) so the
440
+ caller can tell a document that could not be read or did not
441
+ validate from a cross-document check made afterwards. Those later
442
+ checks read ``flux_docs``, which a failed document is not in, so
443
+ every reference to it is reported as dangling -- a chain of derived
444
+ errors asserting that a document sitting on disk is missing.
445
+ """
446
+ for path in self.flux_paths():
447
+ docs, load_error = load_yaml_docs(path)
448
+ if load_error:
449
+ self.err(path.name, _with_yaml_mark(path, load_error))
450
+ continue
451
+ for doc in docs:
452
+ self._load_flux_document(path, doc)
453
+ for path in self.fluid_paths():
454
+ docs, load_error = load_yaml_docs(path)
455
+ if load_error:
456
+ self.err(path.name, _with_yaml_mark(path, load_error))
457
+ continue
458
+ for doc in docs:
459
+ self._load_fluid_document(path, doc)
460
+ self.load_errors = tuple(self.errors)
461
+
462
+ def flux_paths(self) -> List[Path]:
463
+ return [path for pattern in FLUX_DOCUMENT_GLOBS for path in sorted(self.dir.glob(pattern))]
464
+
465
+ def fluid_paths(self) -> List[Path]:
466
+ return [path for pattern in FLUID_DOCUMENT_GLOBS for path in sorted(self.dir.glob(pattern))]
467
+
468
+ def _load_flux_document(self, path: Path, doc: Any) -> None:
469
+ if not isinstance(doc, dict):
470
+ self.err(path.name, f"document is not a mapping ({type(doc).__name__})")
471
+ return
472
+ candidate: Mapping[str, Any] = doc
473
+ if self.tolerate_additive:
474
+ candidate, removed = strip_additive_seam_fields(doc)
475
+ if removed:
476
+ self.tolerated[str(doc.get("id", path.name))] = removed
477
+ errors = sorted(self.flux_validator.iter_errors(candidate), key=lambda e: e.json_path)
478
+ for error in errors:
479
+ self.err(path.name, f"schema: {error.json_path}: {error.message}")
480
+ if errors:
481
+ return
482
+ doc_id = doc.get("id")
483
+ if not isinstance(doc_id, str): # pragma: no cover - the schema requires an id
484
+ self.err(path.name, "document has no string 'id'")
485
+ elif doc_id in self.flux_docs:
486
+ self.err(path.name, f"duplicate document id '{doc_id}'")
487
+ else:
488
+ self.flux_docs[doc_id] = doc
489
+
490
+ def _load_fluid_document(self, path: Path, doc: Any) -> None:
491
+ if not isinstance(doc, dict):
492
+ self.err(path.name, f"document is not a mapping ({type(doc).__name__})")
493
+ return
494
+ doc_id = doc.get("id")
495
+ if not isinstance(doc_id, str):
496
+ self.err(path.name, "FLUID document has no string 'id'")
497
+ elif doc_id in self.fluid_docs:
498
+ self.err(path.name, f"duplicate FLUID document id '{doc_id}'")
499
+ elif doc_id in self.flux_docs:
500
+ self.err(path.name, f"FLUID document id '{doc_id}' collides with a FLUX document id")
501
+ else:
502
+ self.fluid_docs[doc_id] = (path, doc)
503
+
504
+
505
+ @dataclass(frozen=True)
506
+ class BundleDigestInputs:
507
+ """The three maps KERNEL-SPEC §11 builds ``inputDigest`` from, plus what it left out.
508
+
509
+ ``documents``, ``fluid_documents`` and ``lock`` are the bundle's
510
+ inputs, keyed by filename and holding the bytes on disk.
511
+ ``not_hashed`` names every remaining file the loader read, so a stage
512
+ can report what it found beside the documents and did not cover. For a
513
+ bundle :func:`load_bundle` returned, those are the pack products:
514
+ :func:`load_bundle` refuses any other name.
515
+ """
516
+
517
+ documents: Mapping[str, bytes]
518
+ fluid_documents: Mapping[str, bytes]
519
+ lock: Optional[bytes]
520
+ not_hashed: Tuple[str, ...]
521
+
522
+
523
+ @dataclass(frozen=True)
524
+ class LoadedBundle:
525
+ """A validated bundle, with the file bytes the digests are taken over.
526
+
527
+ ``flux_documents`` and ``fluid_documents`` hold the documents **as
528
+ authored** -- additive fields included, every number exact -- because
529
+ that is what ``H`` and ``contractDigest`` are computed over. They come
530
+ from :class:`ExactLoader`, not from the validator's own read, so no
531
+ binary float ever reaches a digest. ``file_bytes`` maps a
532
+ bundle-relative filename to the bytes on disk, which is what
533
+ KERNEL-SPEC §11's ``inputDigest`` and the shipped-contract copy of
534
+ SEAM-FIDELITY-SPEC §7 need.
535
+
536
+ ``flux_file_names`` and ``fluid_file_names`` are the filenames the
537
+ loader's own globs matched, in the order it read them. They are what
538
+ :meth:`digest_inputs` partitions ``file_bytes`` by, so the files a
539
+ bundle was validated against and the files its ``inputDigest`` covers
540
+ are one selection rather than two that have to be kept equal. They
541
+ carry no default: a caller assembling this object in process is
542
+ stating which of its files are documents, and a default of ``()``
543
+ would silently digest none of them.
544
+ """
545
+
546
+ directory: Path
547
+ flux_documents: Mapping[str, Mapping[str, Any]]
548
+ fluid_documents: Mapping[str, Tuple[Path, Mapping[str, Any]]]
549
+ file_bytes: Mapping[str, bytes]
550
+ flux_file_names: Tuple[str, ...]
551
+ fluid_file_names: Tuple[str, ...]
552
+ tolerated_additive_fields: Mapping[str, Tuple[str, ...]]
553
+
554
+ def digest_inputs(self) -> BundleDigestInputs:
555
+ """Partition :attr:`file_bytes` into KERNEL-SPEC §11's input maps.
556
+
557
+ A file is a FLUX document, a FLUID document or the lockfile
558
+ because the loader matched it as one, never because this method
559
+ matched its name a second time. Everything else is reported in
560
+ :attr:`~BundleDigestInputs.not_hashed` rather than folded into
561
+ ``documents``, which is what keeps a pack product from moving a
562
+ bundle's ``inputDigest``.
563
+ """
564
+ flux_names = set(self.flux_file_names)
565
+ fluid_names = set(self.fluid_file_names)
566
+ documents: Dict[str, bytes] = {}
567
+ fluid_documents: Dict[str, bytes] = {}
568
+ not_hashed: List[str] = []
569
+ for name, data in self.file_bytes.items():
570
+ if name in flux_names:
571
+ documents[name] = data
572
+ elif name in fluid_names:
573
+ fluid_documents[name] = data
574
+ elif name != LOCK_FILE_NAME:
575
+ not_hashed.append(name)
576
+ return BundleDigestInputs(
577
+ documents=documents,
578
+ fluid_documents=fluid_documents,
579
+ lock=self.file_bytes.get(LOCK_FILE_NAME),
580
+ not_hashed=tuple(sorted(not_hashed)),
581
+ )
582
+
583
+ def simulation(self, simulation_id: str) -> Mapping[str, Any]:
584
+ """Return the ``Simulation`` document called *simulation_id*."""
585
+ document = self.flux_documents.get(nfc(simulation_id))
586
+ if document is None or document.get("kind") != "Simulation":
587
+ raise FluxError(
588
+ FLX_3105,
589
+ f"bundle declares no Simulation {simulation_id!r} "
590
+ f"(has: {sorted(self.flux_documents)})",
591
+ )
592
+ return document
593
+
594
+ def simulation_ids(self) -> Tuple[str, ...]:
595
+ """Every ``Simulation`` id in the bundle, sorted."""
596
+ return tuple(
597
+ sorted(
598
+ doc_id
599
+ for doc_id, doc in self.flux_documents.items()
600
+ if doc.get("kind") == "Simulation"
601
+ )
602
+ )
603
+
604
+
605
+ def load_bundle(directory: Path, *, tolerate_additive: bool = True) -> LoadedBundle:
606
+ """Validate the bundle at *directory* and return its resolved documents.
607
+
608
+ Two reads, for the two consumers :class:`ExactLoader` describes: the
609
+ validator's own read decides whether the bundle is legal, and the exact
610
+ read supplies the documents every digest is taken over. The document id
611
+ sets of the two reads are compared, so a loader that drifted -- one
612
+ that dropped a document the other kept -- is a failure here rather than
613
+ a digest over a document nothing validated.
614
+
615
+ Raises ``FLX-3107`` when the path is not a directory at all,
616
+ ``FLX-3108`` when the directory holds a regular file that is neither
617
+ a document nor a pack product, and ``FLX-3105`` carrying the
618
+ validator errors when the bundle does not validate. Nothing is
619
+ written.
620
+
621
+ The file-set refusal comes before validation on purpose: it is a
622
+ statement about which files the validator is even going to consider,
623
+ and a reader who is told "this bundle does not validate" for a
624
+ directory holding an unread file is being sent to the wrong place.
625
+ """
626
+ root = Path(directory)
627
+ # Before the validator, and with its own code: a mistyped path is the
628
+ # most common first-run failure, and reporting it as "this bundle does
629
+ # not validate" sent the reader to an explanation about references and
630
+ # ids for a directory that was never opened.
631
+ if not root.is_dir():
632
+ raise FluxError(
633
+ FLX_3107,
634
+ f"{root} is not a directory; pass the bundle directory that holds the "
635
+ "`.flux.yml` documents",
636
+ )
637
+ bundle = SeamBundle(root, flux_schema_validator(), tolerate_additive=tolerate_additive)
638
+ # One level, regular files only. A subdirectory is not part of the
639
+ # bundle: a run state directory such as `.flux/`, and the `run/`
640
+ # directory an extracted evidence archive carries, both sit beside the
641
+ # documents and neither is read here or digested later.
642
+ files = [path for path in sorted(root.iterdir()) if path.is_file()]
643
+ flux_file_names = tuple(path.name for path in bundle.flux_paths())
644
+ fluid_file_names = tuple(path.name for path in bundle.fluid_paths())
645
+ _require_closed_file_set(
646
+ root,
647
+ names=[path.name for path in files],
648
+ document_names=set(flux_file_names) | set(fluid_file_names),
649
+ )
650
+
651
+ errors = bundle.run()
652
+ if errors:
653
+ raise FluxError(FLX_3105, _validation_detail(errors, bundle.load_errors))
654
+
655
+ flux_documents: Dict[str, Mapping[str, Any]] = {}
656
+ for path in bundle.flux_paths():
657
+ for document in load_documents_exact(path):
658
+ doc_id = document.get("id")
659
+ if isinstance(doc_id, str) and doc_id in bundle.flux_docs:
660
+ flux_documents[doc_id] = document
661
+ fluid_documents: Dict[str, Tuple[Path, Mapping[str, Any]]] = {}
662
+ for path in bundle.fluid_paths():
663
+ for document in load_documents_exact(path):
664
+ doc_id = document.get("id")
665
+ if isinstance(doc_id, str) and doc_id in bundle.fluid_docs:
666
+ fluid_documents[doc_id] = (path, document)
667
+
668
+ _require_same_document_set(bundle, flux_documents, fluid_documents)
669
+
670
+ file_bytes = {path.name: path.read_bytes() for path in files}
671
+ return LoadedBundle(
672
+ directory=root,
673
+ flux_documents=flux_documents,
674
+ fluid_documents=fluid_documents,
675
+ file_bytes=file_bytes,
676
+ flux_file_names=flux_file_names,
677
+ fluid_file_names=fluid_file_names,
678
+ tolerated_additive_fields=dict(bundle.tolerated),
679
+ )
680
+
681
+
682
+ #: How many errors one refusal prints before it stops enumerating.
683
+ _MAX_REPORTED_ERRORS = 10
684
+
685
+
686
+ def _validation_detail(errors: Sequence[str], load_errors: Sequence[str]) -> str:
687
+ """Render a bundle's validation errors: one per line, causes only.
688
+
689
+ When any document failed to load or failed schema, only those errors
690
+ are shown. Every check after the load phase reads the documents that
691
+ loaded, so a reference into a document that did not is reported as
692
+ dangling -- and the reader is sent hunting for a file that is right
693
+ there. Those derived lines are replaced by a count of what was skipped,
694
+ which is a true statement about why they are not listed.
695
+ """
696
+ reported = list(load_errors) if load_errors else list(errors)
697
+ suppressed = len(errors) - len(reported)
698
+ lines = [f" {error}" for error in reported[:_MAX_REPORTED_ERRORS]]
699
+ if len(reported) > _MAX_REPORTED_ERRORS:
700
+ lines.append(f" ... and {len(reported) - _MAX_REPORTED_ERRORS} more")
701
+ if suppressed:
702
+ lines.append(
703
+ f" {suppressed} further check(s) skipped: a document above did not "
704
+ "load or did not validate, so every check that reads it would report "
705
+ "it as missing"
706
+ )
707
+ return "\n" + "\n".join(lines)
708
+
709
+
710
+ def _require_closed_file_set(
711
+ root: Path,
712
+ *,
713
+ names: Sequence[str],
714
+ document_names: AbstractSet[str],
715
+ ) -> None:
716
+ """Refuse a bundle directory holding a file that is neither input nor product.
717
+
718
+ The sibling of :func:`_require_same_document_set` one level down.
719
+ That function refuses a bundle whose two reads disagree about which
720
+ documents exist; this one refuses a bundle whose files and whose
721
+ documents disagree.
722
+
723
+ *document_names* is the loader's own glob result, not a second match
724
+ over *names*, so this refusal and the digest's file selection cannot
725
+ hold two opinions about which file is a document. Everything left
726
+ over after the documents, the lockfile and
727
+ :data:`BUNDLE_PACK_PRODUCTS` is named in one refusal.
728
+ """
729
+ unknown = sorted(
730
+ {
731
+ name
732
+ for name in names
733
+ if name not in document_names
734
+ and name != LOCK_FILE_NAME
735
+ and name not in BUNDLE_PACK_PRODUCTS
736
+ }
737
+ )
738
+ if not unknown:
739
+ return
740
+ listed = unknown[:_MAX_REPORTED_ERRORS]
741
+ lines = [f" {name}" for name in listed]
742
+ if len(unknown) > len(listed):
743
+ lines.append(f" ... and {len(unknown) - len(listed)} more")
744
+ recognised = ", ".join([*FLUX_DOCUMENT_GLOBS, *FLUID_DOCUMENT_GLOBS, LOCK_FILE_NAME])
745
+ raise FluxError(
746
+ FLX_3108,
747
+ f"{root} holds {len(unknown)} file(s) this engine does not recognise:\n"
748
+ + "\n".join(lines)
749
+ + f"\n this engine reads {recognised}, and recognises "
750
+ + f"{', '.join(sorted(BUNDLE_PACK_PRODUCTS))} as written by a pack rather than "
751
+ "read by a run",
752
+ )
753
+
754
+
755
+ def _require_same_document_set(
756
+ bundle: SeamBundle,
757
+ flux_documents: Mapping[str, Mapping[str, Any]],
758
+ fluid_documents: Mapping[str, Tuple[Path, Mapping[str, Any]]],
759
+ ) -> None:
760
+ """Refuse a bundle whose two reads disagree about which documents exist."""
761
+ for label, validated, exact in (
762
+ ("FLUX", set(bundle.flux_docs), set(flux_documents)),
763
+ ("FLUID", set(bundle.fluid_docs), set(fluid_documents)),
764
+ ):
765
+ if validated != exact:
766
+ raise FluxError(
767
+ FLX_3105,
768
+ f"the validating and exact reads disagree about the {label} documents: "
769
+ f"{sorted(validated ^ exact)}",
770
+ )
771
+
772
+
773
+ @dataclass(frozen=True)
774
+ class ResolvedEmit:
775
+ """One ``emits[]`` entry, fully resolved against the bundle.
776
+
777
+ Attributes
778
+ ----------
779
+ simulation_id, emit_index
780
+ Where the entry was declared.
781
+ emit
782
+ The entry **as authored**. ``H`` (SEAM-FIDELITY-SPEC §3) is taken
783
+ over this mapping, so the object here and the object hashed there
784
+ are the same object.
785
+ extension
786
+ This emit's entry in the Simulation's
787
+ ``extensions["com.agentics.flux/1"].emits`` map, or ``None`` when
788
+ the Simulation declares none. ``H`` quotes it beside the emit
789
+ entry; a bundle with no entry hashes exactly as it did before the
790
+ block existed.
791
+ product_ref, expose_id, fluid_version
792
+ The three fields that identify the seam crossing.
793
+ contract_document
794
+ The parsed ``.fluid.yml``.
795
+ contract_path, contract_bytes
796
+ The file as it sits in the bundle. SEAM-FIDELITY-SPEC §7 ships
797
+ these bytes verbatim, so they travel with the resolution rather
798
+ than being re-read later from a directory that may have moved on.
799
+ contract_digest
800
+ The recomputed ``jcs-document`` digest of ``contract_document``.
801
+ contract_file_digest
802
+ The ``raw-bytes`` digest of ``contract_bytes``: what the shipped
803
+ copy is checked against.
804
+ declared_contract_digest
805
+ ``provenance.contractDigest`` as the emit declared it, or ``None``
806
+ when the emit declares no provenance block.
807
+ expose
808
+ The referenced ``exposes[]`` entry.
809
+ """
810
+
811
+ simulation_id: str
812
+ emit_index: int
813
+ emit: Mapping[str, Any]
814
+ product_ref: str
815
+ expose_id: str
816
+ fluid_version: str
817
+ contract_document: Mapping[str, Any]
818
+ contract_path: Path
819
+ contract_bytes: bytes
820
+ contract_digest: DigestRef
821
+ contract_file_digest: DigestRef
822
+ declared_contract_digest: Optional[str]
823
+ expose: Mapping[str, Any]
824
+ extension: Optional[Mapping[str, Any]] = None
825
+
826
+ def compile(self) -> CompiledExpose:
827
+ """Compile the referenced expose into its ordered column set."""
828
+ return compile_expose(self.expose)
829
+
830
+ @property
831
+ def declared_row_count(self) -> Optional[int]:
832
+ """The extension block's ``rows`` when it declares one (§1).
833
+
834
+ ``None`` when it does not: §1's fallback -- "the population size of
835
+ the referenced Segment when the emit is journey-driven" -- is a
836
+ property of the world, not of the seam, so it is the runtime that
837
+ supplies it and this property does not guess.
838
+ """
839
+ rows = (self.extension or {}).get(_ROWS_KEY)
840
+ if isinstance(rows, bool) or not isinstance(rows, int):
841
+ return None
842
+ return rows
843
+
844
+ @property
845
+ def fidelity(self) -> Optional[Mapping[str, Any]]:
846
+ """The declared fidelity block, or ``None`` when the emit declares none.
847
+
848
+ ``None`` is the scenario-driven answer, not an error: an emit
849
+ without a block draws its rows from the run's own moments
850
+ (SEAM-FIDELITY-SPEC §1).
851
+ """
852
+ block = (self.extension or {}).get(_FIDELITY_BLOCK_KEY)
853
+ return block if isinstance(block, Mapping) else None
854
+
855
+ @property
856
+ def column_mapping(self) -> Optional[Mapping[str, Any]]:
857
+ """The extension block's ``mapping`` overrides, or ``None``.
858
+
859
+ Read by :func:`flux_engine.seam.mapping.resolve_column_mapping` as
860
+ step 1 -- the author's own word about which runtime attribute fills
861
+ which declared column. Returned unvalidated: the resolver refuses a
862
+ malformed block by name (``FLX-3302``), because it is the module
863
+ that knows what a legal source path is.
864
+ """
865
+ overrides = (self.extension or {}).get(_MAPPING_KEY)
866
+ return overrides if isinstance(overrides, Mapping) else None
867
+
868
+
869
+ def extension_block(
870
+ simulation: Mapping[str, Any], expose_id: str, *, where: str = ""
871
+ ) -> Optional[Mapping[str, Any]]:
872
+ """This engine's extension entry for *expose_id*, or ``None``.
873
+
874
+ Reads ``extensions["com.agentics.flux/1"].emits[<exposeId>]`` off a
875
+ Simulation document. RFC-02 leaves the contents of a namespace to its
876
+ owner, so every shape check below is this engine's own, and each one
877
+ fails rather than passes: a namespace whose value is not a mapping, an
878
+ ``emits`` that is not a mapping, a block that is not a mapping, and a
879
+ block carrying a key outside :data:`_BLOCK_KEYS` are all ``FLX-3105``.
880
+ An unreadable declaration is not a weaker declaration -- it is a
881
+ declaration the engine would silently drop, which is exactly how a
882
+ fidelity block goes missing without anyone noticing.
883
+ """
884
+ extensions = simulation.get("extensions")
885
+ if not isinstance(extensions, Mapping):
886
+ return None
887
+ namespace = extensions.get(EXTENSION_NAMESPACE)
888
+ if namespace is None:
889
+ return None
890
+ prefix = f"{where}: " if where else ""
891
+ if not isinstance(namespace, Mapping):
892
+ raise FluxError(
893
+ FLX_3105,
894
+ f"{prefix}extensions[{EXTENSION_NAMESPACE!r}] is "
895
+ f"{type(namespace).__name__}, not a mapping",
896
+ )
897
+ emits = namespace.get(_EMITS_KEY)
898
+ if emits is None:
899
+ return None
900
+ if not isinstance(emits, Mapping):
901
+ raise FluxError(
902
+ FLX_3105,
903
+ f"{prefix}extensions[{EXTENSION_NAMESPACE!r}].{_EMITS_KEY} is "
904
+ f"{type(emits).__name__}, not a mapping keyed by exposeId",
905
+ )
906
+ wanted = nfc(expose_id)
907
+ block = next((emits[key] for key in emits if nfc(str(key)) == wanted), None)
908
+ if block is None:
909
+ return None
910
+ if not isinstance(block, Mapping):
911
+ raise FluxError(
912
+ FLX_3105,
913
+ f"{prefix}extensions[{EXTENSION_NAMESPACE!r}].{_EMITS_KEY}[{wanted!r}] is "
914
+ f"{type(block).__name__}, not a mapping",
915
+ )
916
+ unknown = sorted(str(key) for key in block if nfc(str(key)) not in _BLOCK_KEYS)
917
+ if unknown:
918
+ raise FluxError(
919
+ FLX_3105,
920
+ f"{prefix}extensions[{EXTENSION_NAMESPACE!r}].{_EMITS_KEY}[{wanted!r}] "
921
+ f"declares {unknown}; this namespace carries {sorted(_BLOCK_KEYS)}",
922
+ )
923
+ return block
924
+
925
+
926
+ def _require_extension_emits_resolve(simulation: Mapping[str, Any], simulation_id: str) -> None:
927
+ """Refuse an extension block keyed by an expose the Simulation never emits.
928
+
929
+ A typo'd ``exposeId`` under the namespace would otherwise be a fidelity
930
+ block, a row count and a column mapping that no emit ever reads --
931
+ declared, valid against the published schema, and completely inert.
932
+ """
933
+ extensions = simulation.get("extensions")
934
+ namespace = extensions.get(EXTENSION_NAMESPACE) if isinstance(extensions, Mapping) else None
935
+ emits = namespace.get(_EMITS_KEY) if isinstance(namespace, Mapping) else None
936
+ if not isinstance(emits, Mapping):
937
+ return
938
+ declared = simulation.get("spec", {}).get("emits")
939
+ known = (
940
+ {nfc(str(entry.get("exposeId", ""))) for entry in declared if isinstance(entry, Mapping)}
941
+ if isinstance(declared, Sequence) and not isinstance(declared, (str, bytes))
942
+ else set()
943
+ )
944
+ stray = sorted(nfc(str(key)) for key in emits if nfc(str(key)) not in known)
945
+ if stray:
946
+ raise FluxError(
947
+ FLX_3105,
948
+ f"{simulation_id}: extensions[{EXTENSION_NAMESPACE!r}].{_EMITS_KEY} declares "
949
+ f"{stray}, which this Simulation does not emit (it emits {sorted(known)})",
950
+ )
951
+
952
+
953
+ def resolve_emit(loaded: LoadedBundle, *, simulation_id: str, emit_index: int = 0) -> ResolvedEmit:
954
+ """Resolve one ``emits[]`` entry of a Simulation (KERNEL-SPEC §8).
955
+
956
+ Checks, in order: the entry exists and is a mapping; ``productRef``
957
+ resolves to a FLUID document in the bundle (``FLX-3102``); the
958
+ referenced document's declared ``fluidVersion`` satisfies the emit's
959
+ pin or range (``FLX-3104``); ``exposeId`` is a member of its
960
+ ``exposes[]`` (``FLX-3103``); and, when the emit declares one, the
961
+ recomputed contract digest equals ``provenance.contractDigest``
962
+ (``FLX-3101``).
963
+
964
+ The version check uses the reference validator's own
965
+ :func:`semver_satisfies`, so a pin means here exactly what it means to
966
+ ``fluxsim validate``.
967
+ """
968
+ simulation = loaded.simulation(simulation_id)
969
+ _require_extension_emits_resolve(simulation, simulation_id)
970
+ emits = simulation.get("spec", {}).get("emits")
971
+ if not isinstance(emits, Sequence) or isinstance(emits, (str, bytes)):
972
+ raise FluxError(FLX_3105, f"Simulation {simulation_id!r} declares no emits[]")
973
+ if not 0 <= emit_index < len(emits):
974
+ raise FluxError(
975
+ FLX_3105,
976
+ f"Simulation {simulation_id!r} declares {len(emits)} emits; "
977
+ f"there is no emits[{emit_index}]",
978
+ )
979
+ emit = emits[emit_index]
980
+ if not isinstance(emit, Mapping):
981
+ raise FluxError(
982
+ FLX_3105,
983
+ f"Simulation {simulation_id!r} emits[{emit_index}] is "
984
+ f"{type(emit).__name__}, not a mapping",
985
+ )
986
+ where = f"{simulation_id} emits[{emit_index}]"
987
+
988
+ product_ref = str(emit.get("productRef", ""))
989
+ entry = loaded.fluid_documents.get(product_ref)
990
+ if entry is None:
991
+ raise FluxError(
992
+ FLX_3102,
993
+ f"{where}: productRef {product_ref!r} (bundle has: "
994
+ f"{sorted(loaded.fluid_documents)})",
995
+ )
996
+ contract_path, contract_document = entry
997
+
998
+ fluid_version = str(emit.get("fluidVersion", ""))
999
+ declared_version = contract_document.get("fluidVersion")
1000
+ if not isinstance(declared_version, str) or not semver_satisfies(
1001
+ declared_version, fluid_version
1002
+ ):
1003
+ raise FluxError(
1004
+ FLX_3104,
1005
+ f"{where}: pin {fluid_version!r}; {contract_path.name} declares "
1006
+ f"{declared_version!r}",
1007
+ )
1008
+
1009
+ expose_id = str(emit.get("exposeId", ""))
1010
+ try:
1011
+ expose = find_expose(contract_document, expose_id)
1012
+ except FluxError as exc:
1013
+ raise FluxError(
1014
+ FLX_3103,
1015
+ f"{where}: exposeId {expose_id!r} ({exc.detail or exc.code.title})",
1016
+ ) from exc
1017
+
1018
+ contract_bytes = loaded.file_bytes.get(contract_path.name, contract_path.read_bytes())
1019
+ contract_digest = digest_of_document(contract_document, subject=f"contractDigest:{product_ref}")
1020
+ contract_file_digest = digest_of_bytes(contract_bytes, subject=contract_path.name)
1021
+
1022
+ provenance = emit.get("provenance")
1023
+ declared_digest = provenance.get("contractDigest") if isinstance(provenance, Mapping) else None
1024
+ if isinstance(declared_digest, str) and declared_digest != contract_digest.value:
1025
+ raise FluxError(
1026
+ FLX_3101,
1027
+ f"{where}: declared {declared_digest}, in-bundle contract is "
1028
+ f"{contract_digest.value}{_canonicalisation_note(contract_path, declared_digest)}",
1029
+ )
1030
+
1031
+ return ResolvedEmit(
1032
+ simulation_id=nfc(simulation_id),
1033
+ emit_index=emit_index,
1034
+ emit=emit,
1035
+ product_ref=product_ref,
1036
+ expose_id=nfc(expose_id),
1037
+ fluid_version=fluid_version,
1038
+ contract_document=contract_document,
1039
+ contract_path=contract_path,
1040
+ contract_bytes=contract_bytes,
1041
+ contract_digest=contract_digest,
1042
+ contract_file_digest=contract_file_digest,
1043
+ declared_contract_digest=declared_digest if isinstance(declared_digest, str) else None,
1044
+ expose=expose,
1045
+ extension=extension_block(simulation, expose_id, where=where),
1046
+ )
1047
+
1048
+
1049
+ def _canonicalisation_note(contract_path: Path, declared_digest: str) -> str:
1050
+ """Say so when the declared digest is the reference validator's, not ours.
1051
+
1052
+ The two canonicalisers agree on every document that carries no YAML
1053
+ float, and disagree on every document that does: KERNEL-SPEC §2.1
1054
+ serialises an exact decimal as a JSON **string** at its declared scale,
1055
+ while the reference validator hands the float straight to RFC 8785.
1056
+ When a mismatch is that divergence rather than a changed contract, the
1057
+ diagnostic says which, because the two have completely different
1058
+ remedies.
1059
+ """
1060
+ documents, load_error = load_yaml_docs(contract_path)
1061
+ if load_error: # pragma: no cover - the bundle already loaded
1062
+ return ""
1063
+ for document in documents:
1064
+ if isinstance(document, dict) and "sha256:" + canonical_digest(document) == declared_digest:
1065
+ return (
1066
+ f" -- the declared digest is the reference validator's canonicalisation of "
1067
+ f"{contract_path.name}; the two differ only where a document carries a YAML "
1068
+ "float, which KERNEL-SPEC §2.1 spells as an exact decimal string"
1069
+ )
1070
+ return ""
1071
+
1072
+
1073
+ def resolve_all_emits(loaded: LoadedBundle, *, simulation_id: str) -> Tuple[ResolvedEmit, ...]:
1074
+ """Resolve every ``emits[]`` entry of a Simulation, in declared order.
1075
+
1076
+ Declared order is load-bearing: KERNEL-SPEC §3 forms ``H_bytes`` for a
1077
+ multi-emit simulation as "the sha256 of the concatenation of the
1078
+ per-emit digests in ``emits[]`` order", so the sequence returned here
1079
+ is the sequence that seeds the run.
1080
+ """
1081
+ simulation = loaded.simulation(simulation_id)
1082
+ emits = simulation.get("spec", {}).get("emits")
1083
+ count = len(emits) if isinstance(emits, Sequence) and not isinstance(emits, (str, bytes)) else 0
1084
+ return tuple(
1085
+ resolve_emit(loaded, simulation_id=simulation_id, emit_index=index)
1086
+ for index in range(count)
1087
+ )