@demlik/tea 0.17.0 → 0.19.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,5 +1,5 @@
-import { C as Cmd, S as Sub, M as Machine, a as BuiltinSub, o as Interpret } from '../core-rDbOaJTN.js';
-import { C as CtxArg, R as Runtime } from '../runtime-types-B62Ucnxr.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';
 
 /**
@@ -160,156 +160,6 @@ declare function bindMachine<S, M extends {
     type: string;
 }, 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**.
- *
- * 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.
- *
- * - `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.
- */
-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 {
-    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>>;
-
 /**
  * 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
@@ -378,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 BoundMachine, DEFAULT_MAX_ROUNDS, type DriveCtxArg, DriveNoHandlerError, type DriveOptions, type DriveResult, DriveRoundsExceededError, type DriveTraceEntry, type ReplayOpts, type StateFactoryAPI, type StateFactoryDefaults, bindMachine, drive, driveTraceOf, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, expectReplayDeterministic, noopRuntime, stateFactory, step };
+export { type BoundMachine, type ReplayOpts, type StateFactoryAPI, type StateFactoryDefaults, bindMachine, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, expectReplayDeterministic, noopRuntime, stateFactory, step };

package/dist/testing/index.js

@@ -1,5 +1,6 @@
-import '../chunk-C4U5D5HP.js';
-import { replay, cmdEdgeOver, Outcome, cmdEdge } from '../chunk-K4ETBNKS.js';
+export { bindMachine } from '../chunk-JVKU2UQC.js';
+import '../chunk-FNGZMVIT.js';
+import { replay } from '../chunk-AIIXV4XB.js';
 import { expect, vi } from 'vitest';
 
 function expectFinalState(machine, opts, expected) {
@@ -22,133 +23,6 @@ function step(machine, loaded, msg, ctx) {
   const { state, cmds } = replay(machine, { msgs: [msg], ctx, loaded });
   return [state, cmds];
 }
-function bindMachine(machine, ctx) {
-  return {
-    step(loaded, msg) {
-      const { state, cmds } = replay(machine, { msgs: [msg], ctx, loaded });
-      return [state, cmds];
-    },
-    expectFinalState(opts, expected) {
-      const { state } = replay(machine, { ...opts, ctx });
-      expect(state).toEqual(expected);
-    },
-    expectCmdEmitted(opts, cmd) {
-      const { cmds } = replay(machine, { ...opts, ctx });
-      expect(cmds).toContainEqual(cmd);
-    },
-    expectCmdSequence(opts, expected) {
-      const { cmds } = replay(machine, { ...opts, ctx });
-      expect(cmds).toEqual(expected);
-    },
-    expectActiveSubs(opts, expected) {
-      const { subs } = replay(machine, { ...opts, ctx });
-      expect(subs).toEqual(expected);
-    },
-    replay(opts) {
-      return replay(machine, { ...opts, ctx });
-    }
-  };
-}
-
-// src/testing/drive.ts
-var DEFAULT_MAX_ROUNDS = 100;
-var DriveRoundsExceededError = class extends Error {
-  constructor(maxRounds, rounds, trace) {
-    super(
-      `@demlik/tea: drive did not settle within ${maxRounds} round(s) \u2014 the machine was still emitting work at round ${rounds}. The partial trace (${trace.length} entr${trace.length === 1 ? "y" : "ies"}) is on the error's \`trace\` field.`
-    );
-    this.maxRounds = maxRounds;
-    this.rounds = rounds;
-    this.trace = trace;
-  }
-  maxRounds;
-  rounds;
-  trace;
-  name = "DriveRoundsExceededError";
-  _tag = "DriveRoundsExceededError";
-};
-var DriveNoHandlerError = class extends Error {
-  constructor(cmdType, trace) {
-    super(
-      `@demlik/tea: drive found no interpret handler for Cmd type "${cmdType}" \u2014 the handlers record must answer every Cmd the machine emits.`
-    );
-    this.cmdType = cmdType;
-    this.trace = trace;
-  }
-  cmdType;
-  trace;
-  name = "DriveNoHandlerError";
-  _tag = "DriveNoHandlerError";
-};
-var TRACE_KEY = "driveTrace";
-function driveTraceOf(err) {
-  if (typeof err !== "object" || err === null) return void 0;
-  const carried = err[TRACE_KEY];
-  return Array.isArray(carried) ? carried : void 0;
-}
-async function drive(machine, initial, msg, handlers, ...[opts]) {
-  const options = opts ?? {};
-  const maxRounds = options.maxRounds ?? DEFAULT_MAX_ROUNDS;
-  const bound = bindMachine(machine, options.ctx);
-  const settle = cmdEdgeOver(machine.cmds ?? [], options.clock ?? Date.now);
-  const noopEmit = { emit: () => {
-  } };
-  const handlerCtx = {
-    ...noopEmit,
-    ok: Outcome.ok,
-    err: Outcome.err,
-    [cmdEdge]: settle,
-    ...options.ctx
-  };
-  const cells = handlers;
-  const trace = [];
-  let state = initial;
-  let pending = [msg];
-  let round = 0;
-  while (pending.length > 0) {
-    round += 1;
-    if (round > maxRounds) {
-      throw new DriveRoundsExceededError(maxRounds, round, trace);
-    }
-    const folding = pending;
-    pending = [];
-    const emitted = [];
-    for (const next of folding) {
-      trace.push({ kind: "msg", msg: next });
-      const [advanced, cmds] = bound.step(state, next);
-      state = advanced;
-      emitted.push(...cmds);
-    }
-    for (const cmd of emitted) {
-      trace.push({ kind: "cmd", cmd });
-      const cell = cells[cmd.type];
-      if (cell === void 0) {
-        throw new DriveNoHandlerError(cmd.type, trace);
-      }
-      let settled;
-      try {
-        settled = settle(
-          cmd,
-          await cell(cmd, handlerCtx, (fired) => {
-            pending.push(fired);
-          })
-        );
-      } catch (err) {
-        if (typeof err === "object" && err !== null) {
-          Object.defineProperty(err, TRACE_KEY, {
-            value: [...trace],
-            enumerable: false,
-            configurable: true,
-            writable: true
-          });
-        }
-        throw err;
-      }
-      if (settled !== void 0) pending.push(settled);
-    }
-  }
-  return { state, trace };
-}
 var AMBIENT_A = { now: 1e6, rng: 0.123 };
 var AMBIENT_B = { now: 9876543, rng: 0.987 };
 function expectReplayDeterministic(machine, opts) {
@@ -248,6 +122,6 @@ function stateFactory(defaults) {
   return api;
 }
 
-export { DEFAULT_MAX_ROUNDS, DriveNoHandlerError, DriveRoundsExceededError, bindMachine, drive, driveTraceOf, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, expectReplayDeterministic, noopRuntime, stateFactory, step };
+export { expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, expectReplayDeterministic, noopRuntime, stateFactory, step };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map