deltafold 0.2.0 → 0.2.1

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 (48) hide show
  1. package/README.md +33 -1
  2. package/dist/changelog.d.ts +10 -10
  3. package/dist/changelog.js +4 -4
  4. package/dist/changelog.js.map +1 -1
  5. package/dist/{document-BZcZo9nr.js → document-HfPyYxEd.js} +20 -20
  6. package/dist/{document-BZcZo9nr.js.map → document-HfPyYxEd.js.map} +1 -1
  7. package/dist/{document-DWHsgywm.d.ts → document-gtXeGFJR.d.ts} +41 -41
  8. package/dist/{document-DWHsgywm.d.ts.map → document-gtXeGFJR.d.ts.map} +1 -1
  9. package/dist/html.d.ts +2 -2
  10. package/dist/html.js +2 -2
  11. package/dist/html.js.map +1 -1
  12. package/dist/index.d.ts +437 -105
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +750 -273
  15. package/dist/index.js.map +1 -1
  16. package/dist/markdown.d.ts +2 -2
  17. package/dist/markdown.js +2 -2
  18. package/dist/markdown.js.map +1 -1
  19. package/dist/{mdast-DiRsYwPU.js → mdast-Oqkh0Gs1.js} +2 -2
  20. package/dist/{mdast-DiRsYwPU.js.map → mdast-Oqkh0Gs1.js.map} +1 -1
  21. package/dist/{package-BfBYnaCz.d.ts → package-CA5R57IC.d.ts} +117 -112
  22. package/dist/{package-BfBYnaCz.d.ts.map → package-CA5R57IC.d.ts.map} +1 -1
  23. package/package.json +3 -3
  24. package/src/features/documents/changelog.ts +8 -8
  25. package/src/features/documents/document.ts +39 -39
  26. package/src/features/documents/index.ts +2 -2
  27. package/src/features/execution/executor.ts +485 -313
  28. package/src/features/execution/handler.ts +30 -30
  29. package/src/features/execution/interaction.ts +11 -11
  30. package/src/features/execution/observation.ts +489 -0
  31. package/src/features/execution/observer.ts +395 -0
  32. package/src/features/package.ts +3 -3
  33. package/src/features/planning/history.ts +10 -10
  34. package/src/features/planning/identifiers.ts +7 -4
  35. package/src/features/planning/resolve-error.ts +13 -13
  36. package/src/features/planning/resolve.ts +11 -4
  37. package/src/features/planning/validate.ts +1 -1
  38. package/src/foundation/action.ts +17 -17
  39. package/src/foundation/change.ts +10 -10
  40. package/src/foundation/instruction.ts +5 -5
  41. package/src/foundation/migration.ts +12 -12
  42. package/src/foundation/plan.ts +23 -18
  43. package/src/foundation/rule.ts +6 -6
  44. package/src/foundation/shortcut.ts +6 -6
  45. package/src/foundation/version.ts +6 -6
  46. package/src/index.ts +14 -12
  47. package/src/renderers/html.ts +1 -1
  48. package/src/renderers/markdown.ts +1 -1
