@demlik/tea 0.16.0 → 0.18.0

package/dist/testing/effect/index.js

@@ -0,0 +1,148 @@
+import { CellFailure, builtinRunners, cellResult, settleCellExit } from '../../chunk-I7E7AD2S.js';
+import { driveLoop, DEFAULT_MAX_ROUNDS, driveContractOf, DriveRoundsExceededError, DriveNoHandlerError, annotateTrace, driveTraceOf, desiredSubs } from '../../chunk-H3MWNH7A.js';
+export { DEFAULT_MAX_ROUNDS, DriveNoHandlerError, DriveRoundsExceededError, driveTraceOf } from '../../chunk-H3MWNH7A.js';
+import '../../chunk-JVKU2UQC.js';
+import '../../chunk-AHW2CLPT.js';
+import '../../chunk-JVE2LBFJ.js';
+import '../../chunk-FNGZMVIT.js';
+import '../../chunk-AIIXV4XB.js';
+import { Effect, Stream, Exit, Cause, Fiber } from 'effect';
+
+var DriveInterrupted = class {
+};
+function drive(machine, initial, msg, interpret, ...[opts]) {
+  const options = opts ?? {};
+  return Effect.gen(function* () {
+    const services = yield* Effect.context();
+    const runEffect = Effect.runPromiseExitWith(services);
+    const fork = Effect.runForkWith(services);
+    return yield* Effect.callback((resume, signal) => {
+      const cells = interpret;
+      const defined = new Set((machine.cmds ?? []).map((def) => def.cmdType));
+      const cellFor = (type) => {
+        const cell = cells[type];
+        if (cell === void 0) return void 0;
+        return async (cmd) => {
+          const exit = await runEffect(cellResult(cell(cmd)), { signal });
+          if (signal.aborted) throw new DriveInterrupted();
+          return settleCellExit(exit, defined.has(type));
+        };
+      };
+      driveLoop(
+        machine,
+        initial,
+        msg,
+        options.ctx,
+        options.maxRounds ?? DEFAULT_MAX_ROUNDS,
+        {
+          contract: driveContractOf(machine, options.clock ?? Date.now),
+          cellFor,
+          subs: effectSubs(
+            machine,
+            options.subscribe ?? {},
+            fork,
+            signal
+          )
+        }
+      ).then(
+        (result) => resume(Effect.succeed(result)),
+        (error) => resume(failureOf(error))
+      );
+    });
+  });
+}
+function failureOf(error) {
+  if (error instanceof DriveRoundsExceededError || error instanceof DriveNoHandlerError) {
+    return Effect.fail(error);
+  }
+  if (error instanceof CellFailure) {
+    annotateTrace(error.failure, driveTraceOf(error) ?? []);
+    return Effect.fail(error.failure);
+  }
+  if (error instanceof DriveInterrupted) return Effect.interrupt;
+  return Effect.die(error);
+}
+function effectSubs(machine, subscribe, fork, signal) {
+  const builtins = builtinRunners;
+  const started = /* @__PURE__ */ new Map();
+  let buffered = [];
+  let failed;
+  let wake;
+  const notify = () => {
+    const woken = wake;
+    wake = void 0;
+    woken?.();
+  };
+  signal.addEventListener("abort", notify, { once: true });
+  const stop = (sub) => {
+    sub.stopped = true;
+    return sub.ended || sub.fiber === void 0 ? Promise.resolve() : Effect.runPromise(Fiber.interrupt(sub.fiber));
+  };
+  const anyRunning = () => [...started.values()].some((sub) => !sub.ended);
+  return {
+    reconcile(state) {
+      const desired = desiredSubs(machine, state);
+      for (const [id, sub] of started) {
+        if (desired.has(id)) continue;
+        started.delete(id);
+        void stop(sub);
+      }
+      for (const [id, sub] of desired) {
+        if (started.has(id)) continue;
+        const make = subscribe[sub.type] ?? builtins[sub.type];
+        if (make === void 0) {
+          throw new Error(
+            `@demlik/tea: no subscribe runner for Sub type "${sub.type}". Pass one to drive in \`subscribe\`.`
+          );
+        }
+        const entry = { stopped: false, ended: false };
+        started.set(id, entry);
+        entry.fiber = fork(
+          Stream.runForEach(
+            make(sub),
+            (next) => Effect.sync(() => {
+              if (entry.stopped) return;
+              buffered.push(next);
+              notify();
+            })
+          ).pipe(
+            Effect.onExit(
+              (exit) => Effect.sync(() => {
+                entry.ended = true;
+                if (!entry.stopped && Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause)) {
+                  failed ??= exit.cause;
+                }
+                notify();
+              })
+            )
+          )
+        );
+      }
+    },
+    async next() {
+      for (; ; ) {
+        if (signal.aborted) throw new DriveInterrupted();
+        if (buffered.length > 0) {
+          const out = buffered;
+          buffered = [];
+          return out;
+        }
+        if (failed !== void 0) throw Cause.squash(failed);
+        if (!anyRunning()) return void 0;
+        await new Promise((resolve) => {
+          wake = resolve;
+        });
+      }
+    },
+    async close() {
+      signal.removeEventListener("abort", notify);
+      const stopping = [...started.values()].map(stop);
+      started.clear();
+      await Promise.all(stopping);
+    }
+  };
+}
+
+export { drive };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/testing/effect/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/testing/effect/drive.ts"],"names":[],"mappings":";;;;;;;;;;AAwDA,IAAM,mBAAN,MAAuB;AAAC,CAAA;AAuDjB,SAAS,MAUd,OAAA,EACA,OAAA,EACA,KACA,SAAA,EAAA,GACG,CAAC,IAAI,CAAA,EAOR;AACA,EAAA,MAAM,OAAA,GAAW,QAAQ,EAAC;AAM1B,EAAA,OAAO,MAAA,CAAO,IAAI,aAAa;AAC7B,IAAA,MAAM,QAAA,GAAW,OAAO,MAAA,CAAO,OAAA,EAE7B;AACF,IAAA,MAAM,SAAA,GAAY,MAAA,CAAO,kBAAA,CAAmB,QAAQ,CAAA;AACpD,IAAA,MAAM,IAAA,GAAO,MAAA,CAAO,WAAA,CAAY,QAAQ,CAAA;AAExC,IAAA,OAAO,OAAO,MAAA,CAAO,QAAA,CAGnB,CAAC,QAAQ,MAAA,KAAW;AACpB,MAAA,MAAM,KAAA,GAAQ,SAAA;AAGd,MAAA,MAAM,OAAA,GAAU,IAAI,GAAA,CAAA,CAAK,OAAA,CAAQ,IAAA,IAAQ,EAAC,EAAG,GAAA,CAAI,CAAC,GAAA,KAAQ,GAAA,CAAI,OAAO,CAAC,CAAA;AACtE,MAAA,MAAM,OAAA,GAAU,CAAC,IAAA,KAA8C;AAC7D,QAAA,MAAM,IAAA,GAAO,MAAM,IAAI,CAAA;AACvB,QAAA,IAAI,IAAA,KAAS,QAAW,OAAO,MAAA;AAC/B,QAAA,OAAO,OAAO,GAAA,KAAQ;AACpB,UAAA,MAAM,IAAA,GAAO,MAAM,SAAA,CAAU,UAAA,CAAW,IAAA,CAAK,GAAG,CAAC,CAAA,EAAG,EAAE,MAAA,EAAQ,CAAA;AAC9D,UAAA,IAAI,MAAA,CAAO,OAAA,EAAS,MAAM,IAAI,gBAAA,EAAiB;AAC/C,UAAA,OAAO,cAAA,CAAe,IAAA,EAAM,OAAA,CAAQ,GAAA,CAAI,IAAI,CAAC,CAAA;AAAA,QAC/C,CAAA;AAAA,MACF,CAAA;AAEA,MAAA,SAAA;AAAA,QACE,OAAA;AAAA,QACA,OAAA;AAAA,QACA,GAAA;AAAA,QACA,OAAA,CAAQ,GAAA;AAAA,QACR,QAAQ,SAAA,IAAa,kBAAA;AAAA,QACrB;AAAA,UACE,UAAU,eAAA,CAAgB,OAAA,EAAS,OAAA,CAAQ,KAAA,IAAS,KAAK,GAAG,CAAA;AAAA,UAC5D,OAAA;AAAA,UACA,IAAA,EAAM,UAAA;AAAA,YACJ,OAAA;AAAA,YACA,OAAA,CAAQ,aAAa,EAAC;AAAA,YACtB,IAAA;AAAA,YACA;AAAA;AACF;AACF,OACF,CAAE,IAAA;AAAA,QACA,CAAC,MAAA,KAAW,MAAA,CAAO,MAAA,CAAO,OAAA,CAAQ,MAAM,CAAC,CAAA;AAAA,QACzC,CAAC,KAAA,KAAmB,MAAA,CAAO,SAAA,CAAmB,KAAK,CAAC;AAAA,OACtD;AAAA,IACF,CAAC,CAAA;AAAA,EACH,CAAC,CAAA;AACH;AAMA,SAAS,UACP,KAAA,EACiD;AACjD,EAAA,IACE,KAAA,YAAiB,wBAAA,IACjB,KAAA,YAAiB,mBAAA,EACjB;AACA,IAAA,OAAO,MAAA,CAAO,KAAK,KAAkC,CAAA;AAAA,EACvD;AACA,EAAA,IAAI,iBAAiB,WAAA,EAAa;AAChC,IAAA,aAAA,CAAc,MAAM,OAAA,EAAS,YAAA,CAAa,KAAK,CAAA,IAAK,EAAE,CAAA;AACtD,IAAA,OAAO,MAAA,CAAO,IAAA,CAAK,KAAA,CAAM,OAAoC,CAAA;AAAA,EAC/D;AACA,EAAA,IAAI,KAAA,YAAiB,gBAAA,EAAkB,OAAO,MAAA,CAAO,SAAA;AACrD,EAAA,OAAO,MAAA,CAAO,IAAI,KAAK,CAAA;AACzB;AAmBA,SAAS,UAAA,CACP,OAAA,EACA,SAAA,EACA,IAAA,EACA,MAAA,EACiB;AACjB,EAAA,MAAM,QAAA,GAAW,cAAA;AAGjB,EAAA,MAAM,OAAA,uBAAc,GAAA,EAAwB;AAC5C,EAAA,IAAI,WAAgB,EAAC;AACrB,EAAA,IAAI,MAAA;AACJ,EAAA,IAAI,IAAA;AACJ,EAAA,MAAM,SAAS,MAAY;AACzB,IAAA,MAAM,KAAA,GAAQ,IAAA;AACd,IAAA,IAAA,GAAO,MAAA;AACP,IAAA,KAAA,IAAQ;AAAA,EACV,CAAA;AACA,EAAA,MAAA,CAAO,iBAAiB,OAAA,EAAS,MAAA,EAAQ,EAAE,IAAA,EAAM,MAAM,CAAA;AAEvD,EAAA,MAAM,IAAA,GAAO,CAAC,GAAA,KAAmC;AAC/C,IAAA,GAAA,CAAI,OAAA,GAAU,IAAA;AACd,IAAA,OAAO,GAAA,CAAI,KAAA,IAAS,GAAA,CAAI,KAAA,KAAU,SAC9B,OAAA,CAAQ,OAAA,EAAQ,GAChB,MAAA,CAAO,UAAA,CAAW,KAAA,CAAM,SAAA,CAAU,GAAA,CAAI,KAAK,CAAC,CAAA;AAAA,EAClD,CAAA;AACA,EAAA,MAAM,UAAA,GAAa,MACjB,CAAC,GAAG,OAAA,CAAQ,MAAA,EAAQ,CAAA,CAAE,IAAA,CAAK,CAAC,GAAA,KAAQ,CAAC,IAAI,KAAK,CAAA;AAEhD,EAAA,OAAO;AAAA,IACL,UAAU,KAAA,EAAO;AACf,MAAA,MAAM,OAAA,GAAU,WAAA,CAAY,OAAA,EAAS,KAAK,CAAA;AAC1C,MAAA,KAAA,MAAW,CAAC,EAAA,EAAI,GAAG,CAAA,IAAK,OAAA,EAAS;AAC/B,QAAA,IAAI,OAAA,CAAQ,GAAA,CAAI,EAAE,CAAA,EAAG;AACrB,QAAA,OAAA,CAAQ,OAAO,EAAE,CAAA;AACjB,QAAA,KAAK,KAAK,GAAG,CAAA;AAAA,MACf;AACA,MAAA,KAAA,MAAW,CAAC,EAAA,EAAI,GAAG,CAAA,IAAK,OAAA,EAAS;AAC/B,QAAA,IAAI,OAAA,CAAQ,GAAA,CAAI,EAAE,CAAA,EAAG;AACrB,QAAA,MAAM,OAAO,SAAA,CAAU,GAAA,CAAI,IAAI,CAAA,IAAK,QAAA,CAAS,IAAI,IAAI,CAAA;AACrD,QAAA,IAAI,SAAS,MAAA,EAAW;AACtB,UAAA,MAAM,IAAI,KAAA;AAAA,YACR,CAAA,+CAAA,EAAkD,IAAI,IAAI,CAAA,sCAAA;AAAA,WAE5D;AAAA,QACF;AACA,QAAA,MAAM,KAAA,GAAoB,EAAE,OAAA,EAAS,KAAA,EAAO,OAAO,KAAA,EAAM;AACzD,QAAA,OAAA,CAAQ,GAAA,CAAI,IAAI,KAAK,CAAA;AACrB,QAAA,KAAA,CAAM,KAAA,GAAQ,IAAA;AAAA,UACZ,MAAA,CAAO,UAAA;AAAA,YAAW,KAAK,GAAG,CAAA;AAAA,YAAG,CAAC,IAAA,KAC5B,MAAA,CAAO,IAAA,CAAK,MAAM;AAChB,cAAA,IAAI,MAAM,OAAA,EAAS;AACnB,cAAA,QAAA,CAAS,KAAK,IAAS,CAAA;AACvB,cAAA,MAAA,EAAO;AAAA,YACT,CAAC;AAAA,WACH,CAAE,IAAA;AAAA,YACA,MAAA,CAAO,MAAA;AAAA,cAAO,CAAC,IAAA,KACb,MAAA,CAAO,IAAA,CAAK,MAAM;AAChB,gBAAA,KAAA,CAAM,KAAA,GAAQ,IAAA;AACd,gBAAA,IACE,CAAC,KAAA,CAAM,OAAA,IACP,IAAA,CAAK,SAAA,CAAU,IAAI,CAAA,IACnB,CAAC,KAAA,CAAM,iBAAA,CAAkB,IAAA,CAAK,KAAK,CAAA,EACnC;AACA,kBAAA,MAAA,KAAW,IAAA,CAAK,KAAA;AAAA,gBAClB;AACA,gBAAA,MAAA,EAAO;AAAA,cACT,CAAC;AAAA;AACH;AACF,SACF;AAAA,MACF;AAAA,IACF,CAAA;AAAA,IACA,MAAM,IAAA,GAAO;AACX,MAAA,WAAS;AACP,QAAA,IAAI,MAAA,CAAO,OAAA,EAAS,MAAM,IAAI,gBAAA,EAAiB;AAC/C,QAAA,IAAI,QAAA,CAAS,SAAS,CAAA,EAAG;AACvB,UAAA,MAAM,GAAA,GAAM,QAAA;AACZ,UAAA,QAAA,GAAW,EAAC;AACZ,UAAA,OAAO,GAAA;AAAA,QACT;AACA,QAAA,IAAI,MAAA,KAAW,MAAA,EAAW,MAAM,KAAA,CAAM,OAAO,MAAM,CAAA;AACnD,QAAA,IAAI,CAAC,UAAA,EAAW,EAAG,OAAO,MAAA;AAC1B,QAAA,MAAM,IAAI,OAAA,CAAc,CAAC,OAAA,KAAY;AACnC,UAAA,IAAA,GAAO,OAAA;AAAA,QACT,CAAC,CAAA;AAAA,MACH;AAAA,IACF,CAAA;AAAA,IACA,MAAM,KAAA,GAAQ;AACZ,MAAA,MAAA,CAAO,mBAAA,CAAoB,SAAS,MAAM,CAAA;AAC1C,MAAA,MAAM,QAAA,GAAW,CAAC,GAAG,OAAA,CAAQ,QAAQ,CAAA,CAAE,IAAI,IAAI,CAAA;AAC/C,MAAA,OAAA,CAAQ,KAAA,EAAM;AACd,MAAA,MAAM,OAAA,CAAQ,IAAI,QAAQ,CAAA;AAAA,IAC5B;AAAA,GACF;AACF","file":"index.js","sourcesContent":["// ---------------------------------------------------------------------------\n// `drive(machine, initial, msg, interpret, opts)` for the Effect engine: the\n// Promise `drive`'s rounds, trace and bound, over the Effect engine's handlers\n// and Subs (#321).\n//\n// There is no second loop. Each Effect cell is adapted into the shared loop's\n// cell with the settle rule the engine itself uses (`settleCellExit` in\n// `src/effect/run.ts`), run with the services the caller provided, so a cell\n// settles here exactly as it does under `run`. The Subs the machine wants are\n// started and stopped after every fold, as the engine reconciles them, and\n// their Msgs are folded once the Cmds in flight have settled.\n// ---------------------------------------------------------------------------\n\nimport { Cause, Effect, Exit, Fiber, Stream } from \"effect\";\nimport { CellFailure } from \"../../effect/failures\";\nimport {\n  builtinRunners,\n  type CellErrors,\n  cellResult,\n  type EffectInterpret,\n  type EffectSubscribe,\n  type InterpretServices,\n  type SubscribeOption,\n  type SubscribeServices,\n  settleCellExit,\n} from \"../../effect/run\";\nimport type { Cmd, Machine, Sub } from \"../../pure/core\";\nimport {\n  annotateTrace,\n  DEFAULT_MAX_ROUNDS,\n  type DriveCell,\n  DriveNoHandlerError,\n  type DriveOptions,\n  type DriveResult,\n  DriveRoundsExceededError,\n  type DriveSubs,\n  desiredSubs,\n  driveContractOf,\n  driveLoop,\n  driveTraceOf,\n} from \"../drive-loop\";\n\n/**\n * The Effect `drive`'s options: the Promise `drive`'s, plus `subscribe` — the\n * runners the engine's `run` takes, required exactly when `run` requires them.\n */\nexport type EffectDriveOptions<U extends Sub, Ctx, B> = DriveOptions<Ctx> &\n  SubscribeOption<U, B>;\n\n/** The failures a drive ends with: the loop's own, and a hand-written cell's. */\nexport type EffectDriveError<M, C extends Cmd, I> =\n  | DriveRoundsExceededError<M, C>\n  | DriveNoHandlerError<M, C>\n  | CellErrors<C, I>;\n\n/** The drive was interrupted; nothing is left to run. */\nclass DriveInterrupted {}\n\ntype AnyCell = (cmd: unknown) => Effect.Effect<unknown, unknown>;\ntype AnyRunner = (sub: Sub) => Stream.Stream<unknown, unknown>;\ntype RunEffect = (\n  effect: Effect.Effect<unknown, unknown>,\n  options: { readonly signal: AbortSignal },\n) => Promise<Exit.Exit<unknown, unknown>>;\ntype ForkEffect = (\n  effect: Effect.Effect<unknown, unknown>,\n) => Fiber.Fiber<unknown, unknown>;\n\n/**\n * Drive `machine` from `initial` through `msg` against the REAL Effect\n * `interpret` map — the one a host hands the Effect engine's `run` — and the\n * Subs the machine wants, feeding every Msg back until the machine goes quiet.\n * Yields the settled state together with the whole history, `{ state, trace }`.\n *\n * The rounds, the trace, `maxRounds` and `clock` are the Promise `drive`'s\n * (`@demlik/tea/testing/promise`). What is the Effect engine's:\n *\n *   - a cell returns an Effect. A `Cmd.define`d Cmd's success mints `_ok` and\n *     its declared failure `_err`; a hand-written Cmd's success is its\n *     follow-up — a Msg, a list of them folded in order, or nothing (#324) —\n *     and its failure fails the drive, typed. A defect dies. A cell takes no\n *     `dispatch`, so a defined Cmd's handler cannot send its own `_ok` /\n *     `_err`: the engine's rule holds by construction;\n *   - the services the cells and runners read are this Effect's requirements,\n *     so a test provides them the way a host does: `Effect.provide(layer)`;\n *   - the Subs the machine wants run, through `opts.subscribe` or the engine's\n *     built-in runner, started and stopped after every fold. Their Msgs are\n *     folded once no Cmd's follow-up is pending. The drive settles once no Msg\n *     is pending and no Sub is still running, so hand it a runner whose Stream\n *     ends — a Sub that never ends keeps it waiting. A Stream that fails with\n *     an error it did not map to a Msg dies, as it stops the engine's run.\n *\n * Interrupting the drive interrupts every cell and Sub still running.\n *\n * ```ts\n * const { state, trace } = await Effect.runPromise(\n *   drive(machine, initial, { type: \"go\" }, {\n *     fetch: (cmd) =>\n *       Effect.gen(function* () {\n *         const api = yield* Api;\n *         return yield* api.get(cmd.id);\n *       }),\n *   }).pipe(Effect.provide(ApiTest)),\n * );\n * ```\n *\n * Fails with {@link DriveRoundsExceededError} when the machine is still\n * emitting work after `opts.maxRounds` rounds, {@link DriveNoHandlerError}\n * for a Cmd no cell answers, or a hand-written cell's own failure — each with\n * the partial trace, readable via `driveTraceOf`.\n */\nexport function drive<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n  // The defaults read no services, so an omitted map adds none to `R`.\n  I extends EffectInterpret<M, C> = EffectInterpret<M, C, never>,\n  B extends EffectSubscribe<M, U> = EffectSubscribe<M, U, never>,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  initial: S,\n  msg: M,\n  interpret: I,\n  ...[opts]: Record<never, never> extends EffectDriveOptions<U, Ctx, B>\n    ? [opts?: EffectDriveOptions<U, Ctx, B>]\n    : [opts: EffectDriveOptions<U, Ctx, B>]\n): Effect.Effect<\n  DriveResult<S, M, C>,\n  EffectDriveError<M, C, I>,\n  InterpretServices<I> | SubscribeServices<B>\n> {\n  const options = (opts ?? {}) as {\n    ctx?: Ctx;\n    maxRounds?: number;\n    clock?: () => number;\n    subscribe?: Readonly<Record<string, AnyRunner | undefined>>;\n  };\n  return Effect.gen(function* () {\n    const services = yield* Effect.context<\n      InterpretServices<I> | SubscribeServices<B>\n    >();\n    const runEffect = Effect.runPromiseExitWith(services) as RunEffect;\n    const fork = Effect.runForkWith(services) as ForkEffect;\n\n    return yield* Effect.callback<\n      DriveResult<S, M, C>,\n      EffectDriveError<M, C, I>\n    >((resume, signal) => {\n      const cells = interpret as unknown as Readonly<\n        Record<string, AnyCell | undefined>\n      >;\n      const defined = new Set((machine.cmds ?? []).map((def) => def.cmdType));\n      const cellFor = (type: string): DriveCell<M, C> | undefined => {\n        const cell = cells[type];\n        if (cell === undefined) return undefined;\n        return async (cmd) => {\n          const exit = await runEffect(cellResult(cell(cmd)), { signal });\n          if (signal.aborted) throw new DriveInterrupted();\n          return settleCellExit(exit, defined.has(type));\n        };\n      };\n\n      driveLoop(\n        machine,\n        initial,\n        msg,\n        options.ctx as Ctx,\n        options.maxRounds ?? DEFAULT_MAX_ROUNDS,\n        {\n          contract: driveContractOf(machine, options.clock ?? Date.now),\n          cellFor,\n          subs: effectSubs<S, M>(\n            machine,\n            options.subscribe ?? {},\n            fork,\n            signal,\n          ),\n        },\n      ).then(\n        (result) => resume(Effect.succeed(result)),\n        (error: unknown) => resume(failureOf<M, C, I>(error)),\n      );\n    });\n  });\n}\n\n/**\n * Sort what left the loop: its own failures and a hand-written cell's failure\n * are typed, everything else — a defect, a contract breach, a failed Sub — dies.\n */\nfunction failureOf<M, C extends Cmd, I>(\n  error: unknown,\n): Effect.Effect<never, EffectDriveError<M, C, I>> {\n  if (\n    error instanceof DriveRoundsExceededError ||\n    error instanceof DriveNoHandlerError\n  ) {\n    return Effect.fail(error as EffectDriveError<M, C, I>);\n  }\n  if (error instanceof CellFailure) {\n    annotateTrace(error.failure, driveTraceOf(error) ?? []);\n    return Effect.fail(error.failure as EffectDriveError<M, C, I>);\n  }\n  if (error instanceof DriveInterrupted) return Effect.interrupt;\n  return Effect.die(error);\n}\n\n/**\n * One started Sub. It stays registered while the machine wants it, even after\n * its Stream ends, so a Sub that finished is not started again — the engine\n * keeps it the same way. `stopped` drops any Msg that arrives after a fold\n * turned it off; `ended` says its Stream no longer runs.\n */\ninterface StartedSub {\n  stopped: boolean;\n  ended: boolean;\n  fiber?: Fiber.Fiber<unknown, unknown>;\n}\n\n/**\n * The Effect engine's Subs as the shared loop runs them: each wanted Sub's\n * Stream is drained on its own fiber into a buffer the loop reads between\n * rounds.\n */\nfunction effectSubs<S, M>(\n  machine: { readonly subs?: ReadonlyArray<unknown> },\n  subscribe: Readonly<Record<string, AnyRunner | undefined>>,\n  fork: ForkEffect,\n  signal: AbortSignal,\n): DriveSubs<S, M> {\n  const builtins = builtinRunners as unknown as Readonly<\n    Record<string, AnyRunner | undefined>\n  >;\n  const started = new Map<string, StartedSub>();\n  let buffered: M[] = [];\n  let failed: Cause.Cause<unknown> | undefined;\n  let wake: (() => void) | undefined;\n  const notify = (): void => {\n    const woken = wake;\n    wake = undefined;\n    woken?.();\n  };\n  signal.addEventListener(\"abort\", notify, { once: true });\n\n  const stop = (sub: StartedSub): Promise<void> => {\n    sub.stopped = true;\n    return sub.ended || sub.fiber === undefined\n      ? Promise.resolve()\n      : Effect.runPromise(Fiber.interrupt(sub.fiber));\n  };\n  const anyRunning = (): boolean =>\n    [...started.values()].some((sub) => !sub.ended);\n\n  return {\n    reconcile(state) {\n      const desired = desiredSubs(machine, state);\n      for (const [id, sub] of started) {\n        if (desired.has(id)) continue;\n        started.delete(id);\n        void stop(sub);\n      }\n      for (const [id, sub] of desired) {\n        if (started.has(id)) continue;\n        const make = subscribe[sub.type] ?? builtins[sub.type];\n        if (make === undefined) {\n          throw new Error(\n            `@demlik/tea: no subscribe runner for Sub type \"${sub.type}\". ` +\n              \"Pass one to drive in `subscribe`.\",\n          );\n        }\n        const entry: StartedSub = { stopped: false, ended: false };\n        started.set(id, entry);\n        entry.fiber = fork(\n          Stream.runForEach(make(sub), (next) =>\n            Effect.sync(() => {\n              if (entry.stopped) return;\n              buffered.push(next as M);\n              notify();\n            }),\n          ).pipe(\n            Effect.onExit((exit) =>\n              Effect.sync(() => {\n                entry.ended = true;\n                if (\n                  !entry.stopped &&\n                  Exit.isFailure(exit) &&\n                  !Cause.hasInterruptsOnly(exit.cause)\n                ) {\n                  failed ??= exit.cause;\n                }\n                notify();\n              }),\n            ),\n          ),\n        );\n      }\n    },\n    async next() {\n      for (;;) {\n        if (signal.aborted) throw new DriveInterrupted();\n        if (buffered.length > 0) {\n          const out = buffered;\n          buffered = [];\n          return out;\n        }\n        if (failed !== undefined) throw Cause.squash(failed);\n        if (!anyRunning()) return undefined;\n        await new Promise<void>((resolve) => {\n          wake = resolve;\n        });\n      }\n    },\n    async close() {\n      signal.removeEventListener(\"abort\", notify);\n      const stopping = [...started.values()].map(stop);\n      started.clear();\n      await Promise.all(stopping);\n    },\n  };\n}\n"]}

