@smthrs/plan 0.0.0-stage → 1.0.0-rc.3

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 (199) hide show
  1. package/CHANGELOG.md +183 -0
  2. package/LICENSE +21 -0
  3. package/README.md +228 -2
  4. package/dist/cjs/CachePolicy.d.ts +131 -0
  5. package/dist/cjs/CachePolicy.d.ts.map +1 -0
  6. package/dist/cjs/CachePolicy.js +50 -0
  7. package/dist/cjs/CachePolicy.js.map +7 -0
  8. package/dist/cjs/Effects.d.ts +240 -0
  9. package/dist/cjs/Effects.d.ts.map +1 -0
  10. package/dist/cjs/Effects.js +76 -0
  11. package/dist/cjs/Effects.js.map +7 -0
  12. package/dist/cjs/FileSet.d.ts +288 -0
  13. package/dist/cjs/FileSet.d.ts.map +1 -0
  14. package/dist/cjs/FileSet.js +191 -0
  15. package/dist/cjs/FileSet.js.map +7 -0
  16. package/dist/cjs/GraphBuildError.d.ts +122 -0
  17. package/dist/cjs/GraphBuildError.d.ts.map +1 -0
  18. package/dist/cjs/GraphBuildError.js +71 -0
  19. package/dist/cjs/GraphBuildError.js.map +7 -0
  20. package/dist/cjs/KeyMaterial.d.ts +102 -0
  21. package/dist/cjs/KeyMaterial.d.ts.map +1 -0
  22. package/dist/cjs/KeyMaterial.js +64 -0
  23. package/dist/cjs/KeyMaterial.js.map +7 -0
  24. package/dist/cjs/Node.d.ts +606 -0
  25. package/dist/cjs/Node.d.ts.map +1 -0
  26. package/dist/cjs/Node.js +207 -0
  27. package/dist/cjs/Node.js.map +7 -0
  28. package/dist/cjs/Placement.d.ts +117 -0
  29. package/dist/cjs/Placement.d.ts.map +1 -0
  30. package/dist/cjs/Placement.js +46 -0
  31. package/dist/cjs/Placement.js.map +7 -0
  32. package/dist/cjs/Plan.d.ts +440 -0
  33. package/dist/cjs/Plan.d.ts.map +1 -0
  34. package/dist/cjs/Plan.js +508 -0
  35. package/dist/cjs/Plan.js.map +7 -0
  36. package/dist/cjs/PlanDiff.d.ts +58 -0
  37. package/dist/cjs/PlanDiff.d.ts.map +1 -0
  38. package/dist/cjs/PlanDiff.js +124 -0
  39. package/dist/cjs/PlanDiff.js.map +7 -0
  40. package/dist/cjs/Planned.d.ts +121 -0
  41. package/dist/cjs/Planned.d.ts.map +1 -0
  42. package/dist/cjs/Planned.js +72 -0
  43. package/dist/cjs/Planned.js.map +7 -0
  44. package/dist/cjs/Repetition.d.ts +31 -0
  45. package/dist/cjs/Repetition.d.ts.map +1 -0
  46. package/dist/cjs/Repetition.js +36 -0
  47. package/dist/cjs/Repetition.js.map +7 -0
  48. package/dist/cjs/Scheduling.d.ts +89 -0
  49. package/dist/cjs/Scheduling.d.ts.map +1 -0
  50. package/dist/cjs/Scheduling.js +76 -0
  51. package/dist/cjs/Scheduling.js.map +7 -0
  52. package/dist/cjs/StepKey.d.ts +333 -0
  53. package/dist/cjs/StepKey.d.ts.map +1 -0
  54. package/dist/cjs/StepKey.js +311 -0
  55. package/dist/cjs/StepKey.js.map +7 -0
  56. package/dist/cjs/index.d.ts +91 -0
  57. package/dist/cjs/index.d.ts.map +1 -0
  58. package/dist/cjs/index.js +59 -0
  59. package/dist/cjs/index.js.map +7 -0
  60. package/dist/cjs/internal/ConflictAnnotation.d.ts +59 -0
  61. package/dist/cjs/internal/ConflictAnnotation.d.ts.map +1 -0
  62. package/dist/cjs/internal/ConflictAnnotation.js +247 -0
  63. package/dist/cjs/internal/ConflictAnnotation.js.map +7 -0
  64. package/dist/cjs/internal/EffectCandidates.d.ts +19 -0
  65. package/dist/cjs/internal/EffectCandidates.d.ts.map +1 -0
  66. package/dist/cjs/internal/EffectCandidates.js +92 -0
  67. package/dist/cjs/internal/EffectCandidates.js.map +7 -0
  68. package/dist/cjs/internal/JsonMirror.d.ts +34 -0
  69. package/dist/cjs/internal/JsonMirror.d.ts.map +1 -0
  70. package/dist/cjs/internal/JsonMirror.js +195 -0
  71. package/dist/cjs/internal/JsonMirror.js.map +7 -0
  72. package/dist/cjs/internal/effects.d.ts +245 -0
  73. package/dist/cjs/internal/effects.d.ts.map +1 -0
  74. package/dist/cjs/internal/effects.js +290 -0
  75. package/dist/cjs/internal/effects.js.map +7 -0
  76. package/dist/cjs/internal/node.d.ts +526 -0
  77. package/dist/cjs/internal/node.d.ts.map +1 -0
  78. package/dist/cjs/internal/node.js +312 -0
  79. package/dist/cjs/internal/node.js.map +7 -0
  80. package/dist/cjs/package.json +1 -0
  81. package/dist/cjs/test/PlanFixtures.d.ts +127 -0
  82. package/dist/cjs/test/PlanFixtures.d.ts.map +1 -0
  83. package/dist/cjs/test/PlanFixtures.js +59 -0
  84. package/dist/cjs/test/PlanFixtures.js.map +7 -0
  85. package/dist/esm/CachePolicy.d.ts +131 -0
  86. package/dist/esm/CachePolicy.d.ts.map +1 -0
  87. package/dist/esm/CachePolicy.js +117 -0
  88. package/dist/esm/CachePolicy.js.map +1 -0
  89. package/dist/esm/Effects.d.ts +240 -0
  90. package/dist/esm/Effects.d.ts.map +1 -0
  91. package/dist/esm/Effects.js +167 -0
  92. package/dist/esm/Effects.js.map +1 -0
  93. package/dist/esm/FileSet.d.ts +288 -0
  94. package/dist/esm/FileSet.d.ts.map +1 -0
  95. package/dist/esm/FileSet.js +324 -0
  96. package/dist/esm/FileSet.js.map +1 -0
  97. package/dist/esm/GraphBuildError.d.ts +122 -0
  98. package/dist/esm/GraphBuildError.d.ts.map +1 -0
  99. package/dist/esm/GraphBuildError.js +146 -0
  100. package/dist/esm/GraphBuildError.js.map +1 -0
  101. package/dist/esm/KeyMaterial.d.ts +102 -0
  102. package/dist/esm/KeyMaterial.d.ts.map +1 -0
  103. package/dist/esm/KeyMaterial.js +85 -0
  104. package/dist/esm/KeyMaterial.js.map +1 -0
  105. package/dist/esm/Node.d.ts +606 -0
  106. package/dist/esm/Node.d.ts.map +1 -0
  107. package/dist/esm/Node.js +521 -0
  108. package/dist/esm/Node.js.map +1 -0
  109. package/dist/esm/Placement.d.ts +117 -0
  110. package/dist/esm/Placement.d.ts.map +1 -0
  111. package/dist/esm/Placement.js +65 -0
  112. package/dist/esm/Placement.js.map +1 -0
  113. package/dist/esm/Plan.d.ts +440 -0
  114. package/dist/esm/Plan.d.ts.map +1 -0
  115. package/dist/esm/Plan.js +673 -0
  116. package/dist/esm/Plan.js.map +1 -0
  117. package/dist/esm/PlanDiff.d.ts +58 -0
  118. package/dist/esm/PlanDiff.d.ts.map +1 -0
  119. package/dist/esm/PlanDiff.js +159 -0
  120. package/dist/esm/PlanDiff.js.map +1 -0
  121. package/dist/esm/Planned.d.ts +121 -0
  122. package/dist/esm/Planned.d.ts.map +1 -0
  123. package/dist/esm/Planned.js +147 -0
  124. package/dist/esm/Planned.js.map +1 -0
  125. package/dist/esm/Repetition.d.ts +31 -0
  126. package/dist/esm/Repetition.d.ts.map +1 -0
  127. package/dist/esm/Repetition.js +24 -0
  128. package/dist/esm/Repetition.js.map +1 -0
  129. package/dist/esm/Scheduling.d.ts +89 -0
  130. package/dist/esm/Scheduling.d.ts.map +1 -0
  131. package/dist/esm/Scheduling.js +82 -0
  132. package/dist/esm/Scheduling.js.map +1 -0
  133. package/dist/esm/StepKey.d.ts +333 -0
  134. package/dist/esm/StepKey.d.ts.map +1 -0
  135. package/dist/esm/StepKey.js +478 -0
  136. package/dist/esm/StepKey.js.map +1 -0
  137. package/dist/esm/index.d.ts +91 -0
  138. package/dist/esm/index.d.ts.map +1 -0
  139. package/dist/esm/index.js +91 -0
  140. package/dist/esm/index.js.map +1 -0
  141. package/dist/esm/internal/ConflictAnnotation.d.ts +59 -0
  142. package/dist/esm/internal/ConflictAnnotation.d.ts.map +1 -0
  143. package/dist/esm/internal/ConflictAnnotation.js +332 -0
  144. package/dist/esm/internal/ConflictAnnotation.js.map +1 -0
  145. package/dist/esm/internal/EffectCandidates.d.ts +19 -0
  146. package/dist/esm/internal/EffectCandidates.d.ts.map +1 -0
  147. package/dist/esm/internal/EffectCandidates.js +86 -0
  148. package/dist/esm/internal/EffectCandidates.js.map +1 -0
  149. package/dist/esm/internal/JsonMirror.d.ts +34 -0
  150. package/dist/esm/internal/JsonMirror.d.ts.map +1 -0
  151. package/dist/esm/internal/JsonMirror.js +204 -0
  152. package/dist/esm/internal/JsonMirror.js.map +1 -0
  153. package/dist/esm/internal/effects.d.ts +245 -0
  154. package/dist/esm/internal/effects.d.ts.map +1 -0
  155. package/dist/esm/internal/effects.js +459 -0
  156. package/dist/esm/internal/effects.js.map +1 -0
  157. package/dist/esm/internal/node.d.ts +526 -0
  158. package/dist/esm/internal/node.d.ts.map +1 -0
  159. package/dist/esm/internal/node.js +564 -0
  160. package/dist/esm/internal/node.js.map +1 -0
  161. package/dist/esm/test/PlanFixtures.d.ts +127 -0
  162. package/dist/esm/test/PlanFixtures.d.ts.map +1 -0
  163. package/dist/esm/test/PlanFixtures.js +60 -0
  164. package/dist/esm/test/PlanFixtures.js.map +1 -0
  165. package/docs/README.md +165 -0
  166. package/docs/api.md +1475 -0
  167. package/docs/concepts/authoring-ast.md +203 -0
  168. package/docs/concepts/effects-and-conflicts.md +135 -0
  169. package/docs/concepts/plan-value.md +168 -0
  170. package/docs/concepts/step-keys.md +179 -0
  171. package/docs/guides/author-a-node-graph.md +182 -0
  172. package/docs/guides/compile-a-plan.md +146 -0
  173. package/docs/guides/declare-file-effects.md +143 -0
  174. package/docs/guides/diff-two-plans.md +101 -0
  175. package/docs/installation.md +71 -0
  176. package/docs/quickstart.md +128 -0
  177. package/docs/testing.md +73 -0
  178. package/docs/troubleshooting.md +314 -0
  179. package/package.json +254 -3
  180. package/src/CachePolicy.ts +143 -0
  181. package/src/Effects.ts +284 -0
  182. package/src/FileSet.ts +411 -0
  183. package/src/GraphBuildError.ts +158 -0
  184. package/src/KeyMaterial.ts +106 -0
  185. package/src/Node.ts +871 -0
  186. package/src/Placement.ts +99 -0
  187. package/src/Plan.ts +868 -0
  188. package/src/PlanDiff.ts +199 -0
  189. package/src/Planned.ts +208 -0
  190. package/src/Repetition.ts +33 -0
  191. package/src/Scheduling.ts +154 -0
  192. package/src/StepKey.ts +710 -0
  193. package/src/index.ts +103 -0
  194. package/src/internal/ConflictAnnotation.ts +374 -0
  195. package/src/internal/EffectCandidates.ts +89 -0
  196. package/src/internal/JsonMirror.ts +255 -0
  197. package/src/internal/effects.ts +543 -0
  198. package/src/internal/node.ts +858 -0
  199. package/src/test/PlanFixtures.ts +76 -0
