flux-sim-engine 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- flux_engine/__init__.py +22 -0
- flux_engine/_links.py +55 -0
- flux_engine/_vendor/__init__.py +5 -0
- flux_engine/_vendor/flux_spec/NOTICE +19 -0
- flux_engine/_vendor/flux_spec/VENDOR-NOTES.md +104 -0
- flux_engine/_vendor/flux_spec/__init__.py +9 -0
- flux_engine/_vendor/flux_spec/bundle.py +410 -0
- flux_engine/_vendor/flux_spec/enforce.py +316 -0
- flux_engine/_vendor/flux_spec/schema/flux-enforcement-0.5.0.json +121 -0
- flux_engine/_vendor/flux_spec/schema/flux-manifest-0.5.0.json +153 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.2.0.json +465 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.3.0.json +876 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.4.0.json +1601 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.4.1.json +1668 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.5.0.json +1669 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-latest.json +1669 -0
- flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.4.0.json +795 -0
- flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.4.1.json +852 -0
- flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.5.0.json +852 -0
- flux_engine/_vendor/flux_spec/validate.py +537 -0
- flux_engine/_vendor/flux_spec/vectors/enforcement-vectors.json +935 -0
- flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.3.json +5234 -0
- flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.4.json +5437 -0
- flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.5.json +5498 -0
- flux_engine/_vocabulary.py +141 -0
- flux_engine/accuracy/__init__.py +5 -0
- flux_engine/accuracy/_scoring/__init__.py +24 -0
- flux_engine/accuracy/accuracy_record.py +96 -0
- flux_engine/accuracy/policy.py +158 -0
- flux_engine/accuracy/records.py +264 -0
- flux_engine/accuracy/store.py +169 -0
- flux_engine/api/__init__.py +163 -0
- flux_engine/api/accuracy.py +209 -0
- flux_engine/api/agentic.py +134 -0
- flux_engine/api/calibration.py +125 -0
- flux_engine/api/claims.py +93 -0
- flux_engine/api/digests.py +73 -0
- flux_engine/api/emit.py +78 -0
- flux_engine/api/expressions.py +72 -0
- flux_engine/api/fidelity.py +110 -0
- flux_engine/api/lineage.py +78 -0
- flux_engine/api/stages.py +242 -0
- flux_engine/api/verdict.py +108 -0
- flux_engine/calibrate/__init__.py +5 -0
- flux_engine/calibrate/declared.py +253 -0
- flux_engine/calibrate/provenance.py +113 -0
- flux_engine/cli/__init__.py +2146 -0
- flux_engine/cli/__main__.py +17 -0
- flux_engine/cli/_documents.py +226 -0
- flux_engine/cli/_hints.py +118 -0
- flux_engine/cli/_init.py +152 -0
- flux_engine/cli/_progress.py +124 -0
- flux_engine/concordance/__init__.py +127 -0
- flux_engine/concordance/boundary/__init__.py +78 -0
- flux_engine/concordance/boundary/merkle.py +287 -0
- flux_engine/concordance/boundary/slice.py +429 -0
- flux_engine/concordance/boundary/statistic.py +561 -0
- flux_engine/concordance/boundary/store.py +334 -0
- flux_engine/concordance/boundary/vault.py +357 -0
- flux_engine/concordance/compiler.py +542 -0
- flux_engine/concordance/errors.py +189 -0
- flux_engine/concordance/gate.py +525 -0
- flux_engine/concordance/predicate.py +1217 -0
- flux_engine/concordance/record.py +554 -0
- flux_engine/concordance/verifier.py +583 -0
- flux_engine/core/__init__.py +5 -0
- flux_engine/core/artifact.py +99 -0
- flux_engine/core/canonical.py +369 -0
- flux_engine/core/clock.py +437 -0
- flux_engine/core/digest.py +288 -0
- flux_engine/core/errors.py +277 -0
- flux_engine/core/fixedpoint.py +929 -0
- flux_engine/core/lrm.py +158 -0
- flux_engine/core/rng.py +736 -0
- flux_engine/core/seedtree.py +891 -0
- flux_engine/core/trace.py +423 -0
- flux_engine/describe.py +207 -0
- flux_engine/engine.py +257 -0
- flux_engine/evidence/__init__.py +5 -0
- flux_engine/evidence/pack.py +411 -0
- flux_engine/evidence/report.py +243 -0
- flux_engine/expr/__init__.py +133 -0
- flux_engine/expr/ast.py +312 -0
- flux_engine/expr/attrs.py +386 -0
- flux_engine/expr/check.py +278 -0
- flux_engine/expr/compile.py +322 -0
- flux_engine/expr/errors.py +256 -0
- flux_engine/expr/lexer.py +297 -0
- flux_engine/expr/parser.py +313 -0
- flux_engine/expr/types.py +177 -0
- flux_engine/generator/__init__.py +97 -0
- flux_engine/generator/families.py +325 -0
- flux_engine/generator/paths.py +227 -0
- flux_engine/generator/rows.py +918 -0
- flux_engine/generator/statistics.py +524 -0
- flux_engine/governance/__init__.py +87 -0
- flux_engine/governance/audit.py +307 -0
- flux_engine/governance/gate.py +334 -0
- flux_engine/governance/skills.py +220 -0
- flux_engine/governance/sovereignty.py +251 -0
- flux_engine/lineage/__init__.py +5 -0
- flux_engine/lineage/emitter.py +398 -0
- flux_engine/py.typed +0 -0
- flux_engine/runtime/__init__.py +153 -0
- flux_engine/runtime/campaign.py +407 -0
- flux_engine/runtime/cast.py +283 -0
- flux_engine/runtime/detector.py +222 -0
- flux_engine/runtime/errors.py +58 -0
- flux_engine/runtime/experiment.py +311 -0
- flux_engine/runtime/journey.py +383 -0
- flux_engine/runtime/jurisdiction.py +72 -0
- flux_engine/runtime/payloads.py +124 -0
- flux_engine/runtime/signals.py +334 -0
- flux_engine/runtime/temperature.py +156 -0
- flux_engine/seam/__init__.py +5 -0
- flux_engine/seam/attest.py +290 -0
- flux_engine/seam/conform.py +448 -0
- flux_engine/seam/contract.py +605 -0
- flux_engine/seam/emit.py +488 -0
- flux_engine/seam/mapping.py +299 -0
- flux_engine/seam/resolve.py +1087 -0
- flux_engine/seam/sinks.py +157 -0
- flux_engine/spec/__init__.py +134 -0
- flux_engine/spec/bundle.py +25 -0
- flux_engine/spec/enforce.py +31 -0
- flux_engine/spec/validate.py +28 -0
- flux_engine/stages/__init__.py +30 -0
- flux_engine/stages/apply.py +447 -0
- flux_engine/stages/errors.py +315 -0
- flux_engine/stages/layout.py +292 -0
- flux_engine/stages/pipeline.py +600 -0
- flux_engine/stages/plan.py +241 -0
- flux_engine/stages/replay.py +83 -0
- flux_engine/stages/run.py +208 -0
- flux_engine/stages/ship.py +934 -0
- flux_engine/stages/validate.py +93 -0
- flux_engine/stages/verify.py +1129 -0
- flux_engine/starter/__init__.py +161 -0
- flux_engine/starter/bundle/detector.flux.yml +15 -0
- flux_engine/starter/bundle/journey.flux.yml +23 -0
- flux_engine/starter/bundle/module.flux.yml +16 -0
- flux_engine/starter/bundle/payment-recovery.fluid.yml +30 -0
- flux_engine/starter/bundle/persona.flux.yml +26 -0
- flux_engine/starter/bundle/signal.flux.yml +13 -0
- flux_engine/starter/bundle/simulation.flux.yml +29 -0
- flux_engine/starter/bundle/taxonomy.flux.yml +17 -0
- flux_engine/starter/bundle/treatment.flux.yml +13 -0
- flux_engine/starter/bundle/world.flux.yml +20 -0
- flux_engine/verticals/__init__.py +85 -0
- flux_engine/verticals/telco.py +89 -0
- flux_engine/world/__init__.py +89 -0
- flux_engine/world/derived.py +195 -0
- flux_engine/world/errors.py +41 -0
- flux_engine/world/families.py +260 -0
- flux_engine/world/population.py +602 -0
- flux_engine/world/tracing.py +66 -0
- flux_engine/world/values.py +121 -0
- flux_sim_engine-0.2.0.dist-info/METADATA +108 -0
- flux_sim_engine-0.2.0.dist-info/RECORD +165 -0
- flux_sim_engine-0.2.0.dist-info/WHEEL +5 -0
- flux_sim_engine-0.2.0.dist-info/entry_points.txt +2 -0
- flux_sim_engine-0.2.0.dist-info/licenses/LICENSE +202 -0
- flux_sim_engine-0.2.0.dist-info/licenses/NOTICE +10 -0
- flux_sim_engine-0.2.0.dist-info/licenses/flux_engine/_vendor/flux_spec/NOTICE +19 -0
- flux_sim_engine-0.2.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,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
|
+
)
|