deltafold 0.0.1 → 0.2.0

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.
package/dist/index.d.ts CHANGED
@@ -1,22 +1,63 @@
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 } from "effect";
1
+ import { _ as Any$2, 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";
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, EffectOptions, Error, ErrorGuard, Handler, Phase, PromiseContext, PromiseOptions$1 as PromiseOptions, ServiceMap, Services, UnexpectedHandlerError, effect$1 as effect, isHandler, promise };
20
+ export { ActionId, Any$1 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$1 as Services, Skip, Step, UnexpectedHandlerError, VerificationFailed, effect$2 as effect, isHandler, manual, manualEffect, prepared, promise$1 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 @next
31
+ */
32
+ type Phase = "prepare" | "apply" | "confirmation" | "verification";
33
+ /**
34
+ * Who performs an action: a handler's apply phase, or a person whose confirmation the
35
+ * executor waits for.
36
+ *
37
+ * @since @next
38
+ */
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>;
8
43
  /**
9
- * Where a handler failure happened.
44
+ * A person confirmed manual work, and the handler's `verify` check returned `false`.
10
45
  *
11
46
  * @since @next
12
47
  */
13
- type Phase = "precondition" | "body";
48
+ declare class VerificationFailed extends VerificationFailed_base<{
49
+ readonly actionId: string;
50
+ readonly kind: string;
51
+ }> {
52
+ get message(): string;
53
+ }
14
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 & {
15
55
  readonly _tag: "UnexpectedHandlerError";
16
56
  } & Readonly<A>;
17
57
  /**
18
58
  * A Promise handler rejected or threw a value that none of its declared error guards
19
- * recognized.
59
+ * recognized, or its prepare phase returned something other than `Handler.prepared` or
60
+ * `Handler.skip`.
20
61
  *
21
62
  * @since @next
22
63
  */
@@ -28,41 +69,105 @@ declare class UnexpectedHandlerError extends UnexpectedHandlerError_base<{
28
69
  }> {
29
70
  get message(): string;
30
71
  }
31
- declare const TypeId = "~deltafold/Handler";
72
+ declare const PreparationTypeId = "~deltafold/Preparation";
32
73
  /**
33
- * Implements one action instance. `E` and `R` are the errors and Effect services of the
34
- * body and precondition together.
74
+ * A prepare phase decided to apply. The apply phase receives `value` unchanged; the
75
+ * executor never reads, validates, or serializes it.
35
76
  *
36
77
  * @since @next
37
78
  */
38
- type Handler<out A extends Any$1, out E = never, out R = never> = {
39
- readonly [TypeId]: typeof TypeId;
79
+ type Prepared<out P> = {
80
+ readonly [PreparationTypeId]: typeof PreparationTypeId;
81
+ readonly _tag: "Prepared";
82
+ readonly value: P;
83
+ };
84
+ /**
85
+ * A prepare phase decided that the action does not apply. The occurrence is skipped
86
+ * with `reason`.
87
+ *
88
+ * @since @next
89
+ */
90
+ type Skip = {
91
+ readonly [PreparationTypeId]: typeof PreparationTypeId;
92
+ readonly _tag: "Skip";
93
+ readonly reason: string;
94
+ };
95
+ /**
96
+ * What a prepare phase returns: `Handler.prepared(value)` or `Handler.skip(reason)`.
97
+ *
98
+ * @since @next
99
+ */
100
+ type Preparation<P> = Prepared<P> | Skip;
101
+ /** The value that a prepare phase passes to its apply phase. */
102
+ type PreparedValue<T> = T extends Prepared<infer P> ? P : never;
103
+ /**
104
+ * Ends a prepare phase with the value its apply phase receives. Wrapping the value keeps
105
+ * it apart from a skip, whatever its shape.
106
+ *
107
+ * @since @next
108
+ */
109
+ declare function prepared(): Prepared<void>;
110
+ declare function prepared<P>(value: P): Prepared<P>;
111
+ /**
112
+ * Ends a prepare phase by skipping the occurrence. The apply phase does not run.
113
+ *
114
+ * @since @next
115
+ */
116
+ declare const skip: (reason: string) => Skip;
117
+ /**
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.
121
+ *
122
+ * @since @next
123
+ */
124
+ type Step<E, R> = Skip | {
125
+ readonly _tag: "Apply";
126
+ readonly apply: Effect.Effect<void, E, R>;
127
+ } | {
128
+ readonly _tag: "Confirm";
129
+ readonly verify: Effect.Effect<void, E, R> | undefined;
130
+ };
131
+ declare const TypeId$1 = "~deltafold/Handler";
132
+ /**
133
+ * Implements one action instance. `E` and `R` are the errors and Effect services of both
134
+ * phases together. A prepared value stays inside the handler, so handlers with
135
+ * different prepared values share this type.
136
+ *
137
+ * @since @next
138
+ */
139
+ type Handler<out A extends Any$2, out E = never, out R = never> = {
140
+ readonly [TypeId$1]: typeof TypeId$1;
40
141
  readonly action: A;
41
- /** Runs the action body. */
42
- readonly body: Effect.Effect<void, E, R>;
43
- /** Decides whether the body applies. `false` skips the occurrence. */
44
- readonly precondition: Effect.Effect<boolean, E, R> | undefined;
45
- /** Explains a skip when the precondition returns `false`. */
46
- readonly skipReason: string;
142
+ /** A `manual` handler has no phases of its own: a person does the work. */
143
+ readonly performer: Performer;
144
+ /** Whether the handler has a prepare phase. */
145
+ readonly prepares: boolean;
146
+ /**
147
+ * Runs the prepare phase, if any, and resolves to the next step. Both phases share
148
+ * `scope`, the occurrence's scope, so resources acquired while preparing stay open
149
+ * until the executor closes it after the occurrence ends.
150
+ */
151
+ readonly prepare: (scope: Scope.Scope) => Effect.Effect<Step<E, R>, E, R>;
47
152
  };
48
153
  /**
49
154
  * Any handler.
50
155
  *
51
156
  * @since @next
52
157
  */
53
- type Any = Handler<Any$1, any, any>;
158
+ type Any$1 = Handler<Any$2, any, any>;
54
159
  /**
55
160
  * The errors of a handler or a union of handlers.
56
161
  *
57
162
  * @since @next
58
163
  */
59
- 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;
60
165
  /**
61
166
  * The Effect services of a handler or a union of handlers.
62
167
  *
63
168
  * @since @next
64
169
  */
65
- type Services<H> = H extends Handler<any, any, infer R> ? R : never;
170
+ type Services$1<H> = H extends Handler<any, any, infer R> ? R : never;
66
171
  /**
67
172
  * The action identifiers implemented by a handler or a union of handlers.
68
173
  *
@@ -70,28 +175,40 @@ type Services<H> = H extends Handler<any, any, infer R> ? R : never;
70
175
  */
71
176
  type ActionId<H> = H extends Handler<infer A, any, any> ? A["id"] : never;
72
177
  /** @since @next */
73
- declare const isHandler: (value: unknown) => value is Any;
74
- type SkipReason<P> = string | ((payload: P) => string);
178
+ declare const isHandler: (value: unknown) => value is Any$1;
75
179
  /**
76
180
  * Named Effect services that a Promise handler declares.
77
181
  *
78
182
  * @since @next
79
183
  */
80
- type ServiceMap = {
81
- readonly [name: string | symbol]: Context.Key<any, any>;
82
- };
83
- type NoServices = Record<never, never>;
184
+ type ServiceMap = ServiceMap$1;
84
185
  /**
85
186
  * The second argument of Promise handler callbacks: the `AbortSignal` that
86
187
  * `Effect.tryPromise` aborts on interruption, and the declared services, resolved.
87
188
  *
88
189
  * @since @next
89
190
  */
90
- type PromiseContext<S extends ServiceMap = NoServices> = {
91
- readonly signal: AbortSignal;
92
- readonly services: { readonly [K in keyof S]: S[K]["Service"]; };
191
+ type PromiseContext<S extends ServiceMap = NoServices> = PromiseContext$1<S>;
192
+ /**
193
+ * The second argument of a Promise apply phase: the Promise context and the action
194
+ * payload.
195
+ *
196
+ * @since @next
197
+ */
198
+ type PromiseApplyContext<Payload, S extends ServiceMap = NoServices> = PromiseContext<S> & {
199
+ readonly payload: Payload;
200
+ };
201
+ /**
202
+ * A Promise handler with a prepare phase. `prepare` reads state and returns
203
+ * `Handler.prepared(value)` or `Handler.skip(reason)`; `apply` receives the value. Each
204
+ * phase gets its own signal.
205
+ *
206
+ * @since @next
207
+ */
208
+ type PromisePhases<Payload, T extends Preparation<unknown>, S extends ServiceMap> = {
209
+ readonly prepare: (payload: Payload, context: PromiseContext<S>) => PromiseLike<T> | T;
210
+ readonly apply: (prepared: PreparedValue<T>, context: PromiseApplyContext<Payload, S>) => PromiseLike<unknown>;
93
211
  };
94
- type ServiceIds<S extends ServiceMap> = ValueOf<{ [K in keyof S]: S[K] extends Context.Key<infer I, any> ? I : never; }>;
95
212
  /**
96
213
  * Recognizes a declared rejection: a schema, or a type guard such as an `instanceof`
97
214
  * check. Guards must declare their parameter type, for example
@@ -99,10 +216,9 @@ type ServiceIds<S extends ServiceMap> = ValueOf<{ [K in keyof S]: S[K] extends C
99
216
  *
100
217
  * @since @next
101
218
  */
102
- type ErrorGuard = Schema.Top | ((cause: unknown) => cause is any);
103
- type GuardedError<G> = G extends Schema.Top ? G["Type"] : G extends ((cause: unknown) => cause is infer E) ? E : never;
219
+ type ErrorGuard = ErrorGuard$1;
104
220
  /** @since @next */
105
- type PromiseOptions$1<P, S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>> = {
221
+ type PromiseOptions$2<S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>> = {
106
222
  /** Effect services resolved for the callbacks and added to the handler requirements. */
107
223
  readonly services?: S;
108
224
  /**
@@ -111,14 +227,15 @@ type PromiseOptions$1<P, S extends ServiceMap, G extends ReadonlyArray<ErrorGuar
111
227
  * those errors.
112
228
  */
113
229
  readonly errors?: G;
114
- /** Read-only precondition. Returning `false` skips the occurrence. */
115
- readonly when?: (payload: P, context: PromiseContext<S>) => boolean | PromiseLike<boolean>;
116
- readonly skipReason?: SkipReason<P>;
117
230
  };
231
+ type PromiseHandler<A extends Any$2, S extends ServiceMap, G> = Handler<A, GuardedError<G> | UnexpectedHandlerError, ServiceIds<S>>;
118
232
  /**
119
233
  * Implements an action with Promise callbacks. The callbacks run lazily through
120
- * `Effect.tryPromise`, and receive its `AbortSignal` and the declared services in
121
- * their second argument.
234
+ * `Effect.tryPromise`, and receive its `AbortSignal` and the declared services.
235
+ *
236
+ * Pass one callback to apply the action directly, or `{ prepare, apply }` to decide
237
+ * first. `prepare` must only read: a dry run calls it and never calls `apply`. A real
238
+ * run calls `apply` once with the prepared value.
122
239
  *
123
240
  * @example
124
241
  * ```ts
@@ -131,24 +248,229 @@ type PromiseOptions$1<P, S extends ServiceMap, G extends ReadonlyArray<ErrorGuar
131
248
  * );
132
249
  * ```
133
250
  *
251
+ * @example
252
+ * ```ts
253
+ * Handler.promise(renameTimeout, {
254
+ * prepare: async ({ file, from }, { signal }) => {
255
+ * const config = await readConfig(file, { signal });
256
+ * return from in config ? Handler.prepared(config) : Handler.skip(`${file} has no ${from}`);
257
+ * },
258
+ * apply: async (config, { payload, signal }) => {
259
+ * await writeConfig(payload.file, rename(config, payload), { signal });
260
+ * },
261
+ * });
262
+ * ```
263
+ *
264
+ * @since @next
265
+ */
266
+ declare function promise$1<A extends Any$2, 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$1<A extends Any$2, 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]>;
268
+ /**
269
+ * The second argument of an Effect apply phase.
270
+ *
271
+ * @since @next
272
+ */
273
+ type EffectApplyContext<Payload> = {
274
+ readonly payload: Payload;
275
+ };
276
+ /**
277
+ * An Effect handler with a prepare phase. `prepare` reads state and succeeds with
278
+ * `Handler.prepared(value)` or `Handler.skip(reason)`; `apply` receives the value.
279
+ *
280
+ * @since @next
281
+ */
282
+ type EffectPhases<Payload, T extends Preparation<unknown>, E1, R1, E2, R2> = {
283
+ readonly prepare: (payload: Payload) => Effect.Effect<T, E1, R1>;
284
+ readonly apply: (prepared: PreparedValue<T>, context: EffectApplyContext<Payload>) => Effect.Effect<unknown, E2, R2>;
285
+ };
286
+ /**
287
+ * Implements an action with an Effect. The handler keeps its own errors and services,
288
+ * and stops through native Effect interruption.
289
+ *
290
+ * Pass one function to apply the action directly, or `{ prepare, apply }` to decide
291
+ * first. `prepare` must only read: a dry run runs it and never runs `apply`. A real run
292
+ * runs `apply` once with the prepared value. Both phases run in the occurrence's
293
+ * `Scope`, so a resource acquired while preparing, such as a lock, stays open until the
294
+ * occurrence ends; the handler does not require `Scope`.
295
+ *
296
+ * @example
297
+ * ```ts
298
+ * Handler.effect(renameTimeout, {
299
+ * prepare: ({ file, from }) =>
300
+ * Effect.gen(function* () {
301
+ * const files = yield* ConfigFiles;
302
+ * const config = yield* files.lock(file);
303
+ * return from in config.data ? Handler.prepared(config) : Handler.skip(`${file} has no ${from}`);
304
+ * }),
305
+ * apply: (config, { payload }) => config.write(rename(config.data, payload)),
306
+ * });
307
+ * ```
308
+ *
134
309
  * @since @next
135
310
  */
136
- declare const promise: <A extends Any$1, const S extends ServiceMap = NoServices, const G extends ReadonlyArray<ErrorGuard> = []>(action: A, run: (payload: A["payload"], context: PromiseContext<S>) => PromiseLike<unknown>, options?: PromiseOptions$1<A["payload"], S, G>) => Handler<A, GuardedError<G[number]> | UnexpectedHandlerError, ServiceIds<S>>;
311
+ declare function effect$2<A extends Any$2, 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$2<A extends Any$2, 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>>;
137
313
  /** @since @next */
138
- type EffectOptions<P, E, R> = {
139
- /** Read-only precondition. Succeeding with `false` skips the occurrence. */
140
- readonly when?: (payload: P) => Effect.Effect<boolean, E, R>;
141
- readonly skipReason?: SkipReason<P>;
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>;
142
325
  };
143
326
  /**
144
- * Implements an action with an Effect. The body keeps its own errors and services, and
145
- * stops through native Effect interruption.
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 @next
345
+ */
346
+ declare function manual<A extends Any$2>(action: A): Handler<A>;
347
+ declare function manual<A extends Any$2, 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 @next */
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 @next
361
+ */
362
+ declare function manualEffect<A extends Any$2>(action: A): Handler<A>;
363
+ declare function manualEffect<A extends Any$2, 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, Error, Interaction, PromiseOptions$1 as PromiseOptions, Request, Services, UnexpectedInteractionError, effect$1 as effect, isInteraction, 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 @next
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 @next
379
+ */
380
+ type Request<A extends Any$2 = Any$2> = {
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 @next
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 = "~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 @next
412
+ */
413
+ type Interaction<out E = never, out R = never> = {
414
+ readonly [TypeId]: typeof TypeId;
415
+ readonly confirm: (request: Request) => Effect.Effect<Answer, E, R>;
416
+ };
417
+ /**
418
+ * Any interaction.
419
+ *
420
+ * @since @next
421
+ */
422
+ type Any = Interaction<any, any>;
423
+ /**
424
+ * The errors of an interaction.
146
425
  *
147
426
  * @since @next
148
427
  */
149
- declare const effect$1: <A extends Any$1, E = never, R = never, E2 = never, R2 = never>(action: A, run: (payload: A["payload"]) => Effect.Effect<unknown, E, R>, options?: EffectOptions<A["payload"], E2, R2>) => Handler<A, E | E2, R | R2>;
428
+ type Error<I> = I extends Interaction<infer E, any> ? E : never;
429
+ /**
430
+ * The Effect services of an interaction.
431
+ *
432
+ * @since @next
433
+ */
434
+ type Services<I> = I extends Interaction<any, infer R> ? R : never;
435
+ /** @since @next */
436
+ declare const isInteraction: (value: unknown) => value is Any;
437
+ /** @since @next */
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 @next
463
+ */
464
+ declare const promise: <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 @next
470
+ */
471
+ declare const effect$1: <E = never, R = never>(confirm: (request: Request) => Effect.Effect<Answer, E, R>) => Interaction<E | UnexpectedInteractionError, R>;
150
472
  declare namespace executor_d_exports {
151
- export { CoverageIssue, Errors, ExecutionError, ExecutionFailed, ExecutionInterrupted, HandlerCoverageError, InterruptReason, OccurrenceReport, Options, Outcome, PromiseOptions, Report, Requirements, Uncovered, effect, runPromise };
473
+ export { CoverageIssue, Errors, ExecutionError, ExecutionFailed, ExecutionInterrupted, HandlerCoverageError, InteractionUnavailable, InterruptReason, OccurrenceReport, Options, Outcome, PromiseOptions, Report, Requirements, Uncovered, effect, runPromise };
152
474
  }
153
475
  /**
154
476
  * What happened to one occurrence, or what a dry run predicts.
@@ -157,9 +479,23 @@ declare namespace executor_d_exports {
157
479
  */
158
480
  type Outcome<E = unknown> = {
159
481
  readonly _tag: "Completed";
482
+ readonly performer: "automated";
483
+ } | {
484
+ readonly _tag: "Completed";
485
+ readonly performer: "manual";
486
+ /**
487
+ * What supports completion. `asserted`: the person said so and nothing checked
488
+ * it. `verified`: the person said so and the handler's `verify` check passed.
489
+ * Neither proves how the work was done.
490
+ */
491
+ readonly confirmation: "asserted" | "verified";
160
492
  } | {
161
493
  readonly _tag: "Skipped";
162
494
  readonly reason: string;
495
+ } |
496
+ /** The person asked to confirm manual work answered that it is not done. */
497
+ {
498
+ readonly _tag: "Declined";
163
499
  } | {
164
500
  readonly _tag: "Failed";
165
501
  readonly phase: Phase;
@@ -181,27 +517,35 @@ type Outcome<E = unknown> = {
181
517
  /** Not started because execution stopped first. */
182
518
  {
183
519
  readonly _tag: "Unattempted";
184
- } | {
520
+ } |
521
+ /**
522
+ * `evaluated`: whether a prepare phase ran and decided to apply. A `manual` occurrence
523
+ * would wait for a person; a dry run never asks.
524
+ */
525
+ {
185
526
  readonly _tag: "WouldExecute";
186
527
  readonly evaluated: boolean;
528
+ readonly performer: Performer;
187
529
  } | {
188
530
  readonly _tag: "WouldSkip";
189
531
  readonly reason: string;
190
532
  } | {
191
533
  readonly _tag: "Undetermined";
192
534
  readonly reason: string;
535
+ /** A `manual` occurrence would wait for a person if it executes. */
536
+ readonly performer: Performer;
193
537
  } | {
194
- readonly _tag: "PreconditionFailed";
538
+ readonly _tag: "PreparationFailed";
195
539
  readonly error: E | undefined;
196
540
  readonly cause: Cause.Cause<E>;
197
541
  };
198
542
  /** @since @next */
199
- type OccurrenceReport<A extends Any$1 = Any$1, E = unknown> = {
543
+ type OccurrenceReport<A extends Any$2 = Any$2, E = unknown> = {
200
544
  readonly occurrence: Occurrence<A>;
201
545
  readonly outcome: Outcome<E>;
202
546
  };
203
547
  /** @since @next */
204
- type Report<A extends Any$1 = Any$1, E = unknown> = {
548
+ type Report<A extends Any$2 = Any$2, E = unknown> = {
205
549
  readonly _tag: "Report";
206
550
  readonly mode: "execute" | "dry-run";
207
551
  readonly status: "completed" | "failed" | "interrupted" | "not-started" | "would-complete" | "would-fail";
@@ -210,7 +554,10 @@ type Report<A extends Any$1 = Any$1, E = unknown> = {
210
554
  readonly route: string;
211
555
  /** Every occurrence in plan order. */
212
556
  readonly occurrences: ReadonlyArray<OccurrenceReport<A, E>>;
213
- /** Whether any action body started. A started body may have partially changed state. */
557
+ /**
558
+ * Whether any apply phase started or any person was asked to do manual work. Either
559
+ * may have partially changed state.
560
+ */
214
561
  readonly bodiesStarted: boolean;
215
562
  /** Progress is not persisted. Rerunning the plan repeats completed actions. */
216
563
  readonly persistence: "none";
@@ -238,29 +585,48 @@ declare const HandlerCoverageBase: new <A extends Record<string, any> = {}>(args
238
585
  readonly _tag: "HandlerCoverageError";
239
586
  } & Readonly<A>;
240
587
  /**
241
- * Handler coverage failed before any precondition or body ran. Every occurrence needs
242
- * exactly one handler, for the same action definition: the same identifier, kind, and
243
- * payload. For an occurrence that a rule produced, the issue names the rule and the
244
- * occurrences it replaced.
588
+ * Handler coverage failed before any handler phase ran. Every occurrence needs exactly
589
+ * one handler, for the same action definition: the same identifier, kind, and payload.
590
+ * For an occurrence that a rule produced, the issue names the rule and the occurrences
591
+ * it replaced.
245
592
  *
246
593
  * @since @next
247
594
  */
248
- declare class HandlerCoverageError<A extends Any$1 = Any$1> extends HandlerCoverageBase<{
595
+ declare class HandlerCoverageError<A extends Any$2 = Any$2> extends HandlerCoverageBase<{
249
596
  readonly issues: ReadonlyArray<CoverageIssue>;
250
597
  readonly report: Report<A, never>;
251
598
  }> {
252
599
  get message(): string;
253
600
  }
601
+ 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 & {
602
+ readonly _tag: "InteractionUnavailable";
603
+ } & Readonly<A>;
604
+ /**
605
+ * The plan has manual handlers, and the run has no `interaction` to ask a person. The
606
+ * run fails before any handler phase or prompt.
607
+ *
608
+ * @since @next
609
+ */
610
+ declare class InteractionUnavailable<A extends Any$2 = Any$2> extends InteractionUnavailableBase<{
611
+ /** The occurrences that a manual handler covers, in plan order. */
612
+ readonly occurrences: ReadonlyArray<Occurrence<A>>;
613
+ readonly report: Report<A, never>;
614
+ }> {
615
+ get message(): string;
616
+ }
254
617
  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 & {
255
618
  readonly _tag: "ExecutionFailed";
256
619
  } & Readonly<A>;
257
620
  /**
258
- * An occurrence failed. Execution stopped admitting new actions; started ones settled.
621
+ * An occurrence failed, or a person declined manual work. Execution stopped admitting
622
+ * new actions; started ones settled.
259
623
  *
260
624
  * @since @next
261
625
  */
262
- declare class ExecutionFailed<A extends Any$1 = Any$1, E = unknown> extends ExecutionFailedBase<{
626
+ declare class ExecutionFailed<A extends Any$2 = Any$2, E = unknown> extends ExecutionFailedBase<{
263
627
  readonly failures: ReadonlyArray<OccurrenceReport<A, E>>;
628
+ /** Manual occurrences that a person declined. */
629
+ readonly declined: ReadonlyArray<OccurrenceReport<A, E>>;
264
630
  readonly report: Report<A, E>;
265
631
  }> {
266
632
  get message(): string;
@@ -281,23 +647,23 @@ type InterruptReason = "cancelled" | "timeout" | "handler";
281
647
  *
282
648
  * @since @next
283
649
  */
284
- declare class ExecutionInterrupted<A extends Any$1 = Any$1, E = unknown> extends ExecutionInterruptedBase<{
650
+ declare class ExecutionInterrupted<A extends Any$2 = Any$2, E = unknown> extends ExecutionInterruptedBase<{
285
651
  readonly reason: InterruptReason;
286
652
  readonly report: Report<A, E>;
287
653
  }> {
288
654
  get message(): string;
289
655
  }
290
656
  /** @since @next */
291
- type ExecutionError<A extends Any$1, E> = HandlerCoverageError<A> | ExecutionFailed<A, E> | ExecutionInterrupted<A, E>;
657
+ type ExecutionError<A extends Any$2, E> = HandlerCoverageError<A> | InteractionUnavailable<A> | ExecutionFailed<A, E> | ExecutionInterrupted<A, E>;
292
658
  /**
293
659
  * Action identifiers of a statically covered plan that no handler in the array
294
660
  * implements.
295
661
  *
296
662
  * @since @next
297
663
  */
298
- 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;
664
+ type Uncovered<A extends Any$2, H, C extends Coverage> = "runtime" extends C ? never : A extends Any$2 ? string extends A["id"] ? never : A["id"] extends ActionId<H> ? never : A["id"] : never;
299
665
  /** Rejects a handler array that leaves statically known actions uncovered, naming them. */
300
- type CoverageCheck<A extends Any$1, H, C extends Coverage> = [Uncovered<A, H, C>] extends [never] ? unknown : {
666
+ type CoverageCheck<A extends Any$2, H, C extends Coverage> = [Uncovered<A, H, C>] extends [never] ? unknown : {
301
667
  readonly handlers: `Missing a handler for action "${Uncovered<A, H, C>}"`;
302
668
  };
303
669
  /**
@@ -305,25 +671,35 @@ type CoverageCheck<A extends Any$1, H, C extends Coverage> = [Uncovered<A, H, C>
305
671
  *
306
672
  * @since @next
307
673
  */
308
- type Errors<H> = Error<H>;
674
+ type Errors<H, I = never> = Error$1<H> | Error<I>;
309
675
  /**
310
- * Effect services an execution requires: the services of its handlers.
676
+ * Effect services an execution requires: the services of its handlers and of its
677
+ * interaction.
311
678
  *
312
679
  * @since @next
313
680
  */
314
- type Requirements<H> = Services<H>;
681
+ type Requirements<H, I = never> = Services$1<H> | Services<I>;
315
682
  /** @since @next */
316
- type Options<H extends Any> = {
683
+ type Options<H extends Any$1, I extends Any = never> = {
317
684
  readonly handlers?: ReadonlyArray<H>;
318
685
  /**
319
- * Evaluate preconditions without running any action body. A precondition that may
320
- * depend on an earlier action is reported `Undetermined`, because the dry run does not
321
- * apply that action.
686
+ * Asks a person to confirm the work of manual handlers. A run whose plan has manual
687
+ * handlers fails with `InteractionUnavailable` before it starts when this is absent.
688
+ * A dry run never asks and does not need it.
689
+ */
690
+ readonly interaction?: I;
691
+ /**
692
+ * Run prepare phases without running any apply phase. A prepare phase that may
693
+ * depend on an earlier action is reported `Undetermined`, because the dry run does
694
+ * not apply that action.
322
695
  */
323
696
  readonly dryRun?: boolean;
324
697
  /**
325
- * Per-occurrence limit for a precondition or body. Exceeding it interrupts that action
326
- * and stops admitting new ones. It applies to dry-run preconditions too.
698
+ * Limit for each phase of an occurrence: the prepare phase and the apply phase each
699
+ * get the full limit, and so does the verification of manual work. Exceeding it
700
+ * interrupts that action and stops admitting new ones. It applies to dry-run prepare
701
+ * phases too. It never limits the wait for a person to confirm manual work; cancel
702
+ * the run to end that wait.
327
703
  */
328
704
  readonly timeout?: Duration.Input;
329
705
  /**
@@ -333,10 +709,16 @@ type Options<H extends Any> = {
333
709
  readonly settleTimeout?: Duration.Input;
334
710
  };
335
711
  /**
336
- * Runs a plan as an Effect. Coverage is checked before any precondition or body runs.
337
- * Steps are sequential barriers; parallel groups run their branches concurrently. On
338
- * failure, no new action starts, and actions already running settle before the effect
339
- * fails with the partial report.
712
+ * Runs a plan as an Effect. Coverage, and the interaction that manual handlers need,
713
+ * are checked before any handler phase runs. Steps
714
+ * are sequential barriers; parallel groups run their branches concurrently. On failure,
715
+ * no new action starts, and actions already running settle before the effect fails
716
+ * with the partial report.
717
+ *
718
+ * Each occurrence has its own scope, shared by its phases and closed when it ends. An
719
+ * interrupted Promise that has not settled keeps its occurrence's scope open until it
720
+ * settles, after the effect has ended. Services that the caller provides stay the
721
+ * caller's to release.
340
722
  *
341
723
  * To cancel, interrupt the fiber. Interruption reaches running actions and aborts the
342
724
  * signal passed to Promise callbacks. The effect then ends as interrupted, without a
@@ -344,35 +726,39 @@ type Options<H extends Any> = {
344
726
  *
345
727
  * @since @next
346
728
  */
347
- 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>>;
729
+ declare const effect: <A extends Any$2, C extends Coverage, H extends Any$1 = never, I extends Any = never>(plan: Plan<A, C>, options: Options<H, I> & CoverageCheck<A, H, C>) => Effect.Effect<Report<A, Errors<H, I>>, ExecutionError<A, Errors<H, I>>, Requirements<H, I>>;
348
730
  type ServicesOption<R, LE> = [R] extends [never] ? {
349
- /** Handlers without Effect services need none. */
731
+ /** Handlers and interactions without Effect services need none. */
350
732
  readonly services?: Context.Context<never> | Layer.Layer<never, LE>;
351
733
  } : {
352
- /** Supplies the handlers' Effect services. */
734
+ /** Supplies the Effect services of the handlers and the interaction. */
353
735
  readonly services: Context.Context<R> | Layer.Layer<R, LE>;
354
736
  };
355
737
  /** @since @next */
356
- type PromiseOptions<H extends Any> = Options<H> & {
738
+ type PromiseOptions<H extends Any$1, I extends Any = never> = Options<H, I> & {
357
739
  /**
358
- * Explicit cancellation. Aborting stops admission, interrupts running actions, and
359
- * rejects with `ExecutionInterrupted` and the partial report.
740
+ * Explicit cancellation. Aborting stops admission, interrupts running actions and
741
+ * pending confirmations, and rejects with `ExecutionInterrupted` and the partial
742
+ * report.
360
743
  */
361
744
  readonly signal?: AbortSignal;
362
745
  };
363
746
  /**
364
747
  * Runs a plan and returns a Promise. It rejects with `HandlerCoverageError`,
365
- * `ExecutionFailed`, or `ExecutionInterrupted`, each carrying the partial report.
748
+ * `InteractionUnavailable`, `ExecutionFailed`, or `ExecutionInterrupted`, each carrying
749
+ * the partial report.
366
750
  * Building a supplied services layer can also reject with the layer's own error,
367
751
  * without a report.
368
752
  *
369
- * A services layer is built for this run and finalized when the run ends. A services
370
- * context stays owned by the caller. A Promise callback that ignores its signal can keep
371
- * running after cancellation or a timeout, beyond `settleTimeout`, and so after the
372
- * run's layer resources are finalized; the report marks it as possibly still running.
753
+ * A services layer is built for this run. A services context stays owned by the
754
+ * caller. A Promise callback that ignores its signal can keep running after
755
+ * cancellation or a timeout, beyond `settleTimeout`; the report marks it as possibly
756
+ * still running. Its occurrence's scope and the run's services layer then stay open
757
+ * until it settles, possibly forever, and close in that order. A cleanup failure after
758
+ * the Promise resolved is logged through Effect.
373
759
  *
374
760
  * @since @next
375
761
  */
376
- 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>>>;
377
- 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 };
762
+ declare const runPromise: <A extends Any$2, C extends Coverage, H extends Any$1 = never, I extends Any = never, LE = never>(plan: Plan<A, C>, options: PromiseOptions<H, I> & ServicesOption<Requirements<H, I>, LE> & CoverageCheck<A, H, C>) => Promise<Report<A, Errors<H, I>>>;
763
+ 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, 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 };
378
764
  //# sourceMappingURL=index.d.ts.map