@@ -0,0 +1,440 @@
1
+ /**
2
+ * The plan: a node graph with every step key computed, inert until run.
3
+ *
4
+ * The way a plan is produced is a law: **planning performs no I/O**.
5
+ * Everything in this module is therefore a pure function of declarations plus
6
+ * the injected `Crypto` service: no filesystem, no clock, no network. A node's
7
+ * key is a function of what it consumes, so an edited declaration re-keys that
8
+ * node and everything downstream of it, and nothing else. That is the entire
9
+ * invalidation mechanism. Invalidation is re-keying, which **rejects**
10
+ * Skyframe's reverse-dependency index and invalidating node visitor outright
11
+ * because content addressing subsumes them. Key invalidation never retains a
12
+ * reverse-dependency index; annotation uses only a temporary reachability cache.
13
+ *
14
+ * Growth is append-only: {@link append} adds a pre-keyed subgraph to the same
15
+ * plan and never rewrites a node already in it.
16
+ *
17
+ * @since 0.1.0
18
+ */
19
+ import type * as Crypto from "effect/Crypto";
20
+ import * as Effect from "effect/Effect";
21
+ import * as Schema from "effect/Schema";
22
+ import * as KeyMaterial from "./KeyMaterial.ts";
23
+ import * as StepKey from "./StepKey.ts";
24
+ /**
25
+ * What a node does to the world, declared. Paths only — measuring them is
26
+ * run-time work, so a digest here would break the no-I/O law.
27
+ *
28
+ * @since 0.1.0
29
+ * @category schemas
30
+ * @slop
31
+ */
32
+ export declare const NodeEffects: Schema.Struct<{
33
+ readonly reads: Schema.$Array<Schema.Union<readonly [Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
34
+ readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
35
+ readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
36
+ }>]>, Schema.TaggedStruct<"Filegroup", {
37
+ readonly name: Schema.NonEmptyString;
38
+ readonly entries: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
39
+ readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
40
+ readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
41
+ }>]>>;
42
+ }>]>>;
43
+ readonly writes: Schema.$Array<Schema.Union<readonly [Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
44
+ readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
45
+ readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
46
+ }>, Schema.TaggedStruct<"TreeArtifact", {
47
+ readonly path: Schema.NonEmptyString;
48
+ }>]>, Schema.TaggedStruct<"Filegroup", {
49
+ readonly name: Schema.NonEmptyString;
50
+ readonly entries: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
51
+ readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
52
+ readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
53
+ }>, Schema.TaggedStruct<"TreeArtifact", {
54
+ readonly path: Schema.NonEmptyString;
55
+ }>]>>;
56
+ }>]>>;
57
+ /**
58
+ * Paths the node declares it will DELETE. A removal mutates the world exactly
59
+ * as a write does, so {@link produces} folds the two together and both the
60
+ * conflict pass and the reader-after-writer pass see them as one set.
61
+ */
62
+ readonly removes: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
63
+ readonly boundaryMode: Schema.Literals<readonly ["hard", "expected"]>;
64
+ }>;
65
+ /**
66
+ * The value form of {@link NodeEffects}.
67
+ *
68
+ * @since 0.1.0
69
+ * @category models
70
+ * @slop
71
+ */
72
+ export type NodeEffects = typeof NodeEffects.Type;
73
+ /**
74
+ * The plan-time write-conflict strategies of the effect taxonomy.
75
+ *
76
+ * @since 0.1.0
77
+ * @category schemas
78
+ * @slop
79
+ */
80
+ export declare const PairStrategy: Schema.Literals<readonly ["serialize", "lane", "fail"]>;
81
+ /**
82
+ * The value form of {@link PairStrategy}.
83
+ *
84
+ * @since 0.1.0
85
+ * @category models
86
+ * @slop
87
+ */
88
+ export type PairStrategy = typeof PairStrategy.Type;
89
+ /**
90
+ * The runtime half of a conflict annotation: what the scheduler
91
+ * does when the overlap the plan predicted actually bites, or when a
92
+ * scheduled node's inputs are invalidated under it.
93
+ *
94
+ * @since 0.1.0
95
+ * @category schemas
96
+ * @slop
97
+ */
98
+ export declare const RuntimeStrategy: Schema.Literals<readonly ["delay-rebase", "stop-merge"]>;
99
+ /**
100
+ * The value form of {@link RuntimeStrategy}.
101
+ *
102
+ * @since 0.1.0
103
+ * @category models
104
+ * @slop
105
+ */
106
+ export type RuntimeStrategy = typeof RuntimeStrategy.Type;
107
+ /**
108
+ * One resolved overlap between two writers that no dependency path already
109
+ * orders. Conflict is a property of the PAIR, not of one declaration.
110
+ *
111
+ * @since 0.1.0
112
+ * @category schemas
113
+ * @slop
114
+ */
115
+ export declare const ConflictAnnotation: Schema.Struct<{
116
+ readonly with: Schema.NonEmptyString;
117
+ readonly paths: Schema.$Array<Schema.String>;
118
+ readonly strategy: Schema.Literals<readonly ["serialize", "lane", "fail"]>;
119
+ readonly runtime: Schema.Literals<readonly ["delay-rebase", "stop-merge"]>;
120
+ }>;
121
+ /**
122
+ * The value form of {@link ConflictAnnotation}.
123
+ *
124
+ * @since 0.1.0
125
+ * @category models
126
+ * @slop
127
+ */
128
+ export type ConflictAnnotation = typeof ConflictAnnotation.Type;
129
+ /**
130
+ * A keyed node of the plan.
131
+ *
132
+ * `dependsOn` is the *edge* set: material references, any ordering edge a
133
+ * `serialize` verdict added, and the reader-after-writer edges that put a
134
+ * node behind whoever produces the paths it reads. Ordering edges are
135
+ * deliberately NOT part of the key — a node ordered behind another still
136
+ * computes the same result, so re-keying it would throw away a legitimate
137
+ * cache hit.
138
+ *
139
+ * `strategy` and `runtime` are this declaration's own preferences, recorded so
140
+ * a later elaboration can resolve a pair against them without re-reading the
141
+ * flow source.
142
+ *
143
+ * @since 0.1.0
144
+ * @category schemas
145
+ * @slop
146
+ */
147
+ export declare const PlanNode: Schema.Struct<{
148
+ readonly id: Schema.NonEmptyString;
149
+ readonly kind: Schema.Literals<readonly ["step", "agent", "merge"]>;
150
+ readonly key: Schema.brand<Schema.String, "@smthrs/keys/Key">;
151
+ readonly material: Schema.Struct<{
152
+ readonly version: Schema.Literal<"flows/key-material/v2">;
153
+ readonly kind: Schema.Literals<readonly ["sealed", "compensable", "irreversible"]>;
154
+ readonly nondeterministic: Schema.optional<Schema.Literal<true>>;
155
+ readonly body: Schema.Unknown;
156
+ readonly inputs: Schema.$Array<Schema.Union<readonly [Schema.TaggedStruct<"Literal", {
157
+ readonly value: Schema.Unknown;
158
+ }>, Schema.TaggedStruct<"Ref", {
159
+ readonly from: Schema.NonEmptyString;
160
+ readonly path: Schema.$Array<Schema.String>;
161
+ }>, Schema.TaggedStruct<"Pending", {
162
+ readonly from: Schema.NonEmptyString;
163
+ }>]>>;
164
+ readonly layers: Schema.$Array<Schema.String>;
165
+ readonly capabilities: Schema.$Array<Schema.String>;
166
+ readonly effects: Schema.optional<Schema.Unknown>;
167
+ readonly placement: Schema.optional<Schema.Unknown>;
168
+ }>;
169
+ readonly effects: Schema.Struct<{
170
+ readonly reads: Schema.$Array<Schema.Union<readonly [Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
171
+ readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
172
+ readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
173
+ }>]>, Schema.TaggedStruct<"Filegroup", {
174
+ readonly name: Schema.NonEmptyString;
175
+ readonly entries: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
176
+ readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
177
+ readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
178
+ }>]>>;
179
+ }>]>>;
180
+ readonly writes: Schema.$Array<Schema.Union<readonly [Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
181
+ readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
182
+ readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
183
+ }>, Schema.TaggedStruct<"TreeArtifact", {
184
+ readonly path: Schema.NonEmptyString;
185
+ }>]>, Schema.TaggedStruct<"Filegroup", {
186
+ readonly name: Schema.NonEmptyString;
187
+ readonly entries: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
188
+ readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
189
+ readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
190
+ }>, Schema.TaggedStruct<"TreeArtifact", {
191
+ readonly path: Schema.NonEmptyString;
192
+ }>]>>;
193
+ }>]>>;
194
+ /**
195
+ * Paths the node declares it will DELETE. A removal mutates the world exactly
196
+ * as a write does, so {@link produces} folds the two together and both the
197
+ * conflict pass and the reader-after-writer pass see them as one set.
198
+ */
199
+ readonly removes: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
200
+ readonly boundaryMode: Schema.Literals<readonly ["hard", "expected"]>;
201
+ }>;
202
+ readonly dependsOn: Schema.$Array<Schema.NonEmptyString>;
203
+ readonly conflicts: Schema.$Array<Schema.Struct<{
204
+ readonly with: Schema.NonEmptyString;
205
+ readonly paths: Schema.$Array<Schema.String>;
206
+ readonly strategy: Schema.Literals<readonly ["serialize", "lane", "fail"]>;
207
+ readonly runtime: Schema.Literals<readonly ["delay-rebase", "stop-merge"]>;
208
+ }>>;
209
+ readonly strategy: Schema.Literals<readonly ["serialize", "lane", "fail"]>;
210
+ readonly runtime: Schema.Literals<readonly ["delay-rebase", "stop-merge"]>;
211
+ readonly priority: Schema.Int;
212
+ readonly generation: Schema.Int;
213
+ }>;
214
+ /**
215
+ * The value form of {@link PlanNode}.
216
+ *
217
+ * @since 0.1.0
218
+ * @category models
219
+ * @slop
220
+ */
221
+ export type PlanNode = typeof PlanNode.Type;
222
+ /**
223
+ * A plan: the whole keyed graph plus the digest an approval binds to.
224
+ *
225
+ * `nodes` follows material-dependency order within each generation. Inferred
226
+ * edges can point to later entries; schedule from the complete `dependsOn`
227
+ * graph, never by iterating the array alone.
228
+ *
229
+ * `baseDigest` is the digest at generation 0: what a human approved and what
230
+ * a `RUNNING` run pins. `digest` advances with every appended elaboration.
231
+ *
232
+ * @since 0.1.0
233
+ * @category schemas
234
+ * @slop
235
+ */
236
+ export declare const Plan: Schema.Struct<{
237
+ readonly planId: Schema.NonEmptyString;
238
+ readonly flow: Schema.NonEmptyString;
239
+ readonly generation: Schema.Int;
240
+ readonly baseDigest: Schema.brand<Schema.String, "@smthrs/keys/Key">;
241
+ readonly digest: Schema.brand<Schema.String, "@smthrs/keys/Key">;
242
+ readonly nodes: Schema.$Array<Schema.Struct<{
243
+ readonly id: Schema.NonEmptyString;
244
+ readonly kind: Schema.Literals<readonly ["step", "agent", "merge"]>;
245
+ readonly key: Schema.brand<Schema.String, "@smthrs/keys/Key">;
246
+ readonly material: Schema.Struct<{
247
+ readonly version: Schema.Literal<"flows/key-material/v2">;
248
+ readonly kind: Schema.Literals<readonly ["sealed", "compensable", "irreversible"]>;
249
+ readonly nondeterministic: Schema.optional<Schema.Literal<true>>;
250
+ readonly body: Schema.Unknown;
251
+ readonly inputs: Schema.$Array<Schema.Union<readonly [Schema.TaggedStruct<"Literal", {
252
+ readonly value: Schema.Unknown;
253
+ }>, Schema.TaggedStruct<"Ref", {
254
+ readonly from: Schema.NonEmptyString;
255
+ readonly path: Schema.$Array<Schema.String>;
256
+ }>, Schema.TaggedStruct<"Pending", {
257
+ readonly from: Schema.NonEmptyString;
258
+ }>]>>;
259
+ readonly layers: Schema.$Array<Schema.String>;
260
+ readonly capabilities: Schema.$Array<Schema.String>;
261
+ readonly effects: Schema.optional<Schema.Unknown>;
262
+ readonly placement: Schema.optional<Schema.Unknown>;
263
+ }>;
264
+ readonly effects: Schema.Struct<{
265
+ readonly reads: Schema.$Array<Schema.Union<readonly [Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
266
+ readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
267
+ readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
268
+ }>]>, Schema.TaggedStruct<"Filegroup", {
269
+ readonly name: Schema.NonEmptyString;
270
+ readonly entries: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
271
+ readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
272
+ readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
273
+ }>]>>;
274
+ }>]>>;
275
+ readonly writes: Schema.$Array<Schema.Union<readonly [Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
276
+ readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
277
+ readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
278
+ }>, Schema.TaggedStruct<"TreeArtifact", {
279
+ readonly path: Schema.NonEmptyString;
280
+ }>]>, Schema.TaggedStruct<"Filegroup", {
281
+ readonly name: Schema.NonEmptyString;
282
+ readonly entries: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
283
+ readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
284
+ readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
285
+ }>, Schema.TaggedStruct<"TreeArtifact", {
286
+ readonly path: Schema.NonEmptyString;
287
+ }>]>>;
288
+ }>]>>;
289
+ /**
290
+ * Paths the node declares it will DELETE. A removal mutates the world exactly
291
+ * as a write does, so {@link produces} folds the two together and both the
292
+ * conflict pass and the reader-after-writer pass see them as one set.
293
+ */
294
+ readonly removes: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
295
+ readonly boundaryMode: Schema.Literals<readonly ["hard", "expected"]>;
296
+ }>;
297
+ readonly dependsOn: Schema.$Array<Schema.NonEmptyString>;
298
+ readonly conflicts: Schema.$Array<Schema.Struct<{
299
+ readonly with: Schema.NonEmptyString;
300
+ readonly paths: Schema.$Array<Schema.String>;
301
+ readonly strategy: Schema.Literals<readonly ["serialize", "lane", "fail"]>;
302
+ readonly runtime: Schema.Literals<readonly ["delay-rebase", "stop-merge"]>;
303
+ }>>;
304
+ readonly strategy: Schema.Literals<readonly ["serialize", "lane", "fail"]>;
305
+ readonly runtime: Schema.Literals<readonly ["delay-rebase", "stop-merge"]>;
306
+ readonly priority: Schema.Int;
307
+ readonly generation: Schema.Int;
308
+ }>>;
309
+ }>;
310
+ /**
311
+ * The value form of {@link Plan}.
312
+ *
313
+ * @since 0.1.0
314
+ * @category models
315
+ * @slop
316
+ */
317
+ export type Plan = typeof Plan.Type;
318
+ /**
319
+ * What a planner hands {@link compile}: a node without its key.
320
+ *
321
+ * @since 0.1.0
322
+ * @category models
323
+ * @slop
324
+ */
325
+ export interface NodeDraft {
326
+ readonly id: string;
327
+ readonly material: KeyMaterial.KeyMaterial;
328
+ readonly effects: NodeEffects;
329
+ readonly kind?: PlanNode["kind"] | undefined;
330
+ readonly priority?: number | undefined;
331
+ /** This declaration's preferred plan-time verdict for a detected overlap. */
332
+ readonly conflictStrategy?: PairStrategy | undefined;
333
+ /** This declaration's preferred runtime response. */
334
+ readonly runtimeStrategy?: RuntimeStrategy | undefined;
335
+ }
336
+ declare const PlanError_base: Schema.Class<PlanError, Schema.TaggedStruct<"@smthrs/plan/PlanError", {
337
+ readonly code: Schema.Literals<readonly ["cycle", "unknown_dependency", "duplicate_node", "overlap_forbidden", "invalid_effects", "invalid_node", "invalid_plan", "graph_too_large"]>;
338
+ readonly message: Schema.String;
339
+ }>, import("effect/Cause").YieldableError>;
340
+ /**
341
+ * A graph the compiler refuses.
342
+ *
343
+ * @since 0.1.0
344
+ * @category errors
345
+ * @slop
346
+ */
347
+ export declare class PlanError extends PlanError_base {
348
+ }
349
+ /**
350
+ * Maximum number of nodes retained by one compiled plan.
351
+ *
352
+ * Effect analysis also has a yielding work budget, since a node ceiling alone
353
+ * does not bound dense conflicts to practical work.
354
+ *
355
+ * @since 1.0.0
356
+ * @category limits
357
+ * @slop
358
+ */
359
+ export declare const maximumPlanNodes = 10000;
360
+ /**
361
+ * Compiles drafts into a plan: material-dependency order, dependency-digest
362
+ * substitution, overlap annotation, and the plan digest. No I/O.
363
+ * Inferred edges extend `dependsOn` without reordering the node array.
364
+ *
365
+ * Traversal uses explicit stacks. Because the conflict and reader/writer
366
+ * passes consider a quadratic number of node pairs, plans are bounded by
367
+ * {@link maximumPlanNodes} and fail with `graph_too_large` above that limit
368
+ * or the effect-analysis work budget. Analysis yields periodically.
369
+ *
370
+ * @since 0.1.0
371
+ * @category constructors
372
+ * @slop
373
+ */
374
+ export declare const compile: (options: {
375
+ readonly planId: string;
376
+ readonly flow: string;
377
+ readonly nodes: ReadonlyArray<NodeDraft>;
378
+ }) => Effect.Effect<Plan, PlanError | StepKey.KeyMaterialError | Schema.SchemaError, Crypto.Crypto>;
379
+ /**
380
+ * Appends an elaborated subgraph to an existing plan.
381
+ *
382
+ * The plan GROWS; it is never invalidated. Nodes already in it keep their id,
383
+ * key, edges, and generation byte for byte, and the new nodes arrive pre-keyed
384
+ * against them, so a `hit` shows instantly. New nodes retain their material
385
+ * dependency order; scheduling must honor their complete `dependsOn` graph.
386
+ * Re-ordering after a reconciliation happens by re-keying *future* steps,
387
+ * never by rewriting history.
388
+ *
389
+ * @since 0.1.0
390
+ * @category constructors
391
+ * @slop
392
+ */
393
+ export declare const append: (plan: Plan, drafts: ReadonlyArray<NodeDraft>) => Effect.Effect<Plan, PlanError | StepKey.KeyMaterialError | Schema.SchemaError, Crypto.Crypto>;
394
+ /**
395
+ * Verifies an imported plan against the same key and topology rules as the
396
+ * compiler. Valid compiler-owned immutable values need no second compilation.
397
+ *
398
+ * Generation boundaries are replayed when reconstructing conflict annotations:
399
+ * an append may annotate new nodes, but cannot rewrite an earlier generation.
400
+ * Recorded material-dependency order is verified without sorting inferred edges.
401
+ * Keys and approval digests retain their existing format. The returned snapshot
402
+ * is immutable; later caller mutation cannot change the verified value.
403
+ *
404
+ * @since 1.0.0
405
+ * @category validation
406
+ */
407
+ export declare const verify: (input: unknown) => Effect.Effect<Plan, PlanError | StepKey.KeyMaterialError | Schema.SchemaError, Crypto.Crypto>;
408
+ /**
409
+ * The nodes added by the newest generation: what {@link module:PlanStore}
410
+ * appends and what the `subgraph-appended` journal record names.
411
+ *
412
+ * @since 0.1.0
413
+ * @category accessors
414
+ * @slop
415
+ */
416
+ export declare const generationNodes: (plan: Plan) => ReadonlyArray<PlanNode>;
417
+ /**
418
+ * Whether `input` is a compiler-owned immutable snapshot that already passed
419
+ * {@link verify}: such values take verify's trusted fast path and need no
420
+ * second schema validation.
421
+ *
422
+ * @since 1.0.0
423
+ * @category guards
424
+ * @slop
425
+ */
426
+ export declare const isVerified: (input: unknown) => input is Plan;
427
+ /**
428
+ * The approval digest of every generation before the newest: the digest this
429
+ * plan carried before its last append. {@link module:PlanStore}'s append
430
+ * matches it against the stored envelope, so an append proves the recorded
431
+ * plan's integrity from the already-verified prefix instead of decoding and
432
+ * re-verifying every stored row.
433
+ *
434
+ * @since 1.0.0
435
+ * @category accessors
436
+ * @slop
437
+ */
438
+ export declare const prefixDigest: (plan: Plan) => Effect.Effect<StepKey.StepKey, StepKey.KeyMaterialError | Schema.SchemaError, Crypto.Crypto>;
439
+ export {};
440
+ //# sourceMappingURL=Plan.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"Plan.d.ts","sourceRoot":"","sources":["../../src/Plan.ts"],"names":[],"mappings":"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"}