@demlik/tea 0.2.0 → 0.4.0

package/dist/{chunk-6VDCTR7N.js → chunk-D4NJBQAH.js}

@@ -1,6 +1,34 @@
-import { detectUpdateForm, foldUpdates, __DEV__, deepFreeze, applyCell, assertPureResult } from './chunk-DYRKDCJI.js';
+import { detectUpdateForm, foldUpdates, structuralHash, applyCellChecked } from './chunk-PBDYW2TU.js';
 import { Result } from 'better-result';
 
+// src/observability.ts
+function historyTracker(runtime, size) {
+  const buffer = [];
+  let stopped = false;
+  const push = (entry) => {
+    buffer.push(entry);
+    if (buffer.length > size) buffer.shift();
+  };
+  const unobserve = size <= 0 ? () => {
+  } : runtime.observe((msg, state) => {
+    push({ msg, state });
+  });
+  const unboot = size <= 0 ? () => {
+  } : runtime.onBoot((state) => {
+    push({ msg: null, state });
+  });
+  return {
+    snapshot() {
+      return buffer.slice();
+    },
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      unobserve();
+      unboot();
+    }
+  };
+}
 function absurd(x) {
   throw new Error(`unreachable: ${JSON.stringify(x)}`);
 }
@@ -8,25 +36,25 @@ var noop = (state, _msg) => [state, []];
 var definedPortNames = /* @__PURE__ */ new Set();
 var PortNameCollisionError = class extends Error {
   name = "PortNameCollisionError";
+  _tag = "PortNameCollisionError";
   constructor(portName) {
     super(
       `definePort: a port named "${portName}" was already defined. Each definePort call must use a unique name. If two modules need the same port, export it from one module and import it.`
     );
   }
 };
+var SubIdCollisionError = class extends Error {
+  name = "SubIdCollisionError";
+  _tag = "SubIdCollisionError";
+  constructor(id, declaredType, conflictingType) {
+    super(
+      `@demlik/tea: Sub.id collision: id="${id}" declared as type="${declaredType}" and type="${conflictingType}"`
+    );
+  }
+};
 function __resetPortRegistry() {
   definedPortNames.clear();
 }
