@demlik/tea 0.1.0 → 0.1.2

package/dist/llm-call/index.d.ts

@@ -0,0 +1,309 @@
+import { C as Cmd } from '../core-BoB6t7dB.js';
+import { SucceedMsg, FailMsg, RunCmd, ResilientState } from '../resilient-call/index.js';
+import { RetryPolicy } from '../retry-backoff/index.js';
+import { DeadlineExceeded, DeadlineSub } from '../deadline/index.js';
+export { deadlineSub, subscribeDeadline } from '../deadline/index.js';
+import '../cache/index.js';
+import '../types-B-8bcAp8.js';
+import '../circuit-breaker/index.js';
+import '../protocol-B5YmJr0d.js';
+import '../rate-limit/index.js';
+
+/**
+ * @demlik/tea/llm-call — `resilient-call` + structured-output parse + a typed
+ * failure variant, around a purpose-discriminated LLM invocation.
+ *
+ * This is the ~60-line `call_llm` handler from the audit-agent seed
+ * (`interpret.ts` / `effects.ts`) collapsed into the uniform L2 knob: a config
+ * object, the resilient-call slice it inherits, and one interpret handler that
+ * assembles messages, binds the structured-output schema for the call's
+ * `purpose`, invokes the model (retry composed from `../resilient-call`, NOT
+ * reinvented), parses the output, and RETURNS the enriched resilient settle Msg
+ * (`resilient_ok` / `resilient_err`) so it re-enters the host reducer and drives
+ * the inherited succeed/fail → backoff → onTimer loop.
+ *
+ * ## What it adds over `../resilient-call`
+ *
+ *   - **Two DI ports** (the seed's two seams):
+ *       1. `model: (modelId) => LLM` — the model factory. Tests pass a fake so
+ *          the handler runs end-to-end without touching a real provider; the
+ *          production worker wires `createChatModel(env, …)`.
+ *       2. `loadMessages: Loader` — the SDK / message loader. The seed lazy-
+ *          imports `@langchain/core/messages` (a top-level `import type` blows
+ *          up the workers test runner); the loader keeps that import lazy and
+ *          stubbable. It produces the `BaseMessage[]` for a given call.
+ *   - **Structured-output parse** — each `purpose` maps to a `Schema` in
+ *     `config.schemas`. The handler binds `model.withStructuredOutput(schema)`
+ *     so the invoke resolves to a typed object; a `Schema.parse` that throws
+ *     becomes a `resilient_err` carrying an `LlmErr` (a parse failure is a
+ *     failure, not a stall — "errors are data"). `withStructuredOutput` is the
+ *     seed's brain-only path; the fake model in tests returns the typed object
+ *     directly.
+ *   - **A typed failure variant** — every failure (model throw, timeout-via-
+ *     retry-exhaustion, schema parse) is surfaced as the `LlmErr` carried on the
+ *     enriched `resilient_err` settle Msg, tagged with the `purpose` so the
+ *     consumer's reducer routes per-stage. The seed dispatched
+ *     `llm_failed{purpose}`; the consumer rebuilds that shape in its reducer arm
+ *     from `m.error: LlmErr`.
+ *
+ * ## Inheriting resilient-call by composition (not reinvention)
+ *
+ * The retry / backoff lives in `../resilient-call`: `createLlmCall` builds a
+ * `createResilientCall` knob over the model-invoke port and DELEGATES `init`,
+ * `attempt`, `succeed`, `fail`, `onTimer`, `subs` to it verbatim — the slice is
+ * literally resilient-call's slice (the spec's "retry lives here"). There is no
+ * second backoff implementation here. The handler runs the invoke through the
+ * resilient-call handler so a transient model failure backs off exactly as a
+ * resilient HTTP call would; the `purpose`-branch + structured parse wrap the
+ * port the resilient handler drives.
+ *
+ * ## The two non-negotiables (canon, inherited)
+ *
+ *   - **Durable** — the slice is resilient-call's plain-data slice (a Model
+ *     field). Input carried on the `resilient_run` Cmd is the plain
+ *     `LlmCall` request (purpose + modelId + payload) — no closures.
+ *   - **Replayable** — every transition is a resilient-call verb; the handler
+ *     is the only impurity, and the one clock read is `Date.now()` at the
+ *     effect boundary (inside the handler), exactly as the seed stamped its
+ *     `llm_responded` / `llm_failed` Msgs.
+ *
+ * ## Typical wiring
+ *
+ *   const llm = createLlmCall<MyPurpose, MyOutputs>({
+ *     model: (id) => createChatModel(env, id),
+ *     schemas: { plan: planSchema, report: reportSchema },
+ *     retry: defaultRetryPolicy,
+ *     loadMessages: defaultMessagesLoader,
+ *   });
+ *
+ *   // in the machine:
+ *   init: () => [{ resilience: llm.init() }, []],
+ *   update: {
+ *     call_llm:  (s, m) => lift(s, llm.attempt(s.resilience, m.input, m.at)),
+ *     // `resilient_ok` / `resilient_err` RE-ENTER from `handlers` (the settle
+ *     // Msg the interpret handler returns). Run the inherited verb FIRST so the
+ *     // succeed/fail → backoff → onTimer loop advances, THEN fold the enriched
+ *     // payload (`m.result: LlmOk` / `m.error: LlmErr`) into the host's own
+ *     // state — the enrichment lives in the reducer arm, not the handler.
+ *     resilient_ok:  (s, m) => {
+ *       const [slice, cmds] = llm.succeed(s.resilience, m.key, m);
+ *       return [{ ...s, resilience: slice, output: m.result.output }, cmds];
+ *     },
+ *     resilient_err: (s, m) => {
+ *       const [slice, cmds] = llm.fail(s.resilience, m.key, m);
+ *       return [{ ...s, resilience: slice, failure: m.error }, cmds];
+ *     },
+ *     deadline_exceeded: (s, m) => lift(s, llm.onTimer(s.resilience, m)),
+ *   },
+ *   subscriptions: (s) => llm.subs(s.resilience),
+ *   subscribe: { deadline: subscribeDeadline },
+ *   interpret: llm.handlers(),
+ */
+
+/**
+ * The minimal structured-output schema contract: `parse(unknown) => T`, the
+ * zod-style call the handler uses to validate the model's output before it
+ * settles `resilient_ok`. A throwing `parse` (the zod contract on invalid
+ * input) propagates out of `invokeOne` and is caught by the resilient handler,
+ * which settles `resilient_err` (enriched to `LlmErr`) — a parse failure is a
+ * failure, never a silent pass. Structural so a real `z.ZodType<T>` satisfies
+ * it without an import.
+ */
+interface Schema<T> {
+    /** Validate + narrow `value` to `T`, or throw on mismatch (the zod contract). */
+    parse(value: unknown): T;
+}
+/**
+ * The minimal chat-model contract every model the handler talks to must
+ * satisfy — the seed's `InjectableChatModel`, trimmed to the one operation
+ * llm-call drives for brain-only stages:
+ *
+ *   `withStructuredOutput(schema)` → a runnable whose `invoke(messages)`
+ *   resolves to a typed object matching `schema`.
+ *
+ * `BaseChatModel` from `@langchain/core` is the runtime type; this surface
+ * names only what llm-call calls so a test fake can ignore the rest. Generic
+ * over the message shape `Msg` so a consumer's loader and model agree on it
+ * without llm-call inspecting messages.
+ */
+interface Llm<Msg> {
+    withStructuredOutput<T>(schema: Schema<T>): {
+        invoke(messages: readonly Msg[]): Promise<T>;
+    };
+}
+/**
+ * Build the `Msg[]` the handler hands to the bound model for a given call. The
+ * SDK / message-assembly seam — the seed's `buildBaseMessages` + the lazy
+ * `loadMessages` loader rolled into one injected port. Async because the seed
+ * lazy-imports the SDK (a top-level `import type` of the langchain messages
+ * package explodes the workers test runner). Receives the full `LlmCall` so it
+ * can branch on `purpose` exactly as the seed's `buildBaseMessages` did.
+ */
+type MessageLoader<P extends string, Msg> = (call: LlmCall<P>) => Promise<readonly Msg[]>;
+/**
+ * The model factory — the first DI port. `(modelId) => Llm`. Tests pass a fake
+ * builder; production wires `createChatModel(env, getModelConfig(id))`. `null`
+ * means "the host's default model" (the seed's `string | null`).
+ */
+type ModelFactory<Msg> = (modelId: string | null) => Llm<Msg>;
+/**
+ * The llm-call knob. `model` and `schemas` are the load-bearing pair — the
+ * model factory DI port and the per-purpose structured-output targets; the
+ * rest is optional, exactly the resilient-call "omit a brick → omit its gate"
+ * story for `retry`:
+ *
+ *   - `model`        — DI port 1: the model factory.
+ *   - `schemas`      — one `Schema` per `Purpose`. The handler binds
+ *                      `schemas[call.purpose]` as the structured-output target.
+ *   - `retry`        — backoff policy, composed straight into `../resilient-
+ *                      call`. Omit it and a model failure is terminal (no
+ *                      backoff), exactly as resilient-call with no retry brick.
+ *   - `loadMessages` — DI port 2: the SDK / message loader. Omit it and the
+ *                      handler invokes the bound model with `[]` (a degenerate
+ *                      but valid call) — provide it to assemble real messages.
+ *
+ * `P` is the purpose union (e.g. `"plan" | "report"`); `O` maps each purpose to
+ * its parsed output type; `Msg` is the model's message shape (threaded through
+ * the loader + model so llm-call never inspects a message).
+ */
+interface LlmCallConfig<P extends string, O extends Record<P, unknown>, Msg = unknown> {
+    /** DI port 1 — the model factory. `(modelId) => Llm`. */
+    readonly model: ModelFactory<Msg>;
+    /** One structured-output schema per purpose; the parse target the handler binds. */
+    readonly schemas: {
+        readonly [K in P]: Schema<O[K]>;
+    };
+    /** Backoff policy, composed into `../resilient-call`. Omit → no backoff. */
+    readonly retry?: RetryPolicy;
+    /** DI port 2 — the SDK / message loader. Omit → the handler invokes with `[]`. */
+    readonly loadMessages?: MessageLoader<P, Msg>;
+}
+/**
+ * One LLM call request — the resilient-call `input` for this knob, carried on
+ * the `resilient_run` Cmd as plain data (no closures, invariant 3). Mirrors the
+ * seed's purpose-discriminated `CallLlmCmd`: a `purpose` selecting the schema +
+ * prompt assembly, the `model` id, and the opaque per-purpose `payload` the
+ * loader consumes.
+ *
+ * `key` defaults to `purpose` when the consumer calls `attempt(s, purpose, …)`,
+ * so one in-flight call per purpose is tracked under the resilient-call slice —
+ * the common single-call-per-stage shape. A consumer that fans out many calls
+ * of one purpose passes a distinct `key`.
+ */
+interface LlmCall<P extends string> {
+    /** The stage / schema selector — drives both `schemas[purpose]` and message assembly. */
+    readonly purpose: P;
+    /** The model id to invoke; `null` = the host's default model. */
+    readonly model: string | null;
+    /** The per-purpose prompt payload the `MessageLoader` consumes. Opaque to the knob. */
+    readonly payload: unknown;
+}
+/** The parsed, typed success carried on the `resilient_ok` settle Msg, tagged with its purpose. */
+interface LlmOk<P extends string, O extends Record<P, unknown>> {
+    readonly key: string;
+    readonly purpose: P;
+    readonly output: O[P];
+}
+/** The typed failure variant — every failure path surfaces this, tagged by purpose. */
+interface LlmErr<P extends string> {
+    readonly key: string;
+    readonly purpose: P;
+    /** A human-readable cause (model throw, retry-exhaustion, or schema parse). */
+    readonly reason: string;
+    /** The original error, carried untouched for the consumer to inspect. */
+    readonly error: unknown;
+}
+/**
+ * The settle Msgs llm-call's handler RETURNS from `interpret` so the substrate
+ * enqueues them as follow-up Msgs (re-entry) into the host reducer — exactly as
+ * `../resilient-call` does. They are the resilient-call settle Msgs with the
+ * payloads ENRICHED to llm-call's typed variants: `result` is the parsed,
+ * purpose-tagged `LlmOk`; `error` is the typed `LlmErr` (purpose + reason +
+ * raw). The host wires `resilient_ok` → `succeed` and `resilient_err` → `fail`
+ * reducer arms (the doc-comment wiring), and folds the enriched payload into its
+ * own state there — llm-call never forces a Msg vocabulary on the host, and the
+ * settle Msg drives the inherited succeed/fail → backoff → onTimer loop instead
+ * of bypassing it.
+ */
+type LlmSucceedMsg<P extends string, O extends Record<P, unknown>> = SucceedMsg<LlmOk<P, O>>;
+type LlmFailMsg<P extends string> = Omit<FailMsg, "error"> & {
+    readonly error: LlmErr<P>;
+};
+/** The retry / deadline timer Msg — `DeadlineExceeded`, inherited from resilient-call. */
+type LlmTimerMsg = DeadlineExceeded;
+/**
+ * The ports the LEGACY detached `handlers(ports)` form takes. Two outbound Msg
+ * builders the handler hands the typed Ok / Err; the consumer returns its own
+ * Msg (or `undefined`). KEPT only for `../agent`, which still inherits the
+ * detached shape; that path does NOT drive the retry loop (it dispatches the
+ * consumer's Msg directly and never re-enters the resilient settle Msg). New
+ * consumers use the no-arg `handlers()` form, which RETURNS the settle Msg for
+ * re-entry and drives the inherited succeed/fail → backoff → onTimer loop.
+ * `../agent` carries the same retry-loop gap and is fixed separately.
+ *
+ * The builders return `M | undefined` — `undefined` is the "dispatch nothing"
+ * sentinel the detached form checks (`!== undefined`), spelled as `undefined`
+ * rather than `void` so the union is unambiguous (a `void` member of a union is
+ * confusing and reads as "may return anything").
+ */
+interface LlmCallPorts<P extends string, O extends Record<P, unknown>, M> {
+    /** Build the Msg dispatched on a parsed success. Return `undefined` to dispatch nothing. */
+    readonly onOk: (ok: LlmOk<P, O>) => M | undefined;
+    /** Build the Msg dispatched on any failure (throw / retry-exhausted / parse). */
+    readonly onErr: (err: LlmErr<P>) => M | undefined;
+}
+/**
+ * The effect Cmd the knob emits: run the LLM call for `key` with `input`. The
+ * `input` is the plain `LlmCall` request — the handler reads `purpose` /
+ * `model` / `payload` off it (invariant 3: Cmds are data).
+ *
+ * It is `../resilient-call`'s `RunCmd` specialized to the `LlmCall` input — NOT a
+ * re-declared shape — so the resilient verbs' return tuples (`[State, RunCmd[]]`)
+ * are this exact type and thread through `attempt` / `succeed` / `fail` /
+ * `onTimer` with no cast.
+ */
+type LlmRunCmd<P extends string> = RunCmd<LlmCall<P>>;
+/**
+ * Build an llm-call knob from `config`. `rng` is injected for the inherited
+ * retry jitter (pass a fixed `() => 0.5` in tests to pin backoff; defaults to
+ * `Math.random`, read only at the resilient-call verb boundary).
+ *
+ * Returns the uniform L2 knob contract. The slice + verbs (`init`, `attempt`,
+ * `succeed`, `fail`, `onTimer`, `subs`) are DELEGATED to a `../resilient-call`
+ * knob built over the structured-output model-invoke port — no second backoff
+ * here. `handlers` is the one new piece: the purpose-branching, schema-parsing
+ * wrapper that returns the enriched resilient settle Msg for re-entry.
+ *
+ * `P` is the purpose union, `O` the purpose→output map, `Msg` the model's
+ * message shape.
+ */
+declare function createLlmCall<P extends string, O extends Record<P, unknown>, Msg = unknown>(config: LlmCallConfig<P, O, Msg>, rng?: () => number): {
+    init: () => ResilientState<LlmCall<P>, LlmOk<P, O>>;
+    attempt: (s: ResilientState<LlmCall<P>, LlmOk<P, O>>, input: LlmCall<P>, at: number, key?: string) => readonly [ResilientState<LlmCall<P>, LlmOk<P, O>>, readonly LlmRunCmd<P>[]];
+    succeed: (s: ResilientState<LlmCall<P>, LlmOk<P, O>>, key: string, msg: LlmSucceedMsg<P, O>) => readonly [ResilientState<LlmCall<P>, LlmOk<P, O>>, readonly LlmRunCmd<P>[]];
+    fail: (s: ResilientState<LlmCall<P>, LlmOk<P, O>>, key: string, msg: LlmFailMsg<P>) => readonly [ResilientState<LlmCall<P>, LlmOk<P, O>>, readonly LlmRunCmd<P>[]];
+    onTimer: (s: ResilientState<LlmCall<P>, LlmOk<P, O>>, msg: LlmTimerMsg) => readonly [ResilientState<LlmCall<P>, LlmOk<P, O>>, readonly LlmRunCmd<P>[]];
+    subs: (s: ResilientState<LlmCall<P>, LlmOk<P, O>>) => readonly DeadlineSub[];
+    handlers: {
+        (): {
+            resilient_run: (cmd: LlmRunCmd<P>) => Promise<LlmSucceedMsg<P, O> | LlmFailMsg<P>>;
+        };
+        <M>(ports: LlmCallPorts<P, O, M>): {
+            resilient_run: (cmd: LlmRunCmd<P>, ctx: {
+                waitUntil(p: Promise<unknown>): void;
+                dispatch(msg: M): unknown;
+            }) => void;
+        };
+    };
+    invokeOne: (input: LlmCall<P>) => Promise<LlmOk<P, O>>;
+};
+/**
+ * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the
+ * slice lives at `state.resilience` — the same convenience `../resilient-call`
+ * ships, re-typed for the llm-call slice so consumers wire one import. Pure.
+ */
+declare function liftLlmCall<S extends {
+    resilience: ResilientState<LlmCall<P>, LlmOk<P, O>>;
+}, P extends string, O extends Record<P, unknown>, C extends Cmd>(state: S, result: readonly [ResilientState<LlmCall<P>, LlmOk<P, O>>, readonly C[]]): readonly [S, readonly C[]];
+
+export { DeadlineExceeded, DeadlineSub, type Llm, type LlmCall, type LlmCallConfig, type LlmCallPorts, type LlmErr, type LlmFailMsg, type LlmOk, type LlmRunCmd, type LlmSucceedMsg, type LlmTimerMsg, type MessageLoader, type ModelFactory, ResilientState, type Schema, createLlmCall, liftLlmCall };

