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,891 @@
|
|
|
1
|
+
# Copyright 2026 Agentics Transformation Limited
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
4
|
+
|
|
5
|
+
"""The seed tree -- KERNEL-SPEC §3 (``flux-seed/1``).
|
|
6
|
+
|
|
7
|
+
Every stochastic value in a run comes from a stream addressed by a **path**, and every path
|
|
8
|
+
hangs off one root derived from the seam contract digest and the effective seed::
|
|
9
|
+
|
|
10
|
+
effective_seed = Simulation.spec.seed if present else World.spec.seed # both int64
|
|
11
|
+
root_label = b"flux-seed/1" + b"\\x00" + H_bytes + b"\\x00"
|
|
12
|
+
+ effective_seed.to_bytes(8, "big", signed=True)
|
|
13
|
+
root = int.from_bytes(sha256(root_label).digest(), "big")
|
|
14
|
+
|
|
15
|
+
label(path) = b"\\x1f".join(NFC(str(part)).encode("utf-8") for part in path)
|
|
16
|
+
stream(path) = Generator(PCG64(SeedSequence(
|
|
17
|
+
int.from_bytes(sha256(b"flux-seed/1\\x00" + root_bytes + b"\\x00"
|
|
18
|
+
+ label).digest(), "big"))))
|
|
19
|
+
|
|
20
|
+
Two consequences the rest of the engine leans on:
|
|
21
|
+
|
|
22
|
+
* **Changing the contract changes every stream.** ``H`` is the seam's contract digest, so a
|
|
23
|
+
run against an edited contract is a different run, not the same run with different
|
|
24
|
+
columns.
|
|
25
|
+
* **Derivation is by path, never by spawn order.** A stream's values depend on its address
|
|
26
|
+
and nothing else -- not on how many streams were created before it, not on the order the
|
|
27
|
+
scheduler happened to reach it. This is what makes the "insertion stability" property
|
|
28
|
+
true: adding an unreferenced document to the bundle, or a new consumer on a new path,
|
|
29
|
+
changes no existing stream. A ``SeedSequence.spawn``-based tree would be reproducible
|
|
30
|
+
only for a fixed traversal order, which is a weaker promise wearing the same word.
|
|
31
|
+
|
|
32
|
+
The canonical path table below is **closed**: adding a row is a ``kernelVersion`` bump.
|
|
33
|
+
Every path a run materialises is recorded in a :class:`SeedPathLedger` and written out as
|
|
34
|
+
``seed-paths.ndjson`` beside the plan -- one canonical path per line, sorted -- whose
|
|
35
|
+
raw-bytes digest is the ``seedTreeDigest`` that ``plan.json`` carries. The plan itself keeps
|
|
36
|
+
only that digest and a per-shape count table, so it stays small enough to read and to pin as
|
|
37
|
+
a golden while the addresses themselves stay verifiable line by line. A run that reaches a
|
|
38
|
+
path the plan did not anticipate fails with ``FLX-2201``.
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
from __future__ import annotations
|
|
42
|
+
|
|
43
|
+
import json
|
|
44
|
+
from dataclasses import dataclass, field
|
|
45
|
+
from enum import Enum
|
|
46
|
+
from typing import Dict, FrozenSet, Iterable, List, Optional, Sequence, Tuple, Union
|
|
47
|
+
|
|
48
|
+
from flux_engine.core.canonical import canonical_bytes, nfc, sha256_hex
|
|
49
|
+
from flux_engine.core.errors import FluxError, register
|
|
50
|
+
from flux_engine.core.rng import DrawStream
|
|
51
|
+
|
|
52
|
+
__all__ = [
|
|
53
|
+
"CANONICAL_PATH_SHAPES",
|
|
54
|
+
"FLX_2201",
|
|
55
|
+
"FLX_2202",
|
|
56
|
+
"PathKind",
|
|
57
|
+
"PathShape",
|
|
58
|
+
"SEED_TREE_VERSION",
|
|
59
|
+
"SeedPath",
|
|
60
|
+
"SeedPathLedger",
|
|
61
|
+
"SeedTree",
|
|
62
|
+
"SeedTreeRoot",
|
|
63
|
+
"agentic_path",
|
|
64
|
+
"campaign_path",
|
|
65
|
+
"derive_identifier",
|
|
66
|
+
"derive_root",
|
|
67
|
+
"effective_seed",
|
|
68
|
+
"experiment_assignment_path",
|
|
69
|
+
"journey_path",
|
|
70
|
+
"market_path",
|
|
71
|
+
"match_shape",
|
|
72
|
+
"parse_seed_path",
|
|
73
|
+
"parse_seed_paths",
|
|
74
|
+
"path_label",
|
|
75
|
+
"render_seed_path",
|
|
76
|
+
"seam_bytes",
|
|
77
|
+
"seed_paths_bytes",
|
|
78
|
+
"seed_paths_digest",
|
|
79
|
+
"seed_tree_digest",
|
|
80
|
+
"shape_counts",
|
|
81
|
+
"signal_path",
|
|
82
|
+
"stream_entropy",
|
|
83
|
+
"subject_products_path",
|
|
84
|
+
"subject_trait_path",
|
|
85
|
+
"sweep_effective_seed",
|
|
86
|
+
"sweep_path",
|
|
87
|
+
"temperature_path",
|
|
88
|
+
"world_cohorts_path",
|
|
89
|
+
]
|
|
90
|
+
|
|
91
|
+
FLX_2201 = register(
|
|
92
|
+
"FLX-2201",
|
|
93
|
+
"run touched a seed-tree path the plan did not anticipate",
|
|
94
|
+
"Every stream a run draws from is addressed by a path from the closed table in "
|
|
95
|
+
"KERNEL-SPEC §3, and the set of paths the run will touch is recorded beside the "
|
|
96
|
+
"plan in seed-paths.ndjson, whose digest plan.json carries as seedTreeDigest. A "
|
|
97
|
+
"path outside that table, or outside the planned set, means "
|
|
98
|
+
"the run is not the run that was planned -- so it stops rather than emitting rows "
|
|
99
|
+
"whose provenance the plan cannot account for.",
|
|
100
|
+
)
|
|
101
|
+
|
|
102
|
+
FLX_2202 = register(
|
|
103
|
+
"FLX-2202",
|
|
104
|
+
"seed-tree input outside its declared domain",
|
|
105
|
+
"The root of the seed tree is derived from the seam contract digest and an int64 "
|
|
106
|
+
"effective seed (KERNEL-SPEC §3). A seed outside the int64 range, a malformed or "
|
|
107
|
+
"non-sha256 digest reference, or an empty emit set has no defined derivation, and "
|
|
108
|
+
"guessing one would silently produce a run nobody can reproduce.",
|
|
109
|
+
)
|
|
110
|
+
|
|
111
|
+
#: KERNEL-SPEC §1: the version of the derivation, carried in the receipt and plan.json.
|
|
112
|
+
SEED_TREE_VERSION = "flux-seed/1"
|
|
113
|
+
|
|
114
|
+
_DOMAIN = SEED_TREE_VERSION.encode("utf-8")
|
|
115
|
+
_NUL = b"\x00"
|
|
116
|
+
|
|
117
|
+
#: §3's path separator: ASCII UNIT SEPARATOR between the parts of one path. Chosen by the
|
|
118
|
+
#: spec because it cannot occur in a document id, a trait name or a decimal ordinal, so no
|
|
119
|
+
#: two distinct paths can share a label through a separator collision.
|
|
120
|
+
_PART_SEPARATOR = b"\x1f"
|
|
121
|
+
|
|
122
|
+
#: One rank up from the part separator (ASCII RECORD SEPARATOR). Refused inside a path part
|
|
123
|
+
#: for the same reason ``\x1f`` is: it is the separator a caller reaching for a flat
|
|
124
|
+
#: encoding of a whole path set would pick, so a part that carries one is a part that could
|
|
125
|
+
#: forge a record boundary in someone else's reading of the set.
|
|
126
|
+
_LABEL_SEPARATOR = b"\x1e"
|
|
127
|
+
|
|
128
|
+
_PART_SEPARATOR_TEXT = _PART_SEPARATOR.decode("ascii")
|
|
129
|
+
_LABEL_SEPARATOR_TEXT = _LABEL_SEPARATOR.decode("ascii")
|
|
130
|
+
|
|
131
|
+
_INT64_MIN = -(2**63)
|
|
132
|
+
_INT64_MAX = 2**63 - 1
|
|
133
|
+
|
|
134
|
+
_DIGEST_PREFIX = "sha256:"
|
|
135
|
+
_DIGEST_HEX_LENGTH = 64
|
|
136
|
+
|
|
137
|
+
#: One part of a seed-tree path. Ints appear as ordinals, occurrences, steps and run
|
|
138
|
+
#: indices; strings as the fixed segment names and document ids.
|
|
139
|
+
SeedPathPart = Union[str, int]
|
|
140
|
+
|
|
141
|
+
#: A seed-tree path: the address of one stream.
|
|
142
|
+
SeedPath = Tuple[SeedPathPart, ...]
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
class PathKind(Enum):
|
|
146
|
+
"""The kind of a variable segment in a canonical path shape."""
|
|
147
|
+
|
|
148
|
+
#: A document id, trait name, dial name or skill name.
|
|
149
|
+
NAME = "name"
|
|
150
|
+
#: A non-negative integer: a subject ordinal, an occurrence, a step, a run index.
|
|
151
|
+
ORDINAL = "ordinal"
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
@dataclass(frozen=True)
|
|
155
|
+
class PathShape:
|
|
156
|
+
"""One row of KERNEL-SPEC §3's canonical path table.
|
|
157
|
+
|
|
158
|
+
``pattern`` mixes literal segment names with :class:`PathKind` placeholders, so a path
|
|
159
|
+
can be matched against the closed table without a regular expression over its label.
|
|
160
|
+
``rooted_at`` records §3's one exception: the experiment assignment stream hangs off
|
|
161
|
+
``Experiment.spec.assignment.seed``, **not** off the run's effective seed, so that an
|
|
162
|
+
A/B assignment is stable across the runs of a sweep.
|
|
163
|
+
"""
|
|
164
|
+
|
|
165
|
+
name: str
|
|
166
|
+
consumer: str
|
|
167
|
+
pattern: Tuple[Union[str, PathKind], ...]
|
|
168
|
+
rooted_at: str = "root"
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
#: KERNEL-SPEC §3's canonical path table, transcribed row for row. **Closed**: adding a row
|
|
172
|
+
#: is a ``kernelVersion`` bump with a ``GOLDEN-CHANGELOG.md`` entry.
|
|
173
|
+
CANONICAL_PATH_SHAPES: Tuple[PathShape, ...] = (
|
|
174
|
+
PathShape(
|
|
175
|
+
name="world.cohorts",
|
|
176
|
+
consumer="LRM tie-free, so this stream is reserved and currently unused",
|
|
177
|
+
pattern=("world", PathKind.NAME, "cohorts"),
|
|
178
|
+
),
|
|
179
|
+
PathShape(
|
|
180
|
+
name="world.market",
|
|
181
|
+
consumer="market assignment of subject <ordinal>",
|
|
182
|
+
pattern=("world", PathKind.NAME, "market", PathKind.ORDINAL),
|
|
183
|
+
),
|
|
184
|
+
PathShape(
|
|
185
|
+
name="world.subject.trait",
|
|
186
|
+
consumer="trait draw",
|
|
187
|
+
pattern=("world", PathKind.NAME, "subject", PathKind.ORDINAL, "trait", PathKind.NAME),
|
|
188
|
+
),
|
|
189
|
+
PathShape(
|
|
190
|
+
name="world.subject.products",
|
|
191
|
+
consumer="vertical-pack derived attributes",
|
|
192
|
+
pattern=("world", PathKind.NAME, "subject", PathKind.ORDINAL, "products"),
|
|
193
|
+
),
|
|
194
|
+
PathShape(
|
|
195
|
+
name="sim.signal",
|
|
196
|
+
consumer="event arrival and payload",
|
|
197
|
+
pattern=(
|
|
198
|
+
"sim",
|
|
199
|
+
PathKind.NAME,
|
|
200
|
+
"signal",
|
|
201
|
+
PathKind.NAME,
|
|
202
|
+
"subject",
|
|
203
|
+
PathKind.ORDINAL,
|
|
204
|
+
PathKind.ORDINAL,
|
|
205
|
+
),
|
|
206
|
+
),
|
|
207
|
+
PathShape(
|
|
208
|
+
name="sim.journey",
|
|
209
|
+
consumer="reaction draw",
|
|
210
|
+
pattern=(
|
|
211
|
+
"sim",
|
|
212
|
+
PathKind.NAME,
|
|
213
|
+
"journey",
|
|
214
|
+
PathKind.NAME,
|
|
215
|
+
"subject",
|
|
216
|
+
PathKind.ORDINAL,
|
|
217
|
+
PathKind.ORDINAL,
|
|
218
|
+
),
|
|
219
|
+
),
|
|
220
|
+
PathShape(
|
|
221
|
+
name="sim.campaign",
|
|
222
|
+
consumer="delivery-side randomness",
|
|
223
|
+
pattern=("sim", PathKind.NAME, "campaign", PathKind.NAME, "subject", PathKind.ORDINAL),
|
|
224
|
+
),
|
|
225
|
+
PathShape(
|
|
226
|
+
name="sim.temperature",
|
|
227
|
+
consumer="stochastic share of a dial",
|
|
228
|
+
pattern=(
|
|
229
|
+
"sim",
|
|
230
|
+
PathKind.NAME,
|
|
231
|
+
"temperature",
|
|
232
|
+
PathKind.NAME,
|
|
233
|
+
"subject",
|
|
234
|
+
PathKind.ORDINAL,
|
|
235
|
+
PathKind.ORDINAL,
|
|
236
|
+
),
|
|
237
|
+
),
|
|
238
|
+
PathShape(
|
|
239
|
+
name="experiment.assignment",
|
|
240
|
+
consumer="variant assignment",
|
|
241
|
+
pattern=("experiment", PathKind.NAME, "assignment"),
|
|
242
|
+
rooted_at="Experiment.spec.assignment.seed",
|
|
243
|
+
),
|
|
244
|
+
PathShape(
|
|
245
|
+
name="sweep.run",
|
|
246
|
+
consumer="stochastic sweeps: run k uses effective_seed = baseSeed + k",
|
|
247
|
+
pattern=("sweep", PathKind.ORDINAL),
|
|
248
|
+
rooted_at="baseSeed + run_index",
|
|
249
|
+
),
|
|
250
|
+
PathShape(
|
|
251
|
+
name="sim.agentic",
|
|
252
|
+
consumer="v0.3 agentic skill call",
|
|
253
|
+
pattern=(
|
|
254
|
+
"sim",
|
|
255
|
+
PathKind.NAME,
|
|
256
|
+
"agentic",
|
|
257
|
+
PathKind.NAME,
|
|
258
|
+
"subject",
|
|
259
|
+
PathKind.ORDINAL,
|
|
260
|
+
PathKind.ORDINAL,
|
|
261
|
+
),
|
|
262
|
+
),
|
|
263
|
+
)
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
# ---------------------------------------------------------------------------
|
|
267
|
+
# Labels and roots
|
|
268
|
+
# ---------------------------------------------------------------------------
|
|
269
|
+
|
|
270
|
+
|
|
271
|
+
def path_label(path: Sequence[SeedPathPart]) -> bytes:
|
|
272
|
+
"""Return §3's label for *path*.
|
|
273
|
+
|
|
274
|
+
``b"\\x1f".join(NFC(str(part)).encode("utf-8") for part in path)``. The NFC pass is
|
|
275
|
+
what makes the composed and decomposed spellings of a trait name address one stream
|
|
276
|
+
rather than two.
|
|
277
|
+
|
|
278
|
+
A part that itself contains one of the two separator characters is refused
|
|
279
|
+
(``FLX-2202``) rather than escaped. §3 chose ``\\x1f`` because it cannot occur in a
|
|
280
|
+
document id, a trait name or a decimal ordinal, and the whole of path addressing rests
|
|
281
|
+
on the label being unique to the path: without this check
|
|
282
|
+
``("world", "a\\x1fb", "cohorts")`` and ``("world", "a", "b", "cohorts")`` would share
|
|
283
|
+
a label, and therefore share a stream. Escaping instead would change the label bytes
|
|
284
|
+
for every path and move every digest, so the assumption is enforced rather than worked
|
|
285
|
+
around.
|
|
286
|
+
"""
|
|
287
|
+
if not path:
|
|
288
|
+
raise FluxError(FLX_2202, "a seed-tree path must have at least one part")
|
|
289
|
+
parts = []
|
|
290
|
+
for index, part in enumerate(path):
|
|
291
|
+
text = nfc(str(part))
|
|
292
|
+
if _PART_SEPARATOR_TEXT in text or _LABEL_SEPARATOR_TEXT in text:
|
|
293
|
+
raise FluxError(
|
|
294
|
+
FLX_2202,
|
|
295
|
+
f"path part {index} contains a separator character (U+001F or U+001E), "
|
|
296
|
+
"which would make its label ambiguous",
|
|
297
|
+
)
|
|
298
|
+
parts.append(text.encode("utf-8"))
|
|
299
|
+
return _PART_SEPARATOR.join(parts)
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
def _sha256_bytes(data: bytes) -> bytes:
|
|
303
|
+
"""The raw 32 digest bytes, through the engine's one hashing primitive.
|
|
304
|
+
|
|
305
|
+
KERNEL-SPEC §2 makes :mod:`flux_engine.core.canonical` the only module that touches
|
|
306
|
+
``hashlib``; §3's derivation needs the digest as bytes rather than as hex, and the
|
|
307
|
+
round trip through the hex spelling is exact.
|
|
308
|
+
"""
|
|
309
|
+
return bytes.fromhex(sha256_hex(data))
|
|
310
|
+
|
|
311
|
+
|
|
312
|
+
def digest_bytes(digest_ref: str) -> bytes:
|
|
313
|
+
"""Return the raw 32 bytes of a ``"sha256:<hex>"`` digest reference.
|
|
314
|
+
|
|
315
|
+
Strict by design: a reference without the domain prefix, or with the wrong hex length,
|
|
316
|
+
is refused rather than coerced. A digest is the one value in the engine whose spelling
|
|
317
|
+
must not be guessed at.
|
|
318
|
+
"""
|
|
319
|
+
if not digest_ref.startswith(_DIGEST_PREFIX):
|
|
320
|
+
raise FluxError(FLX_2202, f"digest reference must start with {_DIGEST_PREFIX!r}")
|
|
321
|
+
hex_part = digest_ref[len(_DIGEST_PREFIX) :]
|
|
322
|
+
if len(hex_part) != _DIGEST_HEX_LENGTH:
|
|
323
|
+
raise FluxError(
|
|
324
|
+
FLX_2202,
|
|
325
|
+
f"digest reference carries {len(hex_part)} hex characters, "
|
|
326
|
+
f"expected {_DIGEST_HEX_LENGTH}",
|
|
327
|
+
)
|
|
328
|
+
try:
|
|
329
|
+
return bytes.fromhex(hex_part)
|
|
330
|
+
except ValueError as exc:
|
|
331
|
+
raise FluxError(FLX_2202, "digest reference is not hexadecimal") from exc
|
|
332
|
+
|
|
333
|
+
|
|
334
|
+
def seam_bytes(emit_digests: Sequence[str]) -> bytes:
|
|
335
|
+
"""Return §3's ``H_bytes`` for a Simulation's ``emits[]``.
|
|
336
|
+
|
|
337
|
+
§3: "``H`` is the contract digest of the seam ... When a Simulation has several
|
|
338
|
+
``emits[]``, ``H_bytes`` is the sha256 of the concatenation of the per-emit digests in
|
|
339
|
+
``emits[]`` order."
|
|
340
|
+
|
|
341
|
+
Read literally, that gives two rules, and this function implements both: with one emit,
|
|
342
|
+
``H_bytes`` is that emit's own 32 digest bytes; with several, it is the sha256 of their
|
|
343
|
+
concatenation in declaration order. The one-emit case is deliberately *not* folded
|
|
344
|
+
through a second sha256 -- §3 introduces the folding only for the several-emit case, and
|
|
345
|
+
the single-emit root is the one pinned by the vector file.
|
|
346
|
+
"""
|
|
347
|
+
if not emit_digests:
|
|
348
|
+
raise FluxError(FLX_2202, "a Simulation must declare at least one emit to derive H")
|
|
349
|
+
raw = [digest_bytes(ref) for ref in emit_digests]
|
|
350
|
+
if len(raw) == 1:
|
|
351
|
+
return raw[0]
|
|
352
|
+
return _sha256_bytes(b"".join(raw))
|
|
353
|
+
|
|
354
|
+
|
|
355
|
+
def effective_seed(simulation_seed: Optional[int], world_seed: Optional[int]) -> int:
|
|
356
|
+
"""§3's first line: the Simulation's seed if present, else the World's.
|
|
357
|
+
|
|
358
|
+
Both are int64. A seed outside that range is refused (``FLX-2202``) rather than
|
|
359
|
+
truncated, because ``to_bytes(8, signed=True)`` would otherwise raise deep inside the
|
|
360
|
+
derivation with a message that names neither document.
|
|
361
|
+
"""
|
|
362
|
+
seed = simulation_seed if simulation_seed is not None else world_seed
|
|
363
|
+
if seed is None:
|
|
364
|
+
raise FluxError(FLX_2202, "neither the Simulation nor the World declares a seed")
|
|
365
|
+
return _checked_int64(seed, "effective seed")
|
|
366
|
+
|
|
367
|
+
|
|
368
|
+
def _checked_int64(seed: int, what: str) -> int:
|
|
369
|
+
if isinstance(seed, bool) or not isinstance(seed, int):
|
|
370
|
+
raise FluxError(FLX_2202, f"{what} must be an integer, got {type(seed).__name__}")
|
|
371
|
+
if not _INT64_MIN <= seed <= _INT64_MAX:
|
|
372
|
+
raise FluxError(FLX_2202, f"{what} {seed} is outside the int64 range")
|
|
373
|
+
return seed
|
|
374
|
+
|
|
375
|
+
|
|
376
|
+
def sweep_effective_seed(base_seed: int, run_index: int) -> int:
|
|
377
|
+
"""§3's sweep rule: "run ``k`` uses ``effective_seed = baseSeed + k``".
|
|
378
|
+
|
|
379
|
+
The sum is range-checked as an int64 in its own right, so a sweep that would walk off
|
|
380
|
+
the end of the domain stops at the plan rather than at the 2^63rd run.
|
|
381
|
+
"""
|
|
382
|
+
_checked_int64(base_seed, "sweep base seed")
|
|
383
|
+
if run_index < 0:
|
|
384
|
+
raise FluxError(FLX_2202, f"sweep run index must be >= 0, got {run_index}")
|
|
385
|
+
return _checked_int64(base_seed + run_index, "sweep effective seed")
|
|
386
|
+
|
|
387
|
+
|
|
388
|
+
@dataclass(frozen=True)
|
|
389
|
+
class SeedTreeRoot:
|
|
390
|
+
"""The root of one run's seed tree (KERNEL-SPEC §3).
|
|
391
|
+
|
|
392
|
+
Carries the seam bytes it was derived from as well as the derived digest, so that the
|
|
393
|
+
two streams §3 roots elsewhere -- an experiment's assignment and a sweep's run -- can be
|
|
394
|
+
re-rooted from the same contract with :meth:`reseed` rather than by re-deriving ``H``.
|
|
395
|
+
"""
|
|
396
|
+
|
|
397
|
+
seam_bytes: bytes
|
|
398
|
+
effective_seed: int
|
|
399
|
+
digest: bytes
|
|
400
|
+
|
|
401
|
+
@property
|
|
402
|
+
def value(self) -> int:
|
|
403
|
+
"""The root as §3's integer: ``int.from_bytes(sha256(root_label).digest(), "big")``."""
|
|
404
|
+
return int.from_bytes(self.digest, "big")
|
|
405
|
+
|
|
406
|
+
@property
|
|
407
|
+
def hex(self) -> str:
|
|
408
|
+
"""The root digest in lowercase hex."""
|
|
409
|
+
return self.digest.hex()
|
|
410
|
+
|
|
411
|
+
def reseed(self, seed: int) -> "SeedTreeRoot":
|
|
412
|
+
"""The root for the same contract under a different seed.
|
|
413
|
+
|
|
414
|
+
Used for §3's two re-rooted streams: an ``Experiment``'s assignment seed, and a
|
|
415
|
+
sweep run's ``baseSeed + k``.
|
|
416
|
+
"""
|
|
417
|
+
return derive_root(self.seam_bytes, seed)
|
|
418
|
+
|
|
419
|
+
|
|
420
|
+
def derive_root(seam: bytes, seed: int) -> SeedTreeRoot:
|
|
421
|
+
"""Derive the root from ``H_bytes`` and the effective seed, exactly as §3 spells it."""
|
|
422
|
+
if not seam:
|
|
423
|
+
raise FluxError(FLX_2202, "H_bytes must not be empty")
|
|
424
|
+
checked = _checked_int64(seed, "effective seed")
|
|
425
|
+
root_label = _DOMAIN + _NUL + seam + _NUL + checked.to_bytes(8, "big", signed=True)
|
|
426
|
+
return SeedTreeRoot(seam_bytes=seam, effective_seed=checked, digest=_sha256_bytes(root_label))
|
|
427
|
+
|
|
428
|
+
|
|
429
|
+
def stream_entropy(root: SeedTreeRoot, path: Sequence[SeedPathPart]) -> int:
|
|
430
|
+
"""The ``SeedSequence`` entropy for *path* under *root* (§3's second formula)."""
|
|
431
|
+
label = path_label(path)
|
|
432
|
+
material = _DOMAIN + _NUL + root.digest + _NUL + label
|
|
433
|
+
return int.from_bytes(_sha256_bytes(material), "big")
|
|
434
|
+
|
|
435
|
+
|
|
436
|
+
def derive_identifier(root: SeedTreeRoot, path: Sequence[SeedPathPart], *, length: int = 32) -> str:
|
|
437
|
+
"""A stable identifier for *path*, in lowercase hex.
|
|
438
|
+
|
|
439
|
+
The sanctioned replacement for ``uuid4`` anywhere the engine needs an id: an event id,
|
|
440
|
+
a subject id, the identifier columns SEAM-FIDELITY-SPEC §1 requires to be "derived
|
|
441
|
+
deterministically from ``(H, ordinal)`` -- never random". Two runs of the same plan
|
|
442
|
+
produce the same identifiers, which is what lets a golden compare them at all.
|
|
443
|
+
"""
|
|
444
|
+
if not 1 <= length <= 64:
|
|
445
|
+
raise FluxError(FLX_2202, f"identifier length must be in [1, 64], got {length}")
|
|
446
|
+
material = _DOMAIN + _NUL + b"id" + _NUL + root.digest + _NUL + path_label(path)
|
|
447
|
+
return sha256_hex(material)[:length]
|
|
448
|
+
|
|
449
|
+
|
|
450
|
+
# ---------------------------------------------------------------------------
|
|
451
|
+
# The canonical path table
|
|
452
|
+
# ---------------------------------------------------------------------------
|
|
453
|
+
|
|
454
|
+
|
|
455
|
+
def _is_ordinal(part: SeedPathPart) -> bool:
|
|
456
|
+
return isinstance(part, int) and not isinstance(part, bool) and part >= 0
|
|
457
|
+
|
|
458
|
+
|
|
459
|
+
def match_shape(path: Sequence[SeedPathPart]) -> Optional[PathShape]:
|
|
460
|
+
"""Return the canonical shape *path* matches, or ``None`` if it matches none."""
|
|
461
|
+
for shape in CANONICAL_PATH_SHAPES:
|
|
462
|
+
if len(shape.pattern) != len(path):
|
|
463
|
+
continue
|
|
464
|
+
for expected, part in zip(shape.pattern, path, strict=True):
|
|
465
|
+
if isinstance(expected, str):
|
|
466
|
+
if not isinstance(part, str) or nfc(part) != expected:
|
|
467
|
+
break
|
|
468
|
+
elif expected is PathKind.ORDINAL:
|
|
469
|
+
if not _is_ordinal(part):
|
|
470
|
+
break
|
|
471
|
+
elif not isinstance(part, str) or not part:
|
|
472
|
+
break
|
|
473
|
+
else:
|
|
474
|
+
return shape
|
|
475
|
+
return None
|
|
476
|
+
|
|
477
|
+
|
|
478
|
+
def _require_name(value: str, what: str) -> str:
|
|
479
|
+
if not isinstance(value, str) or not value:
|
|
480
|
+
raise FluxError(FLX_2202, f"{what} must be a non-empty string")
|
|
481
|
+
return value
|
|
482
|
+
|
|
483
|
+
|
|
484
|
+
def _require_ordinal(value: int, what: str) -> int:
|
|
485
|
+
if not _is_ordinal(value):
|
|
486
|
+
raise FluxError(FLX_2202, f"{what} must be a non-negative integer, got {value!r}")
|
|
487
|
+
return value
|
|
488
|
+
|
|
489
|
+
|
|
490
|
+
def world_cohorts_path(world_id: str) -> SeedPath:
|
|
491
|
+
"""``("world", world_id, "cohorts")`` -- reserved; the LRM cohort split is tie-free."""
|
|
492
|
+
return ("world", _require_name(world_id, "world id"), "cohorts")
|
|
493
|
+
|
|
494
|
+
|
|
495
|
+
def market_path(world_id: str, ordinal: int) -> SeedPath:
|
|
496
|
+
"""``("world", world_id, "market", ordinal)`` -- market assignment of one subject."""
|
|
497
|
+
return (
|
|
498
|
+
"world",
|
|
499
|
+
_require_name(world_id, "world id"),
|
|
500
|
+
"market",
|
|
501
|
+
_require_ordinal(ordinal, "subject ordinal"),
|
|
502
|
+
)
|
|
503
|
+
|
|
504
|
+
|
|
505
|
+
def subject_trait_path(world_id: str, ordinal: int, trait_name: str) -> SeedPath:
|
|
506
|
+
"""``("world", world_id, "subject", ordinal, "trait", trait_name)`` -- one trait draw."""
|
|
507
|
+
return (
|
|
508
|
+
"world",
|
|
509
|
+
_require_name(world_id, "world id"),
|
|
510
|
+
"subject",
|
|
511
|
+
_require_ordinal(ordinal, "subject ordinal"),
|
|
512
|
+
"trait",
|
|
513
|
+
_require_name(trait_name, "trait name"),
|
|
514
|
+
)
|
|
515
|
+
|
|
516
|
+
|
|
517
|
+
def subject_products_path(world_id: str, ordinal: int) -> SeedPath:
|
|
518
|
+
"""``("world", world_id, "subject", ordinal, "products")`` -- vertical-pack attributes."""
|
|
519
|
+
return (
|
|
520
|
+
"world",
|
|
521
|
+
_require_name(world_id, "world id"),
|
|
522
|
+
"subject",
|
|
523
|
+
_require_ordinal(ordinal, "subject ordinal"),
|
|
524
|
+
"products",
|
|
525
|
+
)
|
|
526
|
+
|
|
527
|
+
|
|
528
|
+
def signal_path(sim_id: str, signal_id: str, ordinal: int, occurrence: int) -> SeedPath:
|
|
529
|
+
"""``("sim", sim_id, "signal", signal_id, "subject", ordinal, occurrence)``."""
|
|
530
|
+
return (
|
|
531
|
+
"sim",
|
|
532
|
+
_require_name(sim_id, "simulation id"),
|
|
533
|
+
"signal",
|
|
534
|
+
_require_name(signal_id, "signal id"),
|
|
535
|
+
"subject",
|
|
536
|
+
_require_ordinal(ordinal, "subject ordinal"),
|
|
537
|
+
_require_ordinal(occurrence, "occurrence"),
|
|
538
|
+
)
|
|
539
|
+
|
|
540
|
+
|
|
541
|
+
def journey_path(sim_id: str, journey_id: str, ordinal: int, step: int) -> SeedPath:
|
|
542
|
+
"""``("sim", sim_id, "journey", journey_id, "subject", ordinal, step)``."""
|
|
543
|
+
return (
|
|
544
|
+
"sim",
|
|
545
|
+
_require_name(sim_id, "simulation id"),
|
|
546
|
+
"journey",
|
|
547
|
+
_require_name(journey_id, "journey id"),
|
|
548
|
+
"subject",
|
|
549
|
+
_require_ordinal(ordinal, "subject ordinal"),
|
|
550
|
+
_require_ordinal(step, "journey step"),
|
|
551
|
+
)
|
|
552
|
+
|
|
553
|
+
|
|
554
|
+
def campaign_path(sim_id: str, campaign_id: str, ordinal: int) -> SeedPath:
|
|
555
|
+
"""``("sim", sim_id, "campaign", campaign_id, "subject", ordinal)``."""
|
|
556
|
+
return (
|
|
557
|
+
"sim",
|
|
558
|
+
_require_name(sim_id, "simulation id"),
|
|
559
|
+
"campaign",
|
|
560
|
+
_require_name(campaign_id, "campaign id"),
|
|
561
|
+
"subject",
|
|
562
|
+
_require_ordinal(ordinal, "subject ordinal"),
|
|
563
|
+
)
|
|
564
|
+
|
|
565
|
+
|
|
566
|
+
def temperature_path(sim_id: str, dial: str, ordinal: int, occurrence: int) -> SeedPath:
|
|
567
|
+
"""``("sim", sim_id, "temperature", dial, "subject", ordinal, occurrence)``.
|
|
568
|
+
|
|
569
|
+
Dial names are open (§6), so *dial* is validated as a name and not against a closed set.
|
|
570
|
+
"""
|
|
571
|
+
return (
|
|
572
|
+
"sim",
|
|
573
|
+
_require_name(sim_id, "simulation id"),
|
|
574
|
+
"temperature",
|
|
575
|
+
_require_name(dial, "temperature dial"),
|
|
576
|
+
"subject",
|
|
577
|
+
_require_ordinal(ordinal, "subject ordinal"),
|
|
578
|
+
_require_ordinal(occurrence, "occurrence"),
|
|
579
|
+
)
|
|
580
|
+
|
|
581
|
+
|
|
582
|
+
def experiment_assignment_path(experiment_id: str) -> SeedPath:
|
|
583
|
+
"""``("experiment", experiment_id, "assignment")``.
|
|
584
|
+
|
|
585
|
+
Rooted at ``Experiment.spec.assignment.seed``, not at the run's root: build its stream
|
|
586
|
+
from ``root.reseed(assignment_seed)`` so that variant assignment is stable across the
|
|
587
|
+
runs of a sweep.
|
|
588
|
+
"""
|
|
589
|
+
return ("experiment", _require_name(experiment_id, "experiment id"), "assignment")
|
|
590
|
+
|
|
591
|
+
|
|
592
|
+
def sweep_path(run_index: int) -> SeedPath:
|
|
593
|
+
"""``("sweep", run_index)`` -- rooted at ``baseSeed + run_index``."""
|
|
594
|
+
return ("sweep", _require_ordinal(run_index, "sweep run index"))
|
|
595
|
+
|
|
596
|
+
|
|
597
|
+
def agentic_path(sim_id: str, skill_name: str, ordinal: int, call_ordinal: int) -> SeedPath:
|
|
598
|
+
"""``("sim", sim_id, "agentic", skill_name, "subject", ordinal, call_ordinal)`` (v0.3)."""
|
|
599
|
+
return (
|
|
600
|
+
"sim",
|
|
601
|
+
_require_name(sim_id, "simulation id"),
|
|
602
|
+
"agentic",
|
|
603
|
+
_require_name(skill_name, "skill name"),
|
|
604
|
+
"subject",
|
|
605
|
+
_require_ordinal(ordinal, "subject ordinal"),
|
|
606
|
+
_require_ordinal(call_ordinal, "call ordinal"),
|
|
607
|
+
)
|
|
608
|
+
|
|
609
|
+
|
|
610
|
+
# ---------------------------------------------------------------------------
|
|
611
|
+
# The tree
|
|
612
|
+
# ---------------------------------------------------------------------------
|
|
613
|
+
|
|
614
|
+
|
|
615
|
+
def render_seed_path(path: Sequence[SeedPathPart]) -> bytes:
|
|
616
|
+
"""Return the one ``seed-paths.ndjson`` line for *path*, without its newline.
|
|
617
|
+
|
|
618
|
+
The line is the canonical JSON (RFC 8785, KERNEL-SPEC §2.1) of the path as an array,
|
|
619
|
+
so ``("world", "w", "market", 0)`` becomes ``["world","w","market",0]``: the same
|
|
620
|
+
canonicaliser every other hashed document in the engine goes through, which is what
|
|
621
|
+
makes the file's bytes reproducible rather than a spelling this module invented.
|
|
622
|
+
|
|
623
|
+
The path is put through :func:`path_label` first, so a part carrying a separator
|
|
624
|
+
character is refused here exactly as it is when a stream is derived -- the file records
|
|
625
|
+
stream addresses, and an address that cannot be labelled is not one.
|
|
626
|
+
"""
|
|
627
|
+
normalised: SeedPath = tuple(path)
|
|
628
|
+
path_label(normalised)
|
|
629
|
+
return canonical_bytes(list(normalised))
|
|
630
|
+
|
|
631
|
+
|
|
632
|
+
def parse_seed_path(line: Union[str, bytes]) -> SeedPath:
|
|
633
|
+
"""Return the path one ``seed-paths.ndjson`` line records.
|
|
634
|
+
|
|
635
|
+
The inverse of :func:`render_seed_path`, and strict in the same way: a line that is not
|
|
636
|
+
a JSON array of strings and non-negative integers is refused (``FLX-2202``) rather than
|
|
637
|
+
coerced, because a mis-parsed path silently widens the planned set that ``FLX-2201``
|
|
638
|
+
checks against.
|
|
639
|
+
"""
|
|
640
|
+
text = line.decode("utf-8") if isinstance(line, bytes) else line
|
|
641
|
+
try:
|
|
642
|
+
decoded = json.loads(text)
|
|
643
|
+
except ValueError as exc:
|
|
644
|
+
raise FluxError(FLX_2202, f"seed-path line is not JSON: {text!r}") from exc
|
|
645
|
+
if not isinstance(decoded, list) or not decoded:
|
|
646
|
+
raise FluxError(FLX_2202, "a seed-path line must be a non-empty JSON array")
|
|
647
|
+
parts: List[SeedPathPart] = []
|
|
648
|
+
for index, part in enumerate(decoded):
|
|
649
|
+
if isinstance(part, bool) or not isinstance(part, (str, int)):
|
|
650
|
+
raise FluxError(
|
|
651
|
+
FLX_2202,
|
|
652
|
+
f"seed-path part {index} is {type(part).__name__}, expected a string or an "
|
|
653
|
+
"integer",
|
|
654
|
+
)
|
|
655
|
+
parts.append(part)
|
|
656
|
+
return tuple(parts)
|
|
657
|
+
|
|
658
|
+
|
|
659
|
+
def seed_paths_bytes(paths: Iterable[Sequence[SeedPathPart]]) -> bytes:
|
|
660
|
+
"""Return the exact bytes of ``seed-paths.ndjson`` for *paths* (KERNEL-SPEC §3).
|
|
661
|
+
|
|
662
|
+
One canonical path per line, sorted, newline-terminated -- and therefore a pure
|
|
663
|
+
function of the *set* of paths: the order they were materialised in, and how many times
|
|
664
|
+
each was reached, cannot reach the bytes. Sorting is over the rendered lines rather than
|
|
665
|
+
over §3's labels, so the file a reader has in front of them is the file that is sorted
|
|
666
|
+
(``sort -c`` passes on it) and the digest below is a plain ``sha256sum`` of it.
|
|
667
|
+
|
|
668
|
+
Two paths that share a label -- which §3's ``str(part)`` rule allows in principle,
|
|
669
|
+
``("w", 1)`` and ``("w", "1")`` addressing one stream -- contribute **one** line, the
|
|
670
|
+
lexicographically first, because the file records one line per stream.
|
|
671
|
+
"""
|
|
672
|
+
by_label: Dict[bytes, bytes] = {}
|
|
673
|
+
for path in paths:
|
|
674
|
+
normalised: SeedPath = tuple(path)
|
|
675
|
+
label = path_label(normalised)
|
|
676
|
+
line = canonical_bytes(list(normalised))
|
|
677
|
+
previous = by_label.get(label)
|
|
678
|
+
if previous is None or line < previous:
|
|
679
|
+
by_label[label] = line
|
|
680
|
+
return b"".join(line + b"\n" for line in sorted(by_label.values()))
|
|
681
|
+
|
|
682
|
+
|
|
683
|
+
def parse_seed_paths(data: bytes) -> Tuple[SeedPath, ...]:
|
|
684
|
+
"""Return every path recorded in the bytes of a ``seed-paths.ndjson``.
|
|
685
|
+
|
|
686
|
+
Blank lines are skipped; every other line must parse (:func:`parse_seed_path`). The
|
|
687
|
+
result is in file order, which for a file this module wrote is sorted order.
|
|
688
|
+
"""
|
|
689
|
+
return tuple(
|
|
690
|
+
parse_seed_path(line) for line in data.decode("utf-8").splitlines() if line.strip()
|
|
691
|
+
)
|
|
692
|
+
|
|
693
|
+
|
|
694
|
+
def seed_paths_digest(data: bytes) -> str:
|
|
695
|
+
"""§3's ``seedTreeDigest``: the ``raw-bytes`` digest of ``seed-paths.ndjson``.
|
|
696
|
+
|
|
697
|
+
A raw-bytes digest (KERNEL-SPEC §2.3) rather than a digest over a structure the engine
|
|
698
|
+
holds in memory: the file beside the plan is the artifact, and anyone -- a reviewer, a
|
|
699
|
+
CI step, ``sha256sum`` -- can recompute this number from it without running the engine.
|
|
700
|
+
"""
|
|
701
|
+
return f"{_DIGEST_PREFIX}{sha256_hex(data)}"
|
|
702
|
+
|
|
703
|
+
|
|
704
|
+
def seed_tree_digest(paths: Iterable[Sequence[SeedPathPart]]) -> str:
|
|
705
|
+
"""§3's ``seedTreeDigest`` over the set of paths a run materialised.
|
|
706
|
+
|
|
707
|
+
"Every path materialised during a run is recorded (sorted) in ``seed-paths.ndjson``
|
|
708
|
+
beside the plan (one canonical path per line; raw-bytes digest = ``seedTreeDigest``)."
|
|
709
|
+
So this is :func:`seed_paths_digest` of :func:`seed_paths_bytes` -- the digest of the
|
|
710
|
+
file, computed without needing the file on disk.
|
|
711
|
+
"""
|
|
712
|
+
return seed_paths_digest(seed_paths_bytes(paths))
|
|
713
|
+
|
|
714
|
+
|
|
715
|
+
def shape_counts(paths: Iterable[Sequence[SeedPathPart]]) -> Dict[str, int]:
|
|
716
|
+
"""Count *paths* per canonical shape, keyed by :attr:`PathShape.name`.
|
|
717
|
+
|
|
718
|
+
The table ``plan.json`` carries in place of the path list: ``{"world.subject.trait":
|
|
719
|
+
75000, ...}``, in sorted-key order. It is the part of the path set a human reads a plan
|
|
720
|
+
for -- how many streams of each kind this run will touch -- while the addresses
|
|
721
|
+
themselves stay in the NDJSON beside it.
|
|
722
|
+
|
|
723
|
+
A path matching no row of the closed table is refused (``FLX-2201``) rather than
|
|
724
|
+
counted under some catch-all: the counts are a summary of the plan's seed tree, and a
|
|
725
|
+
summary that quietly absorbs an unanticipated shape would defeat the check the plan
|
|
726
|
+
exists to make.
|
|
727
|
+
"""
|
|
728
|
+
counts: Dict[str, int] = {}
|
|
729
|
+
for path in paths:
|
|
730
|
+
normalised: SeedPath = tuple(path)
|
|
731
|
+
shape = match_shape(normalised)
|
|
732
|
+
if shape is None:
|
|
733
|
+
raise FluxError(
|
|
734
|
+
FLX_2201,
|
|
735
|
+
f"path {normalised!r} matches no row of the canonical path table "
|
|
736
|
+
"(KERNEL-SPEC §3)",
|
|
737
|
+
)
|
|
738
|
+
counts[shape.name] = counts.get(shape.name, 0) + 1
|
|
739
|
+
return {name: counts[name] for name in sorted(counts)}
|
|
740
|
+
|
|
741
|
+
|
|
742
|
+
@dataclass
|
|
743
|
+
class SeedPathLedger:
|
|
744
|
+
"""Every path a run has materialised, recorded once, in canonical order.
|
|
745
|
+
|
|
746
|
+
Append-safe in the two senses the plan needs. :meth:`record` is idempotent -- reaching
|
|
747
|
+
one path a second time adds nothing -- so a caller may record as it goes without
|
|
748
|
+
tracking what it has already seen. And the rendered file is a pure function of the set,
|
|
749
|
+
so a ``seed-paths.ndjson`` that was half-written when a run was killed is rewritten
|
|
750
|
+
whole on the next attempt rather than appended to (the same restart-safety
|
|
751
|
+
``fluxsim apply`` gives every other artifact it writes).
|
|
752
|
+
|
|
753
|
+
The sorted view, the file bytes and the digest are memoised and invalidated on
|
|
754
|
+
:meth:`record`, because a plan asks for the digest several times over a set that can
|
|
755
|
+
hold millions of paths, and re-sorting it once per question was measurable.
|
|
756
|
+
"""
|
|
757
|
+
|
|
758
|
+
_paths: Dict[bytes, SeedPath] = field(default_factory=dict, repr=False)
|
|
759
|
+
_sorted: Optional[Tuple[SeedPath, ...]] = field(default=None, repr=False)
|
|
760
|
+
_bytes: Optional[bytes] = field(default=None, repr=False)
|
|
761
|
+
|
|
762
|
+
def record(self, path: Sequence[SeedPathPart]) -> bytes:
|
|
763
|
+
"""Record *path* and return its label. Idempotent."""
|
|
764
|
+
normalised: SeedPath = tuple(path)
|
|
765
|
+
label = path_label(normalised)
|
|
766
|
+
if label not in self._paths:
|
|
767
|
+
self._paths[label] = normalised
|
|
768
|
+
self._sorted = None
|
|
769
|
+
self._bytes = None
|
|
770
|
+
return label
|
|
771
|
+
|
|
772
|
+
def __contains__(self, label: object) -> bool:
|
|
773
|
+
return label in self._paths
|
|
774
|
+
|
|
775
|
+
def __len__(self) -> int:
|
|
776
|
+
return len(self._paths)
|
|
777
|
+
|
|
778
|
+
@property
|
|
779
|
+
def paths(self) -> Tuple[SeedPath, ...]:
|
|
780
|
+
"""Every recorded path, in ``seed-paths.ndjson`` order."""
|
|
781
|
+
if self._sorted is None:
|
|
782
|
+
self._sorted = tuple(
|
|
783
|
+
sorted(self._paths.values(), key=lambda path: canonical_bytes(list(path)))
|
|
784
|
+
)
|
|
785
|
+
return self._sorted
|
|
786
|
+
|
|
787
|
+
def ndjson_bytes(self) -> bytes:
|
|
788
|
+
"""The exact bytes of this ledger's ``seed-paths.ndjson``."""
|
|
789
|
+
if self._bytes is None:
|
|
790
|
+
self._bytes = seed_paths_bytes(self._paths.values())
|
|
791
|
+
return self._bytes
|
|
792
|
+
|
|
793
|
+
def digest(self) -> str:
|
|
794
|
+
"""``seedTreeDigest``: the raw-bytes digest of :meth:`ndjson_bytes`."""
|
|
795
|
+
return seed_paths_digest(self.ndjson_bytes())
|
|
796
|
+
|
|
797
|
+
def shape_counts(self) -> Dict[str, int]:
|
|
798
|
+
""":func:`shape_counts` over the recorded paths."""
|
|
799
|
+
return shape_counts(self.paths)
|
|
800
|
+
|
|
801
|
+
|
|
802
|
+
@dataclass
|
|
803
|
+
class SeedTree:
|
|
804
|
+
"""The path-addressed stream table for one run (KERNEL-SPEC §3).
|
|
805
|
+
|
|
806
|
+
``planned_paths``, when given, is the set the plan anticipated -- the labels of the
|
|
807
|
+
paths in the run's ``seed-paths.ndjson`` -- and a request for any other path raises
|
|
808
|
+
``FLX-2201`` rather than deriving a stream the plan cannot account for. Leave it
|
|
809
|
+
``None`` while planning, when the point of the pass is to discover the set.
|
|
810
|
+
|
|
811
|
+
Streams are memoised by label, so two requests for one path continue **one** stream
|
|
812
|
+
rather than restarting it -- a caller that asks for the same path twice gets the second
|
|
813
|
+
draw, not the first one again.
|
|
814
|
+
"""
|
|
815
|
+
|
|
816
|
+
root: SeedTreeRoot
|
|
817
|
+
planned_paths: Optional[FrozenSet[bytes]] = None
|
|
818
|
+
_streams: Dict[bytes, DrawStream] = field(default_factory=dict, repr=False)
|
|
819
|
+
_ledger: SeedPathLedger = field(default_factory=SeedPathLedger, repr=False)
|
|
820
|
+
|
|
821
|
+
@classmethod
|
|
822
|
+
def for_plan(
|
|
823
|
+
cls, root: SeedTreeRoot, planned_paths: Iterable[Sequence[SeedPathPart]]
|
|
824
|
+
) -> "SeedTree":
|
|
825
|
+
"""Build a tree restricted to the paths a plan recorded.
|
|
826
|
+
|
|
827
|
+
*planned_paths* is what :func:`parse_seed_paths` read back out of the run's
|
|
828
|
+
``seed-paths.ndjson``; the set is held as labels, so the membership test costs one
|
|
829
|
+
hash per stream rather than a scan of the file.
|
|
830
|
+
"""
|
|
831
|
+
return cls(root=root, planned_paths=frozenset(path_label(p) for p in planned_paths))
|
|
832
|
+
|
|
833
|
+
@property
|
|
834
|
+
def ledger(self) -> SeedPathLedger:
|
|
835
|
+
"""The paths this tree has materialised."""
|
|
836
|
+
return self._ledger
|
|
837
|
+
|
|
838
|
+
@property
|
|
839
|
+
def materialised_paths(self) -> Tuple[SeedPath, ...]:
|
|
840
|
+
"""Every path this tree has derived a stream for, in ``seed-paths.ndjson`` order."""
|
|
841
|
+
return self._ledger.paths
|
|
842
|
+
|
|
843
|
+
def seed_paths_bytes(self) -> bytes:
|
|
844
|
+
"""The bytes of the ``seed-paths.ndjson`` this run's paths make up."""
|
|
845
|
+
return self._ledger.ndjson_bytes()
|
|
846
|
+
|
|
847
|
+
def digest(self) -> str:
|
|
848
|
+
"""``seedTreeDigest`` over the paths materialised so far."""
|
|
849
|
+
return self._ledger.digest()
|
|
850
|
+
|
|
851
|
+
def shape_counts(self) -> Dict[str, int]:
|
|
852
|
+
"""The per-shape count table ``plan.json`` carries."""
|
|
853
|
+
return self._ledger.shape_counts()
|
|
854
|
+
|
|
855
|
+
def entropy(self, path: Sequence[SeedPathPart]) -> int:
|
|
856
|
+
"""The ``SeedSequence`` entropy for *path*, without materialising its stream."""
|
|
857
|
+
return stream_entropy(self.root, path)
|
|
858
|
+
|
|
859
|
+
def stream(self, path: Sequence[SeedPathPart]) -> DrawStream:
|
|
860
|
+
"""Return the stream addressed by *path*, deriving it on first request.
|
|
861
|
+
|
|
862
|
+
Refuses a path outside the closed canonical table, and a path outside the planned
|
|
863
|
+
set when one was given -- both ``FLX-2201``.
|
|
864
|
+
"""
|
|
865
|
+
normalised: SeedPath = tuple(path)
|
|
866
|
+
shape = match_shape(normalised)
|
|
867
|
+
if shape is None:
|
|
868
|
+
raise FluxError(
|
|
869
|
+
FLX_2201,
|
|
870
|
+
f"path {normalised!r} matches no row of the canonical path table "
|
|
871
|
+
"(KERNEL-SPEC §3)",
|
|
872
|
+
)
|
|
873
|
+
label = path_label(normalised)
|
|
874
|
+
if self.planned_paths is not None and label not in self.planned_paths:
|
|
875
|
+
raise FluxError(
|
|
876
|
+
FLX_2201,
|
|
877
|
+
f"path {normalised!r} ({shape.name}) is not in the planned path set",
|
|
878
|
+
)
|
|
879
|
+
existing = self._streams.get(label)
|
|
880
|
+
if existing is not None:
|
|
881
|
+
return existing
|
|
882
|
+
created = self._new_stream(normalised, label)
|
|
883
|
+
self._streams[label] = created
|
|
884
|
+
self._ledger.record(normalised)
|
|
885
|
+
return created
|
|
886
|
+
|
|
887
|
+
def _new_stream(self, path: SeedPath, label: bytes) -> DrawStream:
|
|
888
|
+
"""Derive one stream. The single seam a test subclass overrides to break the tree."""
|
|
889
|
+
return DrawStream.from_entropy(
|
|
890
|
+
stream_entropy(self.root, path), label=label.decode("utf-8", "replace")
|
|
891
|
+
)
|