@demlik/tea 0.20.0 → 0.22.0

package/README.md

@@ -10,8 +10,8 @@ pnpm add @demlik/tea
 
 The one runtime dependency is `@standard-schema/spec`, a types-only package
 installed for you. [`Cmd.define`](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/glossary.md#cmd) takes any Standard Schema, so bring the schema
-library you already use (zod, or Effect Schema through
-`Schema.toStandardSchemaV1`). The host and
+library you already use (zod as it is, or Effect Schema through the
+`Cmd.define` that `@demlik/tea/effect` exports). The host and
 testing adapters ride on optional peers you add only for the surface you use:
 `react` / `react-dom` (the `./react` hooks), `ws` (Node WebSocket subs),
 `fast-check` (the `./pbt` property-testing helpers), `vitest` (the testing
@@ -70,6 +70,15 @@ Coming from 0.15?
 [The migration guide](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/how-to/migrate-from-0-15.md)
 shows every removed or reshaped API, before and after.
 
+## Durability
+
+With `fileStore` or `doStore`, state is saved before commands run. Restarting loads it.
+`agent.run` resumes pending work automatically; custom machines handle a boot
+message. An effect can run again if its result was not saved before the crash.
+
+[Make a machine durable](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/how-to/make-durable.md)
+and [understand restore versus replay](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/explanation/durability-model.md).
+
 ## Documentation
 
 The four Diátaxis quadrants live in [`docs/`](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/README.md):

package/dist/agent/index.d.ts

@@ -1,29 +1,29 @@
-import { M as Machine, I as Interpret, c as Subscribe, H as HandlerCtx, C as Cmd } from '../core-CtvAyPpH.js';
-import { b as DeadlinesSub } from '../index-CVU7SK3a.js';
-export { a as DeadlineSub, m as deadlineSub, o as deadlinesSub, s as subscribeDeadline } from '../index-CVU7SK3a.js';
-import { M as MessageContent, T as ToolCall, a as ToolOutcome, C as ContentPart, b as Conversation, c as AnyToolDef, d as ToolsCtx, e as AgentState, f as AgentTurn, g as ToolResult, A as AgentEvent, h as TurnChunk, i as AgentMachineMsg, W as WiredToolMsg, j as AgentCmd, k as ToolCmd, P as PlainModel, S as StreamingModel, l as ToolFailureOf, m as AgentTerminalFailure, N as NotReserved, n as ToolDef, o as ToolThrown, p as AgentEndedStatus, q as AgentConfigCore, r as CompactionPolicy, s as AgentKnob } from '../machine-Dtre2TmN.js';
-export { t as AGENT_EVENT_TYPES, u as AgentBootMsg, v as AgentCancelMsg, w as AgentCompactErrMsg, x as AgentCompactOkMsg, y as AgentCompactRunCmd, z as AgentCompactionConfig, B as AgentConfig, D as AgentEventHead, E as AgentFailure, F as AgentLifecycleNote, G as AgentLlmErrMsg, H as AgentLlmOkMsg, I as AgentLlmRunCmd, J as AgentSnapshotConfig, K as AgentStatus, L as AgentTimerMsg, O as AgentToMachine, Q as Awaiting, R as COMPACTION_PURPOSE, U as CompactInterpret, V as CompactionOutputs, X as CompactionPurpose, Y as CompactionSummary, Z as FILE_OMITTED, _ as FilePart, $ as IMAGE_OMITTED, a0 as ImagePart, a1 as Llm, a2 as LlmCall, a3 as LlmErr, a4 as LlmFailMsg, a5 as LlmOk, a6 as LlmRunCmd, a7 as LlmSucceedMsg, a8 as MediaSource, a9 as MessageLoader, aa as ModelFactory, ab as ModelPort, ac as ModelStream, ad as PLAIN_MODEL_MISROUTE_REASON, ae as ReservedToolName, af as Schema, ag as SnapshotInterpret, ah as TOOL_RETRY_EXHAUSTED_TAG, ai as TOOL_TIMEOUT_TAG, aj as TaggedFailure, ak as TextPart, al as ToolConstructors, am as ToolError, an as ToolFail, ao as ToolFailure, ap as ToolHandler, aq as ToolInput, ar as ToolMsg, as as ToolOk, at as ToolRecord, au as ToolRejectedCmd, av as ToolRejection, aw as ToolResilience, ax as ToolResilienceError, ay as ToolRetryExhausted, az as ToolRouter, aA as ToolSettlement, aB as ToolTimedOut, aC as TurnUsage, aD as WiredToolCmd, aE as agentBootMsg, aF as agentCancelMsg, aG as agentEvents, aH as agentTurnSchema, aI as compactionSummarySchema, aJ as contentParts, aK as fanOutInterpret, aL as isAgentTurn, aM as isCompactionSummary, aN as isReservedToolName, aO as isStreamingModel, aP as isTurnUsage, aQ as liftAgent, aR as mergeInterpret, aS as omitMedia, aT as plainModel, aU as status, aV as tool, aW as toolErrorReason, aX as toolRouter } from '../machine-Dtre2TmN.js';
+import { M as Machine, I as Interpret, S as Subscribe, H as HandlerCtx, C as Cmd } from '../core-DNDAEhO2.js';
+import { b as DeadlinesSub } from '../index-Cg0QXnzf.js';
+export { a as DeadlineSub, m as deadlineSub, o as deadlinesSub, s as subscribeDeadline } from '../index-Cg0QXnzf.js';
+import { M as MessageContent, T as ToolCall, a as ToolOutcome, C as ContentPart, b as Conversation, c as AnyToolDef, d as ToolsCtx, e as AgentState, f as AgentTurn, g as ToolResult, A as AgentEvent, h as TurnChunk, i as AgentMachineMsg, W as WiredToolMsg, j as AgentCmd, k as ToolCmd, P as PlainModel, S as StreamingModel, l as ToolFailureOf, m as AgentTerminalFailure, N as NotReserved, n as ToolDef, o as ToolThrown, p as AgentEndedStatus, q as AgentConfigCore, r as CompactionPolicy, s as AgentKnob } from '../machine-C0WhOAyB.js';
+export { t as AGENT_EVENT_TYPES, u as AgentBootMsg, v as AgentCancelMsg, w as AgentCompactErrMsg, x as AgentCompactOkMsg, y as AgentCompactRunCmd, z as AgentCompactionConfig, B as AgentConfig, D as AgentEventHead, E as AgentFailure, F as AgentLifecycleNote, G as AgentLlmErrMsg, H as AgentLlmOkMsg, I as AgentLlmRunCmd, J as AgentSnapshotConfig, K as AgentStatus, L as AgentTimerMsg, O as AgentToMachine, Q as Awaiting, R as COMPACTION_PURPOSE, U as CompactInterpret, V as CompactionOutputs, X as CompactionPurpose, Y as CompactionSummary, Z as FILE_OMITTED, _ as FilePart, $ as IMAGE_OMITTED, a0 as ImagePart, a1 as Llm, a2 as LlmCall, a3 as LlmErr, a4 as LlmFailMsg, a5 as LlmOk, a6 as LlmRunCmd, a7 as LlmSucceedMsg, a8 as MediaSource, a9 as MessageLoader, aa as ModelFactory, ab as ModelPort, ac as ModelStream, ad as PLAIN_MODEL_MISROUTE_REASON, ae as ReservedToolName, af as Schema, ag as SnapshotInterpret, ah as TOOL_RETRY_EXHAUSTED_TAG, ai as TOOL_TIMEOUT_TAG, aj as TaggedFailure, ak as TextPart, al as ToolConstructors, am as ToolError, an as ToolFail, ao as ToolFailure, ap as ToolHandler, aq as ToolInput, ar as ToolMsg, as as ToolOk, at as ToolRecord, au as ToolRejectedCmd, av as ToolRejection, aw as ToolResilience, ax as ToolResilienceError, ay as ToolRetryExhausted, az as ToolRouter, aA as ToolSettlement, aB as ToolTimedOut, aC as TurnUsage, aD as WiredToolCmd, aE as agentBootMsg, aF as agentCancelMsg, aG as agentEvents, aH as agentTurnSchema, aI as compactionSummarySchema, aJ as contentParts, aK as fanOutInterpret, aL as isAgentTurn, aM as isCompactionSummary, aN as isReservedToolName, aO as isStreamingModel, aP as isTurnUsage, aQ as liftAgent, aR as mergeInterpret, aS as omitMedia, aT as plainModel, aU as status, aV as tool, aW as toolErrorReason, aX as toolRouter } from '../machine-C0WhOAyB.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { C as CtxArg, S as Store } from '../runtime-types-DEluQgGO.js';
-import { E as EndedRun } from '../index-CZZ3HI-Z.js';
-export { M as MonitoredRunCmd, R as RunFailure } from '../index-CZZ3HI-Z.js';
+import { C as CtxArg, S as StoreAndOnError, O as OnError, U as UnfencedStore, b as Store } from '../runtime-types-CP-ykwgf.js';
+import { E as EndedRun } from '../index-CAsUE_d1.js';
+export { M as MonitoredRunCmd, R as RunFailure } from '../index-CAsUE_d1.js';
 import { RetryPolicy } from '../retry-backoff/index.js';
-import '../types-CXNzlbAg.js';
-import '../index-CKtEKGyp.js';
+import '../types-S53WDy_h.js';
+import '../index-C92SgNWz.js';
 import '../protocol-ClRZBhHQ.js';
-import '../index-CrcoVfd_.js';
-import '../index-D3NY3VCN.js';
-import '../index-Bk2hBUdK.js';
+import '../index-9P1PaXIV.js';
+import '../index-BBLI2WWN.js';
+import '../index-COeX9Bmz.js';
 
 /**
  * @demlik/tea/agent — `defineAgent`, the convenience layer over `createAgent`.
  *
- * `defineAgent({ model, tools, instructions })` is the three-line door: it
+ * `defineAgent({ model, tools, instructions })` is the three-line entry: it
  * defaults the single-stage wiring (`stages`, `turnOf`, `schemas`), derives the
  * tool handlers from `toolRouter`, renders the prompt off the Model, and absorbs
  * the drive loop through `driveToDone`. It hides wiring, never state (ADR
  * 0015): the Model it runs is the same `AgentState` a hand-wired `createAgent`
- * produces, under the same keys, and `machine(input)` is the door down to the
+ * produces, under the same keys, and `machine(input)` is the way down to the
  * raw kernel `run`. Each hidden thing is a named helper below.
  */
 
@@ -408,9 +408,11 @@ type DefinedAgentEvent<T extends AnyToolDef> = AgentEvent<ToolResult<T>>;
  *
  * `ctx` is the plain object the tools' handlers read (ADR 0020). A host with a
  * resource to release wraps `run` in its own `try` / `finally`.
+ *
+ * `onError` is the run's sink, and a fenced `store` needs one (see
+ * {@link StoreAndOnError}).
  */
-type DefinedAgentRunOptions<T extends AnyToolDef> = CtxArg<DefinedAgentCtx<T>> & {
-    readonly store?: Store<DefinedAgentState<T>>;
+type DefinedAgentRunOptions<T extends AnyToolDef> = CtxArg<DefinedAgentCtx<T>> & StoreAndOnError<DefinedAgentState<T>> & {
     /** The run's identity. Omit → a fresh UUID. */
     readonly runId?: string;
     /** The clock that stamps `at`. Omit → `Date.now`. */
@@ -524,7 +526,7 @@ interface DefinedAgent<T extends AnyToolDef> {
     readonly run: (input: string, ...opts: [Record<never, never>] extends [DefinedAgentCtx<T>] ? [opts?: DefinedAgentRunOptions<T>] : [opts: DefinedAgentRunOptions<T>]) => Promise<DefinedAgentResolvedState<T>>;
     /**
      * The machine `run` drives for `input` and the interpret table it runs under
-     * — the door down to the raw kernel.
+     * — the way down to the raw kernel.
      */
     readonly machine: (input: string) => DefinedAgentWired<T>;
     /**
@@ -546,7 +548,7 @@ interface DefinedAgent<T extends AnyToolDef> {
      * The wrapped cell settles through the SAME typed Cmd→Msg edge as the cell it
      * wraps — it returns whatever `next` returned — so the reducer folds the same
      * Msgs and a replay of a wrapped run is the unwrapped run's replay. That is
-     * the whole contract: the door is one over the effect boundary, never over
+     * the whole contract: the wrapper is one over the effect boundary, never over
      * the fold. A cell that must settle DIFFERENTLY is a different machine, and
      * `createAgent` is still where you build one.
      *
@@ -654,12 +656,23 @@ type AgentToolSpec<Args, Ok, CT extends AnyToolDef, Ctx> = {
      */
     readonly namespace: (ctx: HandlerCtx<Ctx>) => string;
     /**
-     * The child run's Store at `key`. The same key must reach the same durable
-     * cell on every call, in every process — that is what makes a re-fired call
-     * resume the child instead of restarting it.
+     * What the child run's failures with no caller to reject at reach. See
+     * `run`'s `onError`.
      */
+    readonly onError?: OnError;
+} & ChildCtxOption<CT, Ctx> & ChildStoreOption<CT, Ctx>;
+/**
+ * The child run's Store at `key`. The same key must reach the same durable cell
+ * on every call, in every process — that is what makes a re-fired call resume
+ * the child instead of restarting it. A child on a fenced Store needs an
+ * `onError`, the same rule `run`'s own `store` follows (ADR 0031).
+ */
+type ChildStoreOption<CT extends AnyToolDef, Ctx> = {
+    readonly store: (key: string, ctx: HandlerCtx<Ctx>) => UnfencedStore<DefinedAgentState<CT>>;
+} | {
     readonly store: (key: string, ctx: HandlerCtx<Ctx>) => Store<DefinedAgentState<CT>>;
-} & ChildCtxOption<CT, Ctx>;
+    readonly onError: OnError;
+};
 /**
  * Wrap a child `defineAgent` as a tool a parent `defineAgent` calls and awaits
  * — pass it the child, how to phrase its input and how to read its answer, and

package/dist/agent/index.js

@@ -1,16 +1,18 @@
-export { AGENT_EVENT_TYPES, COMPACTION_PURPOSE, FILE_OMITTED, IMAGE_OMITTED, PLAIN_MODEL_MISROUTE_REASON, TOOL_RETRY_EXHAUSTED_TAG, TOOL_TIMEOUT_TAG, agentBootMsg, agentCancelMsg, agentEvents, agentTool, agentTurnSchema, compactionSummarySchema, contentParts, createAgent, defineAgent, fanOutInterpret, isAgentTurn, isCompactionSummary, isReservedToolName, isStreamingModel, isTurnUsage, liftAgent, mergeInterpret, omitMedia, plainModel, renderPrompt, status, tool, toolErrorReason, toolRouter, transcript } from '../chunk-2774I242.js';
-import '../chunk-EA47MI5Q.js';
-import '../chunk-2R62Q5UK.js';
+export { AGENT_EVENT_TYPES, COMPACTION_PURPOSE, FILE_OMITTED, IMAGE_OMITTED, PLAIN_MODEL_MISROUTE_REASON, TOOL_RETRY_EXHAUSTED_TAG, TOOL_TIMEOUT_TAG, agentBootMsg, agentCancelMsg, agentEvents, agentTool, agentTurnSchema, compactionSummarySchema, contentParts, createAgent, defineAgent, fanOutInterpret, isAgentTurn, isCompactionSummary, isReservedToolName, isStreamingModel, isTurnUsage, liftAgent, mergeInterpret, omitMedia, plainModel, renderPrompt, status, tool, toolErrorReason, toolRouter, transcript } from '../chunk-WZEDIUWR.js';
+import '../chunk-VH5MYJ2K.js';
+import '../chunk-IAHEYPYJ.js';
 import '../chunk-QNGYQMZB.js';
-import '../chunk-72CN3VPY.js';
-export { deadlineSub, deadlinesSub, subscribeDeadline } from '../chunk-TAKPC6SD.js';
+import '../chunk-NFOGYDRS.js';
+export { deadlineSub, deadlinesSub, subscribeDeadline } from '../chunk-UGTC33VH.js';
 import '../chunk-VBDU4JL6.js';
 import '../chunk-4LPY67E4.js';
 import '../chunk-TXN2KFHF.js';
-import '../chunk-JAKM53JF.js';
-import '../chunk-UHAQ4PI6.js';
-import '../chunk-A73IJ27X.js';
-import '../chunk-DVNXEB7V.js';
-import '../chunk-RKVUVALV.js';
+import '../chunk-7K7SEYCH.js';
+import '../chunk-GFGOQIEC.js';
+import '../chunk-2A5XTKQQ.js';
+import '../chunk-R2YNDRGL.js';
+import '../chunk-DEAPNMKO.js';
+import '../chunk-BVFS3ICC.js';
+import '../chunk-A3QPMX5M.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{chunk-UHAQ4PI6.js → chunk-2A5XTKQQ.js}

@@ -1,5 +1,6 @@
-import { restore } from './chunk-A73IJ27X.js';
-import { RuntimeDiscardNotice, detachWork, DispatchDiscardedError, QuiescenceTimeoutError, RuntimeDiscardedError, IdentityDropNotice, checkedStep, cmdContractOver, Outcome, cmdEdge, isFencedStore, DisposeTimeoutNotice, NoCellError, lookupCell, structuralHash, desiredSub, followUps } from './chunk-RKVUVALV.js';
+import { restore } from './chunk-R2YNDRGL.js';
+import { installedState } from './chunk-DEAPNMKO.js';
+import { isFencedStore, RuntimeDiscardNotice, detachWork, acceptedTypes, DispatchDiscardedError, QuiescenceTimeoutError, IdentityDropNotice, checkedStep, cmdContractOver, Outcome, cmdEdge, SubFailedError, RuntimeDiscardedError, NoCellError, lookupCell, structuralHash, desiredSub, followUps, DrainTimeoutNotice, DisposeTimeoutNotice } from './chunk-A3QPMX5M.js';
 
 // src/internal/engine/builtins.ts
 function supervision(declared, machine) {
@@ -17,7 +18,7 @@ function supervision(declared, machine) {
           case "escalate":
             throw reduceError;
           default:
-            loop.halt();
+            loop.halt(reduceError);
             throw reduceError;
         }
       }
@@ -98,6 +99,14 @@ function fencing() {
     }
   });
 }
+function refuseFencedRunWithoutSink(store, onError) {
+  if (onError !== void 0 || store === void 0 || !isFencedStore(store)) {
+    return;
+  }
+  throw new Error(
+    "@demlik/tea: a run on a fenced store needs an `onError`. Without one, a lost fence ends the process and every run in it. Pass `onError` to `run`."
+  );
+}
 function ports() {
   return (loop) => {
     const registry = /* @__PURE__ */ new Map();
@@ -133,8 +142,10 @@ function observation() {
     const bootHandlers = /* @__PURE__ */ new Set();
     let booted = false;
     return {
-      commit(msg, state) {
+      installed() {
         loop.fanout(listeners, "listener", (listener) => listener());
+      },
+      commit(msg, state) {
         if (msg === void 0) {
           booted = true;
           loop.fanout(bootHandlers, "boot", (handler) => handler(state));
@@ -205,23 +216,57 @@ function terminality(isTerminal) {
   const holds = isTerminal ?? (() => false);
   return (loop) => {
     const waiters = /* @__PURE__ */ new Set();
+    let failure;
+    let stoppedBy;
     return {
+      subFailed(error) {
+        failure ??= { answer: new SubFailedError(error) };
+      },
+      halted(error) {
+        failure ??= { answer: error };
+      },
+      drained() {
+        if (failure === void 0) return;
+        stoppedBy = failure;
+        const state = loop.state();
+        const terminal = holds(state);
+        if (terminal && loop.saveStatus().type !== "saved") return;
+        const parked = [...waiters];
+        waiters.clear();
+        for (const waiter of parked) {
+          if (terminal) waiter.resolve(state);
+          else waiter.reject(stoppedBy.answer);
+        }
+      },
       commit(_msg, state) {
+        if (loop.saveStatus().type !== "saved" || waiters.size === 0 || !holds(state))
+          return;
+        const parked = [...waiters];
+        waiters.clear();
+        for (const waiter of parked) waiter.resolve(state);
+      },
+      saveFailed(state, error) {
         if (waiters.size === 0 || !holds(state)) return;
         const parked = [...waiters];
         waiters.clear();
-        for (const resolve of parked) resolve(state);
+        for (const waiter of parked) waiter.reject(error);
       },
       handle: {
         result() {
           const current = loop.state();
-          return holds(current) ? current : void 0;
+          return loop.saveStatus().type === "saved" && holds(current) ? current : void 0;
         },
         done() {
           const current = loop.state();
-          if (holds(current)) return Promise.resolve(current);
-          return new Promise((resolve) => {
-            waiters.add(resolve);
+          if (holds(current)) {
+            const saved = loop.saveStatus();
+            if (saved.type === "saved") return Promise.resolve(current);
+            if (saved.type === "failed") return Promise.reject(saved.error);
+          } else if (stoppedBy !== void 0) {
+            return Promise.reject(stoppedBy.answer);
+          }
+          return new Promise((resolve, reject) => {
+            waiters.add({ resolve, reject });
           });
         }
       }
@@ -266,6 +311,7 @@ function builtinExtensions(machine, opts) {
 
 // src/internal/engine/loop.ts
 var liveWork = /* @__PURE__ */ Symbol("demlik-tea.liveWork");
+var post = /* @__PURE__ */ Symbol("demlik-tea.post");
 function defaultOnError(error, _context) {
   if (error instanceof RuntimeDiscardNotice) {
     console.warn(error);
@@ -291,6 +337,21 @@ var RunningSub = class {
   };
   failed = false;
 };
+var MsgLine = class {
+  counts = /* @__PURE__ */ new Map();
+  joined(type) {
+    this.counts.set(type, (this.counts.get(type) ?? 0) + 1);
+  }
+  reachedTurn(type) {
+    const left = (this.counts.get(type) ?? 0) - 1;
+    if (left > 0) this.counts.set(type, left);
+    else this.counts.delete(type);
+  }
+  /** The counts now, in a fresh object later turns cannot change. */
+  snapshot() {
+    return Object.fromEntries(this.counts);
+  }
+};
 function startLoop(config) {
   const { idleCap, disposeTimeoutMs } = config;
   const onError = config.onError ?? defaultOnError;
@@ -312,18 +373,27 @@ function startLoop(config) {
     }
   }
   let state;
+  let installed;
+  let saveStatus = { type: "pending" };
   let bootError = null;
   let gate = "open";
-  let inFlightCmds = 0;
+  const inFlight = /* @__PURE__ */ new Set();
   const services = {
     report,
     fanout,
-    halt() {
-      gate = "closed";
+    halt(error) {
+      const stopping = gate !== "open";
+      if (gate !== "abandoned") gate = "closed";
+      for (const ext of extensions) ext.halted?.(error);
+      if (!stopping) config.stopOnFailure({ kind: "halt", error });
     },
-    state: () => state
+    state: () => state,
+    saveStatus: () => config.store === void 0 ? { type: "saved" } : saveStatus
   };
   const extensions = config.extensions.map((make) => make(services));
+  function lastStateReached() {
+    fanout(extensions, "sub", (ext) => ext.drained?.());
+  }
   const update = extensions.reduceRight(
     (next, ext) => ext.update ? ext.update(next) : next,
     config.reduce
@@ -333,6 +403,9 @@ function startLoop(config) {
     (inner, ext) => ext.store ? ext.store(inner) : inner,
     config.store
   );
+  const installedCallbacks = extensions.flatMap(
+    (ext) => ext.installed ? [ext.installed] : []
+  );
   const commitCallbacks = extensions.flatMap(
     (ext) => ext.commit ? [ext.commit] : []
   );
@@ -343,6 +416,7 @@ function startLoop(config) {
     { [detachWork]: detachInFlight }
   );
   let tail = Promise.resolve();
+  const line = new MsgLine();
   const subRegistry = /* @__PURE__ */ new Map();
   function stopSubs(ids) {
     for (const id of ids) {
@@ -366,27 +440,45 @@ function startLoop(config) {
     });
     pendingDisposals.add(settling);
   }
-  async function drainDisposals() {
-    if (pendingDisposals.size === 0) return;
-    const outstanding = [...pendingDisposals];
+  async function withinLimit(work) {
     let timer;
     try {
-      const outcome = await Promise.race([
-        Promise.all(outstanding).then(() => "settled"),
+      return await Promise.race([
+        work.then(() => "settled"),
         new Promise((resolve) => {
           timer = setTimeout(() => resolve("timeout"), disposeTimeoutMs);
         })
       ]);
-      if (outcome === "timeout") {
-        report(
-          new DisposeTimeoutNotice(outstanding.length, disposeTimeoutMs),
-          "discard"
-        );
-      }
     } finally {
       if (timer !== void 0) clearTimeout(timer);
     }
   }
+  async function drainTail() {
+    if (await withinLimit(tail) === "settled") {
+      gate = "closed";
+      return;
+    }
+    report(
+      new DrainTimeoutNotice(
+        [...inFlight].flatMap(({ cmdType }) => cmdType ?? []),
+        inFlight.size,
+        disposeTimeoutMs,
+        line.snapshot()
+      ),
+      "discard"
+    );
+    gate = "abandoned";
+  }
+  async function drainDisposals() {
+    if (pendingDisposals.size === 0) return;
+    const outstanding = [...pendingDisposals];
+    if (await withinLimit(Promise.all(outstanding)) === "timeout") {
+      report(
+        new DisposeTimeoutNotice(outstanding.length, disposeTimeoutMs),
+        "discard"
+      );
+    }
+  }
   function reconcileSubs() {
     let firstError = null;
     const remember = (err) => {
@@ -452,10 +544,11 @@ function startLoop(config) {
     report(error, "sub");
     if (gate !== "open") return;
     gate = "draining";
-    config.stopOnSubFailure(error);
+    for (const ext of extensions) ext.subFailed?.(error);
+    config.stopOnFailure({ kind: "sub", error });
   }
   function dispatchUnawaited(msg) {
-    enqueueDispatch(msg).catch(reportUndelivered);
+    enqueueDispatch(msg, "loop").catch(reportUndelivered);
   }
   function reportUndelivered(error) {
     report(
@@ -463,10 +556,11 @@ function startLoop(config) {
       error instanceof DispatchDiscardedError ? "discard" : "follow-up"
     );
   }
-  function trackInFlight(work) {
-    inFlightCmds++;
+  function trackInFlight(work, cmdType) {
+    const entry = { cmdType };
+    inFlight.add(entry);
     return Promise.resolve(work).finally(() => {
-      inFlightCmds--;
+      inFlight.delete(entry);
     });
   }
   function detachInFlight(work) {
@@ -478,22 +572,34 @@ function startLoop(config) {
     });
   }
   function callHandler(cmd, dispatch) {
-    const handler = config.handlerFor(cmd.type);
+    const { type } = cmd;
+    const handler = config.handlerFor(type);
     if (handler === void 0) return Promise.resolve(void 0);
-    return trackInFlight(handler(cmd, handlerCtx, dispatch));
+    return trackInFlight(handler(cmd, handlerCtx, dispatch), type);
   }
   async function runCmds(cmds) {
     for (const cmd of cmds) {
+      if (gate === "abandoned") return;
       const returned = await interpret(cmd, dispatchUnawaited);
-      for (const follow of followUps(returned)) {
-        enqueueDispatch(follow).catch(reportUndelivered);
-      }
+      for (const follow of followUps(returned)) dispatchUnawaited(follow);
     }
   }
   async function commit(next, msg, cmds) {
     state = next;
-    if (store) await store.save(next);
+    saveStatus = { type: "pending" };
+    if (store && gate !== "abandoned") {
+      try {
+        await store.save(next);
+        saveStatus = { type: "saved" };
+      } catch (error) {
+        saveStatus = { type: "failed", error };
+        for (const ext of extensions) ext.saveFailed?.(next, error);
+        throw error;
+      }
+    }
     reconcileSubs();
+    installed = next;
+    for (const callback of installedCallbacks) callback();
     try {
       await runCmds(cmds);
     } finally {
@@ -514,20 +620,39 @@ function startLoop(config) {
     const [initial, cmds] = storeless ?? config.init(await restore(store), config.ctx);
     await commit(initial, void 0, cmds);
   }
-  function enqueueDispatch(msg) {
+  function enqueueDispatch(msg, origin = "caller") {
     if (gate !== "open") {
       return Promise.reject(
-        gate === "draining" ? new DispatchDiscardedError(msg.type) : new RuntimeStoppedError(msg.type)
+        gate === "draining" || gate === "abandoned" && origin === "loop" ? new DispatchDiscardedError(msg.type) : new RuntimeStoppedError(msg.type)
       );
     }
+    return enqueueStep(msg, origin, stepDispatch);
+  }
+  function enqueueStep(msg, origin, step) {
+    line.joined(msg.type);
     const next = tail.then(() => {
+      line.reachedTurn(msg.type);
+      if (gate === "abandoned") {
+        if (origin === "caller") throw new DispatchDiscardedError(msg.type);
+        return;
+      }
       if (bootError !== null) throw bootError;
-      return stepDispatch(msg);
+      return step(msg);
     });
     tail = next.catch(() => {
     });
     return next;
   }
+  function postMsg(msg, takes) {
+    if (gate !== "open") return "stopped";
+    if (!takes(state)) return "no_cell";
+    enqueueStep(
+      msg,
+      "tell",
+      (queued) => takes(state) ? stepDispatch(queued) : void 0
+    ).catch(reportUndelivered);
+    return "queued";
+  }
   async function drainToQuiescence() {
     for (let i = 0; i < idleCap; i++) {
       const observed = tail;
@@ -545,10 +670,30 @@ function startLoop(config) {
   tail = bootPromise.catch((err) => {
     bootError = err;
   });
+  async function teardown() {
+    if (gate === "open") gate = "draining";
+    if (inFlight.size > 0) {
+      report(new RuntimeDiscardedError(inFlight.size), "discard");
+    }
+    await drainTail();
+    lastStateReached();
+    stopSubs([...subRegistry.keys()]);
+    await drainDisposals();
+    if (store && state !== void 0 && bootError === null) {
+      try {
+        await store.save(state);
+      } catch (error) {
+        report(error, "stop-save");
+      }
+    }
+  }
+  let stopped;
   const core = {
-    [liveWork]: () => ({ subs: subRegistry.size, cmds: inFlightCmds }),
+    [liveWork]: () => ({ subs: subRegistry.size, cmds: inFlight.size }),
+    [post]: postMsg,
+    [installedState]: () => installed,
     dispatch: dispatchToQuiescence,
-    dispatchOnce: enqueueDispatch,
+    dispatchOnce: (msg) => enqueueDispatch(msg),
     getState() {
       return state;
     },
@@ -556,22 +701,9 @@ function startLoop(config) {
     // at `.then` time, after `handle` below is built.
     ready: bootPromise.then(() => handle),
     idle: drainToQuiescence,
-    async stop() {
-      if (gate === "open") gate = "draining";
-      if (inFlightCmds > 0) {
-        report(new RuntimeDiscardedError(inFlightCmds), "discard");
-      }
-      await tail;
-      gate = "closed";
-      stopSubs([...subRegistry.keys()]);
-      await drainDisposals();
-      if (store && state !== void 0 && bootError === null) {
-        try {
-          await store.save(state);
-        } catch (error) {
-          report(error, "stop-save");
-        }
-      }
+    stop() {
+      stopped ??= teardown();
+      return stopped;
     }
   };
   const handle = Object.assign(
@@ -581,6 +713,20 @@ function startLoop(config) {
   return handle;
 }
 
-export { RuntimeStoppedError, builtinExtensions, defaultOnError, liveWork, startLoop };
-//# sourceMappingURL=chunk-UHAQ4PI6.js.map
-//# sourceMappingURL=chunk-UHAQ4PI6.js.map
+// src/internal/engine/tell.ts
+function tellRun(machine, runtime, msg) {
+  const postable = runtime[post];
+  if (postable === void 0) {
+    throw new Error(
+      "@demlik/tea: `tell` needs a run handle from `run`; this object has no line to post to."
+    );
+  }
+  return postable(
+    msg,
+    (state) => acceptedTypes(machine, state).includes(msg.type)
+  );
+}
+
+export { RuntimeStoppedError, builtinExtensions, defaultOnError, liveWork, post, refuseFencedRunWithoutSink, startLoop, tellRun };
+//# sourceMappingURL=chunk-2A5XTKQQ.js.map
+//# sourceMappingURL=chunk-2A5XTKQQ.js.map