@@ -0,0 +1,395 @@
1
+ import { type Cause, Effect, Exit, Predicate } from "effect";
2
+
3
+ import type * as Plan from "../../foundation/plan.ts";
4
+ import type { InterruptReason, Outcome, Report } from "./executor.ts";
5
+ import type { Performer, Phase } from "./handler.ts";
6
+
7
+ const TypeId = "~deltafold/Observer";
8
+
9
+ /**
10
+ * The run that emitted an event.
11
+ *
12
+ * @since 0.2.1
13
+ */
14
+ export type Run = {
15
+ /** The `runId` passed to the executor, if any. Shared observers use it to tell runs apart. */
16
+ readonly id: string | undefined;
17
+ readonly mode: Report["mode"];
18
+ readonly from: string;
19
+ readonly to: string;
20
+ readonly route: string;
21
+ };
22
+
23
+ /**
24
+ * Counters at the moment an event was emitted. Counters never decrease during a run.
25
+ *
26
+ * @since 0.2.1
27
+ */
28
+ export type Progress = {
29
+ /** Steps with actions and prose-only steps. Omitted steps are not counted. */
30
+ readonly steps: { readonly total: number; readonly finished: number };
31
+ readonly actions: {
32
+ readonly total: number;
33
+ /** Occurrences whose prepare or apply phase has started and that have not settled. */
34
+ readonly running: number;
35
+ readonly finished: number;
36
+ };
37
+ };
38
+
39
+ /**
40
+ * One step of the route, as observers see it.
41
+ *
42
+ * - `execute`: the step has actions after optimization.
43
+ * - `prose`: the step has instruction prose but no actions. The executor runs nothing
44
+ * for it and does not wait at it.
45
+ * - `omitted`: a noop, or a step whose actions rules removed or moved into another step.
46
+ *
47
+ * @since 0.2.1
48
+ */
49
+ export type StepInfo = {
50
+ /** The plan step's `id`. */
51
+ readonly id: string;
52
+ /** Position in `plan.steps`, including omitted steps. */
53
+ readonly index: number;
54
+ readonly migration: string;
55
+ readonly direction: Plan.Direction;
56
+ readonly from: string;
57
+ readonly to: string;
58
+ /** Occurrence identifiers of the step, in plan order. */
59
+ readonly occurrences: ReadonlyArray<string>;
60
+ /**
61
+ * Other steps whose declared actions this step's replacements stand for. Running this
62
+ * step performs work that those steps declared.
63
+ */
64
+ readonly absorbs: ReadonlyArray<string>;
65
+ } & (
66
+ | { readonly kind: "execute" | "prose" }
67
+ | { readonly kind: "omitted"; readonly reason: "noop" | "all-actions-removed" }
68
+ );
69
+
70
+ /**
71
+ * One occurrence of the plan, as observers see it.
72
+ *
73
+ * @since 0.2.1
74
+ */
75
+ export type ActionInfo = {
76
+ readonly occurrence: string;
77
+ readonly action: string;
78
+ readonly kind: string;
79
+ readonly description: string;
80
+ readonly migration: string;
81
+ readonly direction: Plan.Direction;
82
+ /** The step that runs the occurrence. */
83
+ readonly step: string;
84
+ readonly origin:
85
+ | { readonly _tag: "Declared" }
86
+ | {
87
+ readonly _tag: "Replacement";
88
+ readonly rule: string;
89
+ /** Identifiers of the replaced occurrences, in order. */
90
+ readonly replaces: ReadonlyArray<string>;
91
+ };
92
+ /** Steps that declared the actions behind this occurrence, in plan order. */
93
+ readonly sources: ReadonlyArray<string>;
94
+ };
95
+
96
+ /**
97
+ * An outcome as observers see it. Each variant lists its fields explicitly, so a field
98
+ * added to the report's outcome never reaches observers unreviewed. A failure keeps only
99
+ * the error's string `_tag`; the full error is in the execution's report.
100
+ *
101
+ * @since 0.2.1
102
+ */
103
+ export type OutcomeSummary =
104
+ | { readonly _tag: "Completed"; readonly performer: "automated" }
105
+ | {
106
+ readonly _tag: "Completed";
107
+ readonly performer: "manual";
108
+ readonly confirmation: "asserted" | "verified";
109
+ }
110
+ | { readonly _tag: "Skipped"; readonly reason: string }
111
+ | { readonly _tag: "Declined" }
112
+ | {
113
+ readonly _tag: "Failed";
114
+ readonly phase: Phase;
115
+ readonly errorTag: string | undefined;
116
+ }
117
+ | {
118
+ readonly _tag: "Interrupted";
119
+ readonly phase: Phase;
120
+ readonly reason: InterruptReason;
121
+ readonly settled: boolean;
122
+ }
123
+ | { readonly _tag: "Unattempted" }
124
+ | {
125
+ readonly _tag: "WouldExecute";
126
+ readonly evaluated: boolean;
127
+ readonly performer: Performer;
128
+ }
129
+ | { readonly _tag: "WouldSkip"; readonly reason: string }
130
+ | {
131
+ readonly _tag: "Undetermined";
132
+ readonly reason: string;
133
+ readonly performer: Performer;
134
+ }
135
+ | { readonly _tag: "PreparationFailed"; readonly errorTag: string | undefined };
136
+
137
+ /**
138
+ * Occurrences by outcome tag. `unsettled` counts interrupted occurrences that may still be
139
+ * running.
140
+ *
141
+ * @since 0.2.1
142
+ */
143
+ export type Counts = { readonly [K in Outcome["_tag"]]: number } & {
144
+ readonly unsettled: number;
145
+ };
146
+
147
+ type Base = {
148
+ readonly run: Run;
149
+ /** Position of the event in its run, starting at 0. */
150
+ readonly seq: number;
151
+ /** Milliseconds since the Unix epoch, from Effect's `Clock`. */
152
+ readonly timestamp: number;
153
+ readonly progress: Progress;
154
+ };
155
+
156
+ /**
157
+ * The run is starting: every action has a handler, and manual work has an interaction to
158
+ * ask with. A run that fails either check emits no events. Lists every step of the route,
159
+ * including omitted ones.
160
+ *
161
+ * @since 0.2.1
162
+ */
163
+ export type RunStarted = Base & {
164
+ readonly _tag: "RunStarted";
165
+ readonly steps: ReadonlyArray<StepInfo>;
166
+ };
167
+
168
+ /** @since 0.2.1 */
169
+ export type StepStarted = Base & { readonly _tag: "StepStarted"; readonly step: StepInfo };
170
+
171
+ /**
172
+ * A phase of an occurrence started: its prepare or apply phase, the confirmation of
173
+ * manual work, or its verification. `prepare` appears only for handlers that have a
174
+ * prepare phase. `confirmation` means the run is waiting for a person. An occurrence
175
+ * emits this once per phase that starts.
176
+ *
177
+ * @since 0.2.1
178
+ */
179
+ export type ActionPhaseStarted = Base & {
180
+ readonly _tag: "ActionPhaseStarted";
181
+ readonly action: ActionInfo;
182
+ readonly phase: Phase;
183
+ };
184
+
185
+ /**
186
+ * An occurrence has its final outcome. Emitted once for each occurrence whose outcome is
187
+ * known, and as `Unattempted` for an occurrence that started but stopped before applying
188
+ * or asking. It arrives after the occurrence's scope has closed, except when an
189
+ * interrupted Promise has not settled: then the scope stays open until it does, the
190
+ * reported outcome is already final, and a later cleanup failure is only logged. Dry-run
191
+ * outcomes that need no prepare phase arrive without a start.
192
+ *
193
+ * @since 0.2.1
194
+ */
195
+ export type ActionSettled = Base & {
196
+ readonly _tag: "ActionSettled";
197
+ readonly action: ActionInfo;
198
+ readonly outcome: OutcomeSummary;
199
+ };
200
+
201
+ /**
202
+ * A started step ended. `counts` covers the step's occurrences.
203
+ *
204
+ * @since 0.2.1
205
+ */
206
+ export type StepSettled = Base & {
207
+ readonly _tag: "StepSettled";
208
+ readonly step: StepInfo;
209
+ readonly counts: Counts;
210
+ };
211
+
212
+ /**
213
+ * The run ended. `status` and `counts` match the execution's report. When the fiber of
214
+ * `Executor.effect` is interrupted, there is no report: `report` is `false`, the status is
215
+ * `"interrupted"`, and running occurrences count as unsettled interruptions. If the
216
+ * interruption cuts short the delivery of `RunFinished`, the observers that had not yet
217
+ * received it get the report-less one with the same `seq`, so each observer receives
218
+ * exactly one.
219
+ *
220
+ * @since 0.2.1
221
+ */
222
+ export type RunFinished = Base & {
223
+ readonly _tag: "RunFinished";
224
+ readonly status: Report["status"];
225
+ readonly counts: Counts;
226
+ readonly report: boolean;
227
+ };
228
+
229
+ /**
230
+ * What an observer receives. A run emits `RunStarted`; then, for each step that is not
231
+ * omitted, `StepStarted`, an `ActionPhaseStarted` for each phase that starts, an
232
+ * `ActionSettled` for each occurrence, and `StepSettled`; and finally `RunFinished`. Action
233
+ * events of parallel branches interleave.
234
+ *
235
+ * Events carry identifiers and plain data, never payloads, errors, or causes. Action
236
+ * descriptions are included, so they must not contain secrets.
237
+ *
238
+ * @since 0.2.1
239
+ */
240
+ export type Event =
241
+ | RunStarted
242
+ | StepStarted
243
+ | ActionPhaseStarted
244
+ | ActionSettled
245
+ | StepSettled
246
+ | RunFinished;
247
+
248
+ /**
249
+ * An observer that failed, or that was abandoned after cancellation or a timeout because
250
+ * it did not finish within the settlement grace period. An abandoned callback is
251
+ * interrupted but not awaited, so one that cannot be interrupted may keep running. The
252
+ * cause can hold arbitrary values, so do not serialize it as a whole.
253
+ *
254
+ * @since 0.2.1
255
+ */
256
+ export type ObservationFailure = {
257
+ /** Position of the observer in the `observers` array. */
258
+ readonly observer: number;
259
+ readonly event: Event["_tag"];
260
+ readonly seq: number;
261
+ readonly reason: "failed" | "abandoned";
262
+ readonly cause: Cause.Cause<unknown>;
263
+ };
264
+
265
+ /**
266
+ * Receives the events of a run. Pass observers to the executor's `observers` option. `R`
267
+ * is the Effect services an observer requires, which become requirements of the execution.
268
+ *
269
+ * The executor delivers one event at a time, to each observer in array order, and waits
270
+ * for each delivery before it continues, so every observer sees the same order. After
271
+ * cancellation or a timeout, each delivery waits at most `settleTimeout` and is then
272
+ * abandoned. A failed or abandoned delivery is listed in the report's `observation` and
273
+ * never changes an outcome. Observers only receive events: they cannot answer a manual
274
+ * confirmation.
275
+ *
276
+ * @since 0.2.1
277
+ */
278
+ export type Observer<out R = never> = {
279
+ readonly [TypeId]: typeof TypeId;
280
+ /** Delivers one event and captures how the delivery ended. It never fails. */
281
+ readonly notify: (event: Event) => Effect.Effect<Exit.Exit<unknown, unknown>, never, R>;
282
+ };
283
+
284
+ /**
285
+ * Any observer.
286
+ *
287
+ * @since 0.2.1
288
+ */
289
+ export type Any = Observer<any>;
290
+
291
+ /**
292
+ * The Effect services of an observer or a union of observers.
293
+ *
294
+ * @since 0.2.1
295
+ */
296
+ export type Services<O> = O extends Observer<infer R> ? R : never;
297
+
298
+ /** @since 0.2.1 */
299
+ export const isObserver = (value: unknown): value is Any => Predicate.hasProperty(value, TypeId);
300
+
301
+ class AsyncSyncObserver extends Error {
302
+ override readonly name = "AsyncSyncObserver";
303
+ override readonly message =
304
+ "An Observer.sync callback returned a Promise. Use Observer.promise for asynchronous callbacks.";
305
+ }
306
+
307
+ /**
308
+ * Observes with a synchronous callback. A thrown value is recorded as an observation
309
+ * failure.
310
+ *
311
+ * @example
312
+ * ```ts
313
+ * Observer.sync((event) => {
314
+ * if (event._tag === "ActionSettled") console.error(event.action.occurrence, event.outcome._tag);
315
+ * });
316
+ * ```
317
+ *
318
+ * @since 0.2.1
319
+ */
320
+ export const sync = (callback: (event: Event) => void): Observer => ({
321
+ [TypeId]: TypeId,
322
+ notify: (event) =>
323
+ Effect.sync((): Exit.Exit<void, unknown> => {
324
+ try {
325
+ const result: unknown = callback(event);
326
+ if (!Predicate.isPromiseLike(result)) return Exit.void;
327
+ // Keep a rejection from going unhandled; the misuse is reported instead.
328
+ Promise.resolve(result).catch(() => undefined);
329
+
330
+ return Exit.fail(new AsyncSyncObserver());
331
+ } catch (cause) {
332
+ // The thrown value is the failure, exactly as the observer threw it.
333
+ return Exit.fail(cause);
334
+ }
335
+ }),
336
+ });
337
+
338
+ /**
339
+ * Observes with a Promise callback. The executor waits for the Promise. The `signal`
340
+ * aborts when the executor stops waiting: after cancellation or a timeout, once the
341
+ * settlement grace period has passed, or when the execution is interrupted. A services
342
+ * layer that `Executor.runPromise` built stays open until an abandoned Promise settles.
343
+ *
344
+ * @since 0.2.1
345
+ */
346
+ export const promise = (
347
+ callback: (event: Event, context: { readonly signal: AbortSignal }) => PromiseLike<unknown>,
348
+ ): Observer => ({
349
+ [TypeId]: TypeId,
350
+ notify: (event) =>
351
+ Effect.suspend(() => {
352
+ let pending: Promise<unknown> | undefined;
353
+
354
+ // Declaring `signal` makes Effect.promise allocate an AbortController. The rejection
355
+ // is the failure, exactly as the observer rejected.
356
+ return Effect.promise((signal): Promise<Exit.Exit<unknown, unknown>> => {
357
+ const settles = new Promise<unknown>((resolve) =>
358
+ resolve(callback(event, { signal })),
359
+ ).then(
360
+ () => Exit.void,
361
+ (cause: unknown) => Exit.fail(cause),
362
+ );
363
+ pending = settles;
364
+
365
+ return settles;
366
+ }).pipe(
367
+ // The executor abandons a delivery by interrupting it without waiting, and keeps
368
+ // the run's services open until the interruption ends. Ending it only once the
369
+ // Promise settles keeps them open for the callback's remaining work.
370
+ Effect.onInterrupt(() =>
371
+ pending === undefined
372
+ ? Effect.void
373
+ : Effect.promise(() => pending ?? Promise.resolve()),
374
+ ),
375
+ );
376
+ }),
377
+ });
378
+
379
+ /**
380
+ * Observes with an Effect. Its services become requirements of the execution. Its
381
+ * failures are recorded as observation failures and never fail the execution.
382
+ *
383
+ * @example
384
+ * ```ts
385
+ * Observer.effect((event) => Effect.logDebug(event._tag));
386
+ * ```
387
+ *
388
+ * @since 0.2.1
389
+ */
390
+ export const effect = <E = never, R = never>(
391
+ callback: (event: Event) => Effect.Effect<unknown, E, R>,
392
+ ): Observer<R> => ({
393
+ [TypeId]: TypeId,
394
+ notify: (event) => Effect.exit(Effect.suspend(() => callback(event))),
395
+ });
@@ -3,7 +3,7 @@ import { Predicate } from "effect";
3
3
  import type * as Action from "../foundation/action.ts";
