@demlik/tea 0.19.0 → 0.21.0

package/dist/{runtime-types-BKg2CGMx.d.ts → runtime-types-BPKp2bGo.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-Ce9ncpuv.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-BKJW1Kmq.js';
 
 /**
  * @demlik/tea runtime interface surface + pure helpers — the public types,
@@ -12,6 +12,11 @@ import { C as Cmd, c as Sub, M as Machine, R as RunHandlers, P as Port, N as NoC
  */
 
 declare const ReducerBrand: unique symbol;
+/**
+ * A `Reducer` or `Transitions` value that went through `asReducer` or
+ * `defineMachine`. It carries the phantom brand and otherwise behaves exactly
+ * like the unbranded value.
+ */
 type Branded<T> = T & {
     readonly [ReducerBrand]: true;
 };
@@ -38,6 +43,10 @@ type Branded<T> = T & {
  * ```
  */
 declare function absurd(x: never): never;
+/**
+ * An update cell that ignores its Msg: it returns the state unchanged, with no
+ * Cmds. Use it to say a state deliberately does nothing for a Msg.
+ */
 declare const noop: <S, M, C extends Cmd>(state: S, _msg: M) => readonly [S, readonly C[]];
 /**
  * Thrown by `definePort` when a name has already been registered in the current
@@ -89,12 +98,14 @@ declare function __resetPortRegistry(): void;
  *   run stops — on the Effect engine by closing its Scope with the failure. A
  *   Sub that expects an error maps it to a Msg itself; there is no hook for it
  *   here.
- * - `"discard"` — work lost to a teardown the host asked for. Two witnesses,
- *   both carrying a `RuntimeDiscardNotice`: `stop()` was called while interpret
- *   handlers were still awaiting (`RuntimeDiscardedError`), and a Msg that
- *   arrived DURING `stop()`'s drain and so could not be delivered
- *   (`DispatchDiscardedError`), and teardown work that did not settle inside
- *   `disposeTimeoutMs` (`DisposeTimeoutNotice`). The one phase that is a
+ * - `"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`
+ *   (`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
  *   different instance (`IdentityDropNotice`). Its own phase rather than
@@ -228,7 +239,8 @@ declare abstract class RuntimeDiscardNotice extends Error {
 /**
  * Reported to the `OnError` sink under `phase: "discard"` when `stop()` is
  * called while `interpret` handlers are still awaiting. The host is dropping
- * its only handle on that work: `stop()` drains the tail, but the listeners,
+ * its only handle on that work: `stop()` drains the tail, up to
+ * `disposeTimeoutMs`, but the listeners,
  * observers and event handlers that would have consumed the resulting
  * transitions are gone, so the Cmds' results reach nobody.
  *
@@ -285,12 +297,48 @@ declare class DisposeTimeoutNotice extends RuntimeDiscardNotice {
     readonly _tag: "DisposeTimeoutNotice";
     constructor(pendingDisposals: number, timeoutMs: number);
 }
+/**
+ * Reported to the `OnError` sink under `phase: "discard"` when `stop()`'s wait
+ * for the queue hits `disposeTimeoutMs` (ADR 0025): a Cmd handler, a save or
+ * detached work had not returned.
+ *
+ * `stop()` resolves by contract, so it gives up on that work instead of waiting
+ * 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.
+ *
+ * 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;
+ * on a plain store that late save can overwrite what a newer run saved, and a
+ * fenced store refuses it.
+ *
+ * `cmdTypes` names the Cmd of each handler call still awaiting, one entry per
+ * call. `pendingCmds` counts those plus any detached work, the same count
+ * `RuntimeDiscardedError` carries.
+ */
+declare class DrainTimeoutNotice extends RuntimeDiscardNotice {
+    readonly cmdTypes: readonly string[];
+    readonly pendingCmds: number;
+    readonly timeoutMs: number;
+    readonly name = "DrainTimeoutNotice";
+    readonly _tag: "DrainTimeoutNotice";
+    constructor(cmdTypes: readonly string[], pendingCmds: number, timeoutMs: number);
+}
 /**
  * The rejection of a dispatch that arrived DURING `stop()`'s drain — an in-flight
  * interpret handler's follow-up Msg, a detached handler's terminal Msg, or a Sub
  * that is still live because subs are torn down only after the drain. The stop
  * barrier is absolute (the Msg is refused, never folded), so this names the loss.
  *
+ * It is also the rejection of the work `stop()` gave up on (see
+ * `DrainTimeoutNotice`): a Msg a stuck handler produces after `stop()` has
+ * returned, and a Msg that was accepted before `stop()` and was still queued
+ * behind that handler.
+ *
  * It is the SECOND witness of `RuntimeDiscardedError`'s fact, and it is why the
  * drain window is a distinct runtime state rather than a plain `stopped` flag:
  * a Msg refused inside the window was discarded BY the teardown, while the same
@@ -313,6 +361,11 @@ declare class DispatchDiscardedError extends RuntimeDiscardNotice {
  * telemetry) that should NOT be folded into State. Strengthens invariant 7.
  */
 declare function definePort<T>(name: string): Port<T>;
+/**
+ * Where an engine loads and saves a machine's state. Implement `load`, `save`
+ * and `migrate` to persist to your own storage, or use a store an adapter
+ * ships.
+ */
 interface Store<S> {
     load(): Promise<unknown>;
     save(state: S): Promise<void>;
@@ -361,6 +414,10 @@ declare class StoreRefusedError extends Error {
         readonly cause?: unknown;
     });
 }
+/**
+ * What a fenced store's `loadFenced` returns: the raw saved value and the
+ * version it was written at.
+ */
 interface FencedRead {
     /** Raw bytes at the key, the `Store.load` contract unchanged. */
     readonly raw: unknown;
@@ -429,6 +486,10 @@ declare class StoreConflictError extends Error {
     readonly _tag: "store_conflict";
     constructor(expectedVersion: number, actualVersion: number);
 }
+/**
+ * The minimal validator shape `schemaMigrate` accepts: an object with
+ * `safeParse`. A zod schema satisfies it.
+ */
 interface Schema<S> {
     safeParse(raw: unknown): {
         success: true;
@@ -447,7 +508,16 @@ interface Schema<S> {
  * return a {@link refuse}, so `run` fails instead of booting fresh over them.
  */
 declare function schemaMigrate<S>(schema: Schema<S>, upcast?: (raw: unknown) => unknown): (raw: unknown) => Migrated<S>;
+/**
+ * How long a `dispatch` waits before it resolves: `quiescent`, the default,
+ * waits for every follow-up Msg to drain, and `once` waits for the single
+ * transition.
+ */
 type DispatchSettle = "quiescent" | "once";
+/**
+ * The dispatch-only view of a runtime. Use it as the type of a handle one
+ * runtime holds in order to send Msgs to another.
+ */
 interface RuntimeRef<M extends {
     type: string;
 }> {
@@ -699,6 +769,11 @@ type MachineTypes<S, M extends {
     readonly sub?: U;
     readonly ctx?: Ctx;
 };
+/**
+ * Define a machine: its `init`, its `update` (a reducer or a transitions
+ * table), and optionally its `subs`, `cmds` and `identity`. Every tea program
+ * starts here; the result is plain data you hand to an engine's `run`.
+ */
 declare function defineMachine<S, M extends {
     type: string;
 }, D extends AnyCmdDef, U extends Sub = Sub<never>, Ctx = unknown>(m: NoInfer<Omit<Machine<S, M | Settled<D>, CmdOf<D>, U, Ctx>, "cmds">> & {
@@ -736,14 +811,35 @@ declare function defineMachine<S, M extends {
 }, C extends Cmd, U extends Sub, Ctx>(m: Omit<Machine<S, M, C, U, Ctx>, "update"> & {
     update: Reducer<S, M, C>;
 }): Machine<S, M, C, U, Ctx>;
+/**
+ * Type-check a standalone reducer record and return it branded. Use it when you
+ * write `update` apart from `defineMachine`.
+ */
 declare function asReducer<S, M extends {
     type: string;
 }, C extends Cmd>(reducer: Reducer<S, M, C>): Branded<Reducer<S, M, C>>;
+/**
+ * The `ctx` field of an engine's options: optional when the machine's `Ctx` is
+ * empty, required otherwise.
+ */
 type CtxArg<Ctx> = [Record<never, never>] extends [Ctx] ? {
     ctx?: Ctx;
 } : {
     ctx: Ctx;
 };
+/**
+ * Run a machine's `init` and then its `update` over a list of Msgs, with no
+ * engine, store or effects. Use it in unit tests to assert the final state, the
+ * 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.
+ *
+ * `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
+ * engine derives it, deduplicated by id the way the engine runs them. So a test
+ * asserts "the retry timer is armed in `waiting`" without wiring a runner.
+ */
 declare function replay<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, opts: {
@@ -755,6 +851,11 @@ declare function replay<S, M extends {
     cmds: C[];
     subs: (U | BuiltinSub<M>)[];
 };
+/**
+ * Adapt an `InterpretDetached` handler into an ordinary `interpret` cell. Use
+ * it for a Cmd whose work finishes after the handler returns and reports back
+ * through `dispatch`.
+ */
 declare function wrapDetached<C extends Cmd, M extends {
     type: string;
 }, Allowed extends M, Ctx>(handler: InterpretDetached<C, Allowed, Ctx>): (cmd: C, ctx: HandlerCtx<Ctx>, dispatch?: (msg: M) => void) => Promise<void>;
@@ -810,6 +911,16 @@ declare function tryFoldMsgs<S, M extends {
     update: object;
     __form?: UpdateForm;
 }, base: S, msgs: readonly M[]): Outcome<S, FoldRefusal<M>>;
+/**
+ * Wrap a function that may throw into a Cmd handler that never rejects: success
+ * maps to one Msg through `onOk`, failure to another through `onErr`. Use it
+ * for a hand-written Cmd; a `Cmd.define`d Cmd does not need it, because its
+ * handler returns an `Outcome` and the engine mints the Msg (ADR 0021).
+ *
+ * A rejection and a synchronous throw both reach `onErr(error, cmd)`, with the
+ * original error untouched so `instanceof` checks inside `onErr` hold. The
+ * never-rejects promise assumes `onOk` and `onErr` do not throw.
+ */
 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 { defineMachine as A, type BootingRuntime as B, type CtxArg as C, type DeletableStore as D, type EngineRun as E, type FencedStore as F, definePort as G, isFencedStore as H, IdentityDropNotice as I, noop as J, refuse as K, replay as L, type Migrated as M, schemaMigrate as N, type OnError as O, PortNameCollisionError as P, QuiescenceTimeoutError as Q, type Runtime as R, type Store as S, type TelemetrySink as T, tryApplyCell as U, tryFoldMsgs as V, tryInterpret as W, wrapDetached as X, __resetPortRegistry as _, type Supervision as a, type BootedRunHandle as b, type RunHandle as c, type Branded as d, DispatchDiscardedError as e, type DispatchSettle as f, DisposeTimeoutNotice as g, DriveFailedError as h, DriveStalledError as i, type FencedRead as j, type FoldRefusal as k, type MachineTypes as l, Refusal as m, type RunOptions as n, RuntimeDiscardNotice as o, RuntimeDiscardedError as p, type RuntimeErrorContext as q, type RuntimeErrorPhase as r, type RuntimeRef as s, type Schema as t, StoreConflictError as u, StoreRefusedError as v, type SupervisionStrategy as w, type TelemetryEvent as x, absurd as y, asReducer as z };
+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 };

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

@@ -1,9 +1,9 @@
-import { D as DriveRoundsExceededError, a as DriveNoHandlerError, b as DriveOptions, c as DriveResult } from '../../drive-loop-CsUsW3Wo.js';
-export { d as DEFAULT_MAX_ROUNDS, e as DriveCtxArg, f as DriveTraceEntry, g as driveTraceOf } from '../../drive-loop-CsUsW3Wo.js';
+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 '../../index-BnsAqn0-.js';
-import { C as Cmd, c as Sub, M as Machine } from '../../core-Ce9ncpuv.js';
-import '../../runtime-types-BKg2CGMx.js';
+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';
 import '@standard-schema/spec';

package/dist/testing/effect/index.js

@@ -1,11 +1,11 @@
-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 { 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';
 
 var DriveInterrupted = class {

package/dist/testing/index.d.ts

@@ -1,5 +1,5 @@
-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 { C as Cmd, c as Sub, M as Machine, B as BuiltinSub } from '../core-BKJW1Kmq.js';
+import { R as Runtime } from '../runtime-types-BPKp2bGo.js';
 import '@standard-schema/spec';
 
 /**

package/dist/testing/index.js

@@ -1,6 +1,6 @@
-export { bindMachine } from '../chunk-JVKU2UQC.js';
-import '../chunk-FNGZMVIT.js';
-import { replay } from '../chunk-AIIXV4XB.js';
+export { bindMachine } from '../chunk-7Z2IDZ7R.js';
+import '../chunk-VHKDUBXC.js';
+import { replay } from '../chunk-GAVLND5C.js';
 import { expect, vi } from 'vitest';
 
 function expectFinalState(machine, opts, expected) {

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

@@ -1,7 +1,7 @@
-import { b as DriveOptions, c as DriveResult } from '../../drive-loop-CsUsW3Wo.js';
-export { d as DEFAULT_MAX_ROUNDS, e as DriveCtxArg, a as DriveNoHandlerError, D as DriveRoundsExceededError, f as DriveTraceEntry, g as driveTraceOf } from '../../drive-loop-CsUsW3Wo.js';
-import { C as Cmd, c as Sub, M as Machine, I as Interpret } from '../../core-Ce9ncpuv.js';
-import '../../runtime-types-BKg2CGMx.js';
+import { b as DriveOptions, c as DriveResult } from '../../drive-loop-Dc6Z8Vbs.js';
+export { d as DEFAULT_MAX_ROUNDS, e as DriveCtxArg, a as DriveNoHandlerError, D as DriveRoundsExceededError, f as DriveTraceEntry, g as driveTraceOf } from '../../drive-loop-Dc6Z8Vbs.js';
+import { C as Cmd, c as Sub, M as Machine, I as Interpret } from '../../core-BKJW1Kmq.js';
+import '../../runtime-types-BPKp2bGo.js';
 import '@standard-schema/spec';
 
 /**

package/dist/testing/promise/index.js

@@ -1,8 +1,8 @@
-import { driveContractOf, driveLoop, DEFAULT_MAX_ROUNDS } from '../../chunk-H3MWNH7A.js';
-export { DEFAULT_MAX_ROUNDS, DriveNoHandlerError, DriveRoundsExceededError, driveTraceOf } from '../../chunk-H3MWNH7A.js';
-import '../../chunk-JVKU2UQC.js';
-import '../../chunk-FNGZMVIT.js';
-import { cmdEdge, Outcome } from '../../chunk-AIIXV4XB.js';
+import { driveContractOf, driveLoop, DEFAULT_MAX_ROUNDS } from '../../chunk-BFSZ4L6Y.js';
+export { DEFAULT_MAX_ROUNDS, DriveNoHandlerError, DriveRoundsExceededError, driveTraceOf } from '../../chunk-BFSZ4L6Y.js';
+import '../../chunk-7Z2IDZ7R.js';
+import '../../chunk-VHKDUBXC.js';
+import { cmdEdge, Outcome } from '../../chunk-GAVLND5C.js';
 
 // src/testing/promise/drive.ts
 async function drive(machine, initial, msg, handlers, ...[opts]) {

package/dist/timing/index.d.ts

@@ -1,9 +1,9 @@
 export { D as Debounced, d as debounce } from '../index-DHSUmQTR.js';
-import { C as Cmd } from '../core-Ce9ncpuv.js';
-import { T as TtlCache, a as DeadlineSub } from '../index-e36uEyl4.js';
-export { D as ThrottledInputSettled, s as subscribeThrottledInput, d as throttledInputSettled } from '../index-e36uEyl4.js';
+import { C as Cmd } from '../core-BKJW1Kmq.js';
+import { T as TtlCache, a as DeadlineSub } from '../index-Diyo8WBO.js';
+export { D as ThrottledInputSettled, s as subscribeThrottledInput, d as throttledInputSettled } from '../index-Diyo8WBO.js';
 import '@standard-schema/spec';
-import '../types-SzNSHKlV.js';
+import '../types-BiXj7k_k.js';
 
 /**
  * internal/timing/throttle — a timer-based call transformer that caps invocation

package/dist/timing/index.js

@@ -1,8 +1,8 @@
 export { debounce } from '../chunk-LFZUK6J2.js';
-import { deadlineSub, initCache, get, set } from '../chunk-C3G2QFEZ.js';
-export { subscribeDeadline as subscribeThrottledInput, deadlineExceeded as throttledInputSettled } from '../chunk-C3G2QFEZ.js';
-import '../chunk-FNGZMVIT.js';
-import '../chunk-AIIXV4XB.js';
+import { deadlineSub, initCache, get, set } from '../chunk-QIE4Y6BK.js';
+export { subscribeDeadline as subscribeThrottledInput, deadlineExceeded as throttledInputSettled } from '../chunk-QIE4Y6BK.js';
+import '../chunk-VHKDUBXC.js';
+import '../chunk-GAVLND5C.js';
 
 // src/internal/timing/throttle/index.ts
 function throttle(fn, ms, opts) {

package/dist/types-BiXj7k_k.d.ts

@@ -0,0 +1,9 @@
+import { c as Sub, D as Dispose } from './core-BKJW1Kmq.js';
+
+/**
+ * A Sub runner: given the Sub, the `ctx` and a `dispatch`, it opens the
+ * resource and returns a `Dispose`. Every `from*` factory returns one.
+ */
+type SubscribeHandler<S extends Sub, M, Ctx> = (sub: S, ctx: Ctx, dispatch: (msg: M) => void) => Dispose;
+
+export type { SubscribeHandler as S };

package/dist/work-queue/index.d.ts

@@ -1,7 +1,7 @@
-import { Q as QueueItem } from '../index-DWdg7R1l.js';
-export { E as EnqueueInput, a as QueueItemStatus, c as createQueue } from '../index-DWdg7R1l.js';
-import '../runtime-types-BKg2CGMx.js';
-import '../core-Ce9ncpuv.js';
+import { Q as QueueItem } from '../index-Cuy1_xTh.js';
+export { E as EnqueueInput, a as QueueItemStatus, c as createQueue } from '../index-Cuy1_xTh.js';
+import '../runtime-types-BPKp2bGo.js';
+import '../core-BKJW1Kmq.js';
 import '@standard-schema/spec';
 
 /**

package/dist/work-queue/index.js

@@ -1,7 +1,7 @@
 import { enqueueOp, claimNextOp, markDoneOp, patchItemOp, resetRunningOp, removeOp } from '../chunk-TXN2KFHF.js';
 export { claimNextOp, enqueueOp, markDoneOp, patchItemOp, queueAdapter, removeOp, resetRunningOp } from '../chunk-TXN2KFHF.js';
-import { restore } from '../chunk-JVE2LBFJ.js';
-import '../chunk-AIIXV4XB.js';
+import { restore } from '../chunk-Z7IL735U.js';
+import '../chunk-GAVLND5C.js';
 
 // src/internal/work-queue/index.ts
 function genId() {

package/dist/work-queue/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/internal/work-queue/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * internal/work-queue — substrate-agnostic work-queue lifecycle on `Store<S>`.\n *\n * Two public surfaces, one shape:\n *   - `createQueue(store)` (this file) is the in-process adapter — it binds the\n *     pure ops to an injected `Store` and runs `load → mutate → save`.\n *   - `internal/work-queue/ops` (`./ops`) is the BLESSED, importable surface\n *     of those same pure ops. L2 compositions that own their own Model slice\n *     (`monitored-run`, `idempotent-intake`, …) import the ops directly and\n *     delegate status flips to them instead of re-rolling the transitions.\n * Both routes call the identical ops, so the lifecycle rules live in exactly\n * one place. This mirrors `@demlik/tea/do`'s one-shape-per-package rule.\n *\n * The package is generic in the input payload `I` (audit-specific fields go\n * here in the extension host). `output` is a free-form side-channel correlation\n * token (a backend id, URL, trace id) — typed as `string` because that's its\n * only honest type. Consumers that need structured per-item data persist it in\n * their own store and put the foreign-key string in `output`.\n */\n\nimport type { Store } from \"../../index\";\nimport { restore } from \"../engine/restore\";\nimport {\n  claimNextOp,\n  enqueueOp,\n  markDoneOp,\n  patchItemOp,\n  removeOp,\n  resetRunningOp,\n} from \"./ops\";\n\n/**\n * Generate a queue-item id at the adapter boundary. Reads `Date.now()` and\n * `Math.random()` — impure helpers belong in the adapter (`index.ts`),\n * never in `ops.ts` (which is purely-functional by contract). Uses native\n * UUID when available, falls back to timestamp + random for environments\n * without `crypto.randomUUID`.\n */\nfunction genId(): string {\n  return (\n    globalThis.crypto?.randomUUID?.() ??\n    `q_${Date.now()}_${Math.random().toString(36).slice(2)}`\n  );\n}\n\nexport type QueueItemStatus =\n  | \"pending\"\n  | \"running\"\n  | \"done\"\n  | \"failed\"\n  | \"cancelled\";\n\n/**\n * A single queue entry. Every field is `readonly`: a persisted slice is\n * immutable, so a transition returns a NEW item (the ops always spread —\n * `{ ...item, status: … }`) rather than mutating in place. This type-enforces\n * the durability invariant the consumers already honor by convention, and\n * keeps a slice round-trippable through JSON unchanged across a reload.\n */\nexport interface QueueItem<I> {\n  readonly id: string;\n  readonly status: QueueItemStatus;\n  readonly input: I;\n  readonly enqueuedAt: number;\n  readonly startedAt?: number;\n  readonly finishedAt?: number;\n  readonly output?: string;\n  readonly error?: string;\n}\n\n/**\n * Caller-facing enqueue payload. Just `I` today — kept named so future\n * variants (priority, deferUntil, …) can grow without breaking callers.\n */\nexport type EnqueueInput<I> = I;\n\n/**\n * Adapter that binds the pure ops to an injected `Store<QueueItem<I>[]>`.\n *\n * `load → mutate → save` is the only durability discipline this package\n * imposes. The store decides what \"save\" means (chrome.storage, KV, DO\n * storage, in-memory) — that decision belongs at the caller.\n *\n * Ops that don't change the queue (e.g. `markDone` on an unknown id) skip the\n * save call so the underlying store doesn't observe a write churn.\n */\nexport function createQueue<I>(store: Store<QueueItem<I>[]>) {\n  // `Store<S>.load()` returns `unknown` (invariant 8 boundary). Route\n  // through `store.migrate(raw)` to get the typed value before any\n  // queue operation reads it — the same `restore` the substrate's `run()` uses\n  // at boot, so a queue it cannot read throws `StoreRefusedError` and no op\n  // saves over it. The work queue is a substrate-agnostic primitive on top of\n  // `Store<S>`, so it honors the same contract.\n  function loadParsed(): Promise<QueueItem<I>[] | null> {\n    return restore(store);\n  }\n\n  async function list(): Promise<QueueItem<I>[]> {\n    return (await loadParsed()) ?? [];\n  }\n\n  async function enqueue(input: EnqueueInput<I>): Promise<QueueItem<I>> {\n    const queue = await list();\n    const { next, item } = enqueueOp<I>(queue, input, Date.now(), genId());\n    await store.save(next);\n    return item;\n  }\n\n  async function claimNext(): Promise<QueueItem<I> | null> {\n    const queue = await list();\n    const result = claimNextOp<I>(queue, Date.now());\n    if (!result) return null;\n    await store.save(result.next);\n    return result.claimed;\n  }\n\n  // `markDone` ignores the optional second arg by design: completed runs leave\n  // the queue, and the consumer is expected to persist any output (auditId,\n  // etc.) wherever those completed records belong. Kept in the signature for\n  // call-site readability and forward-compat with `bindOutput`.\n  async function markDone(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = markDoneOp<I>(queue, id);\n    if (changed) await store.save(next);\n  }\n\n  async function markFailed(id: string, error: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"failed\",\n      finishedAt: Date.now(),\n      error,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  async function markCancelled(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"cancelled\",\n      finishedAt: Date.now(),\n    }));\n    if (changed) await store.save(next);\n  }\n\n  async function resetRunningToPending(): Promise<void> {\n    const queue = await list();\n    const { next, changed } = resetRunningOp<I>(queue);\n    if (changed) await store.save(next);\n  }\n\n  async function removeItem(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = removeOp<I>(queue, id);\n    if (changed) await store.save(next);\n  }\n\n  async function retryItem(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"pending\",\n      startedAt: undefined,\n      finishedAt: undefined,\n      error: undefined,\n      output: undefined,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  // `bindOutput` attaches a side-channel correlation token (string) to a\n  // running item without changing its status. The queue can't reach into\n  // `I` to mutate it (the substrate is domain-agnostic), so callers that\n  // need to thread a backend id / URL / trace id through the lifecycle\n  // route it here. Consumers needing structured payloads should persist\n  // them in their own store and put the foreign-key string in `output`.\n  async function bindOutput(id: string, value: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      output: value,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  return {\n    enqueue,\n    claimNext,\n    markDone,\n    markFailed,\n    markCancelled,\n    resetRunningToPending,\n    removeItem,\n    retryItem,\n    bindOutput,\n    list,\n  };\n}\n"]}
+{"version":3,"sources":["../../src/internal/work-queue/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * internal/work-queue — substrate-agnostic work-queue lifecycle on `Store<S>`.\n *\n * Two public surfaces, one shape:\n *   - `createQueue(store)` (this file) is the in-process adapter — it binds the\n *     pure ops to an injected `Store` and runs `load → mutate → save`.\n *   - `internal/work-queue/ops` (`./ops`) is the BLESSED, importable surface\n *     of those same pure ops. L2 compositions that own their own Model slice\n *     (`monitored-run`, `idempotent-intake`, …) import the ops directly and\n *     delegate status flips to them instead of re-rolling the transitions.\n * Both routes call the identical ops, so the lifecycle rules live in exactly\n * one place. This mirrors `@demlik/tea/do`'s one-shape-per-package rule.\n *\n * The package is generic in the input payload `I` (audit-specific fields go\n * here in the extension host). `output` is a free-form side-channel correlation\n * token (a backend id, URL, trace id) — typed as `string` because that's its\n * only honest type. Consumers that need structured per-item data persist it in\n * their own store and put the foreign-key string in `output`.\n */\n\nimport type { Store } from \"../../index\";\nimport { restore } from \"../engine/restore\";\nimport {\n  claimNextOp,\n  enqueueOp,\n  markDoneOp,\n  patchItemOp,\n  removeOp,\n  resetRunningOp,\n} from \"./ops\";\n\n/**\n * Generate a queue-item id at the adapter boundary. Reads `Date.now()` and\n * `Math.random()` — impure helpers belong in the adapter (`index.ts`),\n * never in `ops.ts` (which is purely-functional by contract). Uses native\n * UUID when available, falls back to timestamp + random for environments\n * without `crypto.randomUUID`.\n */\nfunction genId(): string {\n  return (\n    globalThis.crypto?.randomUUID?.() ??\n    `q_${Date.now()}_${Math.random().toString(36).slice(2)}`\n  );\n}\n\n/**\n * Where a queue item is in its lifecycle: `pending`, `running`, `done`,\n * `failed` or `cancelled`.\n */\nexport type QueueItemStatus =\n  | \"pending\"\n  | \"running\"\n  | \"done\"\n  | \"failed\"\n  | \"cancelled\";\n\n/**\n * A single queue entry. Every field is `readonly`: a persisted slice is\n * immutable, so a transition returns a NEW item (the ops always spread —\n * `{ ...item, status: … }`) rather than mutating in place. This type-enforces\n * the durability invariant the consumers already honor by convention, and\n * keeps a slice round-trippable through JSON unchanged across a reload.\n */\nexport interface QueueItem<I> {\n  readonly id: string;\n  readonly status: QueueItemStatus;\n  readonly input: I;\n  readonly enqueuedAt: number;\n  readonly startedAt?: number;\n  readonly finishedAt?: number;\n  readonly output?: string;\n  readonly error?: string;\n}\n\n/**\n * Caller-facing enqueue payload. Just `I` today — kept named so future\n * variants (priority, deferUntil, …) can grow without breaking callers.\n */\nexport type EnqueueInput<I> = I;\n\n/**\n * Adapter that binds the pure ops to an injected `Store<QueueItem<I>[]>`.\n *\n * `load → mutate → save` is the only durability discipline this package\n * imposes. The store decides what \"save\" means (chrome.storage, KV, DO\n * storage, in-memory) — that decision belongs at the caller.\n *\n * Ops that don't change the queue (e.g. `markDone` on an unknown id) skip the\n * save call so the underlying store doesn't observe a write churn.\n */\nexport function createQueue<I>(store: Store<QueueItem<I>[]>) {\n  // `Store<S>.load()` returns `unknown` (invariant 8 boundary). Route\n  // through `store.migrate(raw)` to get the typed value before any\n  // queue operation reads it — the same `restore` the substrate's `run()` uses\n  // at boot, so a queue it cannot read throws `StoreRefusedError` and no op\n  // saves over it. The work queue is a substrate-agnostic primitive on top of\n  // `Store<S>`, so it honors the same contract.\n  function loadParsed(): Promise<QueueItem<I>[] | null> {\n    return restore(store);\n  }\n\n  async function list(): Promise<QueueItem<I>[]> {\n    return (await loadParsed()) ?? [];\n  }\n\n  async function enqueue(input: EnqueueInput<I>): Promise<QueueItem<I>> {\n    const queue = await list();\n    const { next, item } = enqueueOp<I>(queue, input, Date.now(), genId());\n    await store.save(next);\n    return item;\n  }\n\n  async function claimNext(): Promise<QueueItem<I> | null> {\n    const queue = await list();\n    const result = claimNextOp<I>(queue, Date.now());\n    if (!result) return null;\n    await store.save(result.next);\n    return result.claimed;\n  }\n\n  // `markDone` ignores the optional second arg by design: completed runs leave\n  // the queue, and the consumer is expected to persist any output (auditId,\n  // etc.) wherever those completed records belong. Kept in the signature for\n  // call-site readability and forward-compat with `bindOutput`.\n  async function markDone(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = markDoneOp<I>(queue, id);\n    if (changed) await store.save(next);\n  }\n\n  async function markFailed(id: string, error: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"failed\",\n      finishedAt: Date.now(),\n      error,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  async function markCancelled(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"cancelled\",\n      finishedAt: Date.now(),\n    }));\n    if (changed) await store.save(next);\n  }\n\n  async function resetRunningToPending(): Promise<void> {\n    const queue = await list();\n    const { next, changed } = resetRunningOp<I>(queue);\n    if (changed) await store.save(next);\n  }\n\n  async function removeItem(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = removeOp<I>(queue, id);\n    if (changed) await store.save(next);\n  }\n\n  async function retryItem(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"pending\",\n      startedAt: undefined,\n      finishedAt: undefined,\n      error: undefined,\n      output: undefined,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  // `bindOutput` attaches a side-channel correlation token (string) to a\n  // running item without changing its status. The queue can't reach into\n  // `I` to mutate it (the substrate is domain-agnostic), so callers that\n  // need to thread a backend id / URL / trace id through the lifecycle\n  // route it here. Consumers needing structured payloads should persist\n  // them in their own store and put the foreign-key string in `output`.\n  async function bindOutput(id: string, value: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      output: value,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  return {\n    enqueue,\n    claimNext,\n    markDone,\n    markFailed,\n    markCancelled,\n    resetRunningToPending,\n    removeItem,\n    retryItem,\n    bindOutput,\n    list,\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@demlik/tea",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "TEA-faithful state machine substrate — one package, every host adapter. Core + subs + testing, plus React, Durable Object, Chrome extension, Node, in-memory, devtools, and property-testing modules as subpaths.",
   "keywords": [
     "tea",
@@ -193,7 +193,8 @@
     "vite": "^8.2.1",
     "vitest": "~5.0.1",
     "ws": "^8.21.0",
-    "zod": "^4.5.4"
+    "zod": "^4.5.4",
+    "@demlik/code-graph": "0.8.0"
   },
   "publishConfig": {
     "access": "public"
@@ -211,7 +212,9 @@
     "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
     "typecheck:consumers": "tsc -p tsconfig.consumers.json",
     "docs:reference": "TEA_DOCS_WRITE=1 vitest run src/docs/reference/generate-reference.test.ts",
-    "docs:reference:check": "pnpm run docs:reference && git diff --exit-code -- docs/reference",
+    "docs:reference:strays": "vitest run src/docs/reference/generate-reference.test.ts -t 'holds nothing the generator does not write'",
+    "api:ratchet": "node scripts/api-ratchet.mjs",
+    "docs:reference:check": "pnpm run docs:reference:strays && pnpm run docs:reference && git diff --exit-code -- docs/reference",
     "verify:exports": "node scripts/verify-exports.mjs",
     "verify-optional-peer-install": "node scripts/verify-optional-peer-install.mjs"
   }