@demlik/tea 0.21.0 → 0.22.0

package/dist/{runtime-types-BPKp2bGo.d.ts → runtime-types-CP-ykwgf.d.ts}

@@ -1,4 +1,4 @@
-import { C as Cmd, c as Sub, M as Machine, R as RunHandlers, P as Port, N as NoCellError, g as Reducer, A as AnyCmdDef, h as Settled, a as CmdOf, i as Transitions, B as BuiltinSub, U as UpdateForm, O as Outcome, j as InterpretDetached, H as HandlerCtx } from './core-BKJW1Kmq.js';
+import { C as Cmd, c as Sub, M as Machine, R as RunHandlers, P as Port, N as NoCellError, g as Reducer, A as AnyCmdDef, h as Settled, a as CmdOf, i as Transitions, B as BuiltinSub, U as UpdateForm, O as Outcome, j as InterpretDetached, H as HandlerCtx } from './core-DNDAEhO2.js';
 
 /**
  * @demlik/tea runtime interface surface + pure helpers — the public types,
@@ -101,10 +101,11 @@ declare function __resetPortRegistry(): void;
  * - `"discard"` — work lost to a teardown the host asked for. Four witnesses,
  *   each carrying a `RuntimeDiscardNotice`: `stop()` was called while interpret
  *   handlers were still awaiting (`RuntimeDiscardedError`), a Msg that
- *   arrived DURING `stop()`'s drain, or was still queued when `stop()` gave up
- *   on it, and so could not be delivered (`DispatchDiscardedError`), a drain
- *   that did not finish inside `disposeTimeoutMs` (`DrainTimeoutNotice`), and
- *   teardown work that did not settle inside `disposeTimeoutMs`
+ *   arrived DURING `stop()`'s drain, or from a handler `stop()` gave up on, and
+ *   so could not be delivered (`DispatchDiscardedError`), a drain that did not
+ *   finish inside `disposeTimeoutMs`, which also counts the Msgs that were still
+ *   queued (`DrainTimeoutNotice`), and teardown work that did not settle inside
+ *   `disposeTimeoutMs`
  *   (`DisposeTimeoutNotice`). The one phase that is a
  *   LIFECYCLE report rather than a failure: legal, merely lossy.
  * - `"identity-drop"` — the `Identity` filter dropped a message addressed to a
@@ -146,6 +147,14 @@ interface RuntimeErrorContext {
  * `run(machine, { onError })`. Should be total — a throw inside the sink is
  * itself surfaced via the default sink, so it can never re-introduce a silent
  * failure.
+ *
+ * Optional, except beside a fenced store (see {@link StoreAndOnError}): there it
+ * does not compile without one, and a run whose store is fenced at runtime is
+ * refused at start without one, whatever its type says. With no
+ * sink a `RuntimeDiscardNotice` is warned, and every other failure is rethrown on
+ * a fresh macrotask, which ends a Node process and every run in it. That includes
+ * a failing Sub (`"sub"`). A host running several machines in one process passes
+ * a sink that decides what one run's failure means for the rest.
  */
 type OnError = (error: unknown, context: RuntimeErrorContext) => void;
 /** The three declared reducer-throw supervision strategies. */