4
4
  import type { History } from "./planning/history.ts";
5
5
 
6
- /** @since @next */
6
+ /** @since 0.0.1 */
7
7
  export type Package<A extends Action.Any = Action.Any> = {
8
8
  readonly _tag: "Package";
9
9
  /** The name of the modeled package, for example `@acme/widgets`. */
@@ -20,13 +20,13 @@ export type Package<A extends Action.Any = Action.Any> = {
20
20
  * export const widgets = Package.make("@acme/widgets", { history });
21
21
  * ```
22
22
  *
23
- * @since @next
23
+ * @since 0.0.1
24
24
  */
25
25
  export const make = <A extends Action.Any>(
26
26
  name: string,
27
27
  options: { readonly history: History<A> },
28
28
  ): Package<A> => ({ _tag: "Package", name, history: options.history });
29
29
 
30
- /** @since @next */
30
+ /** @since 0.0.1 */
31
31
  export const isPackage = (value: unknown): value is Package<any> =>
32
32
  Predicate.isTagged(value, "Package");
@@ -23,7 +23,7 @@ import { validate as validateDeclarations, type Issue } from "./validate.ts";
23
23
  export * from "./resolve-error.ts";
24
24
  export type { Destination, Issue, ResolveOptions, RoutePolicy };
25
25
 
26
- /** @since @next */
26
+ /** @since 0.0.1 */
27
27
  export type History<A extends Action.Any = Action.Any, C extends Change.Any = Change.Any> = {
28
28
  readonly _tag: "History";
29
29
  readonly versions: ReadonlyArray<Version>;
@@ -39,21 +39,21 @@ export type History<A extends Action.Any = Action.Any, C extends Change.Any = Ch
39
39
  /**
40
40
  * Any history.
41
41
  *
42
- * @since @next
42
+ * @since 0.0.1
43
43
  */
44
44
  export type Any = History<any>;
45
45
 
46
46
  /**
47
47
  * Every action instance that a plan resolved from the history can contain.
48
48
  *
49
- * @since @next
49
+ * @since 0.0.1
50
50
  */
51
51
  export type ActionsOf<H> = H extends History<infer A> ? A : never;
52
52
 
53
53
  /**
54
54
  * Every change that a plan resolved from the history can list in `changes`.
55
55
  *
56
- * @since @next
56
+ * @since 0.0.1
57
57
  */
58
58
  export type ChangesOf<H> = H extends History<any, infer C> ? C : never;
59
59
 
@@ -64,7 +64,7 @@ export type ChangesOf<H> = H extends History<any, infer C> ? C : never;
64
64
  * `make` does not throw. Use `History.validate` to list declaration issues;
65
65
  * resolution fails with `InvalidHistory` when there are any.
66
66
  *
67
- * @since @next
67
+ * @since 0.0.1
68
68
  */
69
69
  export const make = <
70
70
  const M extends ReadonlyArray<Migration.Any>,
@@ -86,7 +86,7 @@ export const make = <
86
86
  shortcuts: declarations.shortcuts ?? [],
87
87
  });
88
88
 
89
- /** @since @next */
89
+ /** @since 0.0.1 */
90
90
  export const isHistory = (value: unknown): value is Any => Predicate.isTagged(value, "History");
91
91
 
92
92
  const contexts = new WeakMap<
@@ -107,7 +107,7 @@ const prepare = (history: Any) => {
107
107
  /**
108
108
  * Lists declaration issues in a deterministic order. An empty list means valid.
109
109
  *
110
- * @since @next
110
+ * @since 0.0.1
111
111
  */
112
112
  export const validate = (history: Any): ReadonlyArray<Issue> => prepare(history).issues;
113
113
 
@@ -132,7 +132,7 @@ const valid = (history: Any): Result.Result<Context, InvalidHistory> => {
132
132
  * if (Result.isSuccess(result)) console.log(result.success.route.id);
133
133
  * ```
134
134
  *
135
- * @since @next
135
+ * @since 0.0.1
136
136
  */
137
137
  export const resolve = <A extends Action.Any, C extends Change.Any>(
138
138
  history: History<A, C>,
@@ -149,7 +149,7 @@ export const resolve = <A extends Action.Any, C extends Change.Any>(
149
149
  /**
150
150
  * Destinations reachable by upgrade from a version, with their candidate routes.
151
151
  *
152
- * @since @next
152
+ * @since 0.0.1
153
153
  */
154
154
  export const upgrades = (
155
155
  history: Any,
@@ -160,7 +160,7 @@ export const upgrades = (
160
160
  /**
161
161
  * Destinations reachable by downgrade from a version, with their candidate routes.
162
162
  *
163
- * @since @next
163
+ * @since 0.0.1
164
164
  */
165
165
  export const downgrades = (
166
166
  history: Any,
@@ -11,15 +11,18 @@ const occurrencePart = (id: string) => escape(id, /[\\/()+]/g);
11
11
 
12
12
  const routePart = (id: string) => escape(id, /[\\>[\]]/g);
13
13
 
14
+ /** A plan step: `<migration>` forward, `<migration>/revert` in reverse. */
15
+ export const stepId = (migration: Migration.Any, direction: Direction): string =>
16
+ direction === "forward"
17
+ ? occurrencePart(migration.id)
18
+ : `${occurrencePart(migration.id)}/revert`;
19
+
14
20
  /** `<migration>/<action>` forward, `<migration>/revert/<action>` in reverse. */
15
21
  export const declaredOccurrenceId = (
16
22
  migration: Migration.Any,
17
23
  direction: Direction,
18
24
  action: Action.Any,
19
- ): string =>
20
- direction === "forward"
21
- ? `${occurrencePart(migration.id)}/${occurrencePart(action.id)}`
22
- : `${occurrencePart(migration.id)}/revert/${occurrencePart(action.id)}`;
25
+ ): string => `${stepId(migration, direction)}/${occurrencePart(action.id)}`;
23
26
 
24
27
  /**
25
28
  * `<rule>(<replaced>+<replaced>)/<action>`. Replaced identifiers are complete occurrence
@@ -6,7 +6,7 @@ import type { Issue } from "./validate.ts";
6
6
  /**
7
7
  * A candidate route, summarized for diagnostics and explicit selection.
8
8
  *
9
- * @since @next
9
+ * @since 0.0.1
10
10
  */
11
11
  export type RouteSummary = {
12
12
  /** Pass this as the `route` option to select the route. */
@@ -23,7 +23,7 @@ export type RouteSummary = {
23
23
  /**
24
24
  * An ancestry hop with no declared route in the requested direction.
25
25
  *
26
- * @since @next
26
+ * @since 0.0.1
27
27
  */
28
28
  export type Blocker = {
29
29
  readonly from: string;
@@ -34,7 +34,7 @@ export type Blocker = {
34
34
  /**
35
35
  * The history's declarations are invalid. Resolution needs a valid history.
36
36
  *
37
- * @since @next
37
+ * @since 0.0.1
38
38
  */
39
39
  export class InvalidHistory extends Data.TaggedError("InvalidHistory")<{
40
40
  readonly issues: ReadonlyArray<Issue>;
@@ -46,7 +46,7 @@ export class InvalidHistory extends Data.TaggedError("InvalidHistory")<{
46
46
  }
47
47
  }
48
48
 
49
- /** @since @next */
49
+ /** @since 0.0.1 */
50
50
  export class UnknownVersion extends Data.TaggedError("UnknownVersion")<{
51
51
  readonly version: string;
52
52
  readonly known: ReadonlyArray<string>;
@@ -60,7 +60,7 @@ export class UnknownVersion extends Data.TaggedError("UnknownVersion")<{
60
60
  * No declared route connects the versions. This never means that no work is needed:
61
61
  * declare `Migration.noop` for a supported zero-work transition.
62
62
  *
63
- * @since @next
63
+ * @since 0.0.1
64
64
  */
65
65
  export class UnsupportedRoute extends Data.TaggedError("UnsupportedRoute")<{
66
66
  readonly from: string;
@@ -83,7 +83,7 @@ export class UnsupportedRoute extends Data.TaggedError("UnsupportedRoute")<{
83
83
  /**
84
84
  * Several routes connect the versions and no selection or policy chose one.
85
85
  *
86
- * @since @next
86
+ * @since 0.0.1
87
87
  */
88
88
  export class AmbiguousRoute extends Data.TaggedError("AmbiguousRoute")<{
89
89
  readonly from: string;
@@ -103,7 +103,7 @@ export class AmbiguousRoute extends Data.TaggedError("AmbiguousRoute")<{
103
103
  /**
104
104
  * The `route` option names no candidate route.
105
105
  *
106
- * @since @next
106
+ * @since 0.0.1
107
107
  */
108
108
  export class UnknownRoute extends Data.TaggedError("UnknownRoute")<{
109
109
  readonly route: string;
@@ -119,7 +119,7 @@ export class UnknownRoute extends Data.TaggedError("UnknownRoute")<{
119
119
  /**
120
120
  * Rules rewrite a sequence back into itself.
121
121
  *
122
- * @since @next
122
+ * @since 0.0.1
123
123
  */
124
124
  export class RewriteCycle extends Data.TaggedError("RewriteCycle")<{
125
125
  readonly route: string;
@@ -134,7 +134,7 @@ export class RewriteCycle extends Data.TaggedError("RewriteCycle")<{
134
134
  /**
135
135
  * Rules can produce different results depending on which applies first.
136
136
  *
137
- * @since @next
137
+ * @since 0.0.1
138
138
  */
139
139
  export class ConflictingRewrites extends Data.TaggedError("ConflictingRewrites")<{
140
140
  readonly route: string;
@@ -152,7 +152,7 @@ export class ConflictingRewrites extends Data.TaggedError("ConflictingRewrites")
152
152
  * Optimization explored too many states or chained too many rule applications, for
153
153
  * example because a rule keeps growing the sequence.
154
154
  *
155
- * @since @next
155
+ * @since 0.0.1
156
156
  */
157
157
  export class RewriteLimitExceeded extends Data.TaggedError("RewriteLimitExceeded")<{
158
158
  readonly route: string;
@@ -169,7 +169,7 @@ export class RewriteLimitExceeded extends Data.TaggedError("RewriteLimitExceeded
169
169
  /**
170
170
  * More candidate routes exist than the resolver enumerates.
171
171
  *
172
- * @since @next
172
+ * @since 0.0.1
173
173
  */
174
174
  export class TooManyRoutes extends Data.TaggedError("TooManyRoutes")<{
175
175
  readonly from: string;
@@ -181,7 +181,7 @@ export class TooManyRoutes extends Data.TaggedError("TooManyRoutes")<{
181
181
  }
182
182
  }
183
183
 
184
- /** @since @next */
184
+ /** @since 0.0.1 */
185
185
  export type RewriteError = RewriteCycle | ConflictingRewrites | RewriteLimitExceeded;
186
186
 
187
187
  /**
@@ -189,7 +189,7 @@ export type RewriteError = RewriteCycle | ConflictingRewrites | RewriteLimitExce
189
189
  * closest ones by release ancestry, and blockers. `AmbiguousRoute` lists the candidate
190
190
  * routes: pass one as `route`, or choose a `policy`.
191
191
  *
192
- * @since @next
192
+ * @since 0.0.1
193
193
  */
194
194
  export type ResolveError =
195
195
  | InvalidHistory
@@ -15,7 +15,13 @@ import type {
15
15
  import type * as Shortcut from "../../foundation/shortcut.ts";
16
16
  import type { Version } from "../../foundation/version.ts";
17
17
  import { resolveGuide } from "./guide.ts";
18
- import { declaredOccurrenceId, routeHop, routeShortcut, routeStart } from "./identifiers.ts";
18
+ import {
19
+ declaredOccurrenceId,
20
+ routeHop,
21
+ routeShortcut,
22
+ routeStart,
23
+ stepId,
24
+ } from "./identifiers.ts";
19
25
  import {
20
26
  AmbiguousRoute,
21
27
  ConflictingRewrites,
@@ -43,7 +49,7 @@ import { actionsOfSteps, hasProse, stepsOf, type Declarations } from "./validate
43
49
  * `cost`; a shortcut costs its declared `cost` or the total of its migrations.
44
50
  * - `prefer-shortcuts`: a route through a shortcut over the route the shortcut replaces.
45
51
  *
46
- * @since @next
52
+ * @since 0.0.1
47
53
  */
48
54
  export type RoutePolicy =
49
55
  | "fewest-actions"
@@ -344,6 +350,7 @@ const buildPlan = (
344
350
 
345
351
  return {
346
352
  _tag: "Step",
353
+ id: stepId(member.migration, member.direction),
347
354
  migration: member.migration,
348
355
  direction: member.direction,
349
356
  from: stepFrom,
@@ -570,7 +577,7 @@ const unsupported = (context: Context, from: string, to: string, direction: Requ
570
577
  });
571
578
  };
572
579
 
573
- /** @since @next */
580
+ /** @since 0.0.1 */
574
581
  export type ResolveOptions = {
575
582
  readonly from: Version | string;
576
583
  readonly to: Version | string;
@@ -658,7 +665,7 @@ export const resolve = (
658
665
  /**
659
666
  * A reachable destination and the identifiers of its candidate routes.
660
667
  *
661
- * @since @next
668
+ * @since 0.0.1
662
669
  */
663
670
  export type Destination = {
664
671
  readonly version: Version;
@@ -11,7 +11,7 @@ import { stepKey } from "./rewrite.ts";
11
11
  /**
12
12
  * A problem in a history's declarations.
13
13
  *
14
- * @since @next
14
+ * @since 0.0.1
15
15
  */
16
16
  export type Issue = {
17
17
  readonly _tag: