deltafold 0.0.1 → 0.1.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.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, Graph, Option, Order, Predicate, Result, Schema, SemVer } from "effect";
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";
3
3
  import dedentText from "dedent";
4
4
  // src/foundation/action.ts
5
5
  var action_exports = /* @__PURE__ */ __exportAll({
@@ -101,7 +101,7 @@ const describeValue = (value) => {
101
101
  var change_exports = /* @__PURE__ */ __exportAll({
102
102
  define: () => define,
103
103
  isChange: () => isChange,
104
- make: () => make$5
104
+ make: () => make$6
105
105
  });
106
106
  const describe = (id, metadata, relations) => (strings, ...values) => {
107
107
  const literals = dedent(strings);
@@ -122,7 +122,7 @@ const describe = (id, metadata, relations) => (strings, ...values) => {
122
122
  backportOf: relations.backportOf
123
123
  };
124
124
  };
125
- function make$5(id, metadata = {}, relations = {}) {
125
+ function make$6(id, metadata = {}, relations = {}) {
126
126
  return describe(id, metadata, relations);
127
127
  }
128
128
  /**
@@ -144,17 +144,18 @@ function make$5(id, metadata = {}, relations = {}) {
144
144
  *
145
145
  * @since @next
146
146
  */
147
- const define = () => ({ make: make$5 });
147
+ const define = () => ({ make: make$6 });
148
148
  /** @since @next */
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: () => ({
152
152
  grace: Duration.zero,
153
- record: () => {}
153
+ unsettled: () => {}
154
154
  }) });
155
155
  /**
156
156
  * Runs a Promise-producing effect. If it is interrupted after the Promise started,
157
- * waits up to the settlement grace period and records whether the Promise settled.
157
+ * waits up to the settlement grace period and hands a still-pending Promise to the
158
+ * settlement, which can hold resources until it settles.
158
159
  */
159
160
  const trackPromise = (start) => Effect.suspend(() => {
160
161
  let pending;
@@ -165,9 +166,10 @@ const trackPromise = (start) => Effect.suspend(() => {
165
166
  return start(capture).pipe(Effect.onInterrupt(() => Effect.gen(function* () {
166
167
  const started = pending;
167
168
  if (started === void 0) return;
169
+ const settles = started.then(() => void 0, () => void 0);
168
170
  const settlement = yield* SettlementReference;
169
- const settled = yield* Effect.promise(() => started.then(() => void 0, () => void 0)).pipe(Effect.timeoutOption(settlement.grace));
170
- settlement.record(Option.isSome(settled));
171
+ const settled = yield* Effect.promise(() => settles).pipe(Effect.timeoutOption(settlement.grace));
172
+ if (Option.isNone(settled)) settlement.unsettled(settles);
171
173
  })));
172
174
  });
173
175
  // src/features/execution/handler.ts
@@ -175,86 +177,90 @@ var handler_exports = /* @__PURE__ */ __exportAll({
175
177
  UnexpectedHandlerError: () => UnexpectedHandlerError,
176
178
  effect: () => effect$1,
177
179
  isHandler: () => isHandler,
178
- promise: () => promise
180
+ prepared: () => prepared,
181
+ promise: () => promise,
182
+ skip: () => skip
179
183
  });
180
184
  /**
181
185
  * A Promise handler rejected or threw a value that none of its declared error guards
182
- * recognized.
186
+ * recognized, or its prepare phase returned something other than `Handler.prepared` or
187
+ * `Handler.skip`.
183
188
  *
184
189
  * @since @next
185
190
  */
186
191
  var UnexpectedHandlerError = class extends Data.TaggedError("UnexpectedHandlerError") {
187
192
  get message() {
188
- return `Handler for action "${this.actionId}" failed unexpectedly in its ${this.phase}`;
193
+ return `Handler for action "${this.actionId}" failed unexpectedly in its ${this.phase} phase`;
189
194
  }
190
195
  };
191
- const TypeId = "~deltafold/Handler";
192
- /** @since @next */
193
- const isHandler = (value) => Predicate.hasProperty(value, TypeId);
194
- const skipReasonOf = (action, reason) => {
195
- if (reason === void 0) return "Precondition returned false";
196
- return typeof reason === "string" ? reason : reason(action.payload);
197
- };
198
- const declaredError = (guards) => (cause) => guards.some((guard) => Schema.isSchema(guard) ? Schema.is(guard)(cause) : guard(cause));
196
+ const PreparationTypeId = "~deltafold/Preparation";
197
+ function prepared(value) {
198
+ return {
199
+ [PreparationTypeId]: PreparationTypeId,
200
+ _tag: "Prepared",
201
+ value
202
+ };
203
+ }
199
204
  /**
200
- * Implements an action with Promise callbacks. The callbacks run lazily through
201
- * `Effect.tryPromise`, and receive its `AbortSignal` and the declared services in
202
- * their second argument.
203
- *
204
- * @example
205
- * ```ts
206
- * Handler.promise(
207
- * updateRemoteConfig,
208
- * async (payload, { signal, services: { editor } }) => {
209
- * await editor.update(payload, { signal });
210
- * },
211
- * { services: { editor: ConfigEditor } },
212
- * );
213
- * ```
205
+ * Ends a prepare phase by skipping the occurrence. The apply phase does not run.
214
206
  *
215
207
  * @since @next
216
208
  */
217
- const promise = (action, run, options) => {
209
+ const skip = (reason) => ({
210
+ [PreparationTypeId]: PreparationTypeId,
211
+ _tag: "Skip",
212
+ reason
213
+ });
214
+ const isPreparation = (value) => Predicate.hasProperty(value, PreparationTypeId);
215
+ const notAPreparation = () => /* @__PURE__ */ new TypeError("A prepare phase must return Handler.prepared(value) or Handler.skip(reason)");
216
+ const applyStep = (apply) => ({
217
+ _tag: "Apply",
218
+ apply
219
+ });
220
+ const TypeId = "~deltafold/Handler";
221
+ /** @since @next */
222
+ const isHandler = (value) => Predicate.hasProperty(value, TypeId);
223
+ const make$5 = (action, prepares, prepare) => ({
224
+ [TypeId]: TypeId,
225
+ action,
226
+ prepares,
227
+ prepare
228
+ });
229
+ const declaredError = (guards) => (cause) => guards.some((guard) => Schema.isSchema(guard) ? Schema.is(guard)(cause) : guard(cause));
230
+ function promise(action, run, options) {
218
231
  const isDeclared = declaredError(options?.errors ?? []);
219
232
  const services = options?.services ?? {};
220
233
  const resolve = Effect.map(Effect.context(), (context) => Object.fromEntries(Reflect.ownKeys(services).map((name) => [name, Context.get(context, services[name])])));
234
+ const unexpected = (phase, cause) => new UnexpectedHandlerError({
235
+ actionId: action.id,
236
+ kind: action.kind,
237
+ phase,
238
+ cause
239
+ });
221
240
  const adapt = (phase, callback) => Effect.flatMap(resolve, (resolved) => trackPromise((capture) => Effect.tryPromise({
222
241
  try: (signal) => capture(Promise.resolve(callback({
223
242
  signal,
224
243
  services: resolved
225
244
  }))),
226
- catch: (cause) => isDeclared(cause) ? cause : new UnexpectedHandlerError({
227
- actionId: action.id,
228
- kind: action.kind,
229
- phase,
230
- cause
231
- })
245
+ catch: (cause) => isDeclared(cause) ? cause : unexpected(phase, cause)
232
246
  })));
233
- const when = options?.when;
234
- return {
235
- [TypeId]: TypeId,
236
- action,
237
- body: Effect.asVoid(adapt("body", (context) => run(action.payload, context))),
238
- precondition: when === void 0 ? void 0 : adapt("precondition", (context) => when(action.payload, context)),
239
- skipReason: skipReasonOf(action, options?.skipReason)
240
- };
241
- };
242
- /**
243
- * Implements an action with an Effect. The body keeps its own errors and services, and
244
- * stops through native Effect interruption.
245
- *
246
- * @since @next
247
- */
248
- const effect$1 = (action, run, options = {}) => {
249
- const when = options.when;
250
- return {
251
- [TypeId]: TypeId,
252
- action,
253
- body: Effect.asVoid(Effect.suspend(() => run(action.payload))),
254
- precondition: when === void 0 ? void 0 : Effect.suspend(() => when(action.payload)),
255
- skipReason: skipReasonOf(action, options.skipReason)
256
- };
257
- };
247
+ if (Predicate.isFunction(run)) {
248
+ const apply = Effect.asVoid(adapt("apply", (context) => run(action.payload, context)));
249
+ return make$5(action, false, () => Effect.succeed(applyStep(apply)));
250
+ }
251
+ const prepare = adapt("prepare", (context) => run.prepare(action.payload, context)).pipe(Effect.filterOrFail(isPreparation, () => unexpected("prepare", notAPreparation())), Effect.map((preparation) => preparation._tag === "Skip" ? preparation : applyStep(Effect.asVoid(adapt("apply", (context) => run.apply(preparation.value, {
252
+ ...context,
253
+ payload: action.payload
254
+ }))))));
255
+ return make$5(action, true, () => prepare);
256
+ }
257
+ function effect$1(action, run) {
258
+ if (Predicate.isFunction(run)) {
259
+ const apply = Effect.asVoid(Effect.suspend(() => run(action.payload)));
260
+ return make$5(action, false, (scope) => Effect.succeed(applyStep(Scope.provide(apply, scope))));
261
+ }
262
+ 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
+ }
258
264
  // src/features/execution/executor.ts
259
265
  var executor_exports = /* @__PURE__ */ __exportAll({
260
266
  ExecutionFailed: () => ExecutionFailed,
@@ -265,10 +271,10 @@ var executor_exports = /* @__PURE__ */ __exportAll({
265
271
  });
266
272
  const HandlerCoverageBase = Data.TaggedError("HandlerCoverageError");
267
273
  /**
268
- * Handler coverage failed before any precondition or body ran. Every occurrence needs
269
- * exactly one handler, for the same action definition: the same identifier, kind, and
270
- * payload. For an occurrence that a rule produced, the issue names the rule and the
271
- * occurrences it replaced.
274
+ * Handler coverage failed before any handler phase ran. Every occurrence needs exactly
275
+ * one handler, for the same action definition: the same identifier, kind, and payload.
276
+ * For an occurrence that a rule produced, the issue names the rule and the occurrences
277
+ * it replaced.
272
278
  *
273
279
  * @since @next
274
280
  */
@@ -360,10 +366,24 @@ const failureOf = (cause) => ({
360
366
  error: Option.getOrUndefined(Cause.findErrorOption(cause)),
361
367
  cause
362
368
  });
369
+ /** The exit an occurrence's scope closes with, so finalizers see how it ended. */
370
+ const exitOf = (outcome) => {
371
+ switch (outcome?._tag) {
372
+ case "Failed":
373
+ case "PreparationFailed": return Exit.failCause(outcome.cause);
374
+ case "Interrupted": return Exit.interrupt();
375
+ default: return Exit.void;
376
+ }
377
+ };
363
378
  const forEachBranch = (branches, concurrency, run) => Effect.forEach(branches, run, {
364
379
  concurrency,
365
380
  discard: true
366
381
  });
382
+ /**
383
+ * Logs a cleanup failure that the report cannot carry, with the occurrence or the
384
+ * services layer that owned the resources.
385
+ */
386
+ const logCleanupFailure = (owner) => (cause) => Effect.logError("deltafold: cleanup failed", cause).pipe(Effect.annotateLogs(owner));
367
387
  /** Admission state, cancellation, and timeouts shared by real and dry runs. */
368
388
  const makeControl = (options, subscribe) => Effect.gen(function* () {
369
389
  const halt = { reason: void 0 };
@@ -376,13 +396,17 @@ const makeControl = (options, subscribe) => Effect.gen(function* () {
376
396
  stop("cancelled");
377
397
  Deferred.doneUnsafe(cancelled, Exit.succeed("cancelled"));
378
398
  });
379
- /** Runs one precondition or body, racing it against cancellation and the timeout. */
380
- const runPhase = (work) => Effect.gen(function* () {
399
+ /**
400
+ * Runs one phase, racing it against cancellation and its own timeout. An
401
+ * interrupted Promise that outlives the settlement grace period goes to `unsettled`.
402
+ */
403
+ const runPhase = (work, unsettled) => Effect.gen(function* () {
381
404
  let settled = true;
382
405
  const tracked = work.pipe(Effect.provideService(SettlementReference, {
383
406
  grace: settleTimeout,
384
- record: (value) => {
385
- settled = value;
407
+ unsettled: (promise) => {
408
+ settled = false;
409
+ unsettled.push(promise);
386
410
  }
387
411
  }));
388
412
  const stopSignals = [Deferred.await(cancelled)];
@@ -407,89 +431,112 @@ const makeControl = (options, subscribe) => Effect.gen(function* () {
407
431
  runPhase
408
432
  };
409
433
  });
434
+ /**
435
+ * Runs one occurrence in its own scope, which both phases share. `use` returns the
436
+ * exit to close the scope with. The scope closes as soon as the occurrence ends, and
437
+ * a failing finalizer goes to `onCleanupFailure`. If an interrupted Promise has not
438
+ * settled, the scope stays open until it does, possibly forever; a failing
439
+ * finalizer is then logged, because the report may already have been returned.
440
+ */
441
+ const inScope = (retain, occurrenceId, use, onCleanupFailure) => Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
442
+ const scope = yield* Scope.make();
443
+ const unsettled = [];
444
+ const used = yield* Effect.exit(restore(use(scope, unsettled)));
445
+ const end = Exit.isSuccess(used) ? used.value : used;
446
+ if (unsettled.length > 0) retain(yield* Effect.forkDetach(Effect.promise(() => Promise.all(unsettled)).pipe(Effect.andThen(Scope.close(scope, end)), Effect.catchCause(logCleanupFailure({ occurrence: occurrenceId })))));
447
+ else {
448
+ const closed = yield* Effect.exit(Scope.close(scope, end));
449
+ if (Exit.isFailure(closed)) yield* onCleanupFailure(closed.cause);
450
+ }
451
+ return yield* used;
452
+ })).pipe(Effect.asVoid);
410
453
  const interrupted = (plan, mode, reason, outcomes, bodiesStarted) => new ExecutionInterrupted({
411
454
  reason,
412
455
  report: report(plan, mode, "interrupted", outcomes, bodiesStarted)
413
456
  });
414
- const execute = (plan, resolved, options, subscribe) => Effect.gen(function* () {
457
+ /**
458
+ * The outcome of a phase that did not succeed. `undefined` when it succeeded. An Effect
459
+ * handler that interrupted itself stops admission.
460
+ */
461
+ const unsuccessful = (phase, result, stop) => {
462
+ if (result._tag === "Interrupted") return {
463
+ _tag: "Interrupted",
464
+ phase,
465
+ reason: result.reason,
466
+ settled: result.settled
467
+ };
468
+ if (Exit.isFailure(result.exit) && Cause.hasInterruptsOnly(result.exit.cause)) {
469
+ stop("handler");
470
+ return {
471
+ _tag: "Interrupted",
472
+ phase,
473
+ reason: "handler",
474
+ settled: true
475
+ };
476
+ }
477
+ };
478
+ const execute = (plan, resolved, options, subscribe, retain) => Effect.gen(function* () {
415
479
  const outcomes = /* @__PURE__ */ new Map();
416
480
  const { halt, stop, runPhase } = yield* makeControl(options, subscribe);
417
481
  let bodiesStarted = false;
418
- const runOccurrence = (occurrence) => Effect.gen(function* () {
419
- if (halt.reason !== void 0) return;
482
+ const runOccurrence = (occurrence) => {
483
+ if (halt.reason !== void 0) return Effect.void;
420
484
  const handler = resolved.get(occurrence.id);
421
- if (handler === void 0) return;
422
- if (handler.precondition !== void 0) {
423
- const checked = yield* runPhase(handler.precondition);
424
- if (checked._tag === "Interrupted") {
425
- outcomes.set(occurrence.id, {
426
- _tag: "Interrupted",
427
- phase: "precondition",
428
- reason: checked.reason,
429
- settled: checked.settled
430
- });
431
- return;
432
- }
433
- if (Exit.isFailure(checked.exit) && Cause.hasInterruptsOnly(checked.exit.cause)) {
434
- stop("handler");
435
- outcomes.set(occurrence.id, {
436
- _tag: "Interrupted",
437
- phase: "precondition",
438
- reason: "handler",
439
- settled: true
440
- });
441
- return;
442
- }
443
- if (Exit.isFailure(checked.exit)) {
444
- stop("failure");
445
- outcomes.set(occurrence.id, {
446
- _tag: "Failed",
447
- phase: "precondition",
448
- ...failureOf(checked.exit.cause)
449
- });
450
- return;
451
- }
452
- if (!checked.exit.value) {
453
- outcomes.set(occurrence.id, {
454
- _tag: "Skipped",
455
- reason: handler.skipReason
456
- });
457
- return;
458
- }
459
- if (halt.reason === "cancelled") return;
460
- }
461
- bodiesStarted = true;
462
- const ran = yield* runPhase(handler.body);
463
- if (ran._tag === "Interrupted") {
464
- outcomes.set(occurrence.id, {
465
- _tag: "Interrupted",
466
- phase: "body",
467
- reason: ran.reason,
468
- settled: ran.settled
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)
469
497
  });
470
- return;
471
- }
472
- if (Exit.isFailure(ran.exit) && Cause.hasInterruptsOnly(ran.exit.cause)) {
473
- stop("handler");
474
- outcomes.set(occurrence.id, {
475
- _tag: "Interrupted",
476
- phase: "body",
477
- reason: "handler",
478
- settled: true
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);
504
+ 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
479
517
  });
480
- return;
481
- }
482
- if (Exit.isFailure(ran.exit)) {
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);
483
530
  stop("failure");
484
531
  outcomes.set(occurrence.id, {
485
532
  _tag: "Failed",
486
- phase: "body",
487
- ...failureOf(ran.exit.cause)
533
+ phase,
534
+ ...failureOf(outcome?._tag === "Failed" ? Cause.combine(outcome.cause, cause) : cause)
488
535
  });
489
- return;
490
- }
491
- outcomes.set(occurrence.id, { _tag: "Completed" });
492
- });
536
+ return Effect.void;
537
+ });
538
+ return inScope(retain, occurrence.id, use, onCleanupFailure);
539
+ };
493
540
  const runNode = (node) => {
494
541
  switch (node._tag) {
495
542
  case "Occurrence": return runOccurrence(node);
@@ -511,10 +558,49 @@ const execute = (plan, resolved, options, subscribe) => Effect.gen(function* ()
511
558
  }
512
559
  return yield* interrupted(plan, "execute", halt.reason, outcomes, bodiesStarted);
513
560
  });
514
- const dryRun = (plan, resolved, options, subscribe) => Effect.gen(function* () {
561
+ const dryRun = (plan, resolved, options, subscribe, retain) => Effect.gen(function* () {
515
562
  const outcomes = /* @__PURE__ */ new Map();
516
563
  const { halt, stop, runPhase } = yield* makeControl(options, subscribe);
517
564
  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);
570
+ };
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)
581
+ });
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
+ });
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)
599
+ });
600
+ return Effect.void;
601
+ });
602
+ return inScope(retain, id, use, onCleanupFailure);
603
+ };
518
604
  /** Returns whether the node would or might change state. */