package/dist/testing/index.d.ts

@@ -1,112 +1,7 @@
-import { C as Cmd, S as Sub, M as Machine, a as BuiltinSub, p as Interpret } from '../core-BbgtiXdg.js';
-import { C as CtxArg, R as Runtime } from '../runtime-types-CiVpC0HN.js';
+import { C as Cmd, c as Sub, M as Machine, B as BuiltinSub } from '../core-Ce9ncpuv.js';
+import { R as Runtime } from '../runtime-types-BKg2CGMx.js';
 import '@standard-schema/spec';
 
-/**
- * The composed Model shape every `withX` wrapper produces: the base machine's
- * state nested under `base`, and the wrapper's own NAMED, serializable slice
- * under a single `$`-prefixed key. This helper does not care WHICH `$`-key the
- * wrapper uses — it discovers it structurally (the one non-`base` field).
- */
-type WrapperModel<S> = {
-    readonly base: S;
-} & {
-    readonly [K: `$${string}`]: unknown;
-};
-/** Options for the conformance replay. Mirrors `replay`'s second argument. */
-interface AssertWrapperFaithfulOpts<S, WM, BaseM, BaseCtx, WrapperCtx> {
-    /** The Msg sequence to fold through BOTH machines. Use the base's Msgs. */
-    readonly msgs: readonly BaseM[];
-    /** Ctx for the WRAPPED machine (base ctx + wrapper ports). */
-    readonly ctx: WrapperCtx;
-    /** Ctx for the BARE base machine. Defaults to `ctx` when omitted. */
-    readonly baseCtx?: BaseCtx;
-    /** Optional pre-`init` snapshot of the COMPOSED Model (wrapped rehydrate). */
-    readonly loaded?: WM | null;
-    /**
-     * Optional pre-`init` snapshot of the BARE base state. Supply when the
-     * wrapped `loaded` is non-null so the base-equivalence check rehydrates the
-     * base machine from the matching nested slice. Defaults to `loaded?.base`.
-     */
-    readonly baseLoaded?: S | null;
-    /**
-     * Opt-in relaxation for an INTERCEPTING wrapper (e.g. a retry wrapper).
-     *
-     * DEFAULT (`undefined` / `false`) — the OBSERVE-ONLY contract that a
-     * deadline wrapper satisfies: every bare base Cmd must appear
-     * UNCHANGED, in order, as a subsequence of the wrapped Cmd stream (properties
-     * 1 and 3b). The wrapper may APPEND its own Cmds but may NOT alter, drop, or
-     * retime a base Cmd. This is the strict default and it is NOT weakened.
-     *
-     * WHEN SET — for a wrapper whose whole job is to INTERCEPT a chosen base Cmd
-     * (retag it into a wrapper-owned carrier so the concern — cache / breaker /
-     * rate-limit / retry — can gate it), a target base Cmd LEGITIMATELY does not
-     * appear raw at the top level of the wrapped stream. The contract is still
-     * **retag-and-re-emit, never swallow** (rule 2): the Cmd must be RECORDED, not
-     * vanished. So when a bare base Cmd is ABSENT from the top-level wrapped
-     * subsequence, this option accepts it IFF, in that SAME transition window, it
-     * is recorded by the wrapper as one of:
-     *
-     *   - the inner payload of a `$x:*` "run" carrier Cmd (`carrierCmdType` +
-     *     `innerField`) — the retag path; OR
-     *   - any other `$x:*` divergence Cmd whose `recordsField` deep-equals the
-     *     base Cmd — the gate/defer path (e.g. a "fast-failed" or "deferred"
-     *     record Cmd that carries the base Cmd it diverged on).
-     *
-     * A target base Cmd that is NEITHER present raw NOR recorded by any `$x:*`
-     * Cmd in its window is a SWALLOW betrayal and still fails the gate.
-     *
-     * Provide the field names the carrier uses so the gate can unwrap it
-     * structurally without hard-coding any one wrapper's vocabulary.
-     */
-    readonly intercepting?: InterceptingOpt;
-}
-/**
- * Configures the intercepting relaxation (see
- * `AssertWrapperFaithfulOpts.intercepting`). All fields name the carrier /
- * divergence shape so the gate can structurally find a retagged base Cmd
- * inside a `$x:*` Cmd. The gate only EVER inspects `$x:*`-prefixed wrapped
- * Cmds for a recorded base Cmd — it never relaxes the check for a base Cmd
- * that appears under any non-wrapper Cmd type.
- */
-interface InterceptingOpt {
-    /**
-     * The `Cmd.type` of the wrapper's run-carrier (e.g. `"$resilience:run"`).
-     * A bare base Cmd that is retagged appears as `carrier[innerField]`.
-     */
-    readonly carrierCmdType: string;
-    /** The field on the carrier Cmd that holds the original base Cmd. */
-    readonly innerField: string;
-    /**
-     * OPTIONAL field on ANY OTHER `$x:*` Cmd that records a base Cmd the wrapper
-     * gated/deferred without running it (e.g. a fast-fail record). When present
-     * on a `$x:*` Cmd and deep-equal to the missing base Cmd, it counts as a
-     * recorded divergence. Omit when the wrapper only ever retags via the
-     * carrier.
-     */
-    readonly recordsField?: string;
-}
-/**
- * Assert a `withX` wrapper is TEA-faithful. Replays the wrapped machine and the
- * bare base machine over the same Msgs and checks the four conformance
- * properties (see file header).
- *
- * @param base       the bare base `Machine`.
- * @param makeWrapped a thunk that wraps `base` and returns the composed machine
- *   (e.g. `() => withTimeout(wired, cfg).machine`, where `wired.machine` is
- *   `base`). A thunk — not the wrapped value — so a wrapper that registers
- *   process-scoped ports (`definePort`) is constructed inside the assertion's
- *   control, and so the same betrayal-detector reads as
- *   `assertWrapperFaithful(wired.machine, () => withX(wired, cfg).machine, ...)`
- *   at every wrapper's test site.
- * @param opts       the conformance replay options.
- */
-declare function assertWrapperFaithful<S, BaseM extends {
-    type: string;
-}, BaseC extends Cmd, BaseU extends Sub, BaseCtx, WM extends WrapperModel<S>, WrapperM extends {
-    type: string;
-}, WrapperC extends Cmd, WrapperU extends Sub, WrapperCtx>(base: Machine<S, BaseM, BaseC, BaseU, BaseCtx>, makeWrapped: () => Machine<WM, WrapperM, WrapperC, WrapperU, WrapperCtx>, opts: AssertWrapperFaithfulOpts<S, WM, BaseM, BaseCtx, WrapperCtx>): void;
-
 /**
  * Shared options shape for every test assertion below. Mirrors the
  * second argument of `replay(machine, opts)` — `msgs` is the sequence to
@@ -266,154 +161,23 @@ declare function bindMachine<S, M extends {
 }, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, ctx: Ctx): BoundMachine<S, M, C, U, Ctx>;
 
 /**
- * The default round bound when `opts.maxRounds` is omitted: **100**.
+ * Assert that replaying `opts.msgs` is a pure function of the Msg log: the
+ * final state and every emitted Cmd come out the same under two different
+ * global wall-clocks and RNG seeds.
  *
- * A round is one drain of the pending Msgs plus one drain of the Cmds those
- * folds emitted, so a settling machine costs a handful; 100 is loose enough
- * that a legitimate retry ladder finishes inside it and tight enough that a
- * genuine cycle stops rather than hangs.
- */
-declare const DEFAULT_MAX_ROUNDS = 100;
-/**
- * One entry of a driven run's history, in dispatch order.
+ * `init` and `update` never receive a clock, so a cell that reads
+ * `Date.now()` or `Math.random()` reaches for the global one, and a replay of
+ * the same log on another day or another host lands somewhere else. Two
+ * back-to-back replays under one clock would hide that; this helper stubs
+ * two distinct ambients and compares. Time belongs in the Msg (an `at`
+ * field), where it is identical across replays.
  *
- * - `msg` — a Msg folded through the machine's reducer. The seed Msg is the
- *   first entry of every trace; every later one is a settle Msg a handler
- *   returned (or fired through its injected `dispatch`).
- * - `cmd` — a Cmd handed to an interpret handler. It is recorded BEFORE the
- *   handler is awaited, so a trace recovered from a rejected handler names the
- *   Cmd that rejected as its last entry.
+ * Subs are not compared: they are derived from the final state, so a state
+ * that matches yields the same Subs.
  */
