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

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