@demlik/tea 0.14.0 → 0.15.0

package/dist/parity/index.d.ts

@@ -1,6 +1,6 @@
-import { B as BootingRuntime } from '../runtime-types-LWDoi943.js';
-import { C as Cmd, S as Sub, M as Machine } from '../core-CTzMJ82M.js';
-import { T as Trace, R as RecorderOptions } from '../index-TvRb1KVf.js';
+import { B as BootingRuntime } from '../runtime-types-CMF13BBh.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-DnzqWy6u.js';
+import { T as Trace, R as RecorderOptions } from '../index-DrIRb_Ch.js';
 import 'better-result';
 import 'zod';
 

package/dist/parity/index.js

@@ -1,6 +1,6 @@
-import { recorder, deepEqual } from '../chunk-BLJ2JQSH.js';
+import { recorder, deepEqual } from '../chunk-V46HSVCK.js';
 import '../chunk-HWVW4AXC.js';
-import { replay } from '../chunk-RQULHGYH.js';
+import { replay } from '../chunk-66PY5WYF.js';
 
 // src/parity/index.ts
 function recordRun(runtime, opts) {

package/dist/pbt/index.d.ts

@@ -1,5 +1,5 @@
 import * as fc from 'fast-check';
-import { C as Cmd, S as Sub, M as Machine, d as Reducer, T as Transitions, U as UpdateForm } from '../core-CTzMJ82M.js';
+import { C as Cmd, S as Sub, M as Machine, d as Reducer, T as Transitions, U as UpdateForm } from '../core-DnzqWy6u.js';
 import 'zod';
 
 /**

package/dist/pbt/index.js

@@ -1,4 +1,4 @@
-import { replay, applyCell, msgKeysOf } from '../chunk-RQULHGYH.js';
+import { replay, applyCell, msgKeysOf } from '../chunk-66PY5WYF.js';
 import * as fc from 'fast-check';
 
 // src/pbt/arbitraries/ctx.ts

package/dist/persistence/index.d.ts

@@ -1,8 +1,8 @@
-import { T as Trace } from '../index-TvRb1KVf.js';
-export { B as BreadcrumbsOptions, a as Recorder, R as RecorderOptions, b as TraceAttachment, c as TraceBreadcrumb, d as breadcrumbsFromTrace, p as parseJSONL, r as recorder, t as traceAttachment } from '../index-TvRb1KVf.js';
-export { h as SnapshotConfig, d as SnapshotFailedMsg, i as SnapshotKnob, g as SnapshotLoadCmd, f as SnapshotLoadFailedMsg, e as SnapshotLoadedMsg, j as SnapshotPorts, c as SnapshotSavedMsg, a as SnapshotState, b as SnapshotStore, S as SnapshotWriteCmd, k as createSnapshot, s as snapshotFailed, l as snapshotLoad, m as snapshotLoadFailed, n as snapshotLoaded, o as snapshotSaved, p as snapshotWriteDef } from '../index-DMCeMPMJ.js';
-import { C as Cmd, S as Sub, M as Machine } from '../core-CTzMJ82M.js';
-import '../runtime-types-LWDoi943.js';
+import { T as Trace } from '../index-DrIRb_Ch.js';
+export { B as BreadcrumbsOptions, a as Recorder, R as RecorderOptions, b as TraceAttachment, c as TraceBreadcrumb, d as breadcrumbsFromTrace, p as parseJSONL, r as recorder, t as traceAttachment } from '../index-DrIRb_Ch.js';
+export { h as SnapshotConfig, d as SnapshotFailedMsg, i as SnapshotKnob, g as SnapshotLoadCmd, f as SnapshotLoadFailedMsg, e as SnapshotLoadedMsg, j as SnapshotPorts, c as SnapshotSavedMsg, a as SnapshotState, b as SnapshotStore, S as SnapshotWriteCmd, k as createSnapshot, s as snapshotFailed, l as snapshotLoad, m as snapshotLoadFailed, n as snapshotLoaded, o as snapshotSaved, p as snapshotWriteDef } from '../index-ZCMhnVKN.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-DnzqWy6u.js';
+import '../runtime-types-CMF13BBh.js';
 import 'better-result';
 import 'zod';
 

package/dist/persistence/index.js

@@ -1,6 +1,6 @@
-export { breadcrumbsFromTrace, deepEqual, parseJSONL, recorder, replayTrace, traceAttachment } from '../chunk-BLJ2JQSH.js';
-export { createSnapshot, snapshotFailed, snapshotLoad, snapshotLoadFailed, snapshotLoaded, snapshotSaved, snapshotWriteDef } from '../chunk-HUKZQX6U.js';
+export { breadcrumbsFromTrace, deepEqual, parseJSONL, recorder, replayTrace, traceAttachment } from '../chunk-V46HSVCK.js';
+export { createSnapshot, snapshotFailed, snapshotLoad, snapshotLoadFailed, snapshotLoaded, snapshotSaved, snapshotWriteDef } from '../chunk-L3TND7LA.js';
 import '../chunk-HWVW4AXC.js';
-import '../chunk-RQULHGYH.js';
+import '../chunk-66PY5WYF.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/protocol-D8VbH-VH.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The closed set of cross-module Msg/Cmd discriminant strings. Declared `as
+ * const` so each entry is usable as both a value (construction / reducer keys /
+ * switch labels) and, via `typeof MsgType.X`, a literal type (`readonly type:`
+ * fields). The single source of truth for issue #60.
+ */
+declare const MsgType: {
+    /** The "run the port for `key`" effect Cmd resilient-call emits. */
+    readonly ResilientRun: "resilient_run";
+    /** PRIVATE success settle Msg (read only by `agentEvents`, #47). */
+    readonly ResilientOk: "resilient_ok";
+    /** Failure settle Msg — routed to the `fail` verb (back off via retry). */
+    readonly ResilientErr: "resilient_err";
+    /** Begin a run. */
+    readonly AgentStart: "agent_start";
+    /** PRIVATE tool-fan-out success settle Msg (read only by `agentEvents`, #47). */
+    readonly AgentToolOk: "agent_tool_ok";
+    /** Tool-fan-out failure settle Msg. */
+    readonly AgentToolErr: "agent_tool_err";
+    /**
+     * Re-fire the one outstanding effect on rehydrate (the do↔agent seam). Fired
+     * by `do/host`'s `autoBoot` via the typed `agentBootMsg` constructor, matched
+     * by the agent reducer — see `AgentBootPort` in `../agent`.
+     */
+    readonly AgentBoot: "agent_boot";
+    /**
+     * Stop the run from outside and settle it `cancelled` — what an `AbortSignal`
+     * handed to `driveToDone` / a defined agent's `run` dispatches on abort. A
+     * transition, never a throw: the outcome lands in the Model, so a reload reads
+     * a run that ended rather than one to resume.
+     */
+    readonly AgentCancel: "agent_cancel";
+    /**
+     * The "summarize the oldest N turns" effect Cmd the agent emits when its
+     * `CompactionPolicy` asks to compact before a brain call. A DEDICATED
+     * round-trip (design B1), distinct from the brain call's `resilient_run`, so
+     * compaction is its own honest `Awaiting` state — see `../agent`.
+     */
+    readonly CompactRun: "compact_run";
+    /** Compaction round-trip resolved — carries the summary text the fold-back folds. */
+    readonly CompactOk: "compact_ok";
+    /** Compaction round-trip failed (exhausted retry) — surfaced as data, not a stall. */
+    readonly CompactErr: "compact_err";
+    /** Refresh port resolved — carries the fresh `Token`. */
+    readonly TokenRefreshed: "token_refreshed";
+    /** Refresh port rejected — carries the rejection (errors are data). */
+    readonly TokenRefreshFailed: "token_refresh_failed";
+    /** The 401 the consumer dispatches when a guarded call comes back unauthorized. */
+    readonly Unauthorized: "unauthorized";
+};
+/** The union of every discriminant string in the protocol. */
+type MsgTypeValue = (typeof MsgType)[keyof typeof MsgType];
+
+export { MsgType as M, type MsgTypeValue as a };

package/dist/react/index.d.ts

@@ -1,5 +1,5 @@
-import { S as Store, R as Runtime } from '../runtime-types-LWDoi943.js';
-import { C as Cmd, S as Sub, M as Machine, R as RequiredCtx } from '../core-CTzMJ82M.js';
+import { S as Store, R as Runtime } from '../runtime-types-CMF13BBh.js';
+import { C as Cmd, S as Sub, M as Machine, R as RequiredCtx } from '../core-DnzqWy6u.js';
 import 'better-result';
 import 'zod';
 

package/dist/react/index.js

@@ -1,4 +1,4 @@
-import { run } from '../chunk-RQULHGYH.js';
+import { run } from '../chunk-66PY5WYF.js';
 import { useMemo, useRef, useReducer, useSyncExternalStore, useEffect } from 'react';
 
 function useMachine(machine, opts) {

package/dist/resilience/index.d.ts

@@ -1,11 +1,12 @@
-import { a as CmdOf, b as CmdDef, C as Cmd, I as Interpret, i as CmdValue, g as PortEmitter, S as Sub, M as Machine } from '../core-CTzMJ82M.js';
-import { M as MsgType, e as ResilientConfig, a as ResilientState, R as RunCmd, S as SucceedMsg, F as FailMsg, f as ResilientTimerMsg, d as ResilientPorts } from '../index-B5BZ-_cT.js';
-export { g as CacheConfig, h as CallBudget, i as CallPhase, C as CircuitConfig, j as CircuitPolicy, k as CircuitState, l as DeadlineExceededError, c as RateLimitConfig, D as ResilientCallDeadlineConfig, m as RunCmdDef, n as SlidingWindow, T as TokenBucket, o as canPass, p as createResilientCall, q as defaultCircuitPolicy, r as initBucket, s as initCircuit, t as initWindow, u as liftResilience, v as onFailure, w as onSuccess, x as record, y as refill, z as remaining, A as runCmdDef, B as tryConsume } from '../index-B5BZ-_cT.js';
-import { a as DeadlineSub } from '../index-q0hXFeZ0.js';
-export { A as ArmTimer, e as CacheEntry, c as CacheEvictMsg, C as CacheEvictionSub, D as DeadlineExceeded, f as DeadlineOpts, T as TtlCache, g as cacheEvictMsg, h as cacheEvictionSub, i as cacheEvictionSubscribe, d as deadlineExceeded, b as deadlineSub, j as evictExpired, k as get, l as has, m as initCache, r as remove, n as set, o as setTimeoutArmTimer, s as subscribeDeadline, p as subscribeWith } from '../index-q0hXFeZ0.js';
+import { a as CmdOf, b as CmdDef, C as Cmd, I as Interpret, l as CmdValue, g as PortEmitter, i as NoCtx, S as Sub, M as Machine } from '../core-DnzqWy6u.js';
+import { M as MsgType } from '../protocol-D8VbH-VH.js';
+import { e as ResilientConfig, a as ResilientState, R as RunCmd, S as SucceedMsg, F as FailMsg, f as ResilientTimerMsg, c as ResilientPorts } from '../index-CA_7I5g9.js';
+export { g as CacheConfig, h as CallBudget, i as CallPhase, C as CircuitConfig, j as CircuitPolicy, k as CircuitState, l as DEFAULT_RESILIENT_NAME, n as DeadlineExceededError, o as DeadlineNameOf, p as DeadlineSettled, q as DefaultResilientName, M as MountConfig, r as MountableKnob, s as MountedCell, t as MountedResilientCall, b as RateLimitConfig, D as ResilientCallDeadlineConfig, u as ResilientDeadlineType, v as ResilientErrType, d as ResilientHandlers, w as ResilientOkType, x as ResilientRunType, y as RunCmdDef, z as Settle, A as SettleFold, B as SlidingWindow, T as TokenBucket, E as canPass, G as createResilientCall, H as defaultCircuitPolicy, I as initBucket, J as initCircuit, K as initWindow, L as liftResilience, m as mountResilientCall, N as onFailure, O as onSuccess, P as record, Q as refill, U as remaining, V as runCmdDef, W as tryConsume } from '../index-CA_7I5g9.js';
+import { a as DeadlineSub } from '../index-HSYgG2Yt.js';
+export { A as ArmTimer, e as CacheEntry, c as CacheEvictMsg, C as CacheEvictionSub, D as DeadlineExceeded, f as DeadlineMsgType, g as DeadlineOpts, T as TtlCache, h as cacheEvictMsg, i as cacheEvictionSub, j as cacheEvictionSubscribe, d as deadlineExceeded, k as deadlineMsgType, b as deadlineSub, l as evictExpired, m as get, n as has, o as initCache, r as remove, p as set, q as setTimeoutArmTimer, s as subscribeDeadline, t as subscribeWith } from '../index-HSYgG2Yt.js';
 import { Rng, RetryPolicy } from '../retry-backoff/index.js';
 import 'zod';
-import '../types-DP3f5NIl.js';
+import '../types-BseNPIhr.js';
 
 /**
  * A minted credential: the opaque `value` to send on the wire, and the absolute
@@ -248,7 +249,7 @@ declare function createAuthedCall<I, R>(config: AuthedConfig, rng?: () => number
         } | {
             readonly [detail: string]: unknown;
             readonly _tag: "port_rejected";
-        }, unknown>, ctx: Readonly<Record<never, never>>) => Promise<FailMsg | SucceedMsg<R>>;
+        }, unknown>, ctx: NoCtx) => Promise<SucceedMsg<R, "resilient"> | FailMsg<"resilient">>;
     };
 };
 /** The shape `createAuthedCall` returns — useful for typing a held knob. */

package/dist/resilience/index.js

@@ -1,9 +1,9 @@
-import { MsgType, createResilientCall } from '../chunk-AQ6ZIMEA.js';
-export { canPass, createResilientCall, defaultCircuitPolicy, initBucket, initCircuit, initWindow, liftResilience, onFailure, onSuccess, record, refill, remaining, runCmdDef, tryConsume } from '../chunk-AQ6ZIMEA.js';
+import { MsgType, createResilientCall } from '../chunk-AYS5N6WY.js';
+export { DEFAULT_RESILIENT_NAME, canPass, createResilientCall, defaultCircuitPolicy, initBucket, initCircuit, initWindow, liftResilience, mountResilientCall, onFailure, onSuccess, record, refill, remaining, runCmdDef, tryConsume } from '../chunk-AYS5N6WY.js';
 import { defaultRng, initRetry, recordFailure, shouldRetry, nextDelayMs } from '../chunk-VBDU4JL6.js';
-import { subscribeDeadline } from '../chunk-F2US5BW6.js';
-export { cacheEvictMsg, cacheEvictionSub, cacheEvictionSubscribe, deadlineExceeded, deadlineSub, evictExpired, get, has, initCache, remove, set, setTimeoutArmTimer, subscribeDeadline, subscribeWith } from '../chunk-F2US5BW6.js';
-import { Cmd, msgKeysOf, applyCell, fromTimeout, tryInterpret, cmdEdgeOf, subId, without, formOf } from '../chunk-RQULHGYH.js';
+import { subscribeDeadline } from '../chunk-22POWGFA.js';
+export { cacheEvictMsg, cacheEvictionSub, cacheEvictionSubscribe, deadlineExceeded, deadlineMsgType, deadlineSub, evictExpired, get, has, initCache, remove, set, setTimeoutArmTimer, subscribeDeadline, subscribeWith } from '../chunk-22POWGFA.js';
+import { Cmd, msgKeysOf, applyCell, fromTimeout, tryInterpret, cmdEdgeOf, subId, without, formOf } from '../chunk-66PY5WYF.js';
 import { z } from 'zod';
 
 function initTokenRefresh() {

package/dist/{runtime-types-LWDoi943.d.ts → runtime-types-CMF13BBh.d.ts}

@@ -1,5 +1,5 @@
 import { Result } from 'better-result';
-import { P as Port, N as NoCellError, C as Cmd, S as Sub, d as Reducer, A as AnyCmdDef, M as Machine, e as Settled, a as CmdOf, T as Transitions, f as RequirementsOf, g as PortEmitter, O as OkOf, E as ErrOf, U as UpdateForm, h as InterpretDetached } from './core-CTzMJ82M.js';
+import { P as Port, N as NoCellError, C as Cmd, S as Sub, d as Reducer, A as AnyCmdDef, M as Machine, e as Settled, a as CmdOf, T as Transitions, f as RequirementsOf, g as PortEmitter, O as OkOf, E as ErrOf, U as UpdateForm, h as InterpretDetached } from './core-DnzqWy6u.js';
 
 /**
  * @packageDocumentation

package/dist/testing/index.d.ts

@@ -1,5 +1,5 @@
-import { C as Cmd, S as Sub, M as Machine } from '../core-CTzMJ82M.js';
-import { R as Runtime } from '../runtime-types-LWDoi943.js';
+import { C as Cmd, S as Sub, M as Machine, I as Interpret } from '../core-DnzqWy6u.js';
+import { C as CtxArg, R as Runtime } from '../runtime-types-CMF13BBh.js';
 import 'zod';
 import 'better-result';
 
@@ -265,6 +265,150 @@ 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;
+};
+/**
+ * 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 record the machine declares as its `interpret` (e.g.
+ * `ask.handlers()` for a jev knob), 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>>;
+
 /**
  * Construct an inert `Runtime<S, M>` value. Use at ctx sites that require
  * a Runtime reference but where the test never invokes `interpret` (so
@@ -324,4 +468,4 @@ declare function stateFactory<S extends {
     type: string;
 }>(defaults: StateFactoryDefaults<S>): StateFactoryAPI<S>;
 
-export { type AssertWrapperFaithfulOpts, type BoundMachine, type InterceptingOpt, type ReplayOpts, type StateFactoryAPI, type StateFactoryDefaults, type WrapperModel, assertWrapperFaithful, bindMachine, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, noopRuntime, stateFactory, step };
+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 };

package/dist/testing/index.js

@@ -1,4 +1,4 @@
-import { replay } from '../chunk-RQULHGYH.js';
+import { replay } from '../chunk-66PY5WYF.js';
 import { expect, vi } from 'vitest';
 
 function assertWrapperFaithful(base, makeWrapped, opts) {
@@ -223,6 +223,99 @@ function bindMachine(machine, 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 noopEmit = { emit: () => {
+  } };
+  const handlerCtx = {
+    ...noopEmit,
+    ...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 settle;
+      try {
+        settle = 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 (settle !== void 0) pending.push(settle);
+    }
+  }
+  return { state, trace };
+}
+
 // src/testing/noop-runtime.ts
 function noopRuntime(opts) {
   const initialState = opts?.initialState;
@@ -297,6 +390,6 @@ function stateFactory(defaults) {
   return api;
 }
 
-export { assertWrapperFaithful, bindMachine, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, noopRuntime, stateFactory, step };
+export { DEFAULT_MAX_ROUNDS, DriveNoHandlerError, DriveRoundsExceededError, assertWrapperFaithful, bindMachine, drive, driveTraceOf, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, noopRuntime, stateFactory, step };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map