-type DriveTraceEntry<M, C> = {
-    readonly kind: "msg";
-    readonly msg: M;
-} | {
-    readonly kind: "cmd";
-    readonly cmd: C;
-};
-/** What a settled {@link drive} hands back. */
-interface DriveResult<S, M, C> {
-    /** The state after the machine went quiet — no Msg pending, no Cmd unperformed. */
-    readonly state: S;
-    /**
-     * Every Msg folded and every Cmd dispatched, in order. Filtering it to its
-     * `msg` entries and replaying those through `replay` from the same initial
-     * state reproduces {@link DriveResult.state}.
-     */
-    readonly trace: readonly DriveTraceEntry<M, C>[];
-}
-/**
- * {@link drive}'s `ctx` field. `CtxArg` widened by exactly one case: a machine
- * declaring `ctx: undefined` in its `types` block — the pure shape every
- * how-to on this package writes — may omit it too. `CtxArg` alone keeps `ctx`
- * REQUIRED there, because `{}` is not assignable to `undefined`, which would
- * make the common pure call site spell `{ ctx: undefined }` to say nothing.
- * A machine whose `Ctx` carries a field a handler reads still requires it.
- */
-type DriveCtxArg<Ctx> = [undefined] extends [Ctx] ? {
-    readonly ctx?: Ctx;
-} : CtxArg<Ctx>;
-/**
- * {@link drive}'s options. `ctx` is conditionally optional (see
- * {@link DriveCtxArg}).
- */
-type DriveOptions<Ctx> = DriveCtxArg<Ctx> & {
-    /**
-     * The round bound. Exceeding it throws {@link DriveRoundsExceededError};
-     * `drive` never returns a half-driven state. Defaults to
-     * {@link DEFAULT_MAX_ROUNDS} (100).
-     */
-    readonly maxRounds?: number;
-    /**
-     * The clock that stamps `at` on a `Cmd.define`d Cmd's minted `_ok` / `_err`
-     * Msg — the one `run` takes. Defaults to `Date.now`; pin it for a test that
-     * asserts on `at`.
-     */
-    readonly clock?: () => number;
-};
-/**
- * Raised when a driven machine is still emitting work after `maxRounds` rounds.
- * Follows the tea error dialect (`override readonly name`) and carries a `_tag`
- * discriminant, so a test branches on it by `instanceof` or on the tag.
- *
- * It carries the round count it stopped at and the PARTIAL trace up to that
- * point, which is what a test needs to see the cycle — the bound alone says
- * only that one exists.
- */
-declare class DriveRoundsExceededError<M, C> extends Error {
-    /** The bound that was exceeded. */
-    readonly maxRounds: number;
-    /** The round the driver stopped at — always `maxRounds + 1`. */
-    readonly rounds: number;
-    /** Every Msg folded and Cmd dispatched before the driver gave up. */
-    readonly trace: readonly DriveTraceEntry<M, C>[];
-    readonly name = "DriveRoundsExceededError";
-    readonly _tag: "DriveRoundsExceededError";
-    constructor(
-    /** The bound that was exceeded. */
-    maxRounds: number, 
-    /** The round the driver stopped at — always `maxRounds + 1`. */
-    rounds: number, 
-    /** Every Msg folded and Cmd dispatched before the driver gave up. */
-    trace: readonly DriveTraceEntry<M, C>[]);
-}
-/**
- * Raised when a Cmd reaches {@link drive} with no handler for its `type` in the
- * `handlers` record. `Interpret`'s mapped type makes that a compile error at a
- * well-typed call site; this is the runtime arm for a handler record assembled
- * dynamically or cast.
- */
-declare class DriveNoHandlerError<M, C> extends Error {
-    /** The Cmd `type` nothing in the handler record answered. */
-    readonly cmdType: string;
-    /** Every Msg folded and Cmd dispatched before the miss. */
-    readonly trace: readonly DriveTraceEntry<M, C>[];
-    readonly name = "DriveNoHandlerError";
-    readonly _tag: "DriveNoHandlerError";
-    constructor(
-    /** The Cmd `type` nothing in the handler record answered. */
-    cmdType: string, 
-    /** Every Msg folded and Cmd dispatched before the miss. */
-    trace: readonly DriveTraceEntry<M, C>[]);
-}
-/**
- * Read back the partial trace `drive` attached to an error a handler rejected
- * with. Returns `undefined` for anything `drive` did not annotate.
- *
- * A rejecting handler's error propagates out of `drive` UNSWALLOWED — same
- * value, same `instanceof`, same `_tag` — so a test that already branches on
- * the handler's own error type keeps doing so. The trace rides along on a
- * non-enumerable property so it is recoverable without changing how the error
- * prints or serializes.
- */
-declare function driveTraceOf<M, C>(err: unknown): readonly DriveTraceEntry<M, C>[] | undefined;
-/**
- * Drive `machine` from `initial` through `msg` against the REAL interpret
- * `handlers`, feeding every settle Msg back until the machine goes quiet, and
- * hand back the settled state together with the whole history.
- *
- * `handlers` is the same table a host hands `run` as its `interpret` (e.g.
- * a jev knob's `resilient_run` handler), so the test drives the real interpreter and
- * mocks only the port beneath it.
- *
- * One round is: fold every pending Msg, then await a handler for every Cmd
- * those folds emitted. A Msg a handler returns — or fires through its injected
- * `dispatch` — is pending for the next round. A machine that emits no Cmd for
- * its seed Msg therefore settles in ONE round and never awaits a handler at
- * all.
- *
- * The `ctx` handed to each handler is `opts.ctx` augmented with a NO-OP `emit`,
- * so a handler that emits to a `Port` runs without a live runtime; nothing here
- * observes ports. Supply your own `emit` on `ctx` to capture them.
- *
- * @throws {DriveRoundsExceededError} when the machine is still emitting work
- *   after `opts.maxRounds` rounds. It never returns a half-driven state.
- * @throws whatever a handler rejects with, unchanged — annotated with the
- *   partial trace, readable via {@link driveTraceOf}.
- */
-declare function drive<S, M extends {
+declare function expectReplayDeterministic<S, M extends {
     type: string;
-}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, initial: S, msg: M, handlers: Interpret<M, C, Ctx>, ...[opts]: Record<never, never> extends DriveOptions<Ctx> ? [opts?: DriveOptions<Ctx>] : [opts: DriveOptions<Ctx>]): Promise<DriveResult<S, M, C>>;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, opts: NoInfer<ReplayOpts<S, M, Ctx>>): void;
 
 /**
  * Construct an inert `Runtime<S, M>` value. Use at ctx sites that require
@@ -464,14 +228,18 @@ type StateFactoryAPI<S extends {
  * overrides (undefineds stripped), then stamps the `type` discriminator.
  *
  * @example
- *   type S = { type: "a"; n: number } | { type: "b"; s: string };
- *   const f = stateFactory<S>({ a: { n: 0 }, b: { s: "" } });
- *   f.a();              // { type: "a", n: 0 }
- *   f.a({ n: 42 });     // { type: "a", n: 42 }
- *   f.b({ s: "hi" });   // { type: "b", s: "hi" }
+ * ```ts
+ * import { stateFactory } from "@demlik/tea/testing";
+ *
+ * type S = { type: "a"; n: number } | { type: "b"; s: string };
+ * const f = stateFactory<S>({ a: { n: 0 }, b: { s: "" } });
+ * f.a();              // { type: "a", n: 0 }
+ * f.a({ n: 42 });     // { type: "a", n: 42 }
+ * f.b({ s: "hi" });   // { type: "b", s: "hi" }
+ * ```
  */
 declare function stateFactory<S extends {
     type: string;
 }>(defaults: StateFactoryDefaults<S>): StateFactoryAPI<S>;
 
-export { type AssertWrapperFaithfulOpts, type BoundMachine, DEFAULT_MAX_ROUNDS, type DriveCtxArg, DriveNoHandlerError, type DriveOptions, type DriveResult, DriveRoundsExceededError, type DriveTraceEntry, type InterceptingOpt, type ReplayOpts, type StateFactoryAPI, type StateFactoryDefaults, type WrapperModel, assertWrapperFaithful, bindMachine, drive, driveTraceOf, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, noopRuntime, stateFactory, step };
+export { type BoundMachine, type ReplayOpts, type StateFactoryAPI, type StateFactoryDefaults, bindMachine, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, expectReplayDeterministic, noopRuntime, stateFactory, step };