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.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { t as __exportAll } from "./rolldown-runtime-D8jQpDG7.js";
2
- import { Array as Array$1, Cause, Context, Data, Deferred, Duration, Effect, Equal, Exit, Fiber, Graph, Layer, Option, Order, Predicate, Result, Schema, Scope, SemVer } from "effect";
2
+ import { Array as Array$1, Cause, Clock, Context, Data, Deferred, Duration, Effect, Equal, Exit, Fiber, Graph, Layer, Option, Order, Predicate, Result, Schema, Scope, SemVer, Semaphore } from "effect";
3
3
  import dedentText from "dedent";
4
4
  // src/foundation/action.ts
5
5
  var action_exports = /* @__PURE__ */ __exportAll({
@@ -28,7 +28,7 @@ var action_exports = /* @__PURE__ */ __exportAll({
28
28
  * });
29
29
  * ```
30
30
  *
31
- * @since @next
31
+ * @since 0.0.1
32
32
  */
33
33
  const define$1 = (kind, options = {}) => {
34
34
  const describe = options.describe ?? (() => kind);
@@ -48,7 +48,7 @@ const define$1 = (kind, options = {}) => {
48
48
  /**
49
49
  * Mentions an action in prose without declaring another occurrence.
50
50
  *
51
- * @since @next
51
+ * @since 0.0.1
52
52
  */
53
53
  const ref = (action) => ({
54
54
  _tag: "ActionRef",
@@ -57,7 +57,7 @@ const ref = (action) => ({
57
57
  /**
58
58
  * Declares steps that run one after another.
59
59
  *
60
- * @since @next
60
+ * @since 0.0.1
61
61
  */
62
62
  const sequence = (children) => ({
63
63
  _tag: "Sequence",
@@ -67,20 +67,20 @@ const sequence = (children) => ({
67
67
  * Declares independent branches that may run concurrently. Each branch can be a single
68
68
  * step or a sequence.
69
69
  *
70
- * @since @next
70
+ * @since 0.0.1
71
71
  */
72
72
  const parallel = (branches, options = {}) => ({
73
73
  _tag: "Parallel",
74
74
  branches,
75
75
  concurrency: options.concurrency ?? "unbounded"
76
76
  });
77
- /** @since @next */
77
+ /** @since 0.0.1 */
78
78
  const isAction = (value) => Predicate.isTagged(value, "Action") && Predicate.hasProperty(value, "id");
79
- /** @since @next */
79
+ /** @since 0.0.1 */
80
80
  const isRef = (value) => Predicate.isTagged(value, "ActionRef");
81
- /** @since @next */
81
+ /** @since 0.0.1 */
82
82
  const isSequence = (value) => Predicate.isTagged(value, "Sequence");
83
- /** @since @next */
83
+ /** @since 0.0.1 */
84
84
  const isParallel = (value) => Predicate.isTagged(value, "Parallel");
85
85
  // src/foundation/template.ts
86
86
  const placeholder = "\0";
@@ -142,10 +142,10 @@ function make$6(id, metadata = {}, relations = {}) {
142
142
  * `;
143
143
  * ```
144
144
  *
145
- * @since @next
145
+ * @since 0.0.1
146
146
  */
147
147
  const define = () => ({ make: make$6 });
148
- /** @since @next */
148
+ /** @since 0.0.1 */
149
149
  const isChange = (value) => Predicate.isTagged(value, "Change");
150
150
  // src/features/execution/settlement.ts
151
151
  const SettlementReference = Context.Reference("deltafold/Settlement", { defaultValue: () => ({
@@ -172,21 +172,53 @@ const trackPromise = (start) => Effect.suspend(() => {
172
172
  if (Option.isNone(settled)) settlement.unsettled(settles);
173
173
  })));
174
174
  });
175
+ // src/features/execution/promise-callback.ts
176
+ const declaredError = (guards) => (cause) => guards.some((guard) => Schema.isSchema(guard) ? Schema.is(guard)(cause) : guard(cause));
177
+ /**
178
+ * Turns Promise callbacks into Effects. Declared services are resolved before each
179
+ * call, rejections that a guard recognizes keep their type, and `unexpected` wraps the
180
+ * rest.
181
+ */
182
+ const adaptPromise = (options) => {
183
+ const isDeclared = declaredError(options.errors ?? []);
184
+ const services = options.services ?? {};
185
+ const resolve = Effect.map(Effect.context(), (context) => Object.fromEntries(Reflect.ownKeys(services).map((name) => [name, Context.get(context, services[name])])));
186
+ return (callback, unexpected) => Effect.flatMap(resolve, (resolved) => trackPromise((capture) => Effect.tryPromise({
187
+ try: (signal) => capture(Promise.resolve(callback({
188
+ signal,
189
+ services: resolved
190
+ }))),
191
+ catch: (cause) => isDeclared(cause) ? cause : unexpected(cause)
192
+ })));
193
+ };
175
194
  // src/features/execution/handler.ts
176
195
  var handler_exports = /* @__PURE__ */ __exportAll({
177
196
  UnexpectedHandlerError: () => UnexpectedHandlerError,
178
- effect: () => effect$1,
197
+ VerificationFailed: () => VerificationFailed,
198
+ effect: () => effect$3,
179
199
  isHandler: () => isHandler,
200
+ manual: () => manual,
201
+ manualEffect: () => manualEffect,
180
202
  prepared: () => prepared,
181
- promise: () => promise,
203
+ promise: () => promise$2,
182
204
  skip: () => skip
183
205
  });
184
206
  /**
207
+ * A person confirmed manual work, and the handler's `verify` check returned `false`.
208
+ *
209
+ * @since 0.2.0
210
+ */
211
+ var VerificationFailed = class extends Data.TaggedError("VerificationFailed") {
212
+ get message() {
213
+ return `Manual work for action "${this.actionId}" was confirmed, but its verification check did not pass`;
214
+ }
215
+ };
216
+ /**
185
217
  * A Promise handler rejected or threw a value that none of its declared error guards
186
218
  * recognized, or its prepare phase returned something other than `Handler.prepared` or
187
219
  * `Handler.skip`.
188
220
  *
189
- * @since @next
221
+ * @since 0.0.1
190
222
  */
191
223
  var UnexpectedHandlerError = class extends Data.TaggedError("UnexpectedHandlerError") {
192
224
  get message() {
@@ -204,7 +236,7 @@ function prepared(value) {
204
236
  /**
205
237
  * Ends a prepare phase by skipping the occurrence. The apply phase does not run.
206
238
  *
207
- * @since @next
239
+ * @since 0.1.0
208
240
  */
209
241
  const skip = (reason) => ({
210
242
  [PreparationTypeId]: PreparationTypeId,
@@ -217,33 +249,25 @@ const applyStep = (apply) => ({
217
249
  _tag: "Apply",
218
250
  apply
219
251
  });
220
- const TypeId = "~deltafold/Handler";
221
- /** @since @next */
222
- const isHandler = (value) => Predicate.hasProperty(value, TypeId);
252
+ const TypeId$2 = "~deltafold/Handler";
253
+ /** @since 0.0.1 */
254
+ const isHandler = (value) => Predicate.hasProperty(value, TypeId$2);
223
255
  const make$5 = (action, prepares, prepare) => ({
224
- [TypeId]: TypeId,
256
+ [TypeId$2]: TypeId$2,
225
257
  action,
258
+ performer: "automated",
226
259
  prepares,
227
260
  prepare
228
261
  });
229
- const declaredError = (guards) => (cause) => guards.some((guard) => Schema.isSchema(guard) ? Schema.is(guard)(cause) : guard(cause));
230
- function promise(action, run, options) {
231
- const isDeclared = declaredError(options?.errors ?? []);
232
- const services = options?.services ?? {};
233
- const resolve = Effect.map(Effect.context(), (context) => Object.fromEntries(Reflect.ownKeys(services).map((name) => [name, Context.get(context, services[name])])));
262
+ function promise$2(action, run, options) {
263
+ const adaptCallback = adaptPromise(options ?? {});
234
264
  const unexpected = (phase, cause) => new UnexpectedHandlerError({
235
265
  actionId: action.id,
236
266
  kind: action.kind,
237
267
  phase,
238
268
  cause
239
269
  });
240
- const adapt = (phase, callback) => Effect.flatMap(resolve, (resolved) => trackPromise((capture) => Effect.tryPromise({
241
- try: (signal) => capture(Promise.resolve(callback({
242
- signal,
243
- services: resolved
244
- }))),
245
- catch: (cause) => isDeclared(cause) ? cause : unexpected(phase, cause)
246
- })));
270
+ const adapt = (phase, callback) => adaptCallback(callback, (cause) => unexpected(phase, cause));
247
271
  if (Predicate.isFunction(run)) {
248
272
  const apply = Effect.asVoid(adapt("apply", (context) => run(action.payload, context)));
249
273
  return make$5(action, false, () => Effect.succeed(applyStep(apply)));
@@ -254,19 +278,380 @@ function promise(action, run, options) {
254
278
  }))))));
255
279
  return make$5(action, true, () => prepare);
256
280
  }
257
- function effect$1(action, run) {
281
+ function effect$3(action, run) {
258
282
  if (Predicate.isFunction(run)) {
259
283
  const apply = Effect.asVoid(Effect.suspend(() => run(action.payload)));
260
284
  return make$5(action, false, (scope) => Effect.succeed(applyStep(Scope.provide(apply, scope))));
261
285
  }
262
286
  return make$5(action, true, (scope) => Effect.suspend(() => run.prepare(action.payload)).pipe(Scope.provide(scope), Effect.filterOrElse(isPreparation, () => Effect.die(notAPreparation())), Effect.map((preparation) => preparation._tag === "Skip" ? preparation : applyStep(Scope.provide(Effect.asVoid(Effect.suspend(() => run.apply(preparation.value, { payload: action.payload }))), scope)))));
263
287
  }
288
+ const verified = (action, check) => Effect.flatMap(check, (passed) => passed ? Effect.void : Effect.fail(new VerificationFailed({
289
+ actionId: action.id,
290
+ kind: action.kind
291
+ })));
292
+ const makeManual = (action, verify) => ({
293
+ [TypeId$2]: TypeId$2,
294
+ action,
295
+ performer: "manual",
296
+ prepares: false,
297
+ prepare: (scope) => Effect.succeed({
298
+ _tag: "Confirm",
299
+ verify: verify?.(scope)
300
+ })
301
+ });
302
+ function manual(action, options) {
303
+ const adapt = adaptPromise(options ?? {});
304
+ const verify = options?.verify;
305
+ if (verify === void 0) return makeManual(action, void 0);
306
+ const check = verified(action, adapt((context) => verify(action.payload, context), (cause) => new UnexpectedHandlerError({
307
+ actionId: action.id,
308
+ kind: action.kind,
309
+ phase: "verification",
310
+ cause
311
+ })));
312
+ return makeManual(action, () => check);
313
+ }
314
+ function manualEffect(action, options) {
315
+ const verify = options?.verify;
316
+ if (verify === void 0) return makeManual(action, void 0);
317
+ return makeManual(action, (scope) => Scope.provide(verified(action, Effect.suspend(() => verify(action.payload))), scope));
318
+ }
319
+ // src/features/execution/observation.ts
320
+ const stepIdsOf = (plan) => (occurrence) => plan.steps.find((step) => step.migration === occurrence.migration && step.direction === occurrence.direction)?.id ?? occurrence.migration.id;
321
+ /** Declared occurrences behind an occurrence, through nested replacements, in order. */
322
+ const leavesOf = (occurrence) => occurrence.origin._tag === "Declared" ? [occurrence] : occurrence.origin.replaces.flatMap(leavesOf);
323
+ const sourcesOf = (occurrence, stepIdOf) => [...new Set(leavesOf(occurrence).map(stepIdOf))];
324
+ const occurrencesOfNode = (node) => {
325
+ switch (node._tag) {
326
+ case "Occurrence": return [node];
327
+ case "Sequence": return node.children.flatMap(occurrencesOfNode);
328
+ }
329
+ return node.branches.flatMap(occurrencesOfNode);
330
+ };
331
+ const stepInfoOf = (step, index, plan, stepIdOf) => {
332
+ const occurrences = occurrencesOfNode(step.node);
333
+ const base = {
334
+ id: step.id,
335
+ index,
336
+ migration: step.migration.id,
337
+ direction: step.direction,
338
+ from: step.from.id,
339
+ to: step.to.id,
340
+ occurrences: occurrences.map((occurrence) => occurrence.id),
341
+ absorbs: [...new Set(occurrences.flatMap((occurrence) => sourcesOf(occurrence, stepIdOf)))].filter((id) => id !== step.id)
342
+ };
343
+ if (occurrences.length > 0) return {
344
+ ...base,
345
+ kind: "execute"
346
+ };
347
+ if (!step.omitted) return {
348
+ ...base,
349
+ kind: "prose"
350
+ };
351
+ const omitted = plan.explanations.find((explanation) => explanation._tag === "OmittedStep" && explanation.migration.id === step.migration.id && explanation.direction === step.direction);
352
+ return {
353
+ ...base,
354
+ kind: "omitted",
355
+ reason: omitted?._tag === "OmittedStep" && omitted.reason === "all-actions-removed" ? "all-actions-removed" : "noop"
356
+ };
357
+ };
358
+ const actionInfoOf = (occurrence, step, stepIdOf) => ({
359
+ occurrence: occurrence.id,
360
+ action: occurrence.action.id,
361
+ kind: occurrence.action.kind,
362
+ description: occurrence.action.description,
363
+ migration: occurrence.migration.id,
364
+ direction: occurrence.direction,
365
+ step,
366
+ origin: occurrence.origin._tag === "Declared" ? { _tag: "Declared" } : {
367
+ _tag: "Replacement",
368
+ rule: occurrence.origin.rule.id,
369
+ replaces: occurrence.origin.replaces.map((replaced) => replaced.id)
370
+ },
371
+ sources: sourcesOf(occurrence, stepIdOf)
372
+ });
373
+ /**
374
+ * Reads a handler error's tag once, so a getter cannot pass the check with one value and
375
+ * return another. A tag that cannot be read, even by a throwing getter, is absent.
376
+ */
377
+ const errorTagOf = (error) => {
378
+ try {
379
+ if (!Predicate.hasProperty(error, "_tag")) return void 0;
380
+ const tag = error._tag;
381
+ return typeof tag === "string" ? tag : void 0;
382
+ } catch {
383
+ return;
384
+ }
385
+ };
386
+ /** Copies only the fields observers may see. */
387
+ const summaryOf$1 = (outcome) => {
388
+ switch (outcome._tag) {
389
+ case "Completed": return outcome.performer === "manual" ? {
390
+ _tag: "Completed",
391
+ performer: "manual",
392
+ confirmation: outcome.confirmation
393
+ } : {
394
+ _tag: "Completed",
395
+ performer: "automated"
396
+ };
397
+ case "Skipped": return {
398
+ _tag: "Skipped",
399
+ reason: outcome.reason
400
+ };
401
+ case "Declined": return { _tag: "Declined" };
402
+ case "Failed": return {
403
+ _tag: "Failed",
404
+ phase: outcome.phase,
405
+ errorTag: errorTagOf(outcome.error)
406
+ };
407
+ case "Interrupted": return {
408
+ _tag: "Interrupted",
409
+ phase: outcome.phase,
410
+ reason: outcome.reason,
411
+ settled: outcome.settled
412
+ };
413
+ case "Unattempted": return { _tag: "Unattempted" };
414
+ case "WouldExecute": return {
415
+ _tag: "WouldExecute",
416
+ evaluated: outcome.evaluated,
417
+ performer: outcome.performer
418
+ };
419
+ case "WouldSkip": return {
420
+ _tag: "WouldSkip",
421
+ reason: outcome.reason
422
+ };
423
+ case "Undetermined": return {
424
+ _tag: "Undetermined",
425
+ reason: outcome.reason,
426
+ performer: outcome.performer
427
+ };
428
+ }
429
+ return {
430
+ _tag: "PreparationFailed",
431
+ errorTag: errorTagOf(outcome.error)
432
+ };
433
+ };
434
+ const emptyCounts = () => ({
435
+ Completed: 0,
436
+ Skipped: 0,
437
+ Declined: 0,
438
+ Failed: 0,
439
+ Interrupted: 0,
440
+ Unattempted: 0,
441
+ WouldExecute: 0,
442
+ WouldSkip: 0,
443
+ Undetermined: 0,
444
+ PreparationFailed: 0,
445
+ unsettled: 0
446
+ });
447
+ const noop$1 = {
448
+ runStarted: Effect.void,
449
+ stepStarted: () => Effect.void,
450
+ stepSettled: () => Effect.void,
451
+ phaseStarted: () => Effect.void,
452
+ settled: () => Effect.void,
453
+ runFinished: () => Effect.void,
454
+ interrupted: Effect.void,
455
+ failures: []
456
+ };
457
+ /**
458
+ * Delivery is awaited and serialized: one event at a time, to each observer in order.
459
+ * Counters change under the same lock, so each event's progress is consistent with the
460
+ * order observers see. Observer failures are recorded and never reach the run.
461
+ */
462
+ const makeEmitter = (options) => Effect.gen(function* () {
463
+ const { plan, observers, outcomes, stopped, grace, retain } = options;
464
+ if (observers.length === 0) return noop$1;
465
+ const stepIdOf = stepIdsOf(plan);
466
+ const lock = yield* Semaphore.make(1);
467
+ const failures = [];
468
+ const run = {
469
+ id: options.runId,
470
+ mode: options.mode,
471
+ from: plan.from.id,
472
+ to: plan.to.id,
473
+ route: plan.route.id
474
+ };
475
+ const steps = plan.steps.map((step, index) => stepInfoOf(step, index, plan, stepIdOf));
476
+ const infoOf = new Map(plan.steps.map((step, index) => [step, steps[index]]));
477
+ const ownerOf = /* @__PURE__ */ new Map();
478
+ for (const info of steps) for (const id of info.occurrences) ownerOf.set(id, info.id);
479
+ const state = {
480
+ seq: 0,
481
+ running: /* @__PURE__ */ new Set(),
482
+ actionsFinished: 0,
483
+ stepsFinished: 0,
484
+ started: false,
485
+ finished: false,
486
+ delivering: void 0
487
+ };
488
+ const stepsTotal = steps.filter((info) => info.kind !== "omitted").length;
489
+ const progress = () => ({
490
+ steps: {
491
+ total: stepsTotal,
492
+ finished: state.stepsFinished
493
+ },
494
+ actions: {
495
+ total: plan.occurrences.length,
496
+ running: state.running.size,
497
+ finished: state.actionsFinished
498
+ }
499
+ });
500
+ const countsOf = (occurrences, inFlight) => {
501
+ const counts = emptyCounts();
502
+ for (const occurrence of occurrences) {
503
+ const outcome = outcomes.get(occurrence.id);
504
+ if (outcome === void 0 && inFlight && state.running.has(occurrence.id)) {
505
+ counts.Interrupted += 1;
506
+ counts.unsettled += 1;
507
+ continue;
508
+ }
509
+ const tag = outcome?._tag ?? "Unattempted";
510
+ counts[tag] += 1;
511
+ if (outcome?._tag === "Interrupted" && !outcome.settled) counts.unsettled += 1;
512
+ }
513
+ return counts;
514
+ };
515
+ /**
516
+ * Interrupts an abandoned delivery without waiting for it to stop. The run's services
517
+ * stay open until it does.
518
+ */
519
+ const abandon = (fiber) => Effect.map(Effect.forkDetach(Fiber.interrupt(fiber)), retain);
520
+ /**
521
+ * Bounds a delivery once the run has been stopped, or always when `bounded` is set.
522
+ * The callback runs in its own fiber, with the run's services, so a delivery that
523
+ * cannot be interrupted is still abandoned when the bound passes.
524
+ */
525
+ const deliver = (observer, event, bounded) => Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
526
+ const fiber = yield* Effect.forkDetach(Effect.interruptible(observer.notify(event)), { startImmediately: true });
527
+ const limit = bounded ? Effect.sleep(grace) : Effect.andThen(Deferred.await(stopped), Effect.sleep(grace));
528
+ const result = yield* restore(Effect.raceFirst(Effect.map(Fiber.await(fiber), (exit) => Option.some(Exit.isSuccess(exit) ? exit.value : exit)), Effect.as(limit, Option.none()))).pipe(Effect.onInterrupt(() => abandon(fiber)));
529
+ if (Option.isNone(result)) yield* abandon(fiber);
530
+ return result;
531
+ }));
532
+ const record = (observer, event, result) => {
533
+ if (Option.isNone(result)) failures.push({
534
+ observer,
535
+ event: event._tag,
536
+ seq: event.seq,
537
+ reason: "abandoned",
538
+ cause: Cause.interrupt()
539
+ });
540
+ else if (Exit.isFailure(result.value)) failures.push({
541
+ observer,
542
+ event: event._tag,
543
+ seq: event.seq,
544
+ reason: "failed",
545
+ cause: result.value.cause
546
+ });
547
+ };
548
+ /** Delivers an event to each observer from `first` on, in order. */
549
+ const deliverFrom = (event, first, bounded) => Effect.gen(function* () {
550
+ for (const [offset, observer] of observers.slice(first).entries()) {
551
+ const index = first + offset;
552
+ state.delivering = {
553
+ event,
554
+ observer: index
555
+ };
556
+ record(index, event, yield* deliver(observer, event, bounded));
557
+ }
558
+ state.delivering = void 0;
559
+ });
560
+ const emit = (update, build, bounded = false) => lock.withPermits(1)(Effect.gen(function* () {
561
+ update();
562
+ const timestamp = yield* Clock.currentTimeMillis;
563
+ const event = build({
564
+ run,
565
+ seq: state.seq,
566
+ timestamp,
567
+ progress: progress()
568
+ });
569
+ state.seq += 1;
570
+ yield* deliverFrom(event, 0, bounded);
571
+ }));
572
+ const stepEvent = (step) => infoOf.get(step) ?? stepInfoOf(step, -1, plan, stepIdOf);
573
+ const actionOf = (occurrence) => actionInfoOf(occurrence, ownerOf.get(occurrence.id) ?? stepIdOf(occurrence), stepIdOf);
574
+ const finish = (status, report, bounded) => emit(() => {
575
+ state.finished = true;
576
+ }, (base) => ({
577
+ ...base,
578
+ _tag: "RunFinished",
579
+ status,
580
+ counts: countsOf(plan.occurrences, !report),
581
+ report
582
+ }), bounded);
583
+ /**
584
+ * Ends the stream after fiber interruption. The delivery the interruption cut short is
585
+ * abandoned. If it was `RunFinished`, the observers that had not received it get a
586
+ * report-less one with the same `seq` instead, so each observer hears exactly one.
587
+ */
588
+ const interrupted = Effect.suspend(() => {
589
+ const cut = state.delivering;
590
+ if (cut !== void 0) {
591
+ record(cut.observer, cut.event, Option.none());
592
+ state.delivering = void 0;
593
+ }
594
+ if (!state.started) return Effect.void;
595
+ if (!state.finished) return finish("interrupted", false, true);
596
+ if (cut?.event._tag !== "RunFinished") return Effect.void;
597
+ const event = {
598
+ ...cut.event,
599
+ status: "interrupted",
600
+ counts: countsOf(plan.occurrences, true),
601
+ report: false
602
+ };
603
+ return lock.withPermits(1)(deliverFrom(event, cut.observer + 1, true));
604
+ });
605
+ return {
606
+ runStarted: emit(() => {
607
+ state.started = true;
608
+ }, (base) => ({
609
+ ...base,
610
+ _tag: "RunStarted",
611
+ steps
612
+ })),
613
+ stepStarted: (step) => emit(() => {}, (base) => ({
614
+ ...base,
615
+ _tag: "StepStarted",
616
+ step: stepEvent(step)
617
+ })),
618
+ stepSettled: (step) => emit(() => {
619
+ state.stepsFinished += 1;
620
+ }, (base) => ({
621
+ ...base,
622
+ _tag: "StepSettled",
623
+ step: stepEvent(step),
624
+ counts: countsOf(occurrencesOfNode(step.node), false)
625
+ })),
626
+ phaseStarted: (occurrence, phase) => emit(() => {
627
+ state.running.add(occurrence.id);
628
+ }, (base) => ({
629
+ ...base,
630
+ _tag: "ActionPhaseStarted",
631
+ action: actionOf(occurrence),
632
+ phase
633
+ })),
634
+ settled: (occurrence) => Effect.suspend(() => !outcomes.has(occurrence.id) && !state.running.has(occurrence.id) ? Effect.void : emit(() => {
635
+ state.running.delete(occurrence.id);
636
+ state.actionsFinished += 1;
637
+ }, (base) => ({
638
+ ...base,
639
+ _tag: "ActionSettled",
640
+ action: actionOf(occurrence),
641
+ outcome: summaryOf$1(outcomes.get(occurrence.id) ?? { _tag: "Unattempted" })
642
+ }))),
643
+ runFinished: (status) => finish(status, true, false),
644
+ interrupted,
645
+ failures
646
+ };
647
+ });
264
648
  // src/features/execution/executor.ts
265
649
  var executor_exports = /* @__PURE__ */ __exportAll({
266
650
  ExecutionFailed: () => ExecutionFailed,
267
651
  ExecutionInterrupted: () => ExecutionInterrupted,
268
652
  HandlerCoverageError: () => HandlerCoverageError,
269
- effect: () => effect,
653
+ InteractionUnavailable: () => InteractionUnavailable,
654
+ effect: () => effect$2,
270
655
  runPromise: () => runPromise
271
656
  });
272
657
  const HandlerCoverageBase = Data.TaggedError("HandlerCoverageError");
@@ -276,22 +661,36 @@ const HandlerCoverageBase = Data.TaggedError("HandlerCoverageError");
276
661
  * For an occurrence that a rule produced, the issue names the rule and the occurrences
277
662
  * it replaced.
278
663
  *
279
- * @since @next
664
+ * @since 0.0.1
280
665
  */
281
666
  var HandlerCoverageError = class extends HandlerCoverageBase {
282
667
  get message() {
283
668
  return `Handler coverage failed for ${this.issues.length} occurrence(s): ${this.issues.map((issue) => `${issue._tag.toLowerCase()} handler for "${issue.actionId}" (${issue.description})`).join("; ")}.`;
284
669
  }
285
670
  };
671
+ const InteractionUnavailableBase = Data.TaggedError("InteractionUnavailable");
672
+ /**
673
+ * The plan has manual handlers, and the run has no `interaction` to ask a person. The
674
+ * run fails before any handler phase or prompt.
675
+ *
676
+ * @since 0.2.0
677
+ */
678
+ var InteractionUnavailable = class extends InteractionUnavailableBase {
679
+ get message() {
680
+ return `No interaction is available to confirm manual work for ${this.occurrences.map((occurrence) => `"${occurrence.id}" (${occurrence.action.description})`).join(", ")}. Supply the \`interaction\` option, or bind automated handlers to these actions.`;
681
+ }
682
+ };
683
+ const listIds = (entries) => entries.map((entry) => entry.outcome._tag === "Failed" ? `"${entry.occurrence.id}" (${entry.outcome.phase})` : `"${entry.occurrence.id}"`).join(", ");
286
684
  const ExecutionFailedBase = Data.TaggedError("ExecutionFailed");