519
605
  const visit = (node, dirty) => Effect.gen(function* () {
520
606
  if (node._tag === "Sequence") {
@@ -532,11 +618,11 @@ const dryRun = (plan, resolved, options, subscribe) => Effect.gen(function* () {
532
618
  if (failedAt !== void 0) {
533
619
  outcomes.set(node.id, {
534
620
  _tag: "Undetermined",
535
- reason: `Execution would stop at the failed precondition of "${failedAt}".`
621
+ reason: `Execution would stop at the failed preparation of "${failedAt}".`
536
622
  });
537
623
  return true;
538
624
  }
539
- if (handler.precondition === void 0) {
625
+ if (!handler.prepares) {
540
626
  outcomes.set(node.id, {
541
627
  _tag: "WouldExecute",
542
628
  evaluated: false
@@ -546,57 +632,19 @@ const dryRun = (plan, resolved, options, subscribe) => Effect.gen(function* () {
546
632
  if (dirty) {
547
633
  outcomes.set(node.id, {
548
634
  _tag: "Undetermined",
549
- reason: "The precondition depends on earlier actions that a dry run does not apply."
550
- });
551
- return true;
552
- }
553
- const checked = yield* runPhase(handler.precondition);
554
- if (checked._tag === "Interrupted") {
555
- outcomes.set(node.id, {
556
- _tag: "Interrupted",
557
- phase: "precondition",
558
- reason: checked.reason,
559
- settled: checked.settled
560
- });
561
- return true;
562
- }
563
- if (Exit.isFailure(checked.exit) && Cause.hasInterruptsOnly(checked.exit.cause)) {
564
- stop("handler");
565
- outcomes.set(node.id, {
566
- _tag: "Interrupted",
567
- phase: "precondition",
568
- reason: "handler",
569
- settled: true
635
+ reason: "The prepare phase depends on earlier actions that a dry run does not apply."
570
636
  });
571
637
  return true;
572
638
  }
573
- if (Exit.isFailure(checked.exit)) {
574
- failedAt = node.id;
575
- outcomes.set(node.id, {
576
- _tag: "PreconditionFailed",
577
- ...failureOf(checked.exit.cause)
578
- });
579
- return true;
580
- }
581
- if (!checked.exit.value) {
582
- outcomes.set(node.id, {
583
- _tag: "WouldSkip",
584
- reason: handler.skipReason
585
- });
586
- return false;
587
- }
588
- outcomes.set(node.id, {
589
- _tag: "WouldExecute",
590
- evaluated: true
591
- });
592
- return true;
639
+ yield* prepare(node.id, handler);
640
+ return outcomes.get(node.id)?._tag !== "WouldSkip";
593
641
  });
594
642
  let dirty = false;
595
643
  for (const step of plan.steps) dirty = yield* visit(step.node, dirty);
596
644
  if (halt.reason !== void 0 && halt.reason !== "failure") return yield* interrupted(plan, "dry-run", halt.reason, outcomes, false);
597
645
  return report(plan, "dry-run", failedAt === void 0 ? "would-complete" : "would-fail", outcomes, false);
598
646
  });
599
- const run = (plan, options, subscribe) => {
647
+ const run = (plan, options, subscribe, retain) => {
600
648
  const handlers = options.handlers ?? [];
601
649
  return Effect.gen(function* () {
602
650
  const checked = coverage(plan, handlers);
@@ -604,14 +652,19 @@ const run = (plan, options, subscribe) => {
604
652
  issues: checked.issues,
605
653
  report: report(plan, options.dryRun === true ? "dry-run" : "execute", "not-started", /* @__PURE__ */ new Map(), false)
606
654
  });
607
- return options.dryRun === true ? yield* dryRun(plan, checked.resolved, options, subscribe) : yield* execute(plan, checked.resolved, options, subscribe);
655
+ return options.dryRun === true ? yield* dryRun(plan, checked.resolved, options, subscribe, retain) : yield* execute(plan, checked.resolved, options, subscribe, retain);
608
656
  });
609
657
  };
610
658
  /**
611
- * Runs a plan as an Effect. Coverage is checked before any precondition or body runs.
612
- * Steps are sequential barriers; parallel groups run their branches concurrently. On
613
- * failure, no new action starts, and actions already running settle before the effect
614
- * fails with the partial report.
659
+ * Runs a plan as an Effect. Coverage is checked before any handler phase runs. Steps
660
+ * are sequential barriers; parallel groups run their branches concurrently. On failure,
661
+ * no new action starts, and actions already running settle before the effect fails
662
+ * with the partial report.
663
+ *
664
+ * Each occurrence has its own scope, shared by its phases and closed when it ends. An
665
+ * interrupted Promise that has not settled keeps its occurrence's scope open until it
666
+ * settles, after the effect has ended. Services that the caller provides stay the
667
+ * caller's to release.
615
668
  *
616
669
  * To cancel, interrupt the fiber. Interruption reaches running actions and aborts the
617
670
  * signal passed to Promise callbacks. The effect then ends as interrupted, without a
@@ -619,17 +672,19 @@ const run = (plan, options, subscribe) => {
619
672
  *
620
673
  * @since @next
621
674
  */
622
- const effect = (plan, options) => run(plan, options, void 0);
675
+ const effect = (plan, options) => run(plan, options, void 0, () => {});
623
676
  /**
624
677
  * Runs a plan and returns a Promise. It rejects with `HandlerCoverageError`,
625
678
  * `ExecutionFailed`, or `ExecutionInterrupted`, each carrying the partial report.
626
679
  * Building a supplied services layer can also reject with the layer's own error,
627
680
  * without a report.
628
681
  *
629
- * A services layer is built for this run and finalized when the run ends. A services
630
- * context stays owned by the caller. A Promise callback that ignores its signal can keep
631
- * running after cancellation or a timeout, beyond `settleTimeout`, and so after the
632
- * run's layer resources are finalized; the report marks it as possibly still running.
682
+ * A services layer is built for this run. A services context stays owned by the
683
+ * caller. A Promise callback that ignores its signal can keep running after
684
+ * cancellation or a timeout, beyond `settleTimeout`; the report marks it as possibly
685
+ * still running. Its occurrence's scope and the run's services layer then stay open
686
+ * until it settles, possibly forever, and close in that order. A cleanup failure after
687
+ * the Promise resolved is logged through Effect.
633
688
  *
634
689
  * @since @next
635
690
  */
@@ -647,12 +702,25 @@ const runPromise = (plan, options) => {
647
702
  else cancelRun();
648
703
  };
649
704
  signal?.addEventListener("abort", onAbort, { once: true });
650
- const program = run(plan, options, signal === void 0 ? void 0 : (cancel) => {
705
+ const subscribe = signal === void 0 ? void 0 : (cancel) => {
651
706
  cancelRun = cancel;
652
707
  if (signal.aborted) cancel();
653
- });
708
+ };
709
+ const retained = [];
710
+ const program = run(plan, options, subscribe, (fiber) => retained.push(fiber));
654
711
  const services = options.services;
655
- const provided = services === void 0 ? program : Context.isContext(services) ? Effect.provideContext(program, services) : Effect.provide(program, services);
712
+ const provided = services === void 0 ? program : Context.isContext(services) ? Effect.provideContext(program, services) : Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
713
+ const scope = yield* Scope.make();
714
+ const built = yield* Effect.exit(restore(Layer.buildWithScope(services, scope)));
715
+ if (Exit.isFailure(built)) {
716
+ yield* Scope.close(scope, built);
717
+ return yield* built;
718
+ }
719
+ const exit = yield* Effect.exit(restore(Effect.provideContext(program, built.value)));
720
+ if (retained.length === 0) yield* Scope.close(scope, exit);
721
+ else yield* Effect.forkDetach(Fiber.awaitAll(retained).pipe(Effect.andThen(Scope.close(scope, exit)), Effect.catchCause(logCleanupFailure({ owner: "services layer" }))));
722
+ return yield* exit;
723
+ }));
656
724
  const cancellable = signal === void 0 ? provided : Effect.raceFirst(provided, Effect.andThen(Deferred.await(abortedBeforeRun), Effect.fail(notStarted())));
657
725
  return Effect.runPromiseExit(cancellable).finally(() => signal?.removeEventListener("abort", onAbort)).then((exit) => {
658
726
  if (Exit.isSuccess(exit)) return exit.value;