@@ -161,6 +170,14 @@ type SupervisionStrategy = "stop" | "escalate" | "restart";
 type Supervision<S, M extends {
     type: string;
 }> = "stop" | "escalate" | {
+    /**
+     * The default. A reducer throw stops the run by itself, the same stop a
+     * Sub failure starts: the Msgs already in line fold, then the Subs close,
+     * the final save runs and, on the Effect engine, the run's own Scope
+     * closes, so a run `spawn` started leaves the host's table and its
+     * `notify` runs. `done()` fails with the throw. A later `stop()` from the
+     * host does nothing more.
+     */
     readonly strategy: "stop";
 } | {
     readonly strategy: "escalate";
@@ -175,6 +192,17 @@ type Supervision<S, M extends {
      */
     readonly rehydrate: (state: S, msg: M, error: unknown) => S;
 };
+/**
+ * What `done()` rejects with once a Sub's failure the Sub did not map to a Msg
+ * has stopped the run, which can then never reach a terminal State. `cause` is
+ * what the Sub failed with, the same value `onError` heard under `"sub"`.
+ */
+declare class SubFailedError extends Error {
+    readonly cause: unknown;
+    readonly name = "SubFailedError";
+    readonly _tag: "SubFailedError";
+    constructor(cause: unknown);
+}
 /**
  * Raised by `idle()` when the quiescence wait hits its iteration cap without the
  * dispatch tail stabilizing — `idle()` REJECTS rather than silently resolving,
@@ -306,10 +334,18 @@ declare class DisposeTimeoutNotice extends RuntimeDiscardNotice {
  * for it without limit. It then stops the Subs and runs the final save as it
  * always does. The work it gave up on is not recalled — a Promise cannot be
  * cancelled — so a handler may still be running after `stop()` has returned.
- * Whatever it returns later is dropped, and so are the Msgs queued behind it:
- * each dropped Msg is a `DispatchDiscardedError`. The rest of its step's
- * Cmds are skipped: no handler starts for them, and they get no notice of
- * their own. None of it is saved.
+ * Whatever it returns later is dropped, and so are the Msgs queued behind it.
+ * The rest of its step's Cmds are skipped: no handler starts for them, and they
+ * get no notice of their own. None of it is saved.
+ *
+ * `droppedMsgs` is how a host learns what it lost. It counts the Msgs queued
+ * behind the stuck work when `stop()` gave up, per Msg type: Msgs handed to
+ * `dispatch` or `tell`, and those a handler or a Sub sent. It carries types and
+ * counts only, never a payload, so a sink can log it. It is read once and does
+ * not change. A Msg it counts is not reported again: if the handler returns
+ * late, a `dispatch` caller's promise rejects with a `DispatchDiscardedError`,
+ * and a Msg with no caller reaches the sink no second time. If the handler
+ * never returns, those promises never settle, and this count is the only word.
  *
  * tea starts no store call after `stop()` has returned. A store call already
  * under way when `stop()` gave up is not cancelled and can finish afterwards;
@@ -324,9 +360,10 @@ declare class DrainTimeoutNotice extends RuntimeDiscardNotice {
     readonly cmdTypes: readonly string[];
     readonly pendingCmds: number;
     readonly timeoutMs: number;
+    readonly droppedMsgs: Readonly<Record<string, number>>;
     readonly name = "DrainTimeoutNotice";
     readonly _tag: "DrainTimeoutNotice";
-    constructor(cmdTypes: readonly string[], pendingCmds: number, timeoutMs: number);
+    constructor(cmdTypes: readonly string[], pendingCmds: number, timeoutMs: number, droppedMsgs?: Readonly<Record<string, number>>);
 }
 /**
  * The rejection of a dispatch that arrived DURING `stop()`'s drain — an in-flight
@@ -470,6 +507,38 @@ interface DeletableStore<S> extends Store<S> {
 }
 /** Narrow a `Store<S>` to a {@link FencedStore} — what `run` uses to decide. */
 declare function isFencedStore<S>(store: Store<S>): store is FencedStore<S>;
+/**
+ * A `Store<S>` whose type says it is not fenced. A plain `Store<S>` fits it and
+ * a {@link FencedStore} does not. It is what lets {@link StoreAndOnError} tell the
+ * two apart, because a `FencedStore` is otherwise also a `Store`.
+ */
+type UnfencedStore<S> = Store<S> & {
+    readonly fenced?: never;
+};
+/**
+ * The `store` and `onError` options of a run: a fenced store needs an `onError`,
+ * and the mistake does not compile (ADR 0031).
+ *
+ * Losing a fence is routine for a host that moves runs between processes, and
+ * with no `onError` the default sink rethrows the conflict and ends the process,
+ * along with every other run in it. A conflict can reach the sink at any save
+ * with no caller to reject at: `"stop-save"` from `stop()`, `"follow-up"` from a
+ * Msg a Sub or a Cmd sent. So the sink is required at the type, not left to be
+ * remembered.
+ *
+ * It reads a store's declared type. A fenced store first assigned to a variable
+ * typed plain `Store<S>` has given that type up, so it compiles with no
+ * `onError`. Both engines then refuse it at start, before anything is loaded:
+ * the Promise engine's `run` throws, and the Effect engine's dies. A JavaScript
+ * caller is refused the same way.
+ */
+type StoreAndOnError<S> = {
+    readonly store?: UnfencedStore<S>;
+    readonly onError?: OnError;
+} | {
+    readonly store: Store<S>;
+    readonly onError: OnError;
+};
 /**
  * Thrown when a fenced save finds a version other than the one it expected —
  * another live writer has this run.
@@ -557,9 +626,12 @@ interface RunHandle<S, M extends {
 } = never> {
     /** Put a Msg in the inbox; resolves once the engine has processed it. */
     dispatch(msg: M): Promise<void>;
-    /** A zero-arg change notifier, fired after each applied transition. */
+    /**
+     * A zero-arg change notifier, fired for each applied transition after its
+     * save and before its first Cmd's handler starts.
+     */
     subscribe(listener: () => void): () => void;
-    /** A `(msg, state)` hook, fired after each applied transition. */
+    /** A `(msg, state)` hook, fired after each applied transition's Cmds. */
     observe(observer: (msg: M, state: S) => void): () => void;
     /** Fires once with the initial State — at once if boot already ran. */
     onBoot(handler: (state: S) => void): () => void;
@@ -584,15 +656,15 @@ interface BootedRunHandle<S, M extends {
 }
 /**
  * The options every engine's `run` accepts: the `ctx`, the handlers the
- * machine runs under, an optional `store`, and the `events` projector that
- * feeds `on`. An engine may take more; a host adapter hands only these.
+ * machine runs under, an optional `store` with the `onError` a fenced one needs,
+ * and the `events` projector that feeds `on`. An engine may take more; a host
+ * adapter hands only these.
  */
 type RunOptions<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx, E extends {
     type: string;
-} = never> = CtxArg<Ctx> & RunHandlers<M, C, U, Ctx> & {
-    readonly store?: Store<S>;
+} = never> = CtxArg<Ctx> & RunHandlers<M, C, U, Ctx> & StoreAndOnError<S> & {
     readonly events?: (msg: M, state: S) => readonly E[];
 };
 /**
@@ -633,12 +705,16 @@ interface BootingRuntime<S, M extends {
     }): Promise<void>;
     dispatchOnce(msg: M): Promise<void>;
     /**
-     * Register a zero-arg change notifier, fired for every applied transition
-     * with the fold's State already committed — `getState()` inside the listener
-     * reads it, not the State before. A `dispatch` issued from the listener is
-     * SCHEDULED onto the serial tail behind the fold that fired it, never folded
-     * re-entrantly and never discarded, so it needs no `setTimeout(fn, 0)`
-     * deferral; two listeners issuing in order fold in that order.
+     * Register a zero-arg change notifier, fired once for every applied
+     * transition, after its save and before its first Cmd's handler starts, so a
+     * view shows the State while that State's Cmds run. `getState()` inside the
+     * listener reads the new State, not the State before. A failed save fires
+     * nothing. The listener does not mean the Cmds are done: `observe`, `on` and
+     * `done()` hear after them. A `dispatch` issued from the listener is SCHEDULED
+     * onto the serial tail behind the fold that fired it, never folded re-entrantly
+     * and never discarded, so it needs no `setTimeout(fn, 0)` deferral; it folds
+     * ahead of what that fold's Cmds return, and two listeners issuing in order
+     * fold in that order.
      */
     subscribe(listener: () => void): () => void;
     /**
@@ -734,19 +810,30 @@ interface Runtime<S, M extends {
      */
     idle(): Promise<void>;
     /**
-     * The terminal State of the run, or `undefined` while in flight — "terminal"
+     * The saved terminal State of the run, or `undefined` while in flight — "terminal"
      * per the `terminal` predicate passed to `run()` (no predicate → never
      * terminal → always `undefined`). The first-class result read: the run's
      * product off the State the machine already owns, NOT scraped off the `observe`
-     * firehose by matching an internal Msg name. Total — never throws.
+     * firehose by matching an internal Msg name. With a store, returns `undefined`
+     * until the current State's save succeeds, including after a failed save.
+     * Without a store, answers as soon as State is set. Total — never throws, so a
+     * run a failure closed reads `undefined` here; `done()` says why.
      */
     result(): S | undefined;
     /**
-     * Resolves with the terminal State the first time the run reaches one (per the
-     * `terminal` predicate). If ALREADY terminal, resolves immediately; otherwise
-     * on the transition that first makes `terminal` hold. The awaitable companion
-     * to `result()`. With no predicate this never resolves. Idempotent and
-     * multi-caller safe.
+     * Resolves with the terminal State only once it is saved (per the `terminal`
+     * predicate). If ALREADY saved and terminal, resolves immediately; otherwise
+     * on that terminal commit. Rejects with the save failure if a terminal State
+     * cannot be saved, for both waiting and later callers. When a failure closes
+     * the run short of a terminal State, it rejects for both waiting and later
+     * callers too: with `SubFailedError` for a Sub failure the Sub did not map to
+     * a Msg, and with what was thrown for a reducer throw under the `stop`
+     * strategy. It answers that only after the Msgs already in line have folded,
+     * because one of them can still reach a terminal State, and then the State is
+     * the answer. A `stop()` with no failure leaves it pending. Without a store,
+     * answers as soon as State is set. The awaitable companion to `result()`. With
+     * no predicate this resolves never, and rejects only on those failures.
+     * Idempotent and multi-caller safe.
      */
     done(): Promise<S>;
 }