287
685
  /**
288
- * An occurrence failed. Execution stopped admitting new actions; started ones settled.
686
+ * An occurrence failed, or a person declined manual work. Execution stopped admitting
687
+ * new actions; started ones settled.
289
688
  *
290
- * @since @next
689
+ * @since 0.0.1
291
690
  */
292
691
  var ExecutionFailed = class extends ExecutionFailedBase {
293
692
  get message() {
294
- return `Execution failed at ${this.failures.map((failure) => `"${failure.occurrence.id}"`).join(", ")}. Completed actions were not rolled back.`;
693
+ return `${[...this.failures.length === 0 ? [] : [`Execution failed at ${listIds(this.failures)}.`], ...this.declined.length === 0 ? [] : [`Manual work was declined at ${listIds(this.declined)}, which stopped the run.`]].join(" ")} Completed actions were not rolled back.`;
295
694
  }
296
695
  };
297
696
  const ExecutionInterruptedBase = Data.TaggedError("ExecutionInterrupted");
@@ -304,7 +703,7 @@ const interruptedBy = {
304
703
  * Explicit cancellation, a configured timeout, or a handler's own interruption stopped
305
704
  * execution.
306
705
  *
307
- * @since @next
706
+ * @since 0.0.1
308
707
  */
309
708
  var ExecutionInterrupted = class extends ExecutionInterruptedBase {
310
709
  get message() {
@@ -348,7 +747,7 @@ const coverage = (plan, handlers) => {
348
747
  issues
349
748
  };
350
749
  };
351
- const report = (plan, mode, status, outcomes, bodiesStarted) => ({
750
+ const report = (plan, mode, status, outcomes, bodiesStarted, observation = []) => ({
352
751
  _tag: "Report",
353
752
  mode,
354
753
  status,
@@ -360,7 +759,8 @@ const report = (plan, mode, status, outcomes, bodiesStarted) => ({
360
759
  outcome: outcomes.get(occurrence.id) ?? { _tag: "Unattempted" }
361
760
  })),
362
761
  bodiesStarted,
363
- persistence: "none"
762
+ persistence: "none",
763
+ observation: [...observation]
364
764
  });
365
765
  const failureOf = (cause) => ({
366
766
  error: Option.getOrUndefined(Cause.findErrorOption(cause)),
@@ -388,11 +788,16 @@ const logCleanupFailure = (owner) => (cause) => Effect.logError("deltafold: clea
388
788
  const makeControl = (options, subscribe) => Effect.gen(function* () {
389
789
  const halt = { reason: void 0 };
390
790
  const cancelled = yield* Deferred.make();
791
+ /** Completes on cancellation or a timeout. Observer deliveries are bounded from then on. */
792
+ const stopped = yield* Deferred.make();
391
793
  const settleTimeout = options.settleTimeout ?? Duration.seconds(5);
392
794
  const stop = (reason) => {
393
795
  halt.reason ??= reason;
796
+ if (reason === "cancelled" || reason === "timeout") Deferred.doneUnsafe(stopped, Exit.void);
394
797
  };
798
+ let cancellationArrived = false;
395
799
  subscribe?.(() => {
800
+ cancellationArrived = true;
396
801
  stop("cancelled");
397
802
  Deferred.doneUnsafe(cancelled, Exit.succeed("cancelled"));
398
803
  });
@@ -400,7 +805,7 @@ const makeControl = (options, subscribe) => Effect.gen(function* () {
400
805
  * Runs one phase, racing it against cancellation and its own timeout. An
401
806
  * interrupted Promise that outlives the settlement grace period goes to `unsettled`.
402
807
  */
403
- const runPhase = (work, unsettled) => Effect.gen(function* () {
808
+ const runPhase = (work, unsettled, timing = "timed") => Effect.gen(function* () {
404
809
  let settled = true;
405
810
  const tracked = work.pipe(Effect.provideService(SettlementReference, {
406
811
  grace: settleTimeout,
@@ -410,7 +815,7 @@ const makeControl = (options, subscribe) => Effect.gen(function* () {
410
815
  }
411
816
  }));
412
817
  const stopSignals = [Deferred.await(cancelled)];
413
- if (options.timeout !== void 0) stopSignals.push(Effect.as(Effect.sleep(options.timeout), "timeout"));
818
+ if (options.timeout !== void 0 && timing === "timed") stopSignals.push(Effect.as(Effect.sleep(options.timeout), "timeout"));
414
819
  const result = yield* Effect.raceFirst(Effect.map(Effect.exit(tracked), (exit) => ({
415
820
  _tag: "Done",
416
821
  exit
@@ -428,7 +833,10 @@ const makeControl = (options, subscribe) => Effect.gen(function* () {
428
833
  return {
429
834
  halt,
430
835
  stop,
431
- runPhase
836
+ runPhase,
837
+ isCancelled: () => cancellationArrived,
838
+ stopped,
839
+ settleTimeout
432
840
  };
433
841
  });
434
842
  /**
@@ -450,10 +858,6 @@ const inScope = (retain, occurrenceId, use, onCleanupFailure) => Effect.uninterr
450
858
  }
451
859
  return yield* used;
452
860
  })).pipe(Effect.asVoid);
453
- const interrupted = (plan, mode, reason, outcomes, bodiesStarted) => new ExecutionInterrupted({
454
- reason,
455
- report: report(plan, mode, "interrupted", outcomes, bodiesStarted)
456
- });
457
861
  /**
458
862
  * The outcome of a phase that did not succeed. `undefined` when it succeeded. An Effect
459
863
  * handler that interrupted itself stops admission.
@@ -475,188 +879,308 @@ const unsuccessful = (phase, result, stop) => {
475
879
  };
476
880
  }
477
881
  };
478
- const execute = (plan, resolved, options, subscribe, retain) => Effect.gen(function* () {
882
+ /**
883
+ * Creates the run's event emitter, and sends observers a report-less `RunFinished` if
884
+ * the fiber running `body` is interrupted.
885
+ */
886
+ const observed = (plan, mode, observation, control, outcomes, retain, body) => Effect.gen(function* () {
887
+ const emitter = yield* makeEmitter({
888
+ plan,
889
+ mode,
890
+ runId: observation.runId,
891
+ observers: observation.observers,
892
+ outcomes,
893
+ stopped: control.stopped,
894
+ grace: control.settleTimeout,
895
+ retain
896
+ });
897
+ return yield* Effect.onInterrupt(body(emitter), () => emitter.interrupted);
898
+ });
899
+ const execute = (plan, resolved, interaction, observation, options, subscribe, retain) => Effect.gen(function* () {
479
900
  const outcomes = /* @__PURE__ */ new Map();
480
- const { halt, stop, runPhase } = yield* makeControl(options, subscribe);
901
+ const control = yield* makeControl(options, subscribe);
902
+ const { halt, stop, runPhase, isCancelled } = control;
481
903
  let bodiesStarted = false;
482
- const runOccurrence = (occurrence) => {
483
- if (halt.reason !== void 0) return Effect.void;
484
- const handler = resolved.get(occurrence.id);
485
- if (handler === void 0) return Effect.void;
486
- let phase = "prepare";
487
- const end = (outcome) => {
488
- outcomes.set(occurrence.id, outcome);
489
- return exitOf(outcome);
490
- };
491
- const fail = (cause) => {
492
- stop("failure");
493
- return end({
494
- _tag: "Failed",
495
- phase,
496
- ...failureOf(cause)
497
- });
498
- };
499
- const use = (scope, unsettled) => Effect.gen(function* () {
500
- let step;
501
- if (handler.prepares) {
502
- const preparation = yield* runPhase(handler.prepare(scope), unsettled);
503
- const stopped = unsuccessful("prepare", preparation, stop);
904
+ return yield* observed(plan, "execute", observation, control, outcomes, retain, (emitter) => Effect.gen(function* () {
905
+ const runOccurrence = (occurrence) => {
906
+ if (halt.reason !== void 0) return Effect.void;
907
+ const handler = resolved.get(occurrence.id);
908
+ if (handler === void 0) return Effect.void;
909
+ let phase = "prepare";
910
+ const end = (outcome) => {
911
+ outcomes.set(occurrence.id, outcome);
912
+ return exitOf(outcome);
913
+ };
914
+ const fail = (cause) => {
915
+ stop("failure");
916
+ return end({
917
+ _tag: "Failed",
918
+ phase,
919
+ ...failureOf(cause)
920
+ });
921
+ };
922
+ const admitted = () => handler.prepares ? !isCancelled() : halt.reason === void 0;
923
+ const use = (scope, unsettled) => Effect.gen(function* () {
924
+ let step;
925
+ if (handler.prepares) {
926
+ yield* emitter.phaseStarted(occurrence, "prepare");
927
+ if (halt.reason !== void 0) return Exit.void;
928
+ const preparation = yield* runPhase(handler.prepare(scope), unsettled);
929
+ const stopped = unsuccessful("prepare", preparation, stop);
930
+ if (stopped !== void 0) return end(stopped);
931
+ if (preparation._tag !== "Done") return Exit.void;
932
+ if (Exit.isFailure(preparation.exit)) return fail(preparation.exit.cause);
933
+ step = preparation.exit.value;
934
+ if (step._tag === "Apply" && halt.reason === "cancelled") return Exit.void;
935
+ } else {
936
+ const started = yield* Effect.exit(handler.prepare(scope));
937
+ if (Exit.isFailure(started)) return fail(started.cause);
938
+ step = started.value;
939
+ }
940
+ if (step._tag === "Skip") return end({
941
+ _tag: "Skipped",
942
+ reason: step.reason
943
+ });
944
+ if (step._tag === "Confirm") {
945
+ if (interaction === void 0) return Exit.void;
946
+ phase = "confirmation";
947
+ yield* emitter.phaseStarted(occurrence, "confirmation");
948
+ if (!admitted()) return Exit.void;
949
+ bodiesStarted = true;
950
+ const asked = yield* runPhase(interaction.confirm({ occurrence }), unsettled, "untimed");
951
+ const unanswered = unsuccessful("confirmation", asked, stop);
952
+ if (unanswered !== void 0) return end(unanswered);
953
+ if (asked._tag !== "Done") return Exit.void;
954
+ if (Exit.isFailure(asked.exit)) return fail(asked.exit.cause);
955
+ if (asked.exit.value === "declined") {
956
+ stop("failure");
957
+ return end({ _tag: "Declined" });
958
+ }
959
+ if (step.verify === void 0) return end({
960
+ _tag: "Completed",
961
+ performer: "manual",
962
+ confirmation: "asserted"
963
+ });
964
+ phase = "verification";
965
+ const unverified = () => end({
966
+ _tag: "Interrupted",
967
+ phase: "verification",
968
+ reason: "cancelled",
969
+ settled: true
970
+ });
971
+ if (isCancelled()) return unverified();
972
+ yield* emitter.phaseStarted(occurrence, "verification");
973
+ if (isCancelled()) return unverified();
974
+ const checked = yield* runPhase(step.verify, unsettled);
975
+ const unchecked = unsuccessful("verification", checked, stop);
976
+ if (unchecked !== void 0) return end(unchecked);
977
+ if (checked._tag !== "Done") return Exit.void;
978
+ if (Exit.isFailure(checked.exit)) return fail(checked.exit.cause);
979
+ return end({
980
+ _tag: "Completed",
981
+ performer: "manual",
982
+ confirmation: "verified"
983
+ });
984
+ }
985
+ phase = "apply";
986
+ yield* emitter.phaseStarted(occurrence, "apply");
987
+ if (!admitted()) return Exit.void;
988
+ bodiesStarted = true;
989
+ const applied = yield* runPhase(step.apply, unsettled);
990
+ const stopped = unsuccessful("apply", applied, stop);
504
991
  if (stopped !== void 0) return end(stopped);
505
- if (preparation._tag !== "Done") return Exit.void;
506
- if (Exit.isFailure(preparation.exit)) return fail(preparation.exit.cause);
507
- step = preparation.exit.value;
508
- if (step._tag === "Apply" && halt.reason === "cancelled") return Exit.void;
509
- } else {
510
- const started = yield* Effect.exit(handler.prepare(scope));
511
- if (Exit.isFailure(started)) return fail(started.cause);
512
- step = started.value;
513
- }
514
- if (step._tag === "Skip") return end({
515
- _tag: "Skipped",
516
- reason: step.reason
992
+ if (applied._tag !== "Done") return Exit.void;
993
+ if (Exit.isFailure(applied.exit)) return fail(applied.exit.cause);
994
+ return end({
995
+ _tag: "Completed",
996
+ performer: "automated"
997
+ });
517
998
  });
518
- phase = "apply";
519
- bodiesStarted = true;
520
- const applied = yield* runPhase(step.apply, unsettled);
521
- const stopped = unsuccessful("apply", applied, stop);
522
- if (stopped !== void 0) return end(stopped);
523
- if (applied._tag !== "Done") return Exit.void;
524
- if (Exit.isFailure(applied.exit)) return fail(applied.exit.cause);
525
- return end({ _tag: "Completed" });
526
- });
527
- const onCleanupFailure = (cause) => Effect.suspend(() => {
528
- const outcome = outcomes.get(occurrence.id);
529
- if (outcome?._tag === "Interrupted") return logCleanupFailure({ occurrence: occurrence.id })(cause);
530
- stop("failure");
531
- outcomes.set(occurrence.id, {
532
- _tag: "Failed",
533
- phase,
534
- ...failureOf(outcome?._tag === "Failed" ? Cause.combine(outcome.cause, cause) : cause)
999
+ const onCleanupFailure = (cause) => Effect.suspend(() => {
1000
+ const outcome = outcomes.get(occurrence.id);
1001
+ if (outcome?._tag === "Interrupted") return logCleanupFailure({ occurrence: occurrence.id })(cause);
1002
+ stop("failure");
1003
+ outcomes.set(occurrence.id, {
1004
+ _tag: "Failed",
1005
+ phase,
1006
+ ...failureOf(outcome?._tag === "Failed" ? Cause.combine(outcome.cause, cause) : cause)
1007
+ });
1008
+ return Effect.void;
535
1009
  });
536
- return Effect.void;
537
- });
538
- return inScope(retain, occurrence.id, use, onCleanupFailure);
539
- };
540
- const runNode = (node) => {
541
- switch (node._tag) {
542
- case "Occurrence": return runOccurrence(node);
543
- case "Sequence": return Effect.forEach(node.children, runNode, { discard: true });
1010
+ return Effect.andThen(inScope(retain, occurrence.id, use, onCleanupFailure), emitter.settled(occurrence));
1011
+ };
1012
+ const runNode = (node) => {
1013
+ switch (node._tag) {
1014
+ case "Occurrence": return runOccurrence(node);
1015
+ case "Sequence": return Effect.forEach(node.children, runNode, { discard: true });
1016
+ }
1017
+ return forEachBranch(node.branches, node.concurrency, runNode);
1018
+ };
1019
+ yield* emitter.runStarted;
1020
+ for (const step of plan.steps) {
1021
+ if (halt.reason !== void 0) break;
1022
+ if (step.omitted) continue;
1023
+ yield* emitter.stepStarted(step);
1024
+ yield* runNode(step.node);
1025
+ yield* emitter.stepSettled(step);
544
1026
  }
545
- return forEachBranch(node.branches, node.concurrency, runNode);
546
- };
547
- for (const step of plan.steps) {
548
- if (halt.reason !== void 0) break;
549
- yield* runNode(step.node);
550
- }
551
- if (halt.reason === void 0) return report(plan, "execute", "completed", outcomes, bodiesStarted);
552
- if (halt.reason === "failure") {
553
- const result = report(plan, "execute", "failed", outcomes, bodiesStarted);
554
- return yield* new ExecutionFailed({
1027
+ const reason = halt.reason;
1028
+ const status = reason === void 0 ? "completed" : reason === "failure" ? "failed" : "interrupted";
1029
+ yield* emitter.runFinished(status);
1030
+ const result = report(plan, "execute", status, outcomes, bodiesStarted, emitter.failures);
1031
+ if (reason === void 0) return result;
1032
+ if (reason === "failure") return yield* new ExecutionFailed({
555
1033
  failures: result.occurrences.filter((entry) => entry.outcome._tag === "Failed"),
1034
+ declined: result.occurrences.filter((entry) => entry.outcome._tag === "Declined"),
556
1035
  report: result
557
1036
  });
558
- }
559
- return yield* interrupted(plan, "execute", halt.reason, outcomes, bodiesStarted);
1037
+ return yield* new ExecutionInterrupted({
1038
+ reason,
1039
+ report: result
1040
+ });
1041
+ }));
560
1042
  });
561
- const dryRun = (plan, resolved, options, subscribe, retain) => Effect.gen(function* () {
1043
+ const dryRun = (plan, resolved, observation, options, subscribe, retain) => Effect.gen(function* () {
562
1044
  const outcomes = /* @__PURE__ */ new Map();
563
- const { halt, stop, runPhase } = yield* makeControl(options, subscribe);
1045
+ const control = yield* makeControl(options, subscribe);
1046
+ const { halt, stop, runPhase } = control;
564
1047
  let failedAt;
565
- /** Runs a prepare phase in the occurrence's scope and records what it predicts. */
566
- const prepare = (id, handler) => {
567
- const end = (outcome) => {
568
- outcomes.set(id, outcome);
569
- return exitOf(outcome);
1048
+ return yield* observed(plan, "dry-run", observation, control, outcomes, retain, (emitter) => Effect.gen(function* () {
1049
+ const settle = (occurrence, outcome) => {
1050
+ outcomes.set(occurrence.id, outcome);
1051
+ return emitter.settled(occurrence);
570
1052
  };
571
- const use = (scope, unsettled) => Effect.gen(function* () {
572
- const preparation = yield* runPhase(handler.prepare(scope), unsettled);
573
- const stopped = unsuccessful("prepare", preparation, stop);
574
- if (stopped !== void 0) return end(stopped);
575
- if (preparation._tag !== "Done") return Exit.void;
576
- if (Exit.isFailure(preparation.exit)) {
577
- failedAt = id;
578
- return end({
579
- _tag: "PreparationFailed",
580
- ...failureOf(preparation.exit.cause)
1053
+ /** Runs a prepare phase in the occurrence's scope and records what it predicts. */
1054
+ const prepare = (occurrence, handler) => {
1055
+ const id = occurrence.id;
1056
+ const end = (outcome) => {
1057
+ outcomes.set(id, outcome);
1058
+ return exitOf(outcome);
1059
+ };
1060
+ const use = (scope, unsettled) => Effect.gen(function* () {
1061
+ yield* emitter.phaseStarted(occurrence, "prepare");
1062
+ if (halt.reason !== void 0) return Exit.void;
1063
+ const preparation = yield* runPhase(handler.prepare(scope), unsettled);
1064
+ const stopped = unsuccessful("prepare", preparation, stop);
1065
+ if (stopped !== void 0) return end(stopped);
1066
+ if (preparation._tag !== "Done") return Exit.void;
1067
+ if (Exit.isFailure(preparation.exit)) {
1068
+ failedAt = id;
1069
+ return end({
1070
+ _tag: "PreparationFailed",
1071
+ ...failureOf(preparation.exit.cause)
1072
+ });
1073
+ }
1074
+ const step = preparation.exit.value;
1075
+ return end(step._tag === "Skip" ? {
1076
+ _tag: "WouldSkip",
1077
+ reason: step.reason
1078
+ } : {
1079
+ _tag: "WouldExecute",
1080
+ evaluated: true,
1081
+ performer: handler.performer
581
1082
  });
582
- }
583
- const step = preparation.exit.value;
584
- return end(step._tag === "Skip" ? {
585
- _tag: "WouldSkip",
586
- reason: step.reason
587
- } : {
588
- _tag: "WouldExecute",
589
- evaluated: true
590
1083
  });
591
- });
592
- const onCleanupFailure = (cause) => Effect.suspend(() => {
593
- const outcome = outcomes.get(id);
594
- if (outcome?._tag === "Interrupted") return logCleanupFailure({ occurrence: id })(cause);
595
- failedAt ??= id;
596
- outcomes.set(id, {
597
- _tag: "PreparationFailed",
598
- ...failureOf(outcome?._tag === "PreparationFailed" ? Cause.combine(outcome.cause, cause) : cause)
1084
+ const onCleanupFailure = (cause) => Effect.suspend(() => {
1085
+ const outcome = outcomes.get(id);
1086
+ if (outcome?._tag === "Interrupted") return logCleanupFailure({ occurrence: id })(cause);
1087
+ failedAt ??= id;
1088
+ outcomes.set(id, {
1089
+ _tag: "PreparationFailed",
1090
+ ...failureOf(outcome?._tag === "PreparationFailed" ? Cause.combine(outcome.cause, cause) : cause)
1091
+ });
1092
+ return Effect.void;
599
1093
  });
600
- return Effect.void;
1094
+ return Effect.andThen(inScope(retain, id, use, onCleanupFailure), emitter.settled(occurrence));
1095
+ };
1096
+ /** Returns whether the node would or might change state. */
1097
+ const visit = (node, dirty) => Effect.gen(function* () {
1098
+ if (node._tag === "Sequence") {
1099
+ let current = dirty;
1100
+ for (const child of node.children) current = yield* visit(child, current);
1101
+ return current;
1102
+ }
1103
+ if (node._tag === "Parallel") {
1104
+ let changed = dirty;
1105
+ for (const branch of node.branches) changed = (yield* visit(branch, dirty)) || changed;
1106
+ return changed;
1107
+ }
1108
+ const handler = resolved.get(node.id);
1109
+ if (handler === void 0 || halt.reason !== void 0) return dirty;
1110
+ if (failedAt !== void 0) {
1111
+ yield* settle(node, {
1112
+ _tag: "Undetermined",
1113
+ reason: `Execution would stop at the failed preparation of "${failedAt}".`,
1114
+ performer: handler.performer
1115
+ });
1116
+ return true;
1117
+ }
1118
+ if (!handler.prepares) {
1119
+ yield* settle(node, {
1120
+ _tag: "WouldExecute",
1121
+ evaluated: false,
1122
+ performer: handler.performer
1123
+ });
1124
+ return true;
1125
+ }
1126
+ if (dirty) {
1127
+ yield* settle(node, {
1128
+ _tag: "Undetermined",
1129
+ reason: "The prepare phase depends on earlier actions that a dry run does not apply.",
1130
+ performer: handler.performer
1131
+ });
1132
+ return true;
1133
+ }
1134
+ yield* prepare(node, handler);
1135
+ return outcomes.get(node.id)?._tag !== "WouldSkip";
601
1136
  });
602
- return inScope(retain, id, use, onCleanupFailure);
603
- };
604
- /** Returns whether the node would or might change state. */
605
- const visit = (node, dirty) => Effect.gen(function* () {
606
- if (node._tag === "Sequence") {
607
- let current = dirty;
608
- for (const child of node.children) current = yield* visit(child, current);
609
- return current;
610
- }
611
- if (node._tag === "Parallel") {
612
- let changed = dirty;
613
- for (const branch of node.branches) changed = (yield* visit(branch, dirty)) || changed;
614
- return changed;
615
- }
616
- const handler = resolved.get(node.id);
617
- if (handler === void 0 || halt.reason !== void 0) return dirty;
618
- if (failedAt !== void 0) {
619
- outcomes.set(node.id, {
620
- _tag: "Undetermined",
621
- reason: `Execution would stop at the failed preparation of "${failedAt}".`
622
- });
623
- return true;
1137
+ yield* emitter.runStarted;
1138
+ let dirty = false;
1139
+ for (const step of plan.steps) {
1140
+ if (halt.reason !== void 0) break;
1141
+ if (step.omitted) continue;
1142
+ yield* emitter.stepStarted(step);
1143
+ dirty = yield* visit(step.node, dirty);
1144
+ yield* emitter.stepSettled(step);
624
1145
  }
625
- if (!handler.prepares) {
626
- outcomes.set(node.id, {
627
- _tag: "WouldExecute",
628
- evaluated: false
1146
+ const reason = halt.reason;
1147
+ if (reason !== void 0 && reason !== "failure") {
1148
+ yield* emitter.runFinished("interrupted");
1149
+ return yield* new ExecutionInterrupted({
1150
+ reason,
1151
+ report: report(plan, "dry-run", "interrupted", outcomes, false, emitter.failures)
629
1152
  });
630
- return true;
631
1153
  }
632
- if (dirty) {
633
- outcomes.set(node.id, {
634
- _tag: "Undetermined",
635
- reason: "The prepare phase depends on earlier actions that a dry run does not apply."
636
- });
637
- return true;
638
- }
639
- yield* prepare(node.id, handler);
640
- return outcomes.get(node.id)?._tag !== "WouldSkip";
641
- });
642
- let dirty = false;
643
- for (const step of plan.steps) dirty = yield* visit(step.node, dirty);
644
- if (halt.reason !== void 0 && halt.reason !== "failure") return yield* interrupted(plan, "dry-run", halt.reason, outcomes, false);
645
- return report(plan, "dry-run", failedAt === void 0 ? "would-complete" : "would-fail", outcomes, false);
1154
+ const status = failedAt === void 0 ? "would-complete" : "would-fail";
1155
+ yield* emitter.runFinished(status);
1156
+ return report(plan, "dry-run", status, outcomes, false, emitter.failures);
1157
+ }));
646
1158
  });
647
1159
  const run = (plan, options, subscribe, retain) => {
648
1160
  const handlers = options.handlers ?? [];
1161
+ const interaction = options.interaction;
1162
+ const observation = {
1163
+ observers: options.observers ?? [],
1164
+ runId: options.runId
1165
+ };
649
1166
  return Effect.gen(function* () {
650
1167
  const checked = coverage(plan, handlers);
651
1168
  if (checked.issues.length > 0) return yield* new HandlerCoverageError({
652
1169
  issues: checked.issues,
653
1170
  report: report(plan, options.dryRun === true ? "dry-run" : "execute", "not-started", /* @__PURE__ */ new Map(), false)
654
1171
  });
655
- return options.dryRun === true ? yield* dryRun(plan, checked.resolved, options, subscribe, retain) : yield* execute(plan, checked.resolved, options, subscribe, retain);
1172
+ if (options.dryRun === true) return yield* dryRun(plan, checked.resolved, observation, options, subscribe, retain);
1173
+ const manual = plan.occurrences.filter((occurrence) => checked.resolved.get(occurrence.id)?.performer === "manual");
1174
+ if (manual.length > 0 && interaction === void 0) return yield* new InteractionUnavailable({
1175
+ occurrences: manual,
1176
+ report: report(plan, "execute", "not-started", /* @__PURE__ */ new Map(), false)
1177
+ });
1178
+ return yield* execute(plan, checked.resolved, interaction, observation, options, subscribe, retain);
656
1179
  });
657
1180
  };
658
1181
  /**
659
- * Runs a plan as an Effect. Coverage is checked before any handler phase runs. Steps
1182
+ * Runs a plan as an Effect. Coverage, and the interaction that manual handlers need,
1183
+ * are checked before any handler phase runs. Steps
660
1184
  * are sequential barriers; parallel groups run their branches concurrently. On failure,
661
1185
  * no new action starts, and actions already running settle before the effect fails
662
1186
  * with the partial report.
@@ -668,14 +1192,16 @@ const run = (plan, options, subscribe, retain) => {
668
1192
  *
669
1193
  * To cancel, interrupt the fiber. Interruption reaches running actions and aborts the
670
1194
  * signal passed to Promise callbacks. The effect then ends as interrupted, without a
671
- * report.
1195
+ * report. Observers receive a final `RunFinished` event without a report, delivered
1196
+ * within `settleTimeout`.
672
1197
  *
673
- * @since @next
1198
+ * @since 0.0.1
674
1199
  */
675
- const effect = (plan, options) => run(plan, options, void 0, () => {});
1200
+ const effect$2 = (plan, options) => run(plan, options, void 0, () => {});
676
1201
  /**
677
1202
  * Runs a plan and returns a Promise. It rejects with `HandlerCoverageError`,
678
- * `ExecutionFailed`, or `ExecutionInterrupted`, each carrying the partial report.
1203
+ * `InteractionUnavailable`, `ExecutionFailed`, or `ExecutionInterrupted`, each carrying
1204
+ * the partial report.
679
1205
  * Building a supplied services layer can also reject with the layer's own error,
680
1206
  * without a report.
681
1207
  *
@@ -686,7 +1212,7 @@ const effect = (plan, options) => run(plan, options, void 0, () => {});
686
1212
  * until it settles, possibly forever, and close in that order. A cleanup failure after
687
1213
  * the Promise resolved is logged through Effect.
688
1214
  *
689
- * @since @next
1215
+ * @since 0.0.1
690
1216
  */
691
1217
  const runPromise = (plan, options) => {
692
1218
  const { signal } = options;
@@ -727,18 +1253,88 @@ const runPromise = (plan, options) => {
727
1253
  throw Cause.squash(exit.cause);
728
1254
  });
729
1255
  };
1256
+ // src/features/execution/interaction.ts
1257
+ var interaction_exports = /* @__PURE__ */ __exportAll({
1258
+ UnexpectedInteractionError: () => UnexpectedInteractionError,
1259
+ effect: () => effect$1,
1260
+ isInteraction: () => isInteraction,
1261
+ promise: () => promise$1
1262
+ });
1263
+ /**
1264
+ * A Promise interaction rejected with a value that none of its declared error guards
1265
+ * recognized (`rejected`), or an interaction answered with something other than
1266
+ * `"confirmed"` or `"declined"` (`invalid-answer`). An invalid answer is never kept: it
1267
+ * may be text that the person typed.
1268
+ *
1269
+ * @since 0.2.0
1270
+ */
1271
+ var UnexpectedInteractionError = class extends Data.TaggedError("UnexpectedInteractionError") {
1272
+ get message() {
1273
+ return this.reason === "rejected" ? `The interaction failed unexpectedly while confirming "${this.occurrenceId}"` : `The interaction answered neither "confirmed" nor "declined" for "${this.occurrenceId}"`;
1274
+ }
1275
+ };
1276
+ const isAnswer = (value) => value === "confirmed" || value === "declined";
1277
+ const checkAnswer = (request) => (answer) => isAnswer(answer) ? Effect.succeed(answer) : Effect.fail(new UnexpectedInteractionError({
1278
+ occurrenceId: request.occurrence.id,
1279
+ reason: "invalid-answer",
1280
+ cause: void 0
1281
+ }));
1282
+ const TypeId$1 = "~deltafold/Interaction";
1283
+ /** @since 0.2.0 */
1284
+ const isInteraction = (value) => Predicate.hasProperty(value, TypeId$1);
1285
+ /**
1286
+ * Confirms manual work with a Promise callback. It receives `{ signal, services }`: an
1287
+ * `AbortSignal` that aborts when the run is cancelled, so it can stop asking, and the
1288
+ * declared services.
1289
+ *
1290
+ * @example
1291
+ * ```ts
1292
+ * // The migration's instruction for this action, or the action's description.
1293
+ * const textOf = ({ action, instruction }: Plan.Occurrence) =>
1294
+ * instruction?.content
1295
+ * .map((part) => (part._tag === "Text" ? part.text : part.action.description))
1296
+ * .join("") ?? action.description;
1297
+ *
1298
+ * const interaction = Interaction.promise(async ({ occurrence }, { signal }) =>
1299
+ * (await ask(textOf(occurrence), { signal })) ? "confirmed" : "declined",
1300
+ * );
1301
+ * ```
1302
+ *
1303
+ * @since 0.2.0
1304
+ */
1305
+ const promise$1 = (confirm, options) => {
1306
+ const adapt = adaptPromise(options ?? {});
1307
+ return {
1308
+ [TypeId$1]: TypeId$1,
1309
+ confirm: (request) => adapt((context) => confirm(request, context), (cause) => new UnexpectedInteractionError({
1310
+ occurrenceId: request.occurrence.id,
1311
+ reason: "rejected",
1312
+ cause
1313
+ })).pipe(Effect.flatMap(checkAnswer(request)))
1314
+ };
1315
+ };
1316
+ /**
1317
+ * Confirms manual work with an Effect, which keeps its own errors and services and
1318
+ * stops through Effect interruption when the run is cancelled.
1319
+ *
1320
+ * @since 0.2.0
1321
+ */
1322
+ const effect$1 = (confirm) => ({
1323
+ [TypeId$1]: TypeId$1,
1324
+ confirm: (request) => Effect.flatMap(Effect.suspend(() => confirm(request)), checkAnswer(request))
1325
+ });
730
1326
  // src/features/planning/resolve-error.ts
731
1327
  /**
732
1328
  * The history's declarations are invalid. Resolution needs a valid history.
733
1329
  *
734
- * @since @next
1330
+ * @since 0.0.1
735
1331
  */
736
1332
  var InvalidHistory = class extends Data.TaggedError("InvalidHistory") {
737
1333
  get message() {
738
1334
  return `The history has ${this.issues.length} declaration issue(s): ${this.issues.map((issue) => issue.message).join(" ")}`;
739
1335
  }
740
1336
  };
741
- /** @since @next */
1337
+ /** @since 0.0.1 */
742
1338
  var UnknownVersion = class extends Data.TaggedError("UnknownVersion") {
743
1339
  get message() {
744
1340
  return `Version "${this.version}" is not registered in the history.`;
@@ -748,7 +1344,7 @@ var UnknownVersion = class extends Data.TaggedError("UnknownVersion") {
748
1344
  * No declared route connects the versions. This never means that no work is needed:
749
1345
  * declare `Migration.noop` for a supported zero-work transition.
750
1346
  *
751
- * @since @next
1347
+ * @since 0.0.1
752
1348
  */
753
1349
  var UnsupportedRoute = class extends Data.TaggedError("UnsupportedRoute") {
754
1350
  get message() {
@@ -759,7 +1355,7 @@ var UnsupportedRoute = class extends Data.TaggedError("UnsupportedRoute") {
759
1355
  /**
760
1356
  * Several routes connect the versions and no selection or policy chose one.
761
1357
  *
762
- * @since @next
1358
+ * @since 0.0.1
763
1359
  */
764
1360
  var AmbiguousRoute = class extends Data.TaggedError("AmbiguousRoute") {
765
1361
  get message() {
@@ -771,7 +1367,7 @@ var AmbiguousRoute = class extends Data.TaggedError("AmbiguousRoute") {
771
1367
  /**
772
1368
  * The `route` option names no candidate route.
773
1369
  *
774
- * @since @next
1370
+ * @since 0.0.1
775
1371
  */
776
1372
  var UnknownRoute = class extends Data.TaggedError("UnknownRoute") {
777
1373
  get message() {
@@ -781,7 +1377,7 @@ var UnknownRoute = class extends Data.TaggedError("UnknownRoute") {
781
1377
  /**
782
1378
  * Rules rewrite a sequence back into itself.
783
1379
  *
784
- * @since @next
1380
+ * @since 0.0.1
785
1381
  */
786
1382
  var RewriteCycle = class extends Data.TaggedError("RewriteCycle") {
787
1383
  get message() {
@@ -791,7 +1387,7 @@ var RewriteCycle = class extends Data.TaggedError("RewriteCycle") {
791
1387
  /**
792
1388
  * Rules can produce different results depending on which applies first.
793
1389
  *
794
- * @since @next
1390
+ * @since 0.0.1
795
1391
  */
796
1392
  var ConflictingRewrites = class extends Data.TaggedError("ConflictingRewrites") {
797
1393
  get message() {
@@ -802,7 +1398,7 @@ var ConflictingRewrites = class extends Data.TaggedError("ConflictingRewrites")
802
1398
  * Optimization explored too many states or chained too many rule applications, for
803
1399
  * example because a rule keeps growing the sequence.
804
1400
  *
805
- * @since @next
1401
+ * @since 0.0.1
806
1402
  */
807
1403
  var RewriteLimitExceeded = class extends Data.TaggedError("RewriteLimitExceeded") {
808
1404
  get message() {
@@ -812,7 +1408,7 @@ var RewriteLimitExceeded = class extends Data.TaggedError("RewriteLimitExceeded"
812
1408
  /**
813
1409
  * More candidate routes exist than the resolver enumerates.
814
1410
  *
815
- * @since @next
1411
+ * @since 0.0.1
816
1412
  */
817
1413
  var TooManyRoutes = class extends Data.TaggedError("TooManyRoutes") {
818
1414
  get message() {
@@ -865,8 +1461,10 @@ const resolveGuide = (content, retained, declaredId) => {
865
1461
  const escape = (value, separators) => value.replace(separators, "\\$&");
866
1462
  const occurrencePart = (id) => escape(id, /[\\/()+]/g);
867
1463
  const routePart = (id) => escape(id, /[\\>[\]]/g);
1464
+ /** A plan step: `<migration>` forward, `<migration>/revert` in reverse. */
1465
+ const stepId = (migration, direction) => direction === "forward" ? occurrencePart(migration.id) : `${occurrencePart(migration.id)}/revert`;
868
1466
  /** `<migration>/<action>` forward, `<migration>/revert/<action>` in reverse. */
869
- const declaredOccurrenceId = (migration, direction, action) => direction === "forward" ? `${occurrencePart(migration.id)}/${occurrencePart(action.id)}` : `${occurrencePart(migration.id)}/revert/${occurrencePart(action.id)}`;
1467
+ const declaredOccurrenceId = (migration, direction, action) => `${stepId(migration, direction)}/${occurrencePart(action.id)}`;
870
1468
  /**
871
1469
  * `<rule>(<replaced>+<replaced>)/<action>`. Replaced identifiers are complete occurrence
872
1470
  * identifiers, so they nest without further escaping.
@@ -1475,6 +2073,7 @@ const buildPlan = (context, from, to, direction, edges) => {
1475
2073
  const [stepFrom, stepTo] = member.direction === "forward" ? [member.migration.from, member.migration.to] : [member.migration.to, member.migration.from];
1476
2074
  return {
1477
2075
  _tag: "Step",
2076
+ id: stepId(member.migration, member.direction),
1478
2077
  migration: member.migration,
1479
2078
  direction: member.direction,
1480
2079
  from: stepFrom,
@@ -1718,7 +2317,7 @@ var history_exports = /* @__PURE__ */ __exportAll({
1718
2317
  * `make` does not throw. Use `History.validate` to list declaration issues;
1719
2318
  * resolution fails with `InvalidHistory` when there are any.
1720
2319
  *
1721
- * @since @next
2320
+ * @since 0.0.1
1722
2321
  */
1723
2322
  const make$4 = (declarations) => ({
1724
2323
  _tag: "History",
@@ -1727,7 +2326,7 @@ const make$4 = (declarations) => ({
1727
2326
  rules: declarations.rules ?? [],
1728
2327
  shortcuts: declarations.shortcuts ?? []
1729
2328
  });
1730
- /** @since @next */
2329
+ /** @since 0.0.1 */
1731
2330
  const isHistory = (value) => Predicate.isTagged(value, "History");
1732
2331
  const contexts = /* @__PURE__ */ new WeakMap();
1733
2332
  const prepare = (history) => {
@@ -1743,7 +2342,7 @@ const prepare = (history) => {
1743
2342
  /**
1744
2343
  * Lists declaration issues in a deterministic order. An empty list means valid.
1745
2344
  *
1746
- * @since @next
2345
+ * @since 0.0.1
1747
2346
  */
1748
2347
  const validate = (history) => prepare(history).issues;
1749
2348
  const valid = (history) => {
@@ -1763,19 +2362,19 @@ const valid = (history) => {
1763
2362
  * if (Result.isSuccess(result)) console.log(result.success.route.id);
1764
2363
  * ```
1765
2364
  *
1766
- * @since @next
2365
+ * @since 0.0.1
1767
2366
  */
1768
2367
  const resolve = (history, options) => Result.flatMap(valid(history), (context) => resolve$1(context, options));
1769
2368
  /**
1770
2369
  * Destinations reachable by upgrade from a version, with their candidate routes.
1771
2370
  *
1772
- * @since @next
2371
+ * @since 0.0.1
1773
2372
  */
1774
2373
  const upgrades = (history, options) => reachableFrom(history, options.from, "upgrade");
1775
2374
  /**
1776
2375
  * Destinations reachable by downgrade from a version, with their candidate routes.
1777
2376
  *
1778
- * @since @next
2377
+ * @since 0.0.1
1779
2378
  */
1780
2379
  const downgrades = (history, options) => reachableFrom(history, options.from, "downgrade");
1781
2380
  const reachableFrom = (history, from, kind) => Result.flatMap(valid(history), (context) => Result.map(lookup(context, from), (version) => destinations(context, version, kind)));
@@ -1827,7 +2426,7 @@ const prose = (strings, values, context) => {
1827
2426
  * `;
1828
2427
  * ```
1829
2428
  *
1830
- * @since @next
2429
+ * @since 0.0.1
1831
2430
  */
1832
2431
  const instruction = (action) => (strings, ...values) => ({
1833
2432
  _tag: "Instruction",
@@ -1842,7 +2441,7 @@ var migration_exports = /* @__PURE__ */ __exportAll({
1842
2441
  noop: () => noop,
1843
2442
  withRevert: () => withRevert
1844
2443
  });
1845
- /** @since @next */
2444
+ /** @since 0.0.1 */
1846
2445
  const isMigration = (value) => Predicate.isTagged(value, "Migration");
1847
2446
  const isStep = (value) => isAction(value) || isInstruction(value) || isSequence(value) || isParallel(value);
1848
2447
  const validateStep = (step, context) => {
@@ -1913,7 +2512,7 @@ const content = (strings, values, context) => {
1913
2512
  * `;
1914
2513
  * ```
1915
2514
  *
1916
- * @since @next
2515
+ * @since 0.0.1
1917
2516
  */
1918
2517
  const make$3 = (id, options) => (strings, ...values) => ({
1919
2518
  _tag: "Migration",
@@ -1931,7 +2530,7 @@ const make$3 = (id, options) => (strings, ...values) => ({
1931
2530
  * like any migration. Do not use it to hide missing support for changes that need
1932
2531
  * instructions.
1933
2532
  *
1934
- * @since @next
2533
+ * @since 0.0.1
1935
2534
  */
1936
2535
  const noop = (id, options) => ({
1937
2536
  _tag: "Migration",
@@ -1958,12 +2557,86 @@ const noop = (id, options) => ({
1958
2557
  * `;
1959
2558
  * ```
1960
2559
  *
1961
- * @since @next
2560
+ * @since 0.0.1
1962
2561
  */
1963
2562
  const withRevert = (migration) => (strings, ...values) => ({
1964
2563
  ...migration,
1965
2564
  revert: content(strings, values, `Revert of migration "${migration.id}"`)
1966
2565
  });
2566
+ // src/features/execution/observer.ts
2567
+ var observer_exports = /* @__PURE__ */ __exportAll({
2568
+ effect: () => effect,
2569
+ isObserver: () => isObserver,
2570
+ promise: () => promise,
2571
+ sync: () => sync
2572
+ });
2573
+ const TypeId = "~deltafold/Observer";
2574
+ /** @since 0.2.1 */
2575
+ const isObserver = (value) => Predicate.hasProperty(value, TypeId);
2576
+ var AsyncSyncObserver = class extends Error {
2577
+ name = "AsyncSyncObserver";
2578
+ message = "An Observer.sync callback returned a Promise. Use Observer.promise for asynchronous callbacks.";
2579
+ };
2580
+ /**
2581
+ * Observes with a synchronous callback. A thrown value is recorded as an observation
2582
+ * failure.
2583
+ *
2584
+ * @example
2585
+ * ```ts
2586
+ * Observer.sync((event) => {
2587
+ * if (event._tag === "ActionSettled") console.error(event.action.occurrence, event.outcome._tag);
2588
+ * });
2589
+ * ```
2590
+ *
2591
+ * @since 0.2.1
2592
+ */
2593
+ const sync = (callback) => ({
2594
+ [TypeId]: TypeId,
2595
+ notify: (event) => Effect.sync(() => {
2596
+ try {
2597
+ const result = callback(event);
2598
+ if (!Predicate.isPromiseLike(result)) return Exit.void;
2599
+ Promise.resolve(result).catch(() => void 0);
2600
+ return Exit.fail(new AsyncSyncObserver());
2601
+ } catch (cause) {
2602
+ return Exit.fail(cause);
2603
+ }
2604
+ })
2605
+ });
2606
+ /**
2607
+ * Observes with a Promise callback. The executor waits for the Promise. The `signal`
2608
+ * aborts when the executor stops waiting: after cancellation or a timeout, once the
2609
+ * settlement grace period has passed, or when the execution is interrupted. A services
2610
+ * layer that `Executor.runPromise` built stays open until an abandoned Promise settles.
2611
+ *
2612
+ * @since 0.2.1
2613
+ */
2614
+ const promise = (callback) => ({
2615
+ [TypeId]: TypeId,
2616
+ notify: (event) => Effect.suspend(() => {
2617
+ let pending;
2618
+ return Effect.promise((signal) => {
2619
+ const settles = new Promise((resolve) => resolve(callback(event, { signal }))).then(() => Exit.void, (cause) => Exit.fail(cause));
2620
+ pending = settles;
2621
+ return settles;
2622
+ }).pipe(Effect.onInterrupt(() => pending === void 0 ? Effect.void : Effect.promise(() => pending ?? Promise.resolve())));
2623
+ })
2624
+ });
2625
+ /**
2626
+ * Observes with an Effect. Its services become requirements of the execution. Its
2627
+ * failures are recorded as observation failures and never fail the execution.
2628
+ *
2629
+ * @example
2630
+ * ```ts
2631
+ * Observer.effect((event) => Effect.logDebug(event._tag));
2632
+ * ```
2633
+ *
2634
+ * @since 0.2.1
2635
+ */
2636
+ const effect = (callback) => ({
2637
+ [TypeId]: TypeId,
2638
+ notify: (event) => Effect.exit(Effect.suspend(() => callback(event)))
2639
+ });
1967
2640
  // src/features/package.ts
1968
2641
  var package_exports = /* @__PURE__ */ __exportAll({
1969
2642
  isPackage: () => isPackage,
@@ -1978,14 +2651,14 @@ var package_exports = /* @__PURE__ */ __exportAll({
1978
2651
  * export const widgets = Package.make("@acme/widgets", { history });
1979
2652
  * ```
1980
2653
  *
1981
- * @since @next
2654
+ * @since 0.0.1
1982
2655
  */
1983
2656
  const make$2 = (name, options) => ({
1984
2657
  _tag: "Package",
1985
2658
  name,
1986
2659
  history: options.history
1987
2660
  });
1988
- /** @since @next */
2661
+ /** @since 0.0.1 */
1989
2662
  const isPackage = (value) => Predicate.isTagged(value, "Package");
1990
2663
  // src/foundation/plan.ts
1991
2664
  var plan_exports = /* @__PURE__ */ __exportAll({
@@ -1995,7 +2668,7 @@ var plan_exports = /* @__PURE__ */ __exportAll({
1995
2668
  /**
1996
2669
  * Whether the plan has no action occurrences. An empty plan is valid.
1997
2670
  *
1998
- * @since @next
2671
+ * @since 0.0.1
1999
2672
  */
2000
2673
  const isEmpty = (plan) => plan.occurrences.length === 0;
2001
2674
  /**
@@ -2003,7 +2676,7 @@ const isEmpty = (plan) => plan.occurrences.length === 0;
2003
2676
  * loaded plans whose action union is not known statically. Executors still reject
2004
2677
  * missing handlers before any action body runs.
2005
2678
  *
2006
- * @since @next
2679
+ * @since 0.0.1
2007
2680
  */
2008
2681
  const withRuntimeCoverage = (plan) => ({
2009
2682
  ...plan,
@@ -2036,7 +2709,7 @@ var rule_exports = /* @__PURE__ */ __exportAll({
2036
2709
  * });
2037
2710
  * ```
2038
2711
  *
2039
- * @since @next
2712
+ * @since 0.0.1
2040
2713
  */
2041
2714
  const replace = (id, options) => ({
2042
2715
  _tag: "Rule",
@@ -2044,7 +2717,7 @@ const replace = (id, options) => ({
2044
2717
  match: options.match,
2045
2718
  replacement: options.replacement
2046
2719
  });
2047
- /** @since @next */
2720
+ /** @since 0.0.1 */
2048
2721
  const isRule = (value) => Predicate.isTagged(value, "Rule");
2049
2722
  // src/foundation/shortcut.ts
2050
2723
  var shortcut_exports = /* @__PURE__ */ __exportAll({
@@ -2065,7 +2738,7 @@ var shortcut_exports = /* @__PURE__ */ __exportAll({
2065
2738
  * });
2066
2739
  * ```
2067
2740
  *
2068
- * @since @next
2741
+ * @since 0.0.1
2069
2742
  */
2070
2743
  const make$1 = (id, options) => ({
2071
2744
  _tag: "Shortcut",
@@ -2076,7 +2749,7 @@ const make$1 = (id, options) => ({
2076
2749
  migrations: options.migrations,
2077
2750
  cost: options.cost
2078
2751
  });
2079
- /** @since @next */
2752
+ /** @since 0.0.1 */
2080
2753
  const isShortcut = (value) => Predicate.isTagged(value, "Shortcut");
2081
2754
  // src/foundation/version.ts
2082
2755
  var version_exports = /* @__PURE__ */ __exportAll({
@@ -2093,7 +2766,7 @@ var version_exports = /* @__PURE__ */ __exportAll({
2093
2766
  * const v100 = Version.make("1.0.0", { previous: v0, changes: [timeoutRenamed] });
2094
2767
  * ```
2095
2768
  *
2096
- * @since @next
2769
+ * @since 0.0.1
2097
2770
  */
2098
2771
  const make = (id, options) => ({
2099
2772
  _tag: "Version",
@@ -2101,7 +2774,7 @@ const make = (id, options) => ({
2101
2774
  previous: options.previous,
2102
2775
  changes: options.changes
2103
2776
  });
2104
- /** @since @next */
2777
+ /** @since 0.0.1 */
2105
2778
  const isVersion = (value) => Predicate.isTagged(value, "Version");
2106
2779
  /**
2107
2780
  * Annotates a version with release metadata.
@@ -2114,13 +2787,13 @@ const isVersion = (value) => Predicate.isTagged(value, "Version");
2114
2787
  * });
2115
2788
  * ```
2116
2789
  *
2117
- * @since @next
2790
+ * @since 0.0.1
2118
2791
  */
2119
2792
  const withMetadata = (version, metadata) => ({
2120
2793
  _tag: "Release",
2121
2794
  version,
2122
2795
  metadata
2123
2796
  });
2124
- export { action_exports as Action, change_exports as Change, executor_exports as Executor, handler_exports as Handler, history_exports as History, migration_exports as Migration, package_exports as Package, plan_exports as Plan, rule_exports as Rule, shortcut_exports as Shortcut, version_exports as Version };
2797
+ export { action_exports as Action, change_exports as Change, executor_exports as Executor, handler_exports as Handler, history_exports as History, interaction_exports as Interaction, migration_exports as Migration, observer_exports as Observer, package_exports as Package, plan_exports as Plan, rule_exports as Rule, shortcut_exports as Shortcut, version_exports as Version };
2125
2798
 
2126
2799
  //# sourceMappingURL=index.js.map