deltafold 0.1.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 (50) hide show
  1. package/README.md +96 -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 +681 -102
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +908 -235
  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 +631 -272
  28. package/src/features/execution/handler.ts +205 -84
  29. package/src/features/execution/interaction.ts +174 -0
  30. package/src/features/execution/observation.ts +489 -0
  31. package/src/features/execution/observer.ts +395 -0
  32. package/src/features/execution/promise-callback.ts +76 -0
  33. package/src/features/package.ts +3 -3
  34. package/src/features/planning/history.ts +10 -10
  35. package/src/features/planning/identifiers.ts +7 -4
  36. package/src/features/planning/resolve-error.ts +13 -13
  37. package/src/features/planning/resolve.ts +11 -4
  38. package/src/features/planning/rewrite.ts +1 -1
  39. package/src/features/planning/validate.ts +1 -1
  40. package/src/foundation/action.ts +17 -17
  41. package/src/foundation/change.ts +10 -10
  42. package/src/foundation/instruction.ts +5 -5
  43. package/src/foundation/migration.ts +12 -12
  44. package/src/foundation/plan.ts +23 -18
  45. package/src/foundation/rule.ts +6 -6
  46. package/src/foundation/shortcut.ts +6 -6
  47. package/src/foundation/version.ts +6 -6
  48. package/src/index.ts +15 -11
  49. package/src/renderers/html.ts +1 -1
  50. package/src/renderers/markdown.ts +1 -1
package/dist/index.d.ts CHANGED
@@ -1,17 +1,56 @@
1
- import { _ as Any$1, a as Occurrence, c as shortcut_d_exports, g as change_d_exports, i as Coverage, l as rule_d_exports, n as package_d_exports, o as Plan, p as version_d_exports, r as history_d_exports, s as plan_d_exports, u as migration_d_exports, v as action_d_exports } from "./package-BfBYnaCz.js";
2
- import { Cause, Context, Duration, Effect, Layer, Schema, Scope } from "effect";
1
+ import { _ as change_d_exports, a as Direction, c as plan_d_exports, d as migration_d_exports, i as Coverage, l as shortcut_d_exports, m as version_d_exports, n as package_d_exports, o as Occurrence, r as history_d_exports, s as Plan, u as rule_d_exports, v as Any$3, y as action_d_exports } from "./package-CA5R57IC.js";
2
+ import { Cause, Context, Duration, Effect, Exit, Layer, Schema, Scope } from "effect";
3
3
  /** The union of an object type's property values. */
4
4
  type ValueOf<T> = T[keyof T];
5
+ /** Named Effect services that Promise callbacks declare. */
6
+ type ServiceMap$1 = {
7
+ readonly [name: string | symbol]: Context.Key<any, any>;
8
+ };
9
+ type NoServices$1 = Record<never, never>;
10
+ /** The `AbortSignal` aborted on interruption, and the declared services, resolved. */
11
+ type PromiseContext$1<S extends ServiceMap$1 = NoServices$1> = {
12
+ readonly signal: AbortSignal;
13
+ readonly services: { readonly [K in keyof S]: S[K]["Service"]; };
14
+ };
15
+ type ServiceIds$1<S extends ServiceMap$1> = ValueOf<{ [K in keyof S]: S[K] extends Context.Key<infer I, any> ? I : never; }>;
16
+ /** Recognizes a declared rejection: a schema, or a type guard. */
17
+ type ErrorGuard$1 = Schema.Top | ((cause: unknown) => cause is any);
18
+ type GuardedError$1<G> = G extends Schema.Top ? G["Type"] : G extends ((cause: unknown) => cause is infer E) ? E : never;
5
19
  declare namespace handler_d_exports {
6
- export { ActionId, Any, EffectApplyContext, EffectPhases, Error, ErrorGuard, Handler, Phase, Preparation, Prepared, PromiseApplyContext, PromiseContext, PromiseOptions$1 as PromiseOptions, PromisePhases, ServiceMap, Services, Skip, Step, UnexpectedHandlerError, effect$1 as effect, isHandler, prepared, promise, skip };
20
+ export { ActionId, Any$2 as Any, EffectApplyContext, EffectPhases, Error$1 as Error, ErrorGuard, Handler, ManualEffectOptions, ManualOptions, Performer, Phase, Preparation, Prepared, PromiseApplyContext, PromiseContext, PromiseOptions$2 as PromiseOptions, PromisePhases, ServiceMap, Services$2 as Services, Skip, Step, UnexpectedHandlerError, VerificationFailed, effect$3 as effect, isHandler, manual, manualEffect, prepared, promise$2 as promise, skip };
7
21
  }
22
+ type NoServices = NoServices$1;
23
+ type ServiceIds<S extends ServiceMap> = ServiceIds$1<S>;
24
+ type GuardedError<G> = GuardedError$1<G>;
25
+ /**
26
+ * Where a handler failure or interruption happened: the read-only prepare phase, or the
27
+ * apply phase that changes state. A manual handler has neither: the executor waits for a
28
+ * person in `confirmation`, then runs the handler's optional check in `verification`.
29
+ *
30
+ * @since 0.0.1
31
+ */
32
+ type Phase = "prepare" | "apply" | "confirmation" | "verification";
8
33
  /**
9
- * Where a handler failure happened: the read-only prepare phase, or the apply phase that
10
- * changes state.
34
+ * Who performs an action: a handler's apply phase, or a person whose confirmation the
35
+ * executor waits for.
11
36
  *
12
- * @since @next
37
+ * @since 0.2.0
13
38
  */
14
- type Phase = "prepare" | "apply";
39
+ type Performer = "automated" | "manual";
40
+ declare const VerificationFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
41
+ readonly _tag: "VerificationFailed";
42
+ } & Readonly<A>;
43
+ /**
44
+ * A person confirmed manual work, and the handler's `verify` check returned `false`.
45
+ *
46
+ * @since 0.2.0
47
+ */
48
+ declare class VerificationFailed extends VerificationFailed_base<{
49
+ readonly actionId: string;
50
+ readonly kind: string;
51
+ }> {
52
+ get message(): string;
53
+ }
15
54
  declare const UnexpectedHandlerError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
16
55
  readonly _tag: "UnexpectedHandlerError";
17
56
  } & Readonly<A>;
@@ -20,7 +59,7 @@ declare const UnexpectedHandlerError_base: new <A extends Record<string, any> =
20
59
  * recognized, or its prepare phase returned something other than `Handler.prepared` or
21
60
  * `Handler.skip`.
22
61
  *
23
- * @since @next
62
+ * @since 0.0.1
24
63
  */
25
64
  declare class UnexpectedHandlerError extends UnexpectedHandlerError_base<{
26
65
  readonly actionId: string;
@@ -35,7 +74,7 @@ declare const PreparationTypeId = "~deltafold/Preparation";
35
74
  * A prepare phase decided to apply. The apply phase receives `value` unchanged; the
36
75
  * executor never reads, validates, or serializes it.
37
76
  *
38
- * @since @next
77
+ * @since 0.1.0
39
78
  */
40
79
  type Prepared<out P> = {
41
80
  readonly [PreparationTypeId]: typeof PreparationTypeId;
@@ -46,7 +85,7 @@ type Prepared<out P> = {
46
85
  * A prepare phase decided that the action does not apply. The occurrence is skipped
47
86
  * with `reason`.
48
87
  *
49
- * @since @next
88
+ * @since 0.1.0
50
89
  */
51
90
  type Skip = {
52
91
  readonly [PreparationTypeId]: typeof PreparationTypeId;
@@ -56,7 +95,7 @@ type Skip = {
56
95
  /**
57
96
  * What a prepare phase returns: `Handler.prepared(value)` or `Handler.skip(reason)`.
58
97
  *
59
- * @since @next
98
+ * @since 0.1.0
60
99
  */
61
100
  type Preparation<P> = Prepared<P> | Skip;
62
101
  /** The value that a prepare phase passes to its apply phase. */
@@ -65,37 +104,43 @@ type PreparedValue<T> = T extends Prepared<infer P> ? P : never;
65
104
  * Ends a prepare phase with the value its apply phase receives. Wrapping the value keeps
66
105
  * it apart from a skip, whatever its shape.
67
106
  *
68
- * @since @next
107
+ * @since 0.1.0
69
108
  */
70
109
  declare function prepared(): Prepared<void>;
71
110
  declare function prepared<P>(value: P): Prepared<P>;
72
111
  /**
73
112
  * Ends a prepare phase by skipping the occurrence. The apply phase does not run.
74
113
  *
75
- * @since @next
114
+ * @since 0.1.0
76
115
  */
77
116
  declare const skip: (reason: string) => Skip;
78
117
  /**
79
- * How an occurrence continues after its prepare phase: skipped, or applied by an effect
80
- * that already holds the prepared value.
118
+ * How an occurrence continues after its prepare phase: skipped, applied by an effect
119
+ * that already holds the prepared value, or confirmed by a person. `verify` checks
120
+ * confirmed work and fails when the check does not pass.
81
121
  *
82
- * @since @next
122
+ * @since 0.1.0
83
123
  */
84
124
  type Step<E, R> = Skip | {
85
125
  readonly _tag: "Apply";
86
126
  readonly apply: Effect.Effect<void, E, R>;
127
+ } | {
128
+ readonly _tag: "Confirm";
129
+ readonly verify: Effect.Effect<void, E, R> | undefined;
87
130
  };
88
- declare const TypeId = "~deltafold/Handler";
131
+ declare const TypeId$2 = "~deltafold/Handler";
89
132
  /**
90
133
  * Implements one action instance. `E` and `R` are the errors and Effect services of both
91
134
  * phases together. A prepared value stays inside the handler, so handlers with
92
135
  * different prepared values share this type.
93
136
  *
94
- * @since @next
137
+ * @since 0.0.1
95
138
  */
96
- type Handler<out A extends Any$1, out E = never, out R = never> = {
97
- readonly [TypeId]: typeof TypeId;
139
+ type Handler<out A extends Any$3, out E = never, out R = never> = {
140
+ readonly [TypeId$2]: typeof TypeId$2;
98
141
  readonly action: A;
142
+ /** A `manual` handler has no phases of its own: a person does the work. */
143
+ readonly performer: Performer;
99
144
  /** Whether the handler has a prepare phase. */
100
145
  readonly prepares: boolean;
101
146
  /**
@@ -108,53 +153,47 @@ type Handler<out A extends Any$1, out E = never, out R = never> = {
108
153
  /**
109
154
  * Any handler.
110
155
  *
111
- * @since @next
156
+ * @since 0.0.1
112
157
  */
113
- type Any = Handler<Any$1, any, any>;
158
+ type Any$2 = Handler<Any$3, any, any>;
114
159
  /**
115
160
  * The errors of a handler or a union of handlers.
116
161
  *
117
- * @since @next
162
+ * @since 0.0.1
118
163
  */
119
- type Error<H> = H extends Handler<any, infer E, any> ? E : never;
164
+ type Error$1<H> = H extends Handler<any, infer E, any> ? E : never;
120
165
  /**
121
166
  * The Effect services of a handler or a union of handlers.
122
167
  *
123
- * @since @next
168
+ * @since 0.0.1
124
169
  */
125
- type Services<H> = H extends Handler<any, any, infer R> ? R : never;
170
+ type Services$2<H> = H extends Handler<any, any, infer R> ? R : never;
126
171
  /**
127
172
  * The action identifiers implemented by a handler or a union of handlers.
128
173
  *
129
- * @since @next
174
+ * @since 0.0.1
130
175
  */
131
176
  type ActionId<H> = H extends Handler<infer A, any, any> ? A["id"] : never;
132
- /** @since @next */
133
- declare const isHandler: (value: unknown) => value is Any;
177
+ /** @since 0.0.1 */
178
+ declare const isHandler: (value: unknown) => value is Any$2;
134
179
  /**
135
180
  * Named Effect services that a Promise handler declares.
136
181
  *
137
- * @since @next
182
+ * @since 0.0.1
138
183
  */
139
- type ServiceMap = {
140
- readonly [name: string | symbol]: Context.Key<any, any>;
141
- };
142
- type NoServices = Record<never, never>;
184
+ type ServiceMap = ServiceMap$1;
143
185
  /**
144
186
  * The second argument of Promise handler callbacks: the `AbortSignal` that
145
187
  * `Effect.tryPromise` aborts on interruption, and the declared services, resolved.
146
188
  *
147
- * @since @next
189
+ * @since 0.0.1
148
190
  */
149
- type PromiseContext<S extends ServiceMap = NoServices> = {
150
- readonly signal: AbortSignal;
151
- readonly services: { readonly [K in keyof S]: S[K]["Service"]; };
152
- };
191
+ type PromiseContext<S extends ServiceMap = NoServices> = PromiseContext$1<S>;
153
192
  /**
154
193
  * The second argument of a Promise apply phase: the Promise context and the action
155
194
  * payload.
156
195
  *
157
- * @since @next
196
+ * @since 0.1.0
158
197
  */
159
198
  type PromiseApplyContext<Payload, S extends ServiceMap = NoServices> = PromiseContext<S> & {
160
199
  readonly payload: Payload;
@@ -164,24 +203,22 @@ type PromiseApplyContext<Payload, S extends ServiceMap = NoServices> = PromiseCo
164
203
  * `Handler.prepared(value)` or `Handler.skip(reason)`; `apply` receives the value. Each
165
204
  * phase gets its own signal.
166
205
  *
167
- * @since @next
206
+ * @since 0.1.0
168
207
  */
169
208
  type PromisePhases<Payload, T extends Preparation<unknown>, S extends ServiceMap> = {
170
209
  readonly prepare: (payload: Payload, context: PromiseContext<S>) => PromiseLike<T> | T;
171
210
  readonly apply: (prepared: PreparedValue<T>, context: PromiseApplyContext<Payload, S>) => PromiseLike<unknown>;
172
211
  };
173
- type ServiceIds<S extends ServiceMap> = ValueOf<{ [K in keyof S]: S[K] extends Context.Key<infer I, any> ? I : never; }>;
174
212
  /**
175
213
  * Recognizes a declared rejection: a schema, or a type guard such as an `instanceof`
176
214
  * check. Guards must declare their parameter type, for example
177
215
  * `(cause: unknown): cause is NotFound => cause instanceof NotFound`.
178
216
  *
179
- * @since @next
217
+ * @since 0.0.1
180
218
  */
181
- type ErrorGuard = Schema.Top | ((cause: unknown) => cause is any);
182
- type GuardedError<G> = G extends Schema.Top ? G["Type"] : G extends ((cause: unknown) => cause is infer E) ? E : never;
183
- /** @since @next */
184
- type PromiseOptions$1<S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>> = {
219
+ type ErrorGuard = ErrorGuard$1;
220
+ /** @since 0.0.1 */
221
+ type PromiseOptions$2<S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>> = {
185
222
  /** Effect services resolved for the callbacks and added to the handler requirements. */
186
223
  readonly services?: S;
187
224
  /**
@@ -191,7 +228,7 @@ type PromiseOptions$1<S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>>
191
228
  */
192
229
  readonly errors?: G;
193
230
  };
194
- type PromiseHandler<A extends Any$1, S extends ServiceMap, G> = Handler<A, GuardedError<G> | UnexpectedHandlerError, ServiceIds<S>>;
231
+ type PromiseHandler<A extends Any$3, S extends ServiceMap, G> = Handler<A, GuardedError<G> | UnexpectedHandlerError, ServiceIds<S>>;
195
232
  /**
196
233
  * Implements an action with Promise callbacks. The callbacks run lazily through
197
234
  * `Effect.tryPromise`, and receive its `AbortSignal` and the declared services.
@@ -224,14 +261,14 @@ type PromiseHandler<A extends Any$1, S extends ServiceMap, G> = Handler<A, Guard
224
261
  * });
225
262
  * ```
226
263
  *
227
- * @since @next
264
+ * @since 0.0.1
228
265
  */
229
- declare function promise<A extends Any$1, const S extends ServiceMap = NoServices, const G extends ReadonlyArray<ErrorGuard> = []>(action: A, apply: (payload: A["payload"], context: PromiseContext<S>) => PromiseLike<unknown>, options?: PromiseOptions$1<S, G>): PromiseHandler<A, S, G[number]>;
230
- declare function promise<A extends Any$1, T extends Preparation<unknown> = Skip, const S extends ServiceMap = NoServices, const G extends ReadonlyArray<ErrorGuard> = []>(action: A, phases: PromisePhases<A["payload"], T, S>, options?: PromiseOptions$1<S, G>): PromiseHandler<A, S, G[number]>;
266
+ declare function promise$2<A extends Any$3, const S extends ServiceMap = NoServices, const G extends ReadonlyArray<ErrorGuard> = []>(action: A, apply: (payload: A["payload"], context: PromiseContext<S>) => PromiseLike<unknown>, options?: PromiseOptions$2<S, G>): PromiseHandler<A, S, G[number]>;
267
+ declare function promise$2<A extends Any$3, T extends Preparation<unknown> = Skip, const S extends ServiceMap = NoServices, const G extends ReadonlyArray<ErrorGuard> = []>(action: A, phases: PromisePhases<A["payload"], T, S>, options?: PromiseOptions$2<S, G>): PromiseHandler<A, S, G[number]>;
231
268
  /**
232
269
  * The second argument of an Effect apply phase.
233
270
  *
234
- * @since @next
271
+ * @since 0.1.0
235
272
  */
236
273
  type EffectApplyContext<Payload> = {
237
274
  readonly payload: Payload;
@@ -240,7 +277,7 @@ type EffectApplyContext<Payload> = {
240
277
  * An Effect handler with a prepare phase. `prepare` reads state and succeeds with
241
278
  * `Handler.prepared(value)` or `Handler.skip(reason)`; `apply` receives the value.
242
279
  *
243
- * @since @next
280
+ * @since 0.1.0
244
281
  */
245
282
  type EffectPhases<Payload, T extends Preparation<unknown>, E1, R1, E2, R2> = {
246
283
  readonly prepare: (payload: Payload) => Effect.Effect<T, E1, R1>;
@@ -269,23 +306,517 @@ type EffectPhases<Payload, T extends Preparation<unknown>, E1, R1, E2, R2> = {
269
306
  * });
270
307
  * ```
271
308
  *
272
- * @since @next
309
+ * @since 0.0.1
310
+ */
311
+ declare function effect$3<A extends Any$3, E = never, R = never>(action: A, apply: (payload: A["payload"]) => Effect.Effect<unknown, E, R>): Handler<A, E, Exclude<R, Scope.Scope>>;
312
+ declare function effect$3<A extends Any$3, T extends Preparation<unknown> = Skip, E1 = never, R1 = never, E2 = never, R2 = never>(action: A, phases: EffectPhases<A["payload"], T, E1, R1, E2, R2>): Handler<A, E1 | E2, Exclude<R1 | R2, Scope.Scope>>;
313
+ /** @since 0.2.0 */
314
+ type ManualOptions<Payload, S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>> = {
315
+ /** Effect services resolved for `verify` and added to the handler requirements. */
316
+ readonly services?: S;
317
+ /** Guards for rejections of `verify` that keep their own type. */
318
+ readonly errors?: G;
319
+ /**
320
+ * Read-only check that runs after the person confirms. Returning `false` fails the
321
+ * occurrence with `VerificationFailed`. A passing check is evidence that the work is
322
+ * in place, not proof of how it was done.
323
+ */
324
+ readonly verify?: (payload: Payload, context: PromiseContext<S>) => boolean | PromiseLike<boolean>;
325
+ };
326
+ /**
327
+ * Declares that a person performs the action. A manual handler has no prepare or apply
328
+ * phase. In a real run the executor asks its `interaction` to confirm the work, showing
329
+ * the occurrence's own instruction or description, and never completes the occurrence
330
+ * on its own. A dry run reports that a person would be asked. The optional `verify`
331
+ * check is a Promise callback that runs only after the confirmation.
332
+ *
333
+ * The same action can have a manual handler in one environment and an automated one in
334
+ * another.
335
+ *
336
+ * @example
337
+ * ```ts
338
+ * Handler.manual(rotateApiKey, {
339
+ * services: { keys: KeyStore },
340
+ * verify: (payload, { services: { keys } }) => keys.isFresh(payload.service),
341
+ * });
342
+ * ```
343
+ *
344
+ * @since 0.2.0
345
+ */
346
+ declare function manual<A extends Any$3>(action: A): Handler<A>;
347
+ declare function manual<A extends Any$3, const S extends ServiceMap = NoServices, const G extends ReadonlyArray<ErrorGuard> = []>(action: A, options: ManualOptions<A["payload"], S, G>): Handler<A, GuardedError<G[number]> | UnexpectedHandlerError | VerificationFailed, ServiceIds<S>>;
348
+ /** @since 0.2.0 */
349
+ type ManualEffectOptions<Payload, E, R> = {
350
+ /**
351
+ * Read-only check that runs after the person confirms. Succeeding with `false` fails
352
+ * the occurrence with `VerificationFailed`. It runs in the occurrence's `Scope`.
353
+ */
354
+ readonly verify?: (payload: Payload) => Effect.Effect<boolean, E, R>;
355
+ };
356
+ /**
357
+ * `Handler.manual` with an Effect `verify` check, which keeps its own errors and
358
+ * services.
359
+ *
360
+ * @since 0.2.0
361
+ */
362
+ declare function manualEffect<A extends Any$3>(action: A): Handler<A>;
363
+ declare function manualEffect<A extends Any$3, E = never, R = never>(action: A, options: ManualEffectOptions<A["payload"], E, R>): Handler<A, E | VerificationFailed, Exclude<R, Scope.Scope>>;
364
+ declare namespace interaction_d_exports {
365
+ export { Answer, Any$1 as Any, Error, Interaction, PromiseOptions$1 as PromiseOptions, Request, Services$1 as Services, UnexpectedInteractionError, effect$2 as effect, isInteraction, promise$1 as promise };
366
+ }
367
+ /**
368
+ * What a person says about manual work. There is no other answer: free-form input never
369
+ * reaches a report.
370
+ *
371
+ * @since 0.2.0
372
+ */
373
+ type Answer = "confirmed" | "declined";
374
+ /**
375
+ * A request to confirm manual work. The occurrence carries the action, its description,
376
+ * and the migration instruction that declared it, which is what to show the person.
377
+ *
378
+ * @since 0.2.0
273
379
  */
274
- declare function effect$1<A extends Any$1, E = never, R = never>(action: A, apply: (payload: A["payload"]) => Effect.Effect<unknown, E, R>): Handler<A, E, Exclude<R, Scope.Scope>>;
275
- declare function effect$1<A extends Any$1, T extends Preparation<unknown> = Skip, E1 = never, R1 = never, E2 = never, R2 = never>(action: A, phases: EffectPhases<A["payload"], T, E1, R1, E2, R2>): Handler<A, E1 | E2, Exclude<R1 | R2, Scope.Scope>>;
380
+ type Request<A extends Any$3 = Any$3> = {
381
+ readonly occurrence: Occurrence<A>;
382
+ };
383
+ declare const UnexpectedInteractionError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
384
+ readonly _tag: "UnexpectedInteractionError";
385
+ } & Readonly<A>;
386
+ /**
387
+ * A Promise interaction rejected with a value that none of its declared error guards
388
+ * recognized (`rejected`), or an interaction answered with something other than
389
+ * `"confirmed"` or `"declined"` (`invalid-answer`). An invalid answer is never kept: it
390
+ * may be text that the person typed.
391
+ *
392
+ * @since 0.2.0
393
+ */
394
+ declare class UnexpectedInteractionError extends UnexpectedInteractionError_base<{
395
+ readonly occurrenceId: string;
396
+ readonly reason: "rejected" | "invalid-answer";
397
+ /** The rejection. Always `undefined` for an invalid answer. */
398
+ readonly cause: unknown;
399
+ }> {
400
+ get message(): string;
401
+ }
402
+ declare const TypeId$1 = "~deltafold/Interaction";
403
+ /**
404
+ * Asks a person to confirm the manual work of a plan. The executor has no terminal or
405
+ * user interface of its own: the consumer running the plan supplies one of these.
406
+ *
407
+ * Parallel branches can ask at the same time. An interaction that owns one terminal
408
+ * serializes its own prompts. A failure or a decline elsewhere stops new actions but
409
+ * does not withdraw a request that was already made; only cancellation does.
410
+ *
411
+ * @since 0.2.0
412
+ */
413
+ type Interaction<out E = never, out R = never> = {
414
+ readonly [TypeId$1]: typeof TypeId$1;
415
+ readonly confirm: (request: Request) => Effect.Effect<Answer, E, R>;
416
+ };
417
+ /**
418
+ * Any interaction.
419
+ *
420
+ * @since 0.2.0
421
+ */
422
+ type Any$1 = Interaction<any, any>;
423
+ /**
424
+ * The errors of an interaction.
425
+ *
426
+ * @since 0.2.0
427
+ */
428
+ type Error<I> = I extends Interaction<infer E, any> ? E : never;
429
+ /**
430
+ * The Effect services of an interaction.
431
+ *
432
+ * @since 0.2.0
433
+ */
434
+ type Services$1<I> = I extends Interaction<any, infer R> ? R : never;
435
+ /** @since 0.2.0 */
436
+ declare const isInteraction: (value: unknown) => value is Any$1;
437
+ /** @since 0.2.0 */
438
+ type PromiseOptions$1<S extends ServiceMap$1, G extends ReadonlyArray<ErrorGuard$1>> = {
439
+ /** Effect services resolved for the callback and added to the run's requirements. */
440
+ readonly services?: S;
441
+ /** Guards for rejections that keep their own type. */
442
+ readonly errors?: G;
443
+ };
444
+ /**
445
+ * Confirms manual work with a Promise callback. It receives `{ signal, services }`: an
446
+ * `AbortSignal` that aborts when the run is cancelled, so it can stop asking, and the
447
+ * declared services.
448
+ *
449
+ * @example
450
+ * ```ts
451
+ * // The migration's instruction for this action, or the action's description.
452
+ * const textOf = ({ action, instruction }: Plan.Occurrence) =>
453
+ * instruction?.content
454
+ * .map((part) => (part._tag === "Text" ? part.text : part.action.description))
455
+ * .join("") ?? action.description;
456
+ *
457
+ * const interaction = Interaction.promise(async ({ occurrence }, { signal }) =>
458
+ * (await ask(textOf(occurrence), { signal })) ? "confirmed" : "declined",
459
+ * );
460
+ * ```
461
+ *
462
+ * @since 0.2.0
463
+ */
464
+ declare const promise$1: <const S extends ServiceMap$1 = NoServices$1, const G extends ReadonlyArray<ErrorGuard$1> = []>(confirm: (request: Request, context: PromiseContext$1<S>) => PromiseLike<Answer>, options?: PromiseOptions$1<S, G>) => Interaction<GuardedError$1<G[number]> | UnexpectedInteractionError, ServiceIds$1<S>>;
465
+ /**
466
+ * Confirms manual work with an Effect, which keeps its own errors and services and
467
+ * stops through Effect interruption when the run is cancelled.
468
+ *
469
+ * @since 0.2.0
470
+ */
471
+ declare const effect$2: <E = never, R = never>(confirm: (request: Request) => Effect.Effect<Answer, E, R>) => Interaction<E | UnexpectedInteractionError, R>;
472
+ declare namespace observer_d_exports {
473
+ export { ActionInfo, ActionPhaseStarted, ActionSettled, Any, Counts, Event, ObservationFailure, Observer, OutcomeSummary, Progress, Run, RunFinished, RunStarted, Services, StepInfo, StepSettled, StepStarted, effect$1 as effect, isObserver, promise, sync };
474
+ }
475
+ declare const TypeId = "~deltafold/Observer";
476
+ /**
477
+ * The run that emitted an event.
478
+ *
479
+ * @since 0.2.1
480
+ */
481
+ type Run = {
482
+ /** The `runId` passed to the executor, if any. Shared observers use it to tell runs apart. */
483
+ readonly id: string | undefined;
484
+ readonly mode: Report["mode"];
485
+ readonly from: string;
486
+ readonly to: string;
487
+ readonly route: string;
488
+ };
489
+ /**
490
+ * Counters at the moment an event was emitted. Counters never decrease during a run.
491
+ *
492
+ * @since 0.2.1
493
+ */
494
+ type Progress = {
495
+ /** Steps with actions and prose-only steps. Omitted steps are not counted. */
496
+ readonly steps: {
497
+ readonly total: number;
498
+ readonly finished: number;
499
+ };
500
+ readonly actions: {
501
+ readonly total: number;
502
+ /** Occurrences whose prepare or apply phase has started and that have not settled. */
503
+ readonly running: number;
504
+ readonly finished: number;
505
+ };
506
+ };
507
+ /**
508
+ * One step of the route, as observers see it.
509
+ *
510
+ * - `execute`: the step has actions after optimization.
511
+ * - `prose`: the step has instruction prose but no actions. The executor runs nothing
512
+ * for it and does not wait at it.
513
+ * - `omitted`: a noop, or a step whose actions rules removed or moved into another step.
514
+ *
515
+ * @since 0.2.1
516
+ */
517
+ type StepInfo = {
518
+ /** The plan step's `id`. */
519
+ readonly id: string;
520
+ /** Position in `plan.steps`, including omitted steps. */
521
+ readonly index: number;
522
+ readonly migration: string;
523
+ readonly direction: Direction;
524
+ readonly from: string;
525
+ readonly to: string;
526
+ /** Occurrence identifiers of the step, in plan order. */
527
+ readonly occurrences: ReadonlyArray<string>;
528
+ /**
529
+ * Other steps whose declared actions this step's replacements stand for. Running this
530
+ * step performs work that those steps declared.
531
+ */
532
+ readonly absorbs: ReadonlyArray<string>;
533
+ } & ({
534
+ readonly kind: "execute" | "prose";
535
+ } | {
536
+ readonly kind: "omitted";
537
+ readonly reason: "noop" | "all-actions-removed";
538
+ });
539
+ /**
540
+ * One occurrence of the plan, as observers see it.
541
+ *
542
+ * @since 0.2.1
543
+ */
544
+ type ActionInfo = {
545
+ readonly occurrence: string;
546
+ readonly action: string;
547
+ readonly kind: string;
548
+ readonly description: string;
549
+ readonly migration: string;
550
+ readonly direction: Direction;
551
+ /** The step that runs the occurrence. */
552
+ readonly step: string;
553
+ readonly origin: {
554
+ readonly _tag: "Declared";
555
+ } | {
556
+ readonly _tag: "Replacement";
557
+ readonly rule: string;
558
+ /** Identifiers of the replaced occurrences, in order. */
559
+ readonly replaces: ReadonlyArray<string>;
560
+ };
561
+ /** Steps that declared the actions behind this occurrence, in plan order. */
562
+ readonly sources: ReadonlyArray<string>;
563
+ };
564
+ /**
565
+ * An outcome as observers see it. Each variant lists its fields explicitly, so a field
566
+ * added to the report's outcome never reaches observers unreviewed. A failure keeps only
567
+ * the error's string `_tag`; the full error is in the execution's report.
568
+ *
569
+ * @since 0.2.1
570
+ */
571
+ type OutcomeSummary = {
572
+ readonly _tag: "Completed";
573
+ readonly performer: "automated";
574
+ } | {
575
+ readonly _tag: "Completed";
576
+ readonly performer: "manual";
577
+ readonly confirmation: "asserted" | "verified";
578
+ } | {
579
+ readonly _tag: "Skipped";
580
+ readonly reason: string;
581
+ } | {
582
+ readonly _tag: "Declined";
583
+ } | {
584
+ readonly _tag: "Failed";
585
+ readonly phase: Phase;
586
+ readonly errorTag: string | undefined;
587
+ } | {
588
+ readonly _tag: "Interrupted";
589
+ readonly phase: Phase;
590
+ readonly reason: InterruptReason;
591
+ readonly settled: boolean;
592
+ } | {
593
+ readonly _tag: "Unattempted";
594
+ } | {
595
+ readonly _tag: "WouldExecute";
596
+ readonly evaluated: boolean;
597
+ readonly performer: Performer;
598
+ } | {
599
+ readonly _tag: "WouldSkip";
600
+ readonly reason: string;
601
+ } | {
602
+ readonly _tag: "Undetermined";
603
+ readonly reason: string;
604
+ readonly performer: Performer;
605
+ } | {
606
+ readonly _tag: "PreparationFailed";
607
+ readonly errorTag: string | undefined;
608
+ };
609
+ /**
610
+ * Occurrences by outcome tag. `unsettled` counts interrupted occurrences that may still be
611
+ * running.
612
+ *
613
+ * @since 0.2.1
614
+ */
615
+ type Counts = { readonly [K in Outcome["_tag"]]: number; } & {
616
+ readonly unsettled: number;
617
+ };
618
+ type Base = {
619
+ readonly run: Run;
620
+ /** Position of the event in its run, starting at 0. */
621
+ readonly seq: number;
622
+ /** Milliseconds since the Unix epoch, from Effect's `Clock`. */
623
+ readonly timestamp: number;
624
+ readonly progress: Progress;
625
+ };
626
+ /**
627
+ * The run is starting: every action has a handler, and manual work has an interaction to
628
+ * ask with. A run that fails either check emits no events. Lists every step of the route,
629
+ * including omitted ones.
630
+ *
631
+ * @since 0.2.1
632
+ */
633
+ type RunStarted = Base & {
634
+ readonly _tag: "RunStarted";
635
+ readonly steps: ReadonlyArray<StepInfo>;
636
+ };
637
+ /** @since 0.2.1 */
638
+ type StepStarted = Base & {
639
+ readonly _tag: "StepStarted";
640
+ readonly step: StepInfo;
641
+ };
642
+ /**
643
+ * A phase of an occurrence started: its prepare or apply phase, the confirmation of
644
+ * manual work, or its verification. `prepare` appears only for handlers that have a
645
+ * prepare phase. `confirmation` means the run is waiting for a person. An occurrence
646
+ * emits this once per phase that starts.
647
+ *
648
+ * @since 0.2.1
649
+ */
650
+ type ActionPhaseStarted = Base & {
651
+ readonly _tag: "ActionPhaseStarted";
652
+ readonly action: ActionInfo;
653
+ readonly phase: Phase;
654
+ };
655
+ /**
656
+ * An occurrence has its final outcome. Emitted once for each occurrence whose outcome is
657
+ * known, and as `Unattempted` for an occurrence that started but stopped before applying
658
+ * or asking. It arrives after the occurrence's scope has closed, except when an
659
+ * interrupted Promise has not settled: then the scope stays open until it does, the
660
+ * reported outcome is already final, and a later cleanup failure is only logged. Dry-run
661
+ * outcomes that need no prepare phase arrive without a start.
662
+ *
663
+ * @since 0.2.1
664
+ */
665
+ type ActionSettled = Base & {
666
+ readonly _tag: "ActionSettled";
667
+ readonly action: ActionInfo;
668
+ readonly outcome: OutcomeSummary;
669
+ };
670
+ /**
671
+ * A started step ended. `counts` covers the step's occurrences.
672
+ *
673
+ * @since 0.2.1
674
+ */
675
+ type StepSettled = Base & {
676
+ readonly _tag: "StepSettled";
677
+ readonly step: StepInfo;
678
+ readonly counts: Counts;
679
+ };
680
+ /**
681
+ * The run ended. `status` and `counts` match the execution's report. When the fiber of
682
+ * `Executor.effect` is interrupted, there is no report: `report` is `false`, the status is
683
+ * `"interrupted"`, and running occurrences count as unsettled interruptions. If the
684
+ * interruption cuts short the delivery of `RunFinished`, the observers that had not yet
685
+ * received it get the report-less one with the same `seq`, so each observer receives
686
+ * exactly one.
687
+ *
688
+ * @since 0.2.1
689
+ */
690
+ type RunFinished = Base & {
691
+ readonly _tag: "RunFinished";
692
+ readonly status: Report["status"];
693
+ readonly counts: Counts;
694
+ readonly report: boolean;
695
+ };
696
+ /**
697
+ * What an observer receives. A run emits `RunStarted`; then, for each step that is not
698
+ * omitted, `StepStarted`, an `ActionPhaseStarted` for each phase that starts, an
699
+ * `ActionSettled` for each occurrence, and `StepSettled`; and finally `RunFinished`. Action
700
+ * events of parallel branches interleave.
701
+ *
702
+ * Events carry identifiers and plain data, never payloads, errors, or causes. Action
703
+ * descriptions are included, so they must not contain secrets.
704
+ *
705
+ * @since 0.2.1
706
+ */
707
+ type Event = RunStarted | StepStarted | ActionPhaseStarted | ActionSettled | StepSettled | RunFinished;
708
+ /**
709
+ * An observer that failed, or that was abandoned after cancellation or a timeout because
710
+ * it did not finish within the settlement grace period. An abandoned callback is
711
+ * interrupted but not awaited, so one that cannot be interrupted may keep running. The
712
+ * cause can hold arbitrary values, so do not serialize it as a whole.
713
+ *
714
+ * @since 0.2.1
715
+ */
716
+ type ObservationFailure = {
717
+ /** Position of the observer in the `observers` array. */
718
+ readonly observer: number;
719
+ readonly event: Event["_tag"];
720
+ readonly seq: number;
721
+ readonly reason: "failed" | "abandoned";
722
+ readonly cause: Cause.Cause<unknown>;
723
+ };
724
+ /**
725
+ * Receives the events of a run. Pass observers to the executor's `observers` option. `R`
726
+ * is the Effect services an observer requires, which become requirements of the execution.
727
+ *
728
+ * The executor delivers one event at a time, to each observer in array order, and waits
729
+ * for each delivery before it continues, so every observer sees the same order. After
730
+ * cancellation or a timeout, each delivery waits at most `settleTimeout` and is then
731
+ * abandoned. A failed or abandoned delivery is listed in the report's `observation` and
732
+ * never changes an outcome. Observers only receive events: they cannot answer a manual
733
+ * confirmation.
734
+ *
735
+ * @since 0.2.1
736
+ */
737
+ type Observer<out R = never> = {
738
+ readonly [TypeId]: typeof TypeId;
739
+ /** Delivers one event and captures how the delivery ended. It never fails. */
740
+ readonly notify: (event: Event) => Effect.Effect<Exit.Exit<unknown, unknown>, never, R>;
741
+ };
742
+ /**
743
+ * Any observer.
744
+ *
745
+ * @since 0.2.1
746
+ */
747
+ type Any = Observer<any>;
748
+ /**
749
+ * The Effect services of an observer or a union of observers.
750
+ *
751
+ * @since 0.2.1
752
+ */
753
+ type Services<O> = O extends Observer<infer R> ? R : never;
754
+ /** @since 0.2.1 */
755
+ declare const isObserver: (value: unknown) => value is Any;
756
+ /**
757
+ * Observes with a synchronous callback. A thrown value is recorded as an observation
758
+ * failure.
759
+ *
760
+ * @example
761
+ * ```ts
762
+ * Observer.sync((event) => {
763
+ * if (event._tag === "ActionSettled") console.error(event.action.occurrence, event.outcome._tag);
764
+ * });
765
+ * ```
766
+ *
767
+ * @since 0.2.1
768
+ */
769
+ declare const sync: (callback: (event: Event) => void) => Observer;
770
+ /**
771
+ * Observes with a Promise callback. The executor waits for the Promise. The `signal`
772
+ * aborts when the executor stops waiting: after cancellation or a timeout, once the
773
+ * settlement grace period has passed, or when the execution is interrupted. A services
774
+ * layer that `Executor.runPromise` built stays open until an abandoned Promise settles.
775
+ *
776
+ * @since 0.2.1
777
+ */
778
+ declare const promise: (callback: (event: Event, context: {
779
+ readonly signal: AbortSignal;
780
+ }) => PromiseLike<unknown>) => Observer;
781
+ /**
782
+ * Observes with an Effect. Its services become requirements of the execution. Its
783
+ * failures are recorded as observation failures and never fail the execution.
784
+ *
785
+ * @example
786
+ * ```ts
787
+ * Observer.effect((event) => Effect.logDebug(event._tag));
788
+ * ```
789
+ *
790
+ * @since 0.2.1
791
+ */
792
+ declare const effect$1: <E = never, R = never>(callback: (event: Event) => Effect.Effect<unknown, E, R>) => Observer<R>;
276
793
  declare namespace executor_d_exports {
277
- export { CoverageIssue, Errors, ExecutionError, ExecutionFailed, ExecutionInterrupted, HandlerCoverageError, InterruptReason, OccurrenceReport, Options, Outcome, PromiseOptions, Report, Requirements, Uncovered, effect, runPromise };
794
+ export { CoverageIssue, Errors, ExecutionError, ExecutionFailed, ExecutionInterrupted, HandlerCoverageError, InteractionUnavailable, InterruptReason, OccurrenceReport, Options, Outcome, PromiseOptions, Report, Requirements, Uncovered, effect, runPromise };
278
795
  }
279
796
  /**
280
797
  * What happened to one occurrence, or what a dry run predicts.
281
798
  *
282
- * @since @next
799
+ * @since 0.0.1
283
800
  */
284
801
  type Outcome<E = unknown> = {
285
802
  readonly _tag: "Completed";
803
+ readonly performer: "automated";
804
+ } | {
805
+ readonly _tag: "Completed";
806
+ readonly performer: "manual";
807
+ /**
808
+ * What supports completion. `asserted`: the person said so and nothing checked
809
+ * it. `verified`: the person said so and the handler's `verify` check passed.
810
+ * Neither proves how the work was done.
811
+ */
812
+ readonly confirmation: "asserted" | "verified";
286
813
  } | {
287
814
  readonly _tag: "Skipped";
288
815
  readonly reason: string;
816
+ } |
817
+ /** The person asked to confirm manual work answered that it is not done. */
818
+ {
819
+ readonly _tag: "Declined";
289
820
  } | {
290
821
  readonly _tag: "Failed";
291
822
  readonly phase: Phase;
@@ -308,28 +839,34 @@ type Outcome<E = unknown> = {
308
839
  {
309
840
  readonly _tag: "Unattempted";
310
841
  } |
311
- /** `evaluated`: whether a prepare phase ran and decided to apply. */
842
+ /**
843
+ * `evaluated`: whether a prepare phase ran and decided to apply. A `manual` occurrence
844
+ * would wait for a person; a dry run never asks.
845
+ */
312
846
  {
313
847
  readonly _tag: "WouldExecute";
314
848
  readonly evaluated: boolean;
849
+ readonly performer: Performer;
315
850
  } | {
316
851
  readonly _tag: "WouldSkip";
317
852
  readonly reason: string;
318
853
  } | {
319
854
  readonly _tag: "Undetermined";
320
855
  readonly reason: string;
856
+ /** A `manual` occurrence would wait for a person if it executes. */
857
+ readonly performer: Performer;
321
858
  } | {
322
859
  readonly _tag: "PreparationFailed";
323
860
  readonly error: E | undefined;
324
861
  readonly cause: Cause.Cause<E>;
325
862
  };
326
- /** @since @next */
327
- type OccurrenceReport<A extends Any$1 = Any$1, E = unknown> = {
863
+ /** @since 0.0.1 */
864
+ type OccurrenceReport<A extends Any$3 = Any$3, E = unknown> = {
328
865
  readonly occurrence: Occurrence<A>;
329
866
  readonly outcome: Outcome<E>;
330
867
  };
331
- /** @since @next */
332
- type Report<A extends Any$1 = Any$1, E = unknown> = {
868
+ /** @since 0.0.1 */
869
+ type Report<A extends Any$3 = Any$3, E = unknown> = {
333
870
  readonly _tag: "Report";
334
871
  readonly mode: "execute" | "dry-run";
335
872
  readonly status: "completed" | "failed" | "interrupted" | "not-started" | "would-complete" | "would-fail";
@@ -339,17 +876,19 @@ type Report<A extends Any$1 = Any$1, E = unknown> = {
339
876
  /** Every occurrence in plan order. */
340
877
  readonly occurrences: ReadonlyArray<OccurrenceReport<A, E>>;
341
878
  /**
342
- * Whether any apply phase started. A started apply phase may have partially changed
343
- * state.
879
+ * Whether any apply phase started or any person was asked to do manual work. Either
880
+ * may have partially changed state.
344
881
  */
345
882
  readonly bodiesStarted: boolean;
346
883
  /** Progress is not persisted. Rerunning the plan repeats completed actions. */
347
884
  readonly persistence: "none";
885
+ /** Observers that failed or were abandoned. Never affects outcomes or status. */
886
+ readonly observation: ReadonlyArray<ObservationFailure>;
348
887
  };
349
888
  /**
350
889
  * A handler is missing, duplicated, or bound to a different definition.
351
890
  *
352
- * @since @next
891
+ * @since 0.0.1
353
892
  */
354
893
  type CoverageIssue = {
355
894
  readonly _tag: "Missing" | "Duplicate" | "Mismatched";
@@ -374,24 +913,43 @@ declare const HandlerCoverageBase: new <A extends Record<string, any> = {}>(args
374
913
  * For an occurrence that a rule produced, the issue names the rule and the occurrences
375
914
  * it replaced.
376
915
  *
377
- * @since @next
916
+ * @since 0.0.1
378
917
  */
379
- declare class HandlerCoverageError<A extends Any$1 = Any$1> extends HandlerCoverageBase<{
918
+ declare class HandlerCoverageError<A extends Any$3 = Any$3> extends HandlerCoverageBase<{
380
919
  readonly issues: ReadonlyArray<CoverageIssue>;
381
920
  readonly report: Report<A, never>;
382
921
  }> {
383
922
  get message(): string;
384
923
  }
924
+ declare const InteractionUnavailableBase: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
925
+ readonly _tag: "InteractionUnavailable";
926
+ } & Readonly<A>;
927
+ /**
928
+ * The plan has manual handlers, and the run has no `interaction` to ask a person. The
929
+ * run fails before any handler phase or prompt.
930
+ *
931
+ * @since 0.2.0
932
+ */
933
+ declare class InteractionUnavailable<A extends Any$3 = Any$3> extends InteractionUnavailableBase<{
934
+ /** The occurrences that a manual handler covers, in plan order. */
935
+ readonly occurrences: ReadonlyArray<Occurrence<A>>;
936
+ readonly report: Report<A, never>;
937
+ }> {
938
+ get message(): string;
939
+ }
385
940
  declare const ExecutionFailedBase: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
386
941
  readonly _tag: "ExecutionFailed";
387
942
  } & Readonly<A>;
388
943
  /**
389
- * An occurrence failed. Execution stopped admitting new actions; started ones settled.
944
+ * An occurrence failed, or a person declined manual work. Execution stopped admitting
945
+ * new actions; started ones settled.
390
946
  *
391
- * @since @next
947
+ * @since 0.0.1
392
948
  */
393
- declare class ExecutionFailed<A extends Any$1 = Any$1, E = unknown> extends ExecutionFailedBase<{
949
+ declare class ExecutionFailed<A extends Any$3 = Any$3, E = unknown> extends ExecutionFailedBase<{
394
950
  readonly failures: ReadonlyArray<OccurrenceReport<A, E>>;
951
+ /** Manual occurrences that a person declined. */
952
+ readonly declined: ReadonlyArray<OccurrenceReport<A, E>>;
395
953
  readonly report: Report<A, E>;
396
954
  }> {
397
955
  get message(): string;
@@ -403,49 +961,64 @@ declare const ExecutionInterruptedBase: new <A extends Record<string, any> = {}>
403
961
  * Why an execution or an occurrence was interrupted: explicit cancellation, a configured
404
962
  * timeout, or an Effect handler that interrupted itself.
405
963
  *
406
- * @since @next
964
+ * @since 0.0.1
407
965
  */
408
966
  type InterruptReason = "cancelled" | "timeout" | "handler";
409
967
  /**
410
968
  * Explicit cancellation, a configured timeout, or a handler's own interruption stopped
411
969
  * execution.
412
970
  *
413
- * @since @next
971
+ * @since 0.0.1
414
972
  */
415
- declare class ExecutionInterrupted<A extends Any$1 = Any$1, E = unknown> extends ExecutionInterruptedBase<{
973
+ declare class ExecutionInterrupted<A extends Any$3 = Any$3, E = unknown> extends ExecutionInterruptedBase<{
416
974
  readonly reason: InterruptReason;
417
975
  readonly report: Report<A, E>;
418
976
  }> {
419
977
  get message(): string;
420
978
  }
421
- /** @since @next */
422
- type ExecutionError<A extends Any$1, E> = HandlerCoverageError<A> | ExecutionFailed<A, E> | ExecutionInterrupted<A, E>;
979
+ /** @since 0.0.1 */
980
+ type ExecutionError<A extends Any$3, E> = HandlerCoverageError<A> | InteractionUnavailable<A> | ExecutionFailed<A, E> | ExecutionInterrupted<A, E>;
423
981
  /**
424
982
  * Action identifiers of a statically covered plan that no handler in the array
425
983
  * implements.
426
984
  *
427
- * @since @next
985
+ * @since 0.0.1
428
986
  */
429
- type Uncovered<A extends Any$1, H, C extends Coverage> = "runtime" extends C ? never : A extends Any$1 ? string extends A["id"] ? never : A["id"] extends ActionId<H> ? never : A["id"] : never;
987
+ type Uncovered<A extends Any$3, H, C extends Coverage> = "runtime" extends C ? never : A extends Any$3 ? string extends A["id"] ? never : A["id"] extends ActionId<H> ? never : A["id"] : never;
430
988
  /** Rejects a handler array that leaves statically known actions uncovered, naming them. */
431
- type CoverageCheck<A extends Any$1, H, C extends Coverage> = [Uncovered<A, H, C>] extends [never] ? unknown : {
989
+ type CoverageCheck<A extends Any$3, H, C extends Coverage> = [Uncovered<A, H, C>] extends [never] ? unknown : {
432
990
  readonly handlers: `Missing a handler for action "${Uncovered<A, H, C>}"`;
433
991
  };
434
992
  /**
435
993
  * Errors an execution can report for its occurrences.
436
994
  *
437
- * @since @next
995
+ * @since 0.0.1
438
996
  */
439
- type Errors<H> = Error<H>;
997
+ type Errors<H, I = never> = Error$1<H> | Error<I>;
440
998
  /**
441
- * Effect services an execution requires: the services of its handlers.
999
+ * Effect services an execution requires: the services of its handlers, its
1000
+ * interaction, and its observers.
442
1001
  *
443
- * @since @next
1002
+ * @since 0.0.1
444
1003
  */
445
- type Requirements<H> = Services<H>;
446
- /** @since @next */
447
- type Options<H extends Any> = {
1004
+ type Requirements<H, I = never, O = never> = Services$2<H> | Services$1<I> | Services<O>;
1005
+ /** @since 0.0.1 */
1006
+ type Options<H extends Any$2, I extends Any$1 = never, O extends Any = never> = {
448
1007
  readonly handlers?: ReadonlyArray<H>;
1008
+ /**
1009
+ * Asks a person to confirm the work of manual handlers. A run whose plan has manual
1010
+ * handlers fails with `InteractionUnavailable` before it starts when this is absent.
1011
+ * A dry run never asks and does not need it.
1012
+ */
1013
+ readonly interaction?: I;
1014
+ /**
1015
+ * Receive the run's events, in array order. The executor waits for each observer
1016
+ * before it continues; an observer failure is recorded in `report.observation` and never changes
1017
+ * the outcome.
1018
+ */
1019
+ readonly observers?: ReadonlyArray<O>;
1020
+ /** Identifies the run in observer events. */
1021
+ readonly runId?: string;
449
1022
  /**
450
1023
  * Run prepare phases without running any apply phase. A prepare phase that may
451
1024
  * depend on an earlier action is reported `Undetermined`, because the dry run does
@@ -454,8 +1027,10 @@ type Options<H extends Any> = {
454
1027
  readonly dryRun?: boolean;
455
1028
  /**
456
1029
  * Limit for each phase of an occurrence: the prepare phase and the apply phase each
457
- * get the full limit. Exceeding it interrupts that action and stops admitting new
458
- * ones. It applies to dry-run prepare phases too.
1030
+ * get the full limit, and so does the verification of manual work. Exceeding it
1031
+ * interrupts that action and stops admitting new ones. It applies to dry-run prepare
1032
+ * phases too. It never limits the wait for a person to confirm manual work; cancel
1033
+ * the run to end that wait.
459
1034
  */
460
1035
  readonly timeout?: Duration.Input;
461
1036
  /**
@@ -465,7 +1040,8 @@ type Options<H extends Any> = {
465
1040
  readonly settleTimeout?: Duration.Input;
466
1041
  };
467
1042
  /**
468
- * Runs a plan as an Effect. Coverage is checked before any handler phase runs. Steps
1043
+ * Runs a plan as an Effect. Coverage, and the interaction that manual handlers need,
1044
+ * are checked before any handler phase runs. Steps
469
1045
  * are sequential barriers; parallel groups run their branches concurrently. On failure,
470
1046
  * no new action starts, and actions already running settle before the effect fails
471
1047
  * with the partial report.
@@ -477,29 +1053,32 @@ type Options<H extends Any> = {
477
1053
  *
478
1054
  * To cancel, interrupt the fiber. Interruption reaches running actions and aborts the
479
1055
  * signal passed to Promise callbacks. The effect then ends as interrupted, without a
480
- * report.
1056
+ * report. Observers receive a final `RunFinished` event without a report, delivered
1057
+ * within `settleTimeout`.
481
1058
  *
482
- * @since @next
1059
+ * @since 0.0.1
483
1060
  */
484
- declare const effect: <A extends Any$1, C extends Coverage, H extends Any = never>(plan: Plan<A, C>, options: Options<H> & CoverageCheck<A, H, C>) => Effect.Effect<Report<A, Errors<H>>, ExecutionError<A, Errors<H>>, Requirements<H>>;
1061
+ declare const effect: <A extends Any$3, C extends Coverage, H extends Any$2 = never, I extends Any$1 = never, O extends Any = never>(plan: Plan<A, C>, options: Options<H, I, O> & CoverageCheck<A, H, C>) => Effect.Effect<Report<A, Errors<H, I>>, ExecutionError<A, Errors<H, I>>, Requirements<H, I, O>>;
485
1062
  type ServicesOption<R, LE> = [R] extends [never] ? {
486
- /** Handlers without Effect services need none. */
1063
+ /** Handlers, interactions, and observers without Effect services need none. */
487
1064
  readonly services?: Context.Context<never> | Layer.Layer<never, LE>;
488
1065
  } : {
489
- /** Supplies the handlers' Effect services. */
1066
+ /** Supplies the Effect services of the handlers, the interaction, and the observers. */
490
1067
  readonly services: Context.Context<R> | Layer.Layer<R, LE>;
491
1068
  };
492
- /** @since @next */
493
- type PromiseOptions<H extends Any> = Options<H> & {
1069
+ /** @since 0.0.1 */
1070
+ type PromiseOptions<H extends Any$2, I extends Any$1 = never, O extends Any = never> = Options<H, I, O> & {
494
1071
  /**
495
- * Explicit cancellation. Aborting stops admission, interrupts running actions, and
496
- * rejects with `ExecutionInterrupted` and the partial report.
1072
+ * Explicit cancellation. Aborting stops admission, interrupts running actions and
1073
+ * pending confirmations, and rejects with `ExecutionInterrupted` and the partial
1074
+ * report.
497
1075
  */
498
1076
  readonly signal?: AbortSignal;
499
1077
  };
500
1078
  /**
501
1079
  * Runs a plan and returns a Promise. It rejects with `HandlerCoverageError`,
502
- * `ExecutionFailed`, or `ExecutionInterrupted`, each carrying the partial report.
1080
+ * `InteractionUnavailable`, `ExecutionFailed`, or `ExecutionInterrupted`, each carrying
1081
+ * the partial report.
503
1082
  * Building a supplied services layer can also reject with the layer's own error,
504
1083
  * without a report.
505
1084
  *
@@ -510,8 +1089,8 @@ type PromiseOptions<H extends Any> = Options<H> & {
510
1089
  * until it settles, possibly forever, and close in that order. A cleanup failure after
511
1090
  * the Promise resolved is logged through Effect.
512
1091
  *
513
- * @since @next
1092
+ * @since 0.0.1
514
1093
  */
515
- declare const runPromise: <A extends Any$1, C extends Coverage, H extends Any = never, LE = never>(plan: Plan<A, C>, options: PromiseOptions<H> & ServicesOption<Requirements<H>, LE> & CoverageCheck<A, H, C>) => Promise<Report<A, Errors<H>>>;
516
- export { action_d_exports as Action, change_d_exports as Change, executor_d_exports as Executor, handler_d_exports as Handler, history_d_exports as History, migration_d_exports as Migration, package_d_exports as Package, plan_d_exports as Plan, rule_d_exports as Rule, shortcut_d_exports as Shortcut, version_d_exports as Version };
1094
+ declare const runPromise: <A extends Any$3, C extends Coverage, H extends Any$2 = never, I extends Any$1 = never, LE = never, O extends Any = never>(plan: Plan<A, C>, options: PromiseOptions<H, I, O> & ServicesOption<Requirements<H, I, O>, LE> & CoverageCheck<A, H, C>) => Promise<Report<A, Errors<H, I>>>;
1095
+ export { action_d_exports as Action, change_d_exports as Change, executor_d_exports as Executor, handler_d_exports as Handler, history_d_exports as History, interaction_d_exports as Interaction, migration_d_exports as Migration, observer_d_exports as Observer, package_d_exports as Package, plan_d_exports as Plan, rule_d_exports as Rule, shortcut_d_exports as Shortcut, version_d_exports as Version };
517
1096
  //# sourceMappingURL=index.d.ts.map