@@ -833,7 +920,9 @@ type CtxArg<Ctx> = [Record<never, never>] extends [Ctx] ? {
  * Cmds emitted, and the Subs that would be running.
  *
  * It composes `init(loaded ?? null, ctx)` and then `update(state, msg)` for each
- * Msg. No Cmd handler is called, no `Store` is touched and no Sub is started.
+ * Msg. Restored init may change State and emit Cmds; those Cmds are collected
+ * alongside update Cmds. No handler, Store or Sub runner is called.
+ * Recorded traces instead use `replayTrace` to fold their captured post-init State.
  *
  * `subs` is each `machine.subs` entry that is on at the final state, as its
  * runner would see it: `{ id, type, deps }`, the id derived exactly as the
@@ -923,4 +1012,4 @@ declare function tryFoldMsgs<S, M extends {
  */
 declare function tryInterpret<C extends Cmd, Ok, M, Ctx>(work: (cmd: C, ctx: Ctx) => Promise<Ok>, onOk: (value: Ok, cmd: C) => M, onErr: (error: unknown, cmd: C) => M): (cmd: C, ctx: Ctx) => Promise<M>;
 
-export { asReducer as A, type BootingRuntime as B, type CtxArg as C, type DeletableStore as D, type EngineRun as E, type FencedStore as F, defineMachine as G, definePort as H, IdentityDropNotice as I, isFencedStore as J, noop as K, refuse as L, type Migrated as M, replay as N, type OnError as O, PortNameCollisionError as P, QuiescenceTimeoutError as Q, type Runtime as R, type Store as S, type TelemetrySink as T, schemaMigrate as U, tryApplyCell as V, tryFoldMsgs as W, tryInterpret as X, wrapDetached as Y, __resetPortRegistry as _, type Supervision as a, type BootedRunHandle as b, type DispatchSettle as c, type RunHandle as d, type Branded as e, DispatchDiscardedError as f, DisposeTimeoutNotice as g, DrainTimeoutNotice as h, DriveFailedError as i, DriveStalledError as j, type FencedRead as k, type FoldRefusal as l, type MachineTypes as m, Refusal as n, type RunOptions as o, RuntimeDiscardNotice as p, RuntimeDiscardedError as q, type RuntimeErrorContext as r, type RuntimeErrorPhase as s, type RuntimeRef as t, type Schema as u, StoreConflictError as v, StoreRefusedError as w, type SupervisionStrategy as x, type TelemetryEvent as y, absurd as z };
+export { tryInterpret as $, type TelemetryEvent as A, type BootingRuntime as B, type CtxArg as C, type DeletableStore as D, type EngineRun as E, type FencedStore as F, absurd as G, asReducer as H, IdentityDropNotice as I, defineMachine as J, definePort as K, isFencedStore as L, type Migrated as M, noop as N, type OnError as O, PortNameCollisionError as P, QuiescenceTimeoutError as Q, type Runtime as R, type StoreAndOnError as S, type TelemetrySink as T, type UnfencedStore as U, refuse as V, replay as W, schemaMigrate as X, tryApplyCell as Y, tryFoldMsgs as Z, __resetPortRegistry as _, type BootedRunHandle as a, wrapDetached as a0, type Store as b, type Supervision as c, type DispatchSettle as d, type RunHandle as e, type Branded as f, DispatchDiscardedError as g, DisposeTimeoutNotice as h, DrainTimeoutNotice as i, DriveFailedError as j, DriveStalledError as k, type FencedRead as l, type FoldRefusal as m, type MachineTypes as n, Refusal as o, type RunOptions as p, RuntimeDiscardNotice as q, RuntimeDiscardedError as r, type RuntimeErrorContext as s, type RuntimeErrorPhase as t, type RuntimeRef as u, type Schema as v, StoreConflictError as w, StoreRefusedError as x, SubFailedError as y, type SupervisionStrategy as z };

package/dist/testing/effect/index.d.ts

@@ -1,12 +1,165 @@
-import { D as DriveRoundsExceededError, a as DriveNoHandlerError, b as DriveOptions, c as DriveResult } from '../../drive-loop-Dc6Z8Vbs.js';
-export { d as DEFAULT_MAX_ROUNDS, e as DriveCtxArg, f as DriveTraceEntry, g as driveTraceOf } from '../../drive-loop-Dc6Z8Vbs.js';
-import { Effect } from 'effect';
-import { C as CellErrors, S as SubscribeOption, E as EffectInterpret, a as EffectSubscribe, I as InterpretServices, b as SubscribeServices } from '../../run-D0sxbyno.js';
-import { C as Cmd, c as Sub, M as Machine } from '../../core-BKJW1Kmq.js';
-import '../../runtime-types-BPKp2bGo.js';
-import 'effect/Cause';
-import 'effect/Types';
+export { F as Fold, L as LawBreak, S as Step, f as foldEvents, l as lawInvariant, a as lawTerminates, b as lawTrace } from '../../laws-DTtCDDlU.js';
+import { e as DriveRoundsExceededError, d as DriveNoHandlerError, D as DriveOptions, a as DriveResult } from '../../drive-loop-DlOEv49c.js';
+export { b as DEFAULT_MAX_ROUNDS, c as DriveCtxArg, f as DriveTraceEntry, g as driveTraceOf } from '../../drive-loop-DlOEv49c.js';
+import * as effect_Cause from 'effect/Cause';
+import * as effect_Types from 'effect/Types';
+import { Arbitrary, Result, Effect } from 'effect';
+import { C as Cmd, c as Sub, M as Machine } from '../../core-DNDAEhO2.js';
+import { C as CellErrors, l as SubscribeOption, c as EffectInterpret, h as EffectSubscribe, I as InterpretServices, k as SubscribeServices } from '../../run-Cnw4qXj2.js';
+import '../../runtime-types-CP-ykwgf.js';
 import '@standard-schema/spec';
+import '../../loop-DReKGV1X.js';
+
+declare const NoCmdsError_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => effect_Cause.YieldableError & {
+    readonly _tag: "NoCmdsError";
+} & Readonly<A>;
+/**
+ * The machine has no `cmds` list, so there is no schema to draw an answer from.
+ *
+ * @experimental
+ */
+declare class NoCmdsError extends NoCmdsError_base<{
+    readonly message: string;
+}> {
+}
+declare const NotEffectSchemaError_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => effect_Cause.YieldableError & {
+    readonly _tag: "NotEffectSchemaError";
+} & Readonly<A>;
+/**
+ * A Cmd's `ok` schema is not an Effect schema, so no answer can be drawn from
+ * it. A Cmd made with `Cmd.define` from `@demlik/tea` over zod, or any other
+ * Standard Schema, lands here. `cmdType` names that Cmd.
+ *
+ * @experimental
+ */
+declare class NotEffectSchemaError extends NotEffectSchemaError_base<{
+    readonly cmdType: string;
+    readonly message: string;
+}> {
+}
+declare const NothingToDrawError_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => effect_Cause.YieldableError & {
+    readonly _tag: "NothingToDrawError";
+} & Readonly<A>;
+/**
+ * `machine.cmds` is empty and no `outside` Msg was given, so every list drawn
+ * would be empty.
+ *
+ * @experimental
+ */
+declare class NothingToDrawError extends NothingToDrawError_base<{
+    readonly message: string;
+}> {
+}
+/**
+ * Why {@link arbSchemaGuidedSequence} drew no lists.
+ *
+ * @experimental
+ */
+type SchemaAnswersError = NoCmdsError | NotEffectSchemaError | NothingToDrawError;
+/**
+ * What {@link arbSchemaGuidedSequence} takes beside the machine and its ctx.
+ *
+ * @experimental
+ */
+interface SchemaGuidedOptions<S, M extends {
+    type: string;
+}> {
+    /**
+     * The Msgs nothing sends a Cmd for, by Msg type: a user's click, a timer. A
+     * Msg type here and in no Cmd's answers is drawn only from here.
+     */
+    readonly outside?: {
+        readonly [K in M["type"]]?: Arbitrary.Arbitrary<Extract<M, {
+            type: K;
+        }>>;
+    };
+    /**
+     * Caps the events drawn. Default 60. `checkEffect` and `sampleEffect` cap a
+     * list at their `size` too, which defaults to 10, so pass a `size` of at least
+     * this to draw lists this long.
+     */
+    readonly maxLength?: number;
+    /**
+     * The saved state the fold starts from. Give `foldEvents` the same one, or it
+     * reads the list from a different start. Default `null`.
+     */
+    readonly loaded?: S | null;
+}
+/**
+ * Draw Msg lists for `Arbitrary.checkEffect` in which every answer answers a Cmd
+ * that was sent and not yet answered, and comes from that Cmd's own schema: an
+ * `ok` answer is drawn from its `schema.ok`, an `err` answer carries one of its
+ * `errTags`. Edit a schema and what is drawn changes with it, with no change to
+ * the test.
+ *
+ * Each list is drawn as blind events folded through the machine. An answer event
+ * names one waiting Cmd and is minted with that Cmd's def, `def.ok(cmd, value)`
+ * or `def.err(cmd, { _tag })`. With nothing waiting the answer is dropped, and an
+ * `outside` Msg the event drew goes in its place, or nothing when there is no
+ * `outside`. An event whose Msg the state has no cell for is dropped too, and a
+ * refused answer leaves its Cmd waiting. A Cmd no def in `machine.cmds` builds is
+ * never answered.
+ *
+ * It runs no check. Fold each list with `foldEvents` and judge it with a law,
+ * `lawInvariant`, `lawTerminates` or `lawTrace`, inside `Arbitrary.checkEffect`.
+ * A list it finds there shrinks by deleting events and shrinking them, and what
+ * is left still folds by the same rule. With `outside` given and every Msg
+ * accepted in every state, each event means one Msg, so a shrunk list is never
+ * longer than the one first found. A dropped event breaks that: deleting an
+ * answer before it can let it back in.
+ *
+ * It returns a failed `Result`, never an empty arbitrary, on a machine with no
+ * `machine.cmds` ({@link NoCmdsError}), on a Cmd whose `ok` schema is not an
+ * Effect schema ({@link NotEffectSchemaError}, naming it), and when there is
+ * nothing at all to draw ({@link NothingToDrawError}).
+ *
+ * @example
+ * ```ts
+ * import type { CmdOf, Machine, Settled } from "@demlik/tea";
+ * import { Cmd } from "@demlik/tea/effect";
+ * import {
+ *   arbSchemaGuidedSequence,
+ *   foldEvents,
+ *   lawInvariant,
+ * } from "@demlik/tea/testing/effect";
+ * import { Arbitrary, Effect, Result, Schema } from "effect";
+ *
+ * const fetchCount = Cmd.define("fetch_count", {
+ *   input: Schema.Struct({}),
+ *   ok: Schema.Struct({ n: Schema.Int }),
+ *   err: ["offline"],
+ * });
+ * type Msg = { type: "start" } | Settled<typeof fetchCount>;
+ * declare const machine: Machine<
+ *   { readonly total: number },
+ *   Msg,
+ *   CmdOf<typeof fetchCount>,
+ *   never,
+ *   object
+ * >;
+ *
+ * const lists = Result.getOrThrow(
+ *   arbSchemaGuidedSequence(machine, {}, {
+ *     outside: { start: Arbitrary.Constant({ type: "start" as const }) },
+ *   }),
+ * );
+ * const result = await Effect.runPromise(
+ *   Arbitrary.checkEffect(
+ *     lists,
+ *     (msgs) =>
+ *       lawInvariant(foldEvents(machine, {}, null, msgs), ({ next }) =>
+ *         Number.isFinite(next.total),
+ *       ) === null,
+ *     { runs: 500, size: 60 },
+ *   ),
+ * );
+ * ```
+ *
+ * @experimental
+ */
+declare function arbSchemaGuidedSequence<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, ctx: NoInfer<Ctx>, opts?: SchemaGuidedOptions<NoInfer<S>, M>): Result.Result<Arbitrary.Arbitrary<readonly M[]>, SchemaAnswersError>;
 
 /**
  * The Effect `drive`'s options: the Promise `drive`'s, plus `subscribe` — the
@@ -62,4 +215,4 @@ declare function drive<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx, I extends EffectInterpret<M, C> = EffectInterpret<M, C, never>, B extends EffectSubscribe<M, U> = EffectSubscribe<M, U, never>>(machine: Machine<S, M, C, U, Ctx>, initial: S, msg: M, interpret: I, ...[opts]: Record<never, never> extends EffectDriveOptions<U, Ctx, B> ? [opts?: EffectDriveOptions<U, Ctx, B>] : [opts: EffectDriveOptions<U, Ctx, B>]): Effect.Effect<DriveResult<S, M, C>, EffectDriveError<M, C, I>, InterpretServices<I> | SubscribeServices<B>>;
 
-export { DriveNoHandlerError, DriveOptions, DriveResult, DriveRoundsExceededError, type EffectDriveError, type EffectDriveOptions, drive };
+export { DriveNoHandlerError, DriveOptions, DriveResult, DriveRoundsExceededError, type EffectDriveError, type EffectDriveOptions, NoCmdsError, NotEffectSchemaError, NothingToDrawError, type SchemaAnswersError, type SchemaGuidedOptions, arbSchemaGuidedSequence, drive };

package/dist/testing/effect/index.js

@@ -1,13 +1,113 @@
-import { CellFailure, builtinRunners, cellResult, settleCellExit } from '../../chunk-HU3Y2AZY.js';
-import { driveLoop, DEFAULT_MAX_ROUNDS, driveContractOf, DriveRoundsExceededError, DriveNoHandlerError, annotateTrace, driveTraceOf, desiredSubs } from '../../chunk-BFSZ4L6Y.js';
-export { DEFAULT_MAX_ROUNDS, DriveNoHandlerError, DriveRoundsExceededError, driveTraceOf } from '../../chunk-BFSZ4L6Y.js';
-import '../../chunk-7Z2IDZ7R.js';
-import '../../chunk-VM7PMFV5.js';
-import '../../chunk-Z7IL735U.js';
-import '../../chunk-VHKDUBXC.js';
-import '../../chunk-GAVLND5C.js';
-import { Effect, Stream, Exit, Cause, Fiber } from 'effect';
+import { resolveGuided, MAX_PICK } from '../../chunk-FXWDDNGD.js';
+export { foldEvents, lawInvariant, lawTerminates, lawTrace } from '../../chunk-FXWDDNGD.js';
+import { CellFailure, builtinRunners, cellResult, settleCellExit } from '../../chunk-SHXUSTHM.js';
+import { driveLoop, DEFAULT_MAX_ROUNDS, driveContractOf, DriveRoundsExceededError, DriveNoHandlerError, annotateTrace, driveTraceOf, desiredSubs } from '../../chunk-ETRNSJCR.js';
+export { DEFAULT_MAX_ROUNDS, DriveNoHandlerError, DriveRoundsExceededError, driveTraceOf } from '../../chunk-ETRNSJCR.js';
+import '../../chunk-RMBZ7YH7.js';
+import '../../chunk-2A5XTKQQ.js';
+import '../../chunk-R2YNDRGL.js';
+import '../../chunk-DEAPNMKO.js';
+import '../../chunk-BVFS3ICC.js';
+import '../../chunk-A3QPMX5M.js';
+import { Data, Result, Arbitrary, Effect, Stream, Exit, Cause, Schema, Fiber } from 'effect';
 
+var NoCmdsError = class extends Data.TaggedError("NoCmdsError") {
+};
+var NotEffectSchemaError = class extends Data.TaggedError(
+  "NotEffectSchemaError"
+) {
+};
+var NothingToDrawError = class extends Data.TaggedError("NothingToDrawError") {
+};
+var PREFIX = "@demlik/tea/testing/effect: arbSchemaGuidedSequence";
+var upTo = (max) => Arbitrary.schema(
+  Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: max }))
+);
+var oneOf = (arms) => arms.length === 1 ? arms[0] : Arbitrary.flatMap(
+  upTo(arms.length - 1),
+  (at) => arms[at]
+);
+function outcomesOf(def) {
+  const ok = def.schema.ok;
+  if (!Schema.isSchema(ok)) return null;
+  const okArm = Schema.Struct({ outcome: Schema.Literal("ok"), value: ok });
+  const outcome = def.errTags.length === 0 ? okArm : Schema.Union([
+    okArm,
+    Schema.Struct({
+      outcome: Schema.Literal("err"),
+      tag: Schema.Literals(def.errTags)
+    })
+  ]);
+  return Arbitrary.schema(outcome);
+}
+function arbSchemaGuidedSequence(machine, ctx, opts) {
+  const defs = machine.cmds;
+  if (defs === void 0) {
+    return Result.fail(
+      new NoCmdsError({
+        message: `${PREFIX}: the machine has no \`cmds\`, so no Cmd has a schema to draw its answer from. List its \`Cmd.define\`d Cmds in \`defineMachine({ cmds })\`.`
+      })
+    );
+  }
+  const answerers = [];
+  const outcomes = [];
+  for (const def of defs) {
+    const drawn = outcomesOf(def);
+    if (drawn === null) {
+      return Result.fail(
+        new NotEffectSchemaError({
+          cmdType: def.cmdType,
+          message: `${PREFIX}: the "${def.cmdType}" Cmd's ok schema is not an Effect schema, so no answer can be drawn from it. Define it with \`Cmd.define\` from \`@demlik/tea/effect\`.`
+        })
+      );
+    }
+    const mint = def;
+    answerers.push({
+      cmdType: def.cmdType,
+      make: (cmd, value) => {
+        const drew = value;
+        return drew.outcome === "ok" ? mint.ok(cmd, drew.value) : mint.err(cmd, { _tag: drew.tag });
+      }
+    });
+    outcomes.push(drawn);
+  }
+  const outsides = Object.values(
+    opts?.outside ?? {}
+  );
+  const outside = outsides.length === 0 ? null : oneOf(outsides);
+  const answer = outcomes.length === 0 ? null : Arbitrary.map(
+    Arbitrary.all([
+      upTo(MAX_PICK),
+      Arbitrary.all(outcomes),
+      outside ?? Arbitrary.Constant(void 0)
+    ]),
+    ([pick, values, otherwise]) => otherwise === void 0 ? { kind: "answer", pick, values } : { kind: "answer", pick, values, otherwise }
+  );
+  const arms = [];
+  if (answer !== null) arms.push(answer, answer);
+  if (outside !== null) {
+    arms.push(
+      Arbitrary.map(
+        outside,
+        (msg) => ({ kind: "outside", msg })
+      )
+    );
+  }
+  if (arms.length === 0) {
+    return Result.fail(
+      new NothingToDrawError({
+        message: `${PREFIX}: \`machine.cmds\` is empty and no \`outside\` Msg was given, so every list would be empty.`
+      })
+    );
+  }
+  const loaded = opts?.loaded ?? null;
+  return Result.succeed(
+    Arbitrary.map(
+      Arbitrary.array(oneOf(arms), { maxLength: opts?.maxLength ?? 60 }),
+      (events) => resolveGuided(machine, ctx, loaded, answerers, events)
+    )
+  );
+}
 var DriveInterrupted = class {
 };
 function drive(machine, initial, msg, interpret, ...[opts]) {
@@ -143,6 +243,6 @@ function effectSubs(machine, subscribe, fork, signal) {
   };
 }
 
-export { drive };
+export { NoCmdsError, NotEffectSchemaError, NothingToDrawError, arbSchemaGuidedSequence, drive };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map