package/dist/llm-call/index.js

@@ -0,0 +1,14 @@
+export { createLlmCall, liftLlmCall } from '../chunk-PS23H6KQ.js';
+import '../chunk-27N2SPTN.js';
+import '../chunk-JELSZN25.js';
+export { deadlineSub, subscribeDeadline } from '../chunk-K7Q23EQ4.js';
+import '../chunk-5VNWZADP.js';
+import '../chunk-2YOE5PIS.js';
+import '../chunk-SC3FAFZN.js';
+import '../chunk-IN33Q4VJ.js';
+import '../chunk-NSDFA6M6.js';
+import '../chunk-2YFLOCWX.js';
+import '../chunk-MMH7CW5K.js';
+import '../chunk-QLA76GIT.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/llm-call/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/machine-viz/index.d.ts

@@ -1,4 +1,4 @@
-import { Cmd, Sub, Machine } from '../index.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-BoB6t7dB.js';
 
 /**
  * @demlik/tea/machine-viz — turn a `Machine` into a Mermaid diagram string.
@@ -14,9 +14,9 @@ import { Cmd, Sub, Machine } from '../index.js';
  * back to a STRUCTURAL self-edge annotated with `?` — visually distinct from a
  * resolved edge and documented in the diagram's legend.
  *
- * Form detection mirrors `run`/`replay` (the `updateMode` logic): inspect the
- * first own key of `update`; a value that is a function ⇒ Reducer form, a value
- * that is a record ⇒ Transitions form. We do NOT add a runtime tag to Machine.
+ * Form detection is `formOf(machine)` — the same reader `run`/`replay` use,
+ * honoring the authoritative `__form` tag `defineMachine` stamps (falling back
+ * to the structural heuristic for machines built without it; #275).
  *
  * What we MUST NOT do (these are the effectful paths, off-limits here):
  *   - call `interpret[*]` handlers (perform I/O)

package/dist/machine-viz/index.js

@@ -1,3 +1,6 @@
+import '../chunk-MMH7CW5K.js';
+import { formOf } from '../chunk-QLA76GIT.js';
+
 // src/machine-viz/index.ts
 function safeId(raw) {
   const cleaned = raw.replace(/[^A-Za-z0-9_]/g, "_");
@@ -7,19 +10,12 @@ function safeId(raw) {
 function safeLabel(raw) {
   return raw.replace(/["\n\r;:]/g, " ").trim();
 }
-function detectMode(update) {
-  const keys = Object.keys(update);
-  const firstKey = keys[0];
-  if (firstKey === void 0) return "reducer";
-  const firstValue = update[firstKey];
-  return typeof firstValue === "function" ? "reducer" : "transitions";
-}
 function toMermaid(machine, opts = {}) {
   const direction = opts.direction ?? "TB";
   const stateSamples = opts.samples?.states ?? {};
   const msgSamples = opts.samples?.msgs ?? {};
   const hasCtx = opts.samples !== void 0 && "ctx" in opts.samples;
-  const mode = detectMode(machine.update);
+  const mode = formOf(machine);
   const lines = [];
   if (opts.title !== void 0) {
     lines.push("---", `title: ${opts.title}`, "---");
@@ -93,7 +89,7 @@ function emitTransitions(machine, lines, ctx) {
       }
     }
   }
-  lines.push("  note right of " + safeId(stateTypes[0] ?? "_empty"));
+  lines.push(`  note right of ${safeId(stateTypes[0] ?? "_empty")}`);
   lines.push("    Transitions-form machine.");
   lines.push("    Edge a --> b : msg = RESOLVED (cell executed with samples).");
   if (anyStructural) {

package/dist/machine-viz/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/machine-viz/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @demlik/tea/machine-viz — turn a `Machine` into a Mermaid diagram string.\n *\n * PURE. No deps, no AST parsing, no file I/O. The function reads only the\n * `Machine` value it is handed plus optional sample states/msgs/ctx.\n *\n * The trick: TEA update cells are PURE (invariant 2 — they return\n * `[nextState, cmds]` as data, no effects). So we can SAFELY EXECUTE a cell to\n * discover its target state — exactly what `replay` does. That gives us REAL\n * edges (`red --> green : go`) without parsing source. When no sample is\n * provided for a `(state, msg)` pair we cannot resolve the target, so we fall\n * back to a STRUCTURAL self-edge annotated with `?` — visually distinct from a\n * resolved edge and documented in the diagram's legend.\n *\n * Form detection mirrors `run`/`replay` (the `updateMode` logic): inspect the\n * first own key of `update`; a value that is a function ⇒ Reducer form, a value\n * that is a record ⇒ Transitions form. We do NOT add a runtime tag to Machine.\n *\n * What we MUST NOT do (these are the effectful paths, off-limits here):\n *   - call `interpret[*]` handlers (perform I/O)\n *   - call `subscribe[*]` handlers (install listeners)\n *   - call `run` / the runtime\n * We MAY call `init`, `update[*]` cells, and `subscriptions(state)` — all pure\n * by the invariants (same set `replay` is allowed to touch).\n */\n\nimport type { Cmd, Machine, Sub } from \"../index\";\n\n// === Public options ===\n\n/**\n * Options controlling diagram emission.\n *\n * `samples` is the lever that turns STRUCTURAL edges into RESOLVED edges. For a\n * Transitions machine, providing a sample state for `stateType` AND a sample\n * msg for `msgType` lets us execute `update[stateType][msgType](state, msg)` and\n * read the real target `next.type`. Sample maps are keyed by the discriminant\n * string (`state.type` / `msg.type`).\n *\n * `samples.ctx` is the argument to `init(null, ctx)` — provide it to draw the\n * `[*] -->` initial-state edge. Omitted ⇒ no init edge (annotated as such),\n * because `init`'s signature requires a ctx and we will not invent one.\n */\nexport interface MachineVizOptions<S, M> {\n  samples?: {\n    /** Sample state per `state.type` — unlocks RESOLVED edges + sub annotations. */\n    states?: Partial<Record<string, S>>;\n    /** Sample msg per `msg.type` — unlocks RESOLVED edges. */\n    msgs?: Partial<Record<string, M>>;\n    /** Ctx for `init(null, ctx)` — unlocks the `[*] -->` initial-state edge. */\n    ctx?: unknown;\n  };\n  /** Mermaid layout direction. Default `\"TB\"` (top-to-bottom). */\n  direction?: \"TB\" | \"LR\";\n  /** Optional diagram title, emitted as a Mermaid front-matter `title:` block. */\n  title?: string;\n}\n\n// === Mermaid label escaping ===\n//\n// Mermaid state ids must be identifier-safe; arbitrary `type` strings (which\n// CAN contain `:`, spaces, `-`, etc.) are not. We sanitize the id used as the\n// node identifier and carry the human-readable original as a quoted label via\n// `stateId : \"Original\"` when they differ. Edge transition labels (after the\n// `:`) are sanitized to avoid breaking the arrow syntax.\n\n/** Sanitize a discriminant string into a Mermaid-safe node identifier. */\nfunction safeId(raw: string): string {\n  // Replace any run of non-identifier chars with `_`; prefix a leading digit so\n  // the id is always a valid Mermaid token. Empty ⇒ a stable placeholder.\n  const cleaned = raw.replace(/[^A-Za-z0-9_]/g, \"_\");\n  if (cleaned === \"\") return \"_empty\";\n  return /^[0-9]/.test(cleaned) ? `s_${cleaned}` : cleaned;\n}\n\n/** Sanitize text used as a Mermaid edge/transition label (after the `:`). */\nfunction safeLabel(raw: string): string {\n  // Strip the chars that terminate or confuse a transition label: newlines,\n  // the `:` that separates label from target, and Mermaid's `\"`/`;` delimiters.\n  return raw.replace(/[\"\\n\\r;:]/g, \" \").trim();\n}\n\n// === Form detection (mirrors run/replay updateMode) ===\n\ntype UpdateMode = \"reducer\" | \"transitions\";\n\n/**\n * Detect Reducer-vs-Transitions form from the value shape — identical logic to\n * `run`/`replay`'s `updateMode`. Inspect the first own key: a function value ⇒\n * Reducer (flat `{ [msg.type]: fn }`), a record value ⇒ Transitions (nested\n * `{ [state.type]: { [msg.type]: fn } }`). Empty object ⇒ M is `never`; the\n * mode is moot, default `\"reducer\"`.\n */\nfunction detectMode(update: unknown): UpdateMode {\n  const keys = Object.keys(update as object);\n  const firstKey = keys[0];\n  if (firstKey === undefined) return \"reducer\";\n  const firstValue = (update as Record<string, unknown>)[firstKey];\n  return typeof firstValue === \"function\" ? \"reducer\" : \"transitions\";\n}\n\n// === Edge model ===\n\ntype Edge =\n  // Resolved: we executed the cell with samples and read the real target.\n  | { kind: \"resolved\"; from: string; to: string; msg: string }\n  // Structural: no samples for the pair → target unknown, drawn as a self-loop.\n  | { kind: \"structural\"; from: string; msg: string };\n\n// === toMermaid ===\n\n/**\n * Render a `Machine` as a Mermaid `stateDiagram-v2` string.\n *\n * - **Transitions form** (`update` is a record-of-records): nodes are the\n *   `state.type` keys; each `(stateType × msgType)` cell becomes an edge. With\n *   samples for both, the edge is RESOLVED by executing the (pure) cell. Without\n *   samples it is STRUCTURAL — a `from --> from : msg?` self-loop (the `?`\n *   suffix marks \"target unresolved\"). A legend note documents the distinction.\n *   The `[*] -->` init edge is drawn only when `samples.ctx` is provided.\n *\n * - **Reducer form** (`update` values are functions): there is no static phase\n *   graph (state is not a discriminated union over phases). We emit a single\n *   node listing the handled `msg.type`s and an honest note saying so. No edges\n *   are invented.\n *\n * Output is deterministic for the same input (keys iterated in insertion order,\n * no clocks, no randomness).\n */\nexport function toMermaid<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  // `NoInfer` pins S/M to the `machine` argument so sample object literals in\n  // `opts` are CHECKED against the machine's State/Msg unions rather than\n  // driving inference (which would widen `{ type: \"open\" }` to `{ type: string }`\n  // and collide with the machine's discriminated union).\n  opts: MachineVizOptions<NoInfer<S>, NoInfer<M>> = {},\n): string {\n  const direction = opts.direction ?? \"TB\";\n  const stateSamples = opts.samples?.states ?? {};\n  const msgSamples = opts.samples?.msgs ?? {};\n  const hasCtx = opts.samples !== undefined && \"ctx\" in opts.samples;\n\n  const mode = detectMode(machine.update);\n  const lines: string[] = [];\n\n  // Front matter — Mermaid reads a YAML `title:` block before the diagram.\n  if (opts.title !== undefined) {\n    lines.push(\"---\", `title: ${opts.title}`, \"---\");\n  }\n  lines.push(\"stateDiagram-v2\");\n  lines.push(`  direction ${direction}`);\n\n  if (mode === \"reducer\") {\n    emitReducer(machine, lines);\n  } else {\n    emitTransitions(machine, lines, {\n      stateSamples,\n      msgSamples,\n      hasCtx,\n      ctx: opts.samples?.ctx,\n    });\n  }\n\n  // Subscriptions annotation — pure call to `subscriptions(sampleState)` per\n  // sampled state. Skipped entirely when no state samples are provided (we\n  // refuse to invent a state to feed it).\n  emitSubscriptions(machine, lines, stateSamples);\n\n  return lines.join(\"\\n\");\n}\n\n// === Reducer-form emission ===\n\n/**\n * Reducer form has no phase graph. Emit one node listing the handled msg types\n * plus an honest note. The msg set is the `update` record's keys (the Reducer\n * mapped type guarantees one cell per Msg variant).\n */\nfunction emitReducer(machine: { update: unknown }, lines: string[]): void {\n  const msgTypes = Object.keys(machine.update as object);\n  lines.push(\"  state ReducerMachine {\");\n  if (msgTypes.length === 0) {\n    lines.push(\"    [*] --> NoMsgs\");\n    lines.push('    NoMsgs : \"(no msg variants — M is never)\"');\n  } else {\n    for (const m of msgTypes) {\n      lines.push(`    ${safeId(m)} : ${safeLabel(m)}`);\n    }\n  }\n  lines.push(\"  }\");\n  // The note IS the design honesty: no edges, because reducer-form state is not\n  // a discriminated union over phases — there is no static target to draw.\n  lines.push(\"  note right of ReducerMachine\");\n  lines.push(\"    Reducer-form machine: flat dispatch keyed by msg.type.\");\n  lines.push(\n    \"    No phase graph — state is not a discriminated union over phases.\",\n  );\n  lines.push(`    Handled msg types: ${msgTypes.length}`);\n  lines.push(\"  end note\");\n}\n\n// === Transitions-form emission ===\n\ninterface TransitionsCtx<S, M> {\n  stateSamples: Partial<Record<string, S>>;\n  msgSamples: Partial<Record<string, M>>;\n  hasCtx: boolean;\n  ctx: unknown;\n}\n\n/**\n * Transitions form: walk the `update[stateType][msgType]` table. Execute the\n * (pure) cell when both samples exist → RESOLVED edge; otherwise → STRUCTURAL\n * self-loop. Draw the `[*] -->` init edge only when a ctx sample is given.\n */\nfunction emitTransitions<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  lines: string[],\n  ctx: TransitionsCtx<S, M>,\n): void {\n  type CellFn = (state: S, msg: M) => readonly [S, readonly C[]];\n  type Table = Record<string, Record<string, CellFn>>;\n  const table = machine.update as unknown as Table;\n  const stateTypes = Object.keys(table);\n\n  // Declare every node up front so even unreachable phases render.\n  for (const st of stateTypes) {\n    lines.push(`  ${safeId(st)}`);\n  }\n\n  // Init edge — only resolvable with a ctx sample. `init(null, ctx)` is pure\n  // (invariant 2: fresh-boot branch returns a starting state). Read `next.type`.\n  if (ctx.hasCtx) {\n    const [initState] = machine.init(null, ctx.ctx as Ctx);\n    const initType = (initState as unknown as { type: string }).type;\n    lines.push(`  [*] --> ${safeId(initType)}`);\n  } else {\n    lines.push(\n      \"  %% init edge omitted: no samples.ctx provided to run init(null, ctx)\",\n    );\n  }\n\n  let anyStructural = false;\n  for (const st of stateTypes) {\n    const row = table[st];\n    if (row === undefined) continue;\n    const msgTypes = Object.keys(row);\n    for (const mt of msgTypes) {\n      const edge = resolveEdge(row, st, mt, ctx);\n      if (edge.kind === \"resolved\") {\n        lines.push(\n          `  ${safeId(edge.from)} --> ${safeId(edge.to)} : ${safeLabel(edge.msg)}`,\n        );\n      } else {\n        anyStructural = true;\n        // Structural self-loop with a `?` suffix — target unresolved. Visually\n        // distinct from a resolved edge (self-loop + trailing `?`).\n        lines.push(\n          `  ${safeId(edge.from)} --> ${safeId(edge.from)} : ${safeLabel(edge.msg)}?`,\n        );\n      }\n    }\n  }\n\n  // Legend — document the resolved-vs-structural distinction in the output.\n  lines.push(\"  note right of \" + safeId(stateTypes[0] ?? \"_empty\"));\n  lines.push(\"    Transitions-form machine.\");\n  lines.push(\"    Edge a --> b : msg = RESOLVED (cell executed with samples).\");\n  if (anyStructural) {\n    lines.push(\n      \"    Self-loop a --> a : msg? = STRUCTURAL (no sample; target unresolved).\",\n    );\n  }\n  lines.push(\"  end note\");\n}\n\n/**\n * Resolve a single `(stateType, msgType)` cell into an Edge. With both a sample\n * state and a sample msg, EXECUTE the pure cell to read the real target. Any\n * missing sample → structural. A thrown cell (e.g. a sample shaped wrong for\n * the cell) degrades to structural rather than crashing the whole diagram —\n * the diagram is a best-effort visualization, not a correctness gate.\n */\nfunction resolveEdge<S, M extends { type: string }, C extends Cmd>(\n  row: Record<string, (state: S, msg: M) => readonly [S, readonly C[]]>,\n  stateType: string,\n  msgType: string,\n  ctx: {\n    stateSamples: Partial<Record<string, S>>;\n    msgSamples: Partial<Record<string, M>>;\n  },\n): Edge {\n  const sampleState = ctx.stateSamples[stateType];\n  const sampleMsg = ctx.msgSamples[msgType];\n  const cell = row[msgType];\n  if (\n    sampleState === undefined ||\n    sampleMsg === undefined ||\n    cell === undefined\n  ) {\n    return { kind: \"structural\", from: stateType, msg: msgType };\n  }\n  try {\n    const [next] = cell(sampleState, sampleMsg);\n    const to = (next as unknown as { type: string }).type;\n    return { kind: \"resolved\", from: stateType, to, msg: msgType };\n  } catch {\n    // Mismatched sample → cannot resolve. Fall back to structural.\n    return { kind: \"structural\", from: stateType, msg: msgType };\n  }\n}\n\n// === Subscriptions annotation ===\n\n/**\n * For each sampled state, call the (pure) `subscriptions(state)` description\n * function and annotate which Sub types are active in that state as a Mermaid\n * note. We call `subscriptions` (the description) but NEVER `subscribe[*]` (the\n * effectful installer) — same boundary `replay` honors. Skipped when no state\n * samples are provided or the machine declares no `subscriptions`.\n */\nfunction emitSubscriptions<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  lines: string[],\n  stateSamples: Partial<Record<string, S>>,\n): void {\n  if (machine.subscriptions === undefined) return;\n  const stateTypes = Object.keys(stateSamples);\n  if (stateTypes.length === 0) return;\n\n  for (const st of stateTypes) {\n    const sample = stateSamples[st];\n    if (sample === undefined) continue;\n    const subs = machine.subscriptions(sample);\n    const subTypes = subs.map((s) => s.type);\n    const body =\n      subTypes.length === 0\n        ? \"(no active subs)\"\n        : `subs: ${subTypes.map(safeLabel).join(\", \")}`;\n    lines.push(`  note left of ${safeId(st)}`);\n    lines.push(`    ${body}`);\n    lines.push(\"  end note\");\n  }\n}\n"]}
+{"version":3,"sources":["../../src/machine-viz/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @demlik/tea/machine-viz — turn a `Machine` into a Mermaid diagram string.\n *\n * PURE. No deps, no AST parsing, no file I/O. The function reads only the\n * `Machine` value it is handed plus optional sample states/msgs/ctx.\n *\n * The trick: TEA update cells are PURE (invariant 2 — they return\n * `[nextState, cmds]` as data, no effects). So we can SAFELY EXECUTE a cell to\n * discover its target state — exactly what `replay` does. That gives us REAL\n * edges (`red --> green : go`) without parsing source. When no sample is\n * provided for a `(state, msg)` pair we cannot resolve the target, so we fall\n * back to a STRUCTURAL self-edge annotated with `?` — visually distinct from a\n * resolved edge and documented in the diagram's legend.\n *\n * Form detection is `formOf(machine)` — the same reader `run`/`replay` use,\n * honoring the authoritative `__form` tag `defineMachine` stamps (falling back\n * to the structural heuristic for machines built without it; #275).\n *\n * What we MUST NOT do (these are the effectful paths, off-limits here):\n *   - call `interpret[*]` handlers (perform I/O)\n *   - call `subscribe[*]` handlers (install listeners)\n *   - call `run` / the runtime\n * We MAY call `init`, `update[*]` cells, and `subscriptions(state)` — all pure\n * by the invariants (same set `replay` is allowed to touch).\n */\n\nimport type { Cmd, Machine, Sub } from \"../index\";\nimport { formOf } from \"../index\";\n\n// === Public options ===\n\n/**\n * Options controlling diagram emission.\n *\n * `samples` is the lever that turns STRUCTURAL edges into RESOLVED edges. For a\n * Transitions machine, providing a sample state for `stateType` AND a sample\n * msg for `msgType` lets us execute `update[stateType][msgType](state, msg)` and\n * read the real target `next.type`. Sample maps are keyed by the discriminant\n * string (`state.type` / `msg.type`).\n *\n * `samples.ctx` is the argument to `init(null, ctx)` — provide it to draw the\n * `[*] -->` initial-state edge. Omitted ⇒ no init edge (annotated as such),\n * because `init`'s signature requires a ctx and we will not invent one.\n */\nexport interface MachineVizOptions<S, M> {\n  samples?: {\n    /** Sample state per `state.type` — unlocks RESOLVED edges + sub annotations. */\n    states?: Partial<Record<string, S>>;\n    /** Sample msg per `msg.type` — unlocks RESOLVED edges. */\n    msgs?: Partial<Record<string, M>>;\n    /** Ctx for `init(null, ctx)` — unlocks the `[*] -->` initial-state edge. */\n    ctx?: unknown;\n  };\n  /** Mermaid layout direction. Default `\"TB\"` (top-to-bottom). */\n  direction?: \"TB\" | \"LR\";\n  /** Optional diagram title, emitted as a Mermaid front-matter `title:` block. */\n  title?: string;\n}\n\n// === Mermaid label escaping ===\n//\n// Mermaid state ids must be identifier-safe; arbitrary `type` strings (which\n// CAN contain `:`, spaces, `-`, etc.) are not. We sanitize the id used as the\n// node identifier and carry the human-readable original as a quoted label via\n// `stateId : \"Original\"` when they differ. Edge transition labels (after the\n// `:`) are sanitized to avoid breaking the arrow syntax.\n\n/** Sanitize a discriminant string into a Mermaid-safe node identifier. */\nfunction safeId(raw: string): string {\n  // Replace any run of non-identifier chars with `_`; prefix a leading digit so\n  // the id is always a valid Mermaid token. Empty ⇒ a stable placeholder.\n  const cleaned = raw.replace(/[^A-Za-z0-9_]/g, \"_\");\n  if (cleaned === \"\") return \"_empty\";\n  return /^[0-9]/.test(cleaned) ? `s_${cleaned}` : cleaned;\n}\n\n/** Sanitize text used as a Mermaid edge/transition label (after the `:`). */\nfunction safeLabel(raw: string): string {\n  // Strip the chars that terminate or confuse a transition label: newlines,\n  // the `:` that separates label from target, and Mermaid's `\"`/`;` delimiters.\n  return raw.replace(/[\"\\n\\r;:]/g, \" \").trim();\n}\n\n// === Edge model ===\n\ntype Edge =\n  // Resolved: we executed the cell with samples and read the real target.\n  | { kind: \"resolved\"; from: string; to: string; msg: string }\n  // Structural: no samples for the pair → target unknown, drawn as a self-loop.\n  | { kind: \"structural\"; from: string; msg: string };\n\n// === toMermaid ===\n\n/**\n * Render a `Machine` as a Mermaid `stateDiagram-v2` string.\n *\n * - **Transitions form** (`update` is a record-of-records): nodes are the\n *   `state.type` keys; each `(stateType × msgType)` cell becomes an edge. With\n *   samples for both, the edge is RESOLVED by executing the (pure) cell. Without\n *   samples it is STRUCTURAL — a `from --> from : msg?` self-loop (the `?`\n *   suffix marks \"target unresolved\"). A legend note documents the distinction.\n *   The `[*] -->` init edge is drawn only when `samples.ctx` is provided.\n *\n * - **Reducer form** (`update` values are functions): there is no static phase\n *   graph (state is not a discriminated union over phases). We emit a single\n *   node listing the handled `msg.type`s and an honest note saying so. No edges\n *   are invented.\n *\n * Output is deterministic for the same input (keys iterated in insertion order,\n * no clocks, no randomness).\n */\nexport function toMermaid<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  // `NoInfer` pins S/M to the `machine` argument so sample object literals in\n  // `opts` are CHECKED against the machine's State/Msg unions rather than\n  // driving inference (which would widen `{ type: \"open\" }` to `{ type: string }`\n  // and collide with the machine's discriminated union).\n  opts: MachineVizOptions<NoInfer<S>, NoInfer<M>> = {},\n): string {\n  const direction = opts.direction ?? \"TB\";\n  const stateSamples = opts.samples?.states ?? {};\n  const msgSamples = opts.samples?.msgs ?? {};\n  const hasCtx = opts.samples !== undefined && \"ctx\" in opts.samples;\n\n  const mode = formOf(machine);\n  const lines: string[] = [];\n\n  // Front matter — Mermaid reads a YAML `title:` block before the diagram.\n  if (opts.title !== undefined) {\n    lines.push(\"---\", `title: ${opts.title}`, \"---\");\n  }\n  lines.push(\"stateDiagram-v2\");\n  lines.push(`  direction ${direction}`);\n\n  if (mode === \"reducer\") {\n    emitReducer(machine, lines);\n  } else {\n    emitTransitions(machine, lines, {\n      stateSamples,\n      msgSamples,\n      hasCtx,\n      ctx: opts.samples?.ctx,\n    });\n  }\n\n  // Subscriptions annotation — pure call to `subscriptions(sampleState)` per\n  // sampled state. Skipped entirely when no state samples are provided (we\n  // refuse to invent a state to feed it).\n  emitSubscriptions(machine, lines, stateSamples);\n\n  return lines.join(\"\\n\");\n}\n\n// === Reducer-form emission ===\n\n/**\n * Reducer form has no phase graph. Emit one node listing the handled msg types\n * plus an honest note. The msg set is the `update` record's keys (the Reducer\n * mapped type guarantees one cell per Msg variant).\n */\nfunction emitReducer(machine: { update: unknown }, lines: string[]): void {\n  const msgTypes = Object.keys(machine.update as object);\n  lines.push(\"  state ReducerMachine {\");\n  if (msgTypes.length === 0) {\n    lines.push(\"    [*] --> NoMsgs\");\n    lines.push('    NoMsgs : \"(no msg variants — M is never)\"');\n  } else {\n    for (const m of msgTypes) {\n      lines.push(`    ${safeId(m)} : ${safeLabel(m)}`);\n    }\n  }\n  lines.push(\"  }\");\n  // The note IS the design honesty: no edges, because reducer-form state is not\n  // a discriminated union over phases — there is no static target to draw.\n  lines.push(\"  note right of ReducerMachine\");\n  lines.push(\"    Reducer-form machine: flat dispatch keyed by msg.type.\");\n  lines.push(\n    \"    No phase graph — state is not a discriminated union over phases.\",\n  );\n  lines.push(`    Handled msg types: ${msgTypes.length}`);\n  lines.push(\"  end note\");\n}\n\n// === Transitions-form emission ===\n\ninterface TransitionsCtx<S, M> {\n  stateSamples: Partial<Record<string, S>>;\n  msgSamples: Partial<Record<string, M>>;\n  hasCtx: boolean;\n  ctx: unknown;\n}\n\n/**\n * Transitions form: walk the `update[stateType][msgType]` table. Execute the\n * (pure) cell when both samples exist → RESOLVED edge; otherwise → STRUCTURAL\n * self-loop. Draw the `[*] -->` init edge only when a ctx sample is given.\n */\nfunction emitTransitions<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  lines: string[],\n  ctx: TransitionsCtx<S, M>,\n): void {\n  type CellFn = (state: S, msg: M) => readonly [S, readonly C[]];\n  type Table = Record<string, Record<string, CellFn>>;\n  const table = machine.update as unknown as Table;\n  const stateTypes = Object.keys(table);\n\n  // Declare every node up front so even unreachable phases render.\n  for (const st of stateTypes) {\n    lines.push(`  ${safeId(st)}`);\n  }\n\n  // Init edge — only resolvable with a ctx sample. `init(null, ctx)` is pure\n  // (invariant 2: fresh-boot branch returns a starting state). Read `next.type`.\n  if (ctx.hasCtx) {\n    const [initState] = machine.init(null, ctx.ctx as Ctx);\n    const initType = (initState as unknown as { type: string }).type;\n    lines.push(`  [*] --> ${safeId(initType)}`);\n  } else {\n    lines.push(\n      \"  %% init edge omitted: no samples.ctx provided to run init(null, ctx)\",\n    );\n  }\n\n  let anyStructural = false;\n  for (const st of stateTypes) {\n    const row = table[st];\n    if (row === undefined) continue;\n    const msgTypes = Object.keys(row);\n    for (const mt of msgTypes) {\n      const edge = resolveEdge(row, st, mt, ctx);\n      if (edge.kind === \"resolved\") {\n        lines.push(\n          `  ${safeId(edge.from)} --> ${safeId(edge.to)} : ${safeLabel(edge.msg)}`,\n        );\n      } else {\n        anyStructural = true;\n        // Structural self-loop with a `?` suffix — target unresolved. Visually\n        // distinct from a resolved edge (self-loop + trailing `?`).\n        lines.push(\n          `  ${safeId(edge.from)} --> ${safeId(edge.from)} : ${safeLabel(edge.msg)}?`,\n        );\n      }\n    }\n  }\n\n  // Legend — document the resolved-vs-structural distinction in the output.\n  lines.push(`  note right of ${safeId(stateTypes[0] ?? \"_empty\")}`);\n  lines.push(\"    Transitions-form machine.\");\n  lines.push(\"    Edge a --> b : msg = RESOLVED (cell executed with samples).\");\n  if (anyStructural) {\n    lines.push(\n      \"    Self-loop a --> a : msg? = STRUCTURAL (no sample; target unresolved).\",\n    );\n  }\n  lines.push(\"  end note\");\n}\n\n/**\n * Resolve a single `(stateType, msgType)` cell into an Edge. With both a sample\n * state and a sample msg, EXECUTE the pure cell to read the real target. Any\n * missing sample → structural. A thrown cell (e.g. a sample shaped wrong for\n * the cell) degrades to structural rather than crashing the whole diagram —\n * the diagram is a best-effort visualization, not a correctness gate.\n */\nfunction resolveEdge<S, M extends { type: string }, C extends Cmd>(\n  row: Record<string, (state: S, msg: M) => readonly [S, readonly C[]]>,\n  stateType: string,\n  msgType: string,\n  ctx: {\n    stateSamples: Partial<Record<string, S>>;\n    msgSamples: Partial<Record<string, M>>;\n  },\n): Edge {\n  const sampleState = ctx.stateSamples[stateType];\n  const sampleMsg = ctx.msgSamples[msgType];\n  const cell = row[msgType];\n  if (\n    sampleState === undefined ||\n    sampleMsg === undefined ||\n    cell === undefined\n  ) {\n    return { kind: \"structural\", from: stateType, msg: msgType };\n  }\n  try {\n    const [next] = cell(sampleState, sampleMsg);\n    const to = (next as unknown as { type: string }).type;\n    return { kind: \"resolved\", from: stateType, to, msg: msgType };\n  } catch {\n    // Mismatched sample → cannot resolve. Fall back to structural.\n    return { kind: \"structural\", from: stateType, msg: msgType };\n  }\n}\n\n// === Subscriptions annotation ===\n\n/**\n * For each sampled state, call the (pure) `subscriptions(state)` description\n * function and annotate which Sub types are active in that state as a Mermaid\n * note. We call `subscriptions` (the description) but NEVER `subscribe[*]` (the\n * effectful installer) — same boundary `replay` honors. Skipped when no state\n * samples are provided or the machine declares no `subscriptions`.\n */\nfunction emitSubscriptions<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  lines: string[],\n  stateSamples: Partial<Record<string, S>>,\n): void {\n  if (machine.subscriptions === undefined) return;\n  const stateTypes = Object.keys(stateSamples);\n  if (stateTypes.length === 0) return;\n\n  for (const st of stateTypes) {\n    const sample = stateSamples[st];\n    if (sample === undefined) continue;\n    const subs = machine.subscriptions(sample);\n    const subTypes = subs.map((s) => s.type);\n    const body =\n      subTypes.length === 0\n        ? \"(no active subs)\"\n        : `subs: ${subTypes.map(safeLabel).join(\", \")}`;\n    lines.push(`  note left of ${safeId(st)}`);\n    lines.push(`    ${body}`);\n    lines.push(\"  end note\");\n  }\n}\n"]}

package/dist/mem/index.d.ts

@@ -1,4 +1,5 @@
 import { Store } from '../index.js';
+import '../core-BoB6t7dB.js';
 
 /**
  * @demlik/tea/mem — in-memory `Store<S>` adapter for `@demlik/tea`.