-function defaultOnError(error, _context) {
-  setTimeout(() => {
-    throw error;
-  }, 0);
-}
-function normalizeSupervision(supervision) {
-  if (supervision === void 0) return { strategy: "stop" };
-  if (typeof supervision === "string") return { strategy: supervision };
-  return supervision;
-}
 var QuiescenceTimeoutError = class extends Error {
   constructor(iterations) {
     super(
@@ -35,6 +63,29 @@ var QuiescenceTimeoutError = class extends Error {
     this.iterations = iterations;
   }
   name = "QuiescenceTimeoutError";
+  _tag = "QuiescenceTimeoutError";
+};
+var RuntimeDiscardNotice = class extends Error {
+};
+var RuntimeDiscardedError = class extends RuntimeDiscardNotice {
+  constructor(pendingCmds) {
+    super(
+      `@demlik/tea: runtime stopped with ${pendingCmds} Cmd(s) in flight \u2014 their results will reach no listener. In React this is usually a ctx-identity change rebuilding useMachine's runtime mid-flight: stabilize the ctx (useMemo / useState) so the runtime outlives the Cmds it started. An intentional teardown (unmount, navigation) can silence this with a run({ onError }) sink that ignores phase: "discard".`
+    );
+    this.pendingCmds = pendingCmds;
+  }
+  name = "RuntimeDiscardedError";
+  _tag = "RuntimeDiscardedError";
+};
+var DispatchDiscardedError = class extends RuntimeDiscardNotice {
+  constructor(msgType) {
+    super(
+      `@demlik/tea: Msg "${msgType}" arrived while the runtime was stopping and was discarded \u2014 stop() refuses new work so the drain terminates. It is the result of a Cmd that outlived its runtime; keep the runtime alive until the Cmd settles (in React: stabilize useMachine's ctx) if the transition matters.`
+    );
+    this.msgType = msgType;
+  }
+  name = "DispatchDiscardedError";
+  _tag = "DispatchDiscardedError";
 };
 function definePort(name) {
   let isHmr = false;
@@ -50,6 +101,18 @@ function definePort(name) {
   definedPortNames.add(name);
   return { __brand: "port", name };
 }
+function schemaMigrate(schema, upcast = (raw) => raw) {
+  return (raw) => {
+    let migrated;
+    try {
+      migrated = upcast(raw);
+    } catch {
+      return null;
+    }
+    const parsed = schema.safeParse(migrated);
+    return parsed.success ? parsed.data : null;
+  };
+}
 function defineMachine(m) {
   if (m.__form === void 0) {
     Object.defineProperty(m, "__form", {
@@ -64,6 +127,68 @@ function defineMachine(m) {
 function asReducer(reducer) {
   return reducer;
 }
+function replay(machine, opts) {
+  const loaded = opts.loaded ?? null;
+  const [initialState, initCmds] = machine.init(loaded, opts.ctx);
+  if (loaded !== null && initCmds.length > 0) {
+    throw new Error(
+      "TEA contract violation: machine.init must return [state, []] (no Cmds) when `loaded` is non-null. Init's rehydrate branch is a pure state passthrough \u2014 the migration/parse boundary, not the boot-effect hook.\n\nRoutes for boot effects:\n  - Stateless infrastructure (e.g. chrome.alarms ensure) \u2192 host module top level, outside TEA.\n  - State-conditional resume (e.g. re-attach a session) \u2192 a `boot` Msg dispatched once from the host after `run(...)` returns, handled in update.\n\nSee .patterns/tea/tea-invariants.md (Invariant 2)."
+    );
+  }
+  const { state, cmds: foldedCmds } = foldUpdates(
+    machine,
+    initialState,
+    opts.msgs
+  );
+  const cmds = [...initCmds, ...foldedCmds];
+  const subs = machine.subscriptions ? [...machine.subscriptions(state)] : [];
+  const depSubs = [];
+  if (machine.subs) {
+    for (const [index, entry] of machine.subs.entries()) {
+      const deps = entry.deps(state);
+      if (deps !== null) depSubs.push({ index, id: structuralHash(deps) });
+    }
+  }
+  return { state, cmds, subs, depSubs };
+}
+function wrapDetached(handler) {
+  return (cmd, ctx, dispatch) => {
+    if (dispatch === void 0) {
+      throw new Error(
+        "@demlik/tea: a wrapDetached handler was invoked without the injected dispatch. The kernel always supplies it; call the handler through the runtime, not directly."
+      );
+    }
+    return handler(cmd, ctx, dispatch);
+  };
+}
+function tryInterpret(work, onOk, onErr) {
+  return async (cmd, ctx) => {
+    const result = await Result.tryPromise({
+      try: () => work(cmd, ctx),
+      catch: (error) => error
+    });
+    return result.match({
+      ok: (value) => onOk(value, cmd),
+      err: (error) => onErr(error, cmd)
+    });
+  };
+}
+
+// src/run.ts
+function defaultOnError(error, _context) {
+  if (error instanceof RuntimeDiscardNotice) {
+    console.warn(error);
+    return;
+  }
+  setTimeout(() => {
+    throw error;
+  }, 0);
+}
+function normalizeSupervision(supervision) {
+  if (supervision === void 0) return { strategy: "stop" };
+  if (typeof supervision === "string") return { strategy: supervision };
+  return supervision;
+}
 function run(machine, opts) {
   const { store } = opts;
   const ctx = opts.ctx ?? {};
@@ -78,11 +203,22 @@ function run(machine, opts) {
       defaultOnError(sinkError);
     }
   };
+  function fanout(items, phase, fn) {
+    for (const item of items) {
+      try {
+        fn(item);
+      } catch (err) {
+        reportError(err, { phase });
+      }
+    }
+  }
   const supervision = normalizeSupervision(opts.supervision);
   let state;
   let bootError = null;
-  let stopped = false;
+  let gate = "open";
+  let inFlightCmds = 0;
   const subRegistry = /* @__PURE__ */ new Map();
+  const depSubRegistry = /* @__PURE__ */ new Map();
   const listeners = /* @__PURE__ */ new Set();
   const observers = /* @__PURE__ */ new Set();
   const bootHandlers = /* @__PURE__ */ new Set();
@@ -93,48 +229,78 @@ function run(machine, opts) {
   function portEmit(port, value) {
     const subscribers = portRegistry.get(port);
     if (!subscribers || subscribers.size === 0) return;
-    for (const listener of subscribers) {
+    fanout(subscribers, "port-emit", (listener) => listener(value));
+  }
+  const augmentedCtx = { ...ctx, emit: portEmit };
+  let tail = Promise.resolve();
+  function stopSubs(ids) {
+    for (const id of ids) {
+      const cleanup = subRegistry.get(id);
+      if (cleanup === void 0) continue;
       try {
-        listener(value);
+        cleanup();
       } catch (err) {
-        reportError(err, { phase: "port-emit" });
+        reportError(err, { phase: "sub-cleanup" });
       }
+      subRegistry.delete(id);
     }
   }
-  const augmentedCtx = { ...ctx, emit: portEmit };
-  function applyUpdate(state2, msg) {
-    if (__DEV__) deepFreeze(state2);
-    const result = applyCell(machine, state2, msg);
-    if (__DEV__) assertPureResult(result, msg.type);
-    return result;
+  function disposeDepSubs(indices) {
+    for (const index of indices) {
+      const running = depSubRegistry.get(index);
+      if (running === void 0) continue;
+      try {
+        running.dispose();
+      } catch (err) {
+        reportError(err, { phase: "sub-cleanup" });
+      }
+      depSubRegistry.delete(index);
+    }
+  }
+  function reconcileDepSubs() {
+    let firstError = null;
+    const subs = machine.subs;
+    if (!subs) return firstError;
+    for (const [i, entry] of subs.entries()) {
+      const deps = entry.deps(state);
+      if (deps === null) {
+        disposeDepSubs([i]);
+        continue;
+      }
+      const id = structuralHash(deps);
+      const running = depSubRegistry.get(i);
+      if (running !== void 0 && running.runningId === id) {
+        continue;
+      }
+      disposeDepSubs([i]);
+      try {
+        const dispose = entry.source(state, enqueueDispatch, ctx);
+        depSubRegistry.set(i, { runningId: id, dispose });
+      } catch (err) {
+        if (firstError === null) firstError = err;
+      }
+    }
+    return firstError;
   }
-  let tail = Promise.resolve();
   function reconcileSubs() {
-    if (!machine.subscriptions) return;
+    const depError = reconcileDepSubs();
+    if (!machine.subscriptions) {
+      if (depError !== null) throw depError;
+      return;
+    }
     const desired = machine.subscriptions(state);
     const desiredIds = /* @__PURE__ */ new Set();
     const desiredTypeById = /* @__PURE__ */ new Map();
     for (const sub of desired) {
       const existing = desiredTypeById.get(sub.id);
       if (existing !== void 0 && existing !== sub.type) {
-        throw new Error(
-          `@demlik/tea: Sub.id collision: id="${sub.id}" declared as type="${existing}" and type="${sub.type}"`
-        );
+        throw new SubIdCollisionError(sub.id, existing, sub.type);
       }
       desiredTypeById.set(sub.id, sub.type);
     }
     for (const sub of desired) desiredIds.add(sub.id);
-    for (const [id, cleanup] of subRegistry) {
-      if (!desiredIds.has(id)) {
-        try {
-          cleanup();
-        } catch (err) {
-          reportError(err, { phase: "sub-cleanup" });
-        }
-        subRegistry.delete(id);
-      }
-    }
-    let firstStartError = null;
+    stopSubs([...subRegistry.keys()].filter((id) => !desiredIds.has(id)));
+    let firstStartError = depError;
     for (const sub of desired) {
       if (subRegistry.has(sub.id)) continue;
       const handler = machine.subscribe?.[sub.type];
@@ -155,40 +321,43 @@ function run(machine, opts) {
     if (firstStartError !== null) throw firstStartError;
   }
   const interpretMap = machine.interpret ?? {};
+  const interpretDispatch = (msg) => {
+    enqueueDispatch(msg).catch(reportUndelivered);
+  };
+  function reportUndelivered(error) {
+    reportError(error, {
+      phase: error instanceof DispatchDiscardedError ? "discard" : "follow-up"
+    });
+  }
+  function trackInFlight(work) {
+    inFlightCmds++;
+    return Promise.resolve(work).finally(() => {
+      inFlightCmds--;
+    });
+  }
   async function runInterpret(cmds) {
     for (const cmd of cmds) {
       const handler = interpretMap[cmd.type];
       if (!handler) continue;
-      const follow = await handler(
-        cmd,
-        augmentedCtx
+      const follow = await trackInFlight(
+        handler(
+          cmd,
+          augmentedCtx,
+          interpretDispatch
+        )
       );
       if (follow !== void 0 && follow !== null) {
-        enqueueDispatch(follow).catch((error) => {
-          reportError(error, { phase: "follow-up" });
-        });
+        enqueueDispatch(follow).catch(reportUndelivered);
       }
     }
   }
   function fireListeners() {
-    for (const listener of listeners) {
-      try {
-        listener();
-      } catch (err) {
-        reportError(err, { phase: "listener" });
-      }
-    }
+    fanout(listeners, "listener", (listener) => listener());
   }
   function fireObservers(msg) {
     if (observers.size === 0 || state === void 0) return;
     const snapshot = state;
-    for (const observer of observers) {
-      try {
-        observer(msg, snapshot);
-      } catch (err) {
-        reportError(err, { phase: "observer" });
-      }
-    }
+    fanout(observers, "observer", (observer) => observer(msg, snapshot));
   }
   function fireEvents(msg) {
     if (eventHandlers.size === 0 || state === void 0) return;
@@ -202,26 +371,14 @@ function run(machine, opts) {
     for (const event of events) {
       const bucket = eventHandlers.get(event.type);
       if (bucket === void 0) continue;
-      for (const handler of bucket) {
-        try {
-          handler(event);
-        } catch (err) {
-          reportError(err, { phase: "event" });
-        }
-      }
+      fanout(bucket, "event", (handler) => handler(event));
     }
   }
   function fireBoot() {
     booted = true;
     if (bootHandlers.size === 0 || state === void 0) return;
     const snapshot = state;
-    for (const handler of bootHandlers) {
-      try {
-        handler(snapshot);
-      } catch (err) {
-        reportError(err, { phase: "boot" });
-      }
-    }
+    fanout(bootHandlers, "boot", (handler) => handler(snapshot));
   }
   function settleDoneWaiters() {
     if (doneWaiters.size === 0 || state === void 0) return;
@@ -245,10 +402,19 @@ function run(machine, opts) {
     if (state === void 0) {
       throw new Error("@demlik/tea: runtime not booted");
     }
+    if (machine.identity !== void 0) {
+      const addressed = machine.identity.ofMsg(msg);
+      if (addressed !== void 0) {
+        const own = machine.identity.ofState(state);
+        if (own !== void 0 && structuralHash(addressed) !== structuralHash(own)) {
+          return;
+        }
+      }
+    }
     let next;
     let cmds;
     try {
-      [next, cmds] = applyUpdate(state, msg);
+      [next, cmds] = applyCellChecked(machine, state, msg);
     } catch (reduceError) {
       reportError(reduceError, { phase: "reduce" });
       switch (supervision.strategy) {
@@ -259,7 +425,7 @@ function run(machine, opts) {
         case "escalate":
           throw reduceError;
         default:
-          stopped = true;
+          gate = "closed";
           throw reduceError;
       }
     }
@@ -287,8 +453,11 @@ function run(machine, opts) {
     settleDoneWaiters();
   }
   function enqueueDispatch(msg) {
-    if (stopped)
-      return Promise.reject(new Error("@demlik/tea: runtime stopped"));
+    if (gate !== "open") {
+      return Promise.reject(
+        gate === "draining" ? new DispatchDiscardedError(msg.type) : new Error("@demlik/tea: runtime stopped")
+      );
+    }
     const next = tail.then(() => {
       if (bootError !== null) throw bootError;
       return stepDispatch(msg);
@@ -337,11 +506,8 @@ function run(machine, opts) {
     },
     onBoot(handler) {
       if (booted && state !== void 0) {
-        try {
-          handler(state);
-        } catch (err) {
-          reportError(err, { phase: "boot" });
-        }
+        const snapshot = state;
+        fanout([handler], "boot", (h) => h(snapshot));
         return () => {
         };
       }
@@ -384,9 +550,6 @@ function run(machine, opts) {
     emitPort(port, value) {
       portEmit(port, value);
     },
-    // `ready` is assigned just below (it must resolve to `runtime` itself,
-    // which can't be referenced inside its own object literal). See the
-    // assignment + rationale after this block.
     ready: readyPromise,
     idle() {
       return drainToQuiescence();
@@ -403,16 +566,16 @@ function run(machine, opts) {
       });
     },
     async stop() {
-      stopped = true;
-      await tail;
-      for (const [id, cleanup] of subRegistry) {
-        try {
-          cleanup();
-        } catch (err) {
-          reportError(err, { phase: "sub-cleanup" });
-        }
-        subRegistry.delete(id);
+      if (gate === "open") gate = "draining";
+      if (inFlightCmds > 0) {
+        reportError(new RuntimeDiscardedError(inFlightCmds), {
+          phase: "discard"
+        });
       }
+      await tail;
+      gate = "closed";
+      stopSubs([...subRegistry.keys()]);
+      disposeDepSubs([...depSubRegistry.keys()]);
       if (store && state !== void 0 && bootError === null) {
         try {
           await store.save(state);
@@ -424,63 +587,7 @@ function run(machine, opts) {
   };
   return runtime;
 }
-function historyTracker(runtime, size) {
-  const buffer = [];
-  let stopped = false;
-  const push = (entry) => {
-    buffer.push(entry);
-    if (buffer.length > size) buffer.shift();
-  };
-  const unobserve = size <= 0 ? () => {
-  } : runtime.observe((msg, state) => {
-    push({ msg, state });
-  });
-  const unboot = size <= 0 ? () => {
-  } : runtime.onBoot((state) => {
-    push({ msg: null, state });
-  });
-  return {
-    snapshot() {
-      return buffer.slice();
-    },
-    stop() {
-      if (stopped) return;
-      stopped = true;
-      unobserve();
-      unboot();
-    }
-  };
-}
-function replay(machine, opts) {
-  const loaded = opts.loaded ?? null;
-  const [initialState, initCmds] = machine.init(loaded, opts.ctx);
-  if (loaded !== null && initCmds.length > 0) {
-    throw new Error(
-      "TEA contract violation: machine.init must return [state, []] (no Cmds) when `loaded` is non-null. Init's rehydrate branch is a pure state passthrough \u2014 the migration/parse boundary, not the boot-effect hook.\n\nRoutes for boot effects:\n  - Stateless infrastructure (e.g. chrome.alarms ensure) \u2192 host module top level, outside TEA.\n  - State-conditional resume (e.g. re-attach a session) \u2192 a `boot` Msg dispatched once from the host after `run(...)` returns, handled in update.\n\nSee .patterns/tea/tea-invariants.md (Invariant 2)."
-    );
-  }
-  const { state, cmds: foldedCmds } = foldUpdates(
-    machine,
-    initialState,
-    opts.msgs
-  );
-  const cmds = [...initCmds, ...foldedCmds];
-  const subs = machine.subscriptions ? [...machine.subscriptions(state)] : [];
-  return { state, cmds, subs };
-}
-function tryInterpret(work, onOk, onErr) {
-  return async (cmd, ctx) => {
-    const result = await Result.tryPromise({
-      try: () => work(cmd, ctx),
-      catch: (error) => error
-    });
-    return result.match({
-      ok: (value) => onOk(value, cmd),
-      err: (error) => onErr(error, cmd)
-    });
-  };
-}
 
-export { PortNameCollisionError, QuiescenceTimeoutError, __resetPortRegistry, absurd, asReducer, defineMachine, definePort, historyTracker, noop, replay, run, tryInterpret };
-//# sourceMappingURL=chunk-6VDCTR7N.js.map
-//# sourceMappingURL=chunk-6VDCTR7N.js.map
+export { DispatchDiscardedError, PortNameCollisionError, QuiescenceTimeoutError, RuntimeDiscardNotice, RuntimeDiscardedError, SubIdCollisionError, __resetPortRegistry, absurd, asReducer, defineMachine, definePort, historyTracker, noop, replay, run, schemaMigrate, tryInterpret, wrapDetached };
+//# sourceMappingURL=chunk-D4NJBQAH.js.map
+//# sourceMappingURL=chunk-D4NJBQAH.js.map