@kyneta/machine 1.6.0 → 1.6.1

package/dist/index.d.ts

@@ -4,7 +4,16 @@
  *
  * A Lease is a plain mutable record. Dispatchers mutate its fields
  * directly; no methods. When `depth` goes 0→1 a dispatcher becomes the
- * owner and resets `iterations`/`history` on its eventual 1→0 exit.
+ * owner and resets `iterations`/`history`/`counts`/`originStack` on its
+ * eventual 1→0 exit.
+ *
+ * Diagnostic instrumentation (history, counts, originStack) supports
+ * `BudgetExhaustedError`'s message:
+ * - `history` — bounded ring buffer of recent `{label, type}` events.
+ * - `counts` — cumulative `${label}:${type}` → count over the whole drain.
+ * - `originStack` — captured at the cascade's entry point (depth 0→1).
+ *   Names the boundary where the dispatch system was re-entered from
+ *   outside (userland for client-side flows, transport for server-side).
  */
 type Lease = {
   depth: number;
@@ -15,6 +24,8 @@ type Lease = {
     type: string;
   }[];
   readonly historyCapacity: number;
+  counts: Map<string, number>;
+  originStack: string | undefined;
 };
 type LeaseOptions = {
   budget?: number;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/dispatcher.ts","../src/machine.ts","../src/observable.ts"],"mappings":";;AAcA;;;;;;KAAY,KAAA;EACV,KAAA;EACA,UAAA;EAAA,SACS,MAAA;EACT,OAAA;IAAW,KAAA;IAAe,IAAA;EAAA;EAAA,SACjB,eAAA;AAAA;AAAA,KAGC,YAAA;EACV,MAAA;EACA,eAAe;AAAA;AAAA,iBAGD,WAAA,CAAY,OAAA,GAAU,YAAA,GAAe,KAAK;AAAA,cAU7C,oBAAA,SAA6B,KAAA;EAAA,SAC/B,KAAA,EAAO,KAAA;EAAA,SACP,KAAA;cACG,KAAA,UAAe,KAAA,EAAO,KAAA;AAAA;AAAA,KAaxB,iBAAA;EACV,KAAA,GAAQ,KAAK;EACb,KAAA;AAAA;AAAA,UAGe,gBAAA;EACf,QAAA,CAAS,GAAA,EAAK,GAAG;EAAA,SACR,UAAA;AAAA;;;;;;;;;;iBAYK,gBAAA,KAAA,CACd,OAAA,GAAU,GAAA,EAAK,GAAA,EAAK,QAAA,GAAW,GAAA,EAAK,GAAA,oBACpC,OAAA,GAAU,iBAAA,GACT,gBAAA,CAAiB,GAAA;;;;KC1ER,QAAA,SAAiB,GAAA,EAAK,GAAG;;KAGzB,MAAA,SAAe,QAAA,EAAU,QAAQ,CAAC,GAAA;;;;;;;;;;ADepB;AAG1B;;KCJY,OAAA,kBAAyB,MAAA,CAAO,GAAA;EAC1C,IAAA,GAAO,KAAA,KAAU,EAAA;EACjB,MAAA,CAAO,GAAA,EAAK,GAAA,EAAK,KAAA,EAAO,KAAA,IAAS,KAAA,KAAU,EAAA;EAC3C,IAAA,EAAM,KAAA,EAAO,KAAA;AAAA;;KAIH,QAAA;;;;;ADE8C;AAU1D;;;;;;;;;;iBCKgB,OAAA,YAAA,CACd,OAAA,EAAS,OAAA,CAAQ,GAAA,EAAK,KAAA,GACtB,IAAA,IAAQ,KAAA,EAAO,KAAA,EAAO,QAAA,EAAU,QAAA,CAAS,GAAA,aACxC,QAAA;;;;;;;;;KCbS,eAAA;EACV,IAAA,EAAM,CAAA;EACN,EAAA,EAAI,CAAC;EACL,SAAA;AAAA;AFhBwB;AAG1B;;AAH0B,KEsBd,kBAAA,OAAyB,UAAA,EAAY,eAAe,CAAC,CAAA;;AFjBhD;AAGjB;;;;;UE2BiB,gBAAA;EF3BoC;EE6BnD,QAAA,EAAU,QAAA,CAAS,GAAA;EF7BqC;EEgCxD,QAAA,IAAY,KAAA;EFtBoB;;;;;;EE8BhC,sBAAA,CAAuB,QAAA,EAAU,kBAAA,CAAmB,KAAA;EF9BZ;;;;;;EEsCxC,YAAA,CACE,SAAA,GAAY,KAAA,EAAO,KAAA,cACnB,OAAA;IAAY,SAAA;EAAA,IACX,OAAA,CAAQ,KAAA;EFtC4B;AAazC;;;;EEgCE,aAAA;IAA0B,MAAA;EAAA,GACxB,IAAA,EAAM,gBAAA,CAAiB,GAAA,EAAK,CAAA,GAC5B,MAAA,EAAQ,CAAA,YACR,OAAA;IAAY,SAAA;EAAA,IACX,OAAA,CAAQ,CAAA;EF/BI;;;EEoCf,OAAA;AAAA;;;;;;AFlCmB;AAYrB;;;;;;;;;;;;;;iBEiDgB,uBAAA,gBAAA,CACd,OAAA,EAAS,OAAA,CAAQ,GAAA,EAAK,KAAA,EAAO,EAAA,GAC7B,QAAA,GAAW,MAAA,EAAQ,EAAA,EAAI,QAAA,EAAU,QAAA,CAAS,GAAA,YAC1C,OAAA;EAAY,KAAA,GAAQ,KAAA;EAAO,KAAA;AAAA,IAC1B,gBAAA,CAAiB,GAAA,EAAK,KAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/dispatcher.ts","../src/machine.ts","../src/observable.ts"],"mappings":";;AAuBA;;;;;;;;;;;;;;;KAAY,KAAA;EACV,KAAA;EACA,UAAA;EAAA,SACS,MAAA;EACT,OAAA;IAAW,KAAA;IAAe,IAAA;EAAA;EAAA,SACjB,eAAA;EACT,MAAA,EAAQ,GAAG;EACX,WAAA;AAAA;AAAA,KAGU,YAAA;EACV,MAAA;EACA,eAAe;AAAA;AAAA,iBAGD,WAAA,CAAY,OAAA,GAAU,YAAA,GAAe,KAAK;AAAA,cAiF7C,oBAAA,SAA6B,KAAA;EAAA,SAC/B,KAAA,EAAO,KAAA;EAAA,SACP,KAAA;cACG,KAAA,UAAe,KAAA,EAAO,KAAA;AAAA;AAAA,KAqBxB,iBAAA;EACV,KAAA,GAAQ,KAAK;EACb,KAAA;AAAA;AAAA,UAGe,gBAAA;EACf,QAAA,CAAS,GAAA,EAAK,GAAG;EAAA,SACR,UAAA;AAAA;;;;;AAAU;AAYrB;;;;iBAAgB,gBAAA,KAAA,CACd,OAAA,GAAU,GAAA,EAAK,GAAA,EAAK,QAAA,GAAW,GAAA,EAAK,GAAA,oBACpC,OAAA,GAAU,iBAAA,GACT,gBAAA,CAAiB,GAAA;;;;KCpKR,QAAA,SAAiB,GAAA,EAAK,GAAG;;KAGzB,MAAA,SAAe,QAAA,EAAU,QAAQ,CAAC,GAAA;;;;;;;;;;;;;KAclC,OAAA,kBAAyB,MAAA,CAAO,GAAA;EAC1C,IAAA,GAAO,KAAA,KAAU,EAAA;EACjB,MAAA,CAAO,GAAA,EAAK,GAAA,EAAK,KAAA,EAAO,KAAA,IAAS,KAAA,KAAU,EAAA;EAC3C,IAAA,EAAM,KAAA,EAAO,KAAA;AAAA;ADcE;AAAA,KCVL,QAAA;;;;;;;;ADa8C;AAiF1D;;;;;;;iBC7EgB,OAAA,YAAA,CACd,OAAA,EAAS,OAAA,CAAQ,GAAA,EAAK,KAAA,GACtB,IAAA,IAAQ,KAAA,EAAO,KAAA,EAAO,QAAA,EAAU,QAAA,CAAS,GAAA,aACxC,QAAA;;;;;;;;;KCbS,eAAA;EACV,IAAA,EAAM,CAAA;EACN,EAAA,EAAI,CAAC;EACL,SAAA;AAAA;;;;KAMU,kBAAA,OAAyB,UAAA,EAAY,eAAe,CAAC,CAAA;AFRjE;;;;AAEiB;AAGjB;;AALA,UEqBiB,gBAAA;EFhByC;EEkBxD,QAAA,EAAU,QAAA,CAAS,GAAA;EFlBO;EEqB1B,QAAA,IAAY,KAAA;EFrB4C;AAAA;AAiF1D;;;;EEpDE,sBAAA,CAAuB,QAAA,EAAU,kBAAA,CAAmB,KAAA;EFoDZ;;;;;;EE5CxC,YAAA,CACE,SAAA,GAAY,KAAA,EAAO,KAAA,cACnB,OAAA;IAAY,SAAA;EAAA,IACX,OAAA,CAAQ,KAAA;EF4CuB;;;AAAK;AAqBzC;EE1DE,aAAA;IAA0B,MAAA;EAAA,GACxB,IAAA,EAAM,gBAAA,CAAiB,GAAA,EAAK,CAAA,GAC5B,MAAA,EAAQ,CAAA,YACR,OAAA;IAAY,SAAA;EAAA,IACX,OAAA,CAAQ,CAAA;EFwDX;;AAAK;EEnDL,OAAA;AAAA;;;;;;;;;AFwDmB;AAYrB;;;;;;;;;;;iBEzCgB,uBAAA,gBAAA,CACd,OAAA,EAAS,OAAA,CAAQ,GAAA,EAAK,KAAA,EAAO,EAAA,GAC7B,QAAA,GAAW,MAAA,EAAQ,EAAA,EAAI,QAAA,EAAU,QAAA,CAAS,GAAA,YAC1C,OAAA;EAAY,KAAA,GAAQ,KAAA;EAAO,KAAA;AAAA,IAC1B,gBAAA,CAAiB,GAAA,EAAK,KAAA"}

package/dist/index.js

@@ -5,18 +5,69 @@ function createLease(options) {
 		iterations: 0,
 		budget: options?.budget ?? 1e5,
 		history: [],
-		historyCapacity: options?.historyCapacity ?? 32
+		historyCapacity: options?.historyCapacity ?? 32,
+		counts: /* @__PURE__ */ new Map(),
+		originStack: void 0
 	};
 }
+/**
+* Single mutation site for the lease's diagnostic projections. Future
+* additions (e.g. subscriber-call site) land here so `history` and
+* `counts` can't drift out of sync with each other.
+*/
+function recordDispatch(lease, label, type) {
+	if (lease.history.length >= lease.historyCapacity) lease.history.shift();
+	lease.history.push({
+		label,
+		type
+	});
+	const key = `${label}:${type}`;
+	lease.counts.set(key, (lease.counts.get(key) ?? 0) + 1);
+}
+/**
+* Pure formatter for the cascade-origin section of `BudgetExhaustedError`'s
+* message. Strips the synthetic `Error: cascade origin` header from the
+* captured stack — it's the label we used to *construct* the Error solely
+* to grab a stack, not a meaningful frame.
+*/
+function formatOrigin(originStack) {
+	if (!originStack) return "";
+	const lines = originStack.split("\n");
+	const start = lines[0]?.startsWith("Error") ? 1 : 0;
+	return `  cascade entered from:\n${lines.slice(start).map((l) => `    ${l.trim()}`).join("\n")}\n`;
+}
+/**
+* Pure formatter for the histogram section. Width is computed per
+* render because cooperating dispatchers produce labels as long as
+* `synchronizer:sync:sync/synthetic-doc-removed-all` (46 chars) — a
+* fixed `padEnd` width would mis-align the count column.
+*/
+function formatHistogram(counts, total, topN) {
+	if (counts.size === 0 || total <= 0) return "";
+	const entries = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, topN);
+	const maxKeyLen = Math.max(...entries.map(([k]) => k.length));
+	return `  top message types:\n${entries.map(([key, n]) => {
+		const pct = (n / total * 100).toFixed(1);
+		return `    ${key.padEnd(maxKeyLen)}  ${String(n).padStart(7)}  (${pct.padStart(4)}%)`;
+	}).join("\n")}\n`;
+}
+function formatRecent(history) {
+	if (history.length === 0) return "";
+	const tail = history.map((h) => `${h.label}:${h.type}`).join(", ");
+	return `  recent (${history.length}): ${tail}\n`;
+}
 var BudgetExhaustedError = class extends Error {
 	lease;
 	label;
 	constructor(label, lease) {
-		super(`[dispatcher:${label}] iteration budget exhausted (${lease.iterations} > ${lease.budget}); recent: ${lease.history.map((h) => `${h.label}:${h.type}`).join(", ")}`);
+		const header = `[dispatcher:${label}] iteration budget exhausted (${lease.iterations} > ${lease.budget})`;
+		const body = formatOrigin(lease.originStack) + formatHistogram(lease.counts, lease.iterations, 5) + formatRecent(lease.history);
+		super(body.length > 0 ? `${header}\n${body}` : header);
 		this.name = "BudgetExhaustedError";
 		this.lease = {
 			...lease,
-			history: [...lease.history]
+			history: [...lease.history],
+			counts: new Map(lease.counts)
 		};
 		this.label = label;
 	}
@@ -40,17 +91,13 @@ function createDispatcher(handler, options) {
 		if (isDispatching) return;
 		isDispatching = true;
 		const owns = lease.depth === 0;
+		if (owns) lease.originStack = (/* @__PURE__ */ new Error("cascade origin")).stack;
 		lease.depth += 1;
 		try {
 			while (pending.length > 0) {
 				const next = pending.shift();
 				lease.iterations += 1;
-				const type = typeof next === "object" && next !== null && "type" in next ? String(next.type) : "<untyped>";
-				if (lease.history.length >= lease.historyCapacity) lease.history.shift();
-				lease.history.push({
-					label,
-					type
-				});
+				recordDispatch(lease, label, typeof next === "object" && next !== null && "type" in next ? String(next.type) : "<untyped>");
 				if (lease.iterations > lease.budget) throw new BudgetExhaustedError(label, lease);
 				handler(next, dispatch);
 			}
@@ -59,6 +106,8 @@ function createDispatcher(handler, options) {
 			if (owns) {
 				lease.iterations = 0;
 				lease.history.length = 0;
+				lease.counts.clear();
+				lease.originStack = void 0;
 			}
 			isDispatching = false;
 		}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/dispatcher.ts","../src/machine.ts","../src/observable.ts"],"sourcesContent":["// dispatcher — drain-to-quiescence primitive shared by reactive frontiers.\n//\n// createDispatcher() is the underlying primitive that the input-processing\n// loop in createObservableProgram is built on. Factoring it out as a named\n// export lets cooperating dispatchers share a Lease — a single iteration\n// budget and re-entry depth tracker that bounds runaway cascades.\n\n/**\n * Shared iteration budget for cooperating dispatchers.\n *\n * A Lease is a plain mutable record. Dispatchers mutate its fields\n * directly; no methods. When `depth` goes 0→1 a dispatcher becomes the\n * owner and resets `iterations`/`history` on its eventual 1→0 exit.\n */\nexport type Lease = {\n  depth: number\n  iterations: number\n  readonly budget: number\n  history: { label: string; type: string }[]\n  readonly historyCapacity: number\n}\n\nexport type LeaseOptions = {\n  budget?: number\n  historyCapacity?: number\n}\n\nexport function createLease(options?: LeaseOptions): Lease {\n  return {\n    depth: 0,\n    iterations: 0,\n    budget: options?.budget ?? 100_000,\n    history: [],\n    historyCapacity: options?.historyCapacity ?? 32,\n  }\n}\n\nexport class BudgetExhaustedError extends Error {\n  readonly lease: Lease\n  readonly label: string\n  constructor(label: string, lease: Lease) {\n    super(\n      `[dispatcher:${label}] iteration budget exhausted (${lease.iterations} > ${lease.budget}); ` +\n        `recent: ${lease.history.map(h => `${h.label}:${h.type}`).join(\", \")}`,\n    )\n    this.name = \"BudgetExhaustedError\"\n    // Snapshot the lease so the history survives the owning dispatcher's\n    // finally-block reset that runs as the exception unwinds.\n    this.lease = { ...lease, history: [...lease.history] }\n    this.label = label\n  }\n}\n\nexport type DispatcherOptions = {\n  lease?: Lease\n  label?: string\n}\n\nexport interface DispatcherHandle<Msg> {\n  dispatch(msg: Msg): void\n  readonly queueDepth: number\n}\n\n/**\n * Drain-to-quiescence dispatcher with optional shared budget.\n *\n * Re-entrant `dispatch(msg)` from inside the handler — including from\n * another `DispatcherHandle.dispatch(...)` sharing the same Lease —\n * joins the current drain rather than recursing. This is the property\n * that lets cooperating dispatchers compose: an A→B→A oscillation is\n * one cascade in one lease, not a stack overflow.\n */\nexport function createDispatcher<Msg>(\n  handler: (msg: Msg, dispatch: (msg: Msg) => void) => void,\n  options?: DispatcherOptions,\n): DispatcherHandle<Msg> {\n  const lease = options?.lease ?? createLease()\n  const label = options?.label ?? \"dispatcher\"\n  const pending: Msg[] = []\n  let isDispatching = false\n\n  function dispatch(msg: Msg): void {\n    pending.push(msg)\n    if (isDispatching) return\n\n    isDispatching = true\n    const owns = lease.depth === 0\n    lease.depth += 1\n    try {\n      while (pending.length > 0) {\n        const next = pending.shift()!\n        lease.iterations += 1\n        const type =\n          typeof next === \"object\" && next !== null && \"type\" in next\n            ? String((next as { type: unknown }).type)\n            : \"<untyped>\"\n        if (lease.history.length >= lease.historyCapacity) {\n          lease.history.shift()\n        }\n        lease.history.push({ label, type })\n        if (lease.iterations > lease.budget) {\n          throw new BudgetExhaustedError(label, lease)\n        }\n        handler(next, dispatch)\n      }\n    } finally {\n      lease.depth -= 1\n      if (owns) {\n        lease.iterations = 0\n        lease.history.length = 0\n      }\n      isDispatching = false\n    }\n  }\n\n  return {\n    dispatch,\n    get queueDepth(): number {\n      return pending.length\n    },\n  }\n}\n","/** Dispatch a message into a running program. */\nexport type Dispatch<Msg> = (msg: Msg) => void\n\n/** An effect is a continuation that may dispatch messages. */\nexport type Effect<Msg> = (dispatch: Dispatch<Msg>) => void\n\n/**\n * A Mealy machine — pure state transitions with effect outputs.\n *\n * `Fx` defaults to `Effect<Msg>` (closure effects) but can be any\n * data type for programs with custom effect executors.\n *\n * - `init`: initial state and zero or more effects to execute at startup.\n * - `update`: pure transition — given a message and the current state,\n *   return the new state and zero or more effects.\n * - `done`: optional teardown hook, called with the final state when\n *   the runtime is disposed.\n */\nexport type Program<Msg, Model, Fx = Effect<Msg>> = {\n  init: [Model, ...Fx[]]\n  update(msg: Msg, model: Model): [Model, ...Fx[]]\n  done?(model: Model): void\n}\n\n/** Dispose a running program — stops message processing and calls `done`. */\nexport type Disposer = () => void\n\n/**\n * Run a program whose effects are `Effect<Msg>` closures.\n *\n * The runtime:\n * 1. Extracts `[model, ...effects]` from `program.init`.\n * 2. Executes each initial effect with `dispatch`.\n * 3. Calls `view(model, dispatch)` if provided.\n * 4. On `dispatch(msg)`: calls `update(msg, state)`, updates state,\n *    executes effects, calls `view`.\n * 5. Returns a `Disposer` that stops dispatch and calls `program.done`.\n *\n * Effects are executed synchronously in order. An effect may call\n * `dispatch` re-entrantly — the runtime processes re-entrant messages\n * after the current dispatch cycle completes (queue-based).\n */\nexport function runtime<Msg, Model>(\n  program: Program<Msg, Model>,\n  view?: (model: Model, dispatch: Dispatch<Msg>) => void,\n): Disposer {\n  let state: Model\n  let isRunning = true\n  const pending: Msg[] = []\n  let isDispatching = false\n\n  function dispatch(msg: Msg): void {\n    if (!isRunning) return\n\n    pending.push(msg)\n    if (isDispatching) return\n\n    isDispatching = true\n    try {\n      while (pending.length > 0) {\n        const next = pending.shift()!\n        const [newModel, ...effects] = program.update(next, state)\n        state = newModel\n        for (const effect of effects) {\n          effect(dispatch)\n        }\n        if (view) view(state, dispatch)\n      }\n    } finally {\n      isDispatching = false\n    }\n  }\n\n  // Initialize\n  const [initialModel, ...initialEffects] = program.init\n  state = initialModel\n  for (const effect of initialEffects) {\n    effect(dispatch)\n  }\n  if (view) view(state, dispatch)\n\n  // Return disposer\n  return () => {\n    if (!isRunning) return\n    isRunning = false\n    program.done?.(state)\n  }\n}\n","// observable — data-effect runtime with state observation.\n//\n// createObservableProgram() is the data-effect counterpart to runtime().\n// Where runtime() executes closure effects (Effect<Msg>), this function\n// accepts a custom executor for data effects (Fx). It also provides\n// state observation: subscribeToTransitions, waitForState, waitForStatus.\n//\n// This subsumes ClientStateMachine's observation API and the peer program's\n// hand-rolled dispatch loop. Transition delivery is synchronous — the\n// listener fires after each update. The microtask-batched delivery from\n// ClientStateMachine is unnecessary complexity that no consumer depends on.\n\nimport { createDispatcher, type Lease } from \"./dispatcher.js\"\nimport type { Dispatch, Program } from \"./machine.js\"\n\n// ---------------------------------------------------------------------------\n// Ambient declarations for timer APIs (not in lib: [\"ESNext\"])\n// ---------------------------------------------------------------------------\n\ndeclare function setTimeout(callback: () => void, ms: number): unknown\ndeclare function clearTimeout(id: unknown): void\n\n// ---------------------------------------------------------------------------\n// Observation types\n// ---------------------------------------------------------------------------\n\n/**\n * A state transition event — from one model to another.\n *\n * Generic over the model type. This is the machine-level primitive;\n * transport packages re-export or alias it for their specific state types.\n */\nexport type StateTransition<S> = {\n  from: S\n  to: S\n  timestamp: number\n}\n\n/**\n * Listener for state transitions.\n */\nexport type TransitionListener<S> = (transition: StateTransition<S>) => void\n\n// ---------------------------------------------------------------------------\n// ObservableHandle\n// ---------------------------------------------------------------------------\n\n/**\n * Handle for a running observable program.\n *\n * Provides dispatch, state access, transition observation, and disposal.\n * The observation API (`subscribeToTransitions`, `waitForState`, `waitForStatus`)\n * matches the surface of the former `ClientStateMachine<S>`.\n */\nexport interface ObservableHandle<Msg, Model> {\n  /** Dispatch a message into the program. */\n  dispatch: Dispatch<Msg>\n\n  /** Get the current model synchronously. */\n  getState(): Model\n\n  /**\n   * Subscribe to state transitions.\n   *\n   * Transitions are delivered synchronously after each update.\n   * Returns an unsubscribe function.\n   */\n  subscribeToTransitions(listener: TransitionListener<Model>): () => void\n\n  /**\n   * Wait for a specific state.\n   *\n   * Resolves immediately if the current state matches the predicate.\n   * Otherwise waits for a transition that matches.\n   */\n  waitForState(\n    predicate: (state: Model) => boolean,\n    options?: { timeoutMs?: number },\n  ): Promise<Model>\n\n  /**\n   * Wait for a specific status string on a model with a `status` discriminant.\n   *\n   * Convenience wrapper around `waitForState()`.\n   */\n  waitForStatus<S extends { status: string }>(\n    this: ObservableHandle<Msg, S>,\n    status: S[\"status\"],\n    options?: { timeoutMs?: number },\n  ): Promise<S>\n\n  /**\n   * Dispose the program — stops dispatch and calls `program.done`.\n   */\n  dispose(): void\n}\n\n// ---------------------------------------------------------------------------\n// createObservableProgram\n// ---------------------------------------------------------------------------\n\n/**\n * Run a program with data effects and state observation.\n *\n * Like `runtime()`, but instead of executing closure effects directly,\n * it delegates to a custom `executor` for each data effect. This enables\n * programs whose effects are inspectable data types (not opaque closures).\n *\n * The runtime:\n * 1. Extracts `[model, ...effects]` from `program.init`.\n * 2. Executes each initial effect via `executor(effect, dispatch)`.\n * 3. On `dispatch(msg)`: calls `update(msg, state)`, updates state,\n *    notifies transition listeners, executes effects.\n * 4. Re-entrant dispatch (effect calls dispatch) is queued and processed\n *    after the current dispatch cycle completes.\n * 5. `dispose()` stops dispatch and calls `program.done`.\n *\n * @param program - The program algebra: init, update, done.\n * @param executor - Interprets data effects as I/O.\n * @returns An observable handle for the running program.\n */\nexport function createObservableProgram<Msg, Model, Fx>(\n  program: Program<Msg, Model, Fx>,\n  executor: (effect: Fx, dispatch: Dispatch<Msg>) => void,\n  options?: { lease?: Lease; label?: string },\n): ObservableHandle<Msg, Model> {\n  let state: Model\n  let isRunning = true\n  const listeners = new Set<TransitionListener<Model>>()\n\n  // --------------------------------------------------------------------------\n  // Transition notification\n  // --------------------------------------------------------------------------\n\n  function notifyTransition(from: Model, to: Model): void {\n    if (from === to) return\n\n    const transition: StateTransition<Model> = {\n      from,\n      to,\n      timestamp: Date.now(),\n    }\n\n    for (const listener of listeners) {\n      try {\n        listener(transition)\n      } catch {\n        // Swallow listener errors — observers must not break dispatch.\n      }\n    }\n  }\n\n  // --------------------------------------------------------------------------\n  // Dispatch\n  // --------------------------------------------------------------------------\n\n  const handle = createDispatcher<Msg>(\n    (msg, redispatch) => {\n      if (!isRunning) return\n      const prev = state\n      const [newModel, ...effects] = program.update(msg, state)\n      state = newModel\n      notifyTransition(prev, state)\n      for (const effect of effects) {\n        executor(effect, redispatch)\n      }\n    },\n    { lease: options?.lease, label: options?.label ?? \"observable\" },\n  )\n\n  function dispatch(msg: Msg): void {\n    if (!isRunning) return\n    handle.dispatch(msg)\n  }\n\n  // --------------------------------------------------------------------------\n  // Observation\n  // --------------------------------------------------------------------------\n\n  function getState(): Model {\n    return state\n  }\n\n  function subscribeToTransitions(\n    listener: TransitionListener<Model>,\n  ): () => void {\n    listeners.add(listener)\n    return () => {\n      listeners.delete(listener)\n    }\n  }\n\n  function waitForState(\n    predicate: (state: Model) => boolean,\n    options?: { timeoutMs?: number },\n  ): Promise<Model> {\n    // Resolve immediately if already matching\n    if (predicate(state)) {\n      return Promise.resolve(state)\n    }\n\n    return new Promise((resolve, reject) => {\n      let timeoutId: unknown\n\n      const unsubscribe = subscribeToTransitions(transition => {\n        if (predicate(transition.to)) {\n          cleanup()\n          resolve(transition.to)\n        }\n      })\n\n      const cleanup = () => {\n        unsubscribe()\n        if (timeoutId !== undefined) {\n          clearTimeout(timeoutId)\n        }\n      }\n\n      if (options?.timeoutMs !== undefined) {\n        timeoutId = setTimeout(() => {\n          cleanup()\n          reject(\n            new Error(`Timeout waiting for state after ${options.timeoutMs}ms`),\n          )\n        }, options.timeoutMs)\n      }\n    })\n  }\n\n  function waitForStatus<S extends { status: string }>(\n    this: ObservableHandle<Msg, S>,\n    status: S[\"status\"],\n    options?: { timeoutMs?: number },\n  ): Promise<S> {\n    return this.waitForState((s: S) => s.status === status, options)\n  }\n\n  function dispose(): void {\n    if (!isRunning) return\n    isRunning = false\n    program.done?.(state)\n  }\n\n  // --------------------------------------------------------------------------\n  // Initialize\n  // --------------------------------------------------------------------------\n\n  const [initialModel, ...initialEffects] = program.init\n  state = initialModel\n  for (const effect of initialEffects) {\n    executor(effect, dispatch)\n  }\n\n  // --------------------------------------------------------------------------\n  // Return handle\n  // --------------------------------------------------------------------------\n\n  return {\n    dispatch,\n    getState,\n    subscribeToTransitions,\n    waitForState,\n    waitForStatus,\n    dispose,\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/dispatcher.ts","../src/machine.ts","../src/observable.ts"],"sourcesContent":["// dispatcher — drain-to-quiescence primitive shared by reactive frontiers.\n//\n// createDispatcher() is the underlying primitive that the input-processing\n// loop in createObservableProgram is built on. Factoring it out as a named\n// export lets cooperating dispatchers share a Lease — a single iteration\n// budget and re-entry depth tracker that bounds runaway cascades.\n\n/**\n * Shared iteration budget for cooperating dispatchers.\n *\n * A Lease is a plain mutable record. Dispatchers mutate its fields\n * directly; no methods. When `depth` goes 0→1 a dispatcher becomes the\n * owner and resets `iterations`/`history`/`counts`/`originStack` on its\n * eventual 1→0 exit.\n *\n * Diagnostic instrumentation (history, counts, originStack) supports\n * `BudgetExhaustedError`'s message:\n * - `history` — bounded ring buffer of recent `{label, type}` events.\n * - `counts` — cumulative `${label}:${type}` → count over the whole drain.\n * - `originStack` — captured at the cascade's entry point (depth 0→1).\n *   Names the boundary where the dispatch system was re-entered from\n *   outside (userland for client-side flows, transport for server-side).\n */\nexport type Lease = {\n  depth: number\n  iterations: number\n  readonly budget: number\n  history: { label: string; type: string }[]\n  readonly historyCapacity: number\n  counts: Map<string, number>\n  originStack: string | undefined\n}\n\nexport type LeaseOptions = {\n  budget?: number\n  historyCapacity?: number\n}\n\nexport function createLease(options?: LeaseOptions): Lease {\n  return {\n    depth: 0,\n    iterations: 0,\n    budget: options?.budget ?? 100_000,\n    history: [],\n    historyCapacity: options?.historyCapacity ?? 32,\n    counts: new Map(),\n    originStack: undefined,\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Diagnostic recording — single mutation site for history + counts\n// ---------------------------------------------------------------------------\n\n/**\n * Single mutation site for the lease's diagnostic projections. Future\n * additions (e.g. subscriber-call site) land here so `history` and\n * `counts` can't drift out of sync with each other.\n */\nfunction recordDispatch(lease: Lease, label: string, type: string): void {\n  if (lease.history.length >= lease.historyCapacity) lease.history.shift()\n  lease.history.push({ label, type })\n  const key = `${label}:${type}`\n  lease.counts.set(key, (lease.counts.get(key) ?? 0) + 1)\n}\n\n// ---------------------------------------------------------------------------\n// Pure formatters for BudgetExhaustedError's message sections\n// ---------------------------------------------------------------------------\n\n/**\n * Pure formatter for the cascade-origin section of `BudgetExhaustedError`'s\n * message. Strips the synthetic `Error: cascade origin` header from the\n * captured stack — it's the label we used to *construct* the Error solely\n * to grab a stack, not a meaningful frame.\n */\nexport function formatOrigin(originStack: string | undefined): string {\n  if (!originStack) return \"\"\n  const lines = originStack.split(\"\\n\")\n  const start = lines[0]?.startsWith(\"Error\") ? 1 : 0\n  const frames = lines.slice(start).map(l => `    ${l.trim()}`)\n  return `  cascade entered from:\\n${frames.join(\"\\n\")}\\n`\n}\n\n/**\n * Pure formatter for the histogram section. Width is computed per\n * render because cooperating dispatchers produce labels as long as\n * `synchronizer:sync:sync/synthetic-doc-removed-all` (46 chars) — a\n * fixed `padEnd` width would mis-align the count column.\n */\nexport function formatHistogram(\n  counts: ReadonlyMap<string, number>,\n  total: number,\n  topN: number,\n): string {\n  if (counts.size === 0 || total <= 0) return \"\"\n  const entries = [...counts.entries()]\n    .sort((a, b) => b[1] - a[1])\n    .slice(0, topN)\n  const maxKeyLen = Math.max(...entries.map(([k]) => k.length))\n  const rows = entries.map(([key, n]) => {\n    const pct = ((n / total) * 100).toFixed(1)\n    return `    ${key.padEnd(maxKeyLen)}  ${String(n).padStart(7)}  (${pct.padStart(4)}%)`\n  })\n  return `  top message types:\\n${rows.join(\"\\n\")}\\n`\n}\n\nexport function formatRecent(\n  history: readonly { label: string; type: string }[],\n): string {\n  if (history.length === 0) return \"\"\n  const tail = history.map(h => `${h.label}:${h.type}`).join(\", \")\n  return `  recent (${history.length}): ${tail}\\n`\n}\n\n// ---------------------------------------------------------------------------\n// BudgetExhaustedError\n// ---------------------------------------------------------------------------\n\nexport class BudgetExhaustedError extends Error {\n  readonly lease: Lease\n  readonly label: string\n  constructor(label: string, lease: Lease) {\n    const header = `[dispatcher:${label}] iteration budget exhausted (${lease.iterations} > ${lease.budget})`\n    const body =\n      formatOrigin(lease.originStack) +\n      formatHistogram(lease.counts, lease.iterations, 5) +\n      formatRecent(lease.history)\n    super(body.length > 0 ? `${header}\\n${body}` : header)\n    this.name = \"BudgetExhaustedError\"\n    // Snapshot the lease so the diagnostic state survives the owning\n    // dispatcher's finally-block reset that runs as the exception unwinds.\n    // `counts` is a Map and must be cloned explicitly — spread does not\n    // copy Map contents.\n    this.lease = {\n      ...lease,\n      history: [...lease.history],\n      counts: new Map(lease.counts),\n    }\n    this.label = label\n  }\n}\n\nexport type DispatcherOptions = {\n  lease?: Lease\n  label?: string\n}\n\nexport interface DispatcherHandle<Msg> {\n  dispatch(msg: Msg): void\n  readonly queueDepth: number\n}\n\n/**\n * Drain-to-quiescence dispatcher with optional shared budget.\n *\n * Re-entrant `dispatch(msg)` from inside the handler — including from\n * another `DispatcherHandle.dispatch(...)` sharing the same Lease —\n * joins the current drain rather than recursing. This is the property\n * that lets cooperating dispatchers compose: an A→B→A oscillation is\n * one cascade in one lease, not a stack overflow.\n */\nexport function createDispatcher<Msg>(\n  handler: (msg: Msg, dispatch: (msg: Msg) => void) => void,\n  options?: DispatcherOptions,\n): DispatcherHandle<Msg> {\n  const lease = options?.lease ?? createLease()\n  const label = options?.label ?? \"dispatcher\"\n  const pending: Msg[] = []\n  let isDispatching = false\n\n  function dispatch(msg: Msg): void {\n    pending.push(msg)\n    if (isDispatching) return\n\n    isDispatching = true\n    const owns = lease.depth === 0\n    if (owns) {\n      // Capture the frame that opened this drain. Subscribers re-entering\n      // mid-cascade don't overwrite it — the owning drain resets it on\n      // exit. The frame names the *entry point* into the dispatch system\n      // (userland or transport), not necessarily user code.\n      lease.originStack = new Error(\"cascade origin\").stack\n    }\n    lease.depth += 1\n    try {\n      while (pending.length > 0) {\n        const next = pending.shift()!\n        lease.iterations += 1\n        const type =\n          typeof next === \"object\" && next !== null && \"type\" in next\n            ? String((next as { type: unknown }).type)\n            : \"<untyped>\"\n        recordDispatch(lease, label, type)\n        if (lease.iterations > lease.budget) {\n          throw new BudgetExhaustedError(label, lease)\n        }\n        handler(next, dispatch)\n      }\n    } finally {\n      lease.depth -= 1\n      if (owns) {\n        lease.iterations = 0\n        lease.history.length = 0\n        lease.counts.clear()\n        lease.originStack = undefined\n      }\n      isDispatching = false\n    }\n  }\n\n  return {\n    dispatch,\n    get queueDepth(): number {\n      return pending.length\n    },\n  }\n}\n","/** Dispatch a message into a running program. */\nexport type Dispatch<Msg> = (msg: Msg) => void\n\n/** An effect is a continuation that may dispatch messages. */\nexport type Effect<Msg> = (dispatch: Dispatch<Msg>) => void\n\n/**\n * A Mealy machine — pure state transitions with effect outputs.\n *\n * `Fx` defaults to `Effect<Msg>` (closure effects) but can be any\n * data type for programs with custom effect executors.\n *\n * - `init`: initial state and zero or more effects to execute at startup.\n * - `update`: pure transition — given a message and the current state,\n *   return the new state and zero or more effects.\n * - `done`: optional teardown hook, called with the final state when\n *   the runtime is disposed.\n */\nexport type Program<Msg, Model, Fx = Effect<Msg>> = {\n  init: [Model, ...Fx[]]\n  update(msg: Msg, model: Model): [Model, ...Fx[]]\n  done?(model: Model): void\n}\n\n/** Dispose a running program — stops message processing and calls `done`. */\nexport type Disposer = () => void\n\n/**\n * Run a program whose effects are `Effect<Msg>` closures.\n *\n * The runtime:\n * 1. Extracts `[model, ...effects]` from `program.init`.\n * 2. Executes each initial effect with `dispatch`.\n * 3. Calls `view(model, dispatch)` if provided.\n * 4. On `dispatch(msg)`: calls `update(msg, state)`, updates state,\n *    executes effects, calls `view`.\n * 5. Returns a `Disposer` that stops dispatch and calls `program.done`.\n *\n * Effects are executed synchronously in order. An effect may call\n * `dispatch` re-entrantly — the runtime processes re-entrant messages\n * after the current dispatch cycle completes (queue-based).\n */\nexport function runtime<Msg, Model>(\n  program: Program<Msg, Model>,\n  view?: (model: Model, dispatch: Dispatch<Msg>) => void,\n): Disposer {\n  let state: Model\n  let isRunning = true\n  const pending: Msg[] = []\n  let isDispatching = false\n\n  function dispatch(msg: Msg): void {\n    if (!isRunning) return\n\n    pending.push(msg)\n    if (isDispatching) return\n\n    isDispatching = true\n    try {\n      while (pending.length > 0) {\n        const next = pending.shift()!\n        const [newModel, ...effects] = program.update(next, state)\n        state = newModel\n        for (const effect of effects) {\n          effect(dispatch)\n        }\n        if (view) view(state, dispatch)\n      }\n    } finally {\n      isDispatching = false\n    }\n  }\n\n  // Initialize\n  const [initialModel, ...initialEffects] = program.init\n  state = initialModel\n  for (const effect of initialEffects) {\n    effect(dispatch)\n  }\n  if (view) view(state, dispatch)\n\n  // Return disposer\n  return () => {\n    if (!isRunning) return\n    isRunning = false\n    program.done?.(state)\n  }\n}\n","// observable — data-effect runtime with state observation.\n//\n// createObservableProgram() is the data-effect counterpart to runtime().\n// Where runtime() executes closure effects (Effect<Msg>), this function\n// accepts a custom executor for data effects (Fx). It also provides\n// state observation: subscribeToTransitions, waitForState, waitForStatus.\n//\n// This subsumes ClientStateMachine's observation API and the peer program's\n// hand-rolled dispatch loop. Transition delivery is synchronous — the\n// listener fires after each update. The microtask-batched delivery from\n// ClientStateMachine is unnecessary complexity that no consumer depends on.\n\nimport { createDispatcher, type Lease } from \"./dispatcher.js\"\nimport type { Dispatch, Program } from \"./machine.js\"\n\n// ---------------------------------------------------------------------------\n// Ambient declarations for timer APIs (not in lib: [\"ESNext\"])\n// ---------------------------------------------------------------------------\n\ndeclare function setTimeout(callback: () => void, ms: number): unknown\ndeclare function clearTimeout(id: unknown): void\n\n// ---------------------------------------------------------------------------\n// Observation types\n// ---------------------------------------------------------------------------\n\n/**\n * A state transition event — from one model to another.\n *\n * Generic over the model type. This is the machine-level primitive;\n * transport packages re-export or alias it for their specific state types.\n */\nexport type StateTransition<S> = {\n  from: S\n  to: S\n  timestamp: number\n}\n\n/**\n * Listener for state transitions.\n */\nexport type TransitionListener<S> = (transition: StateTransition<S>) => void\n\n// ---------------------------------------------------------------------------\n// ObservableHandle\n// ---------------------------------------------------------------------------\n\n/**\n * Handle for a running observable program.\n *\n * Provides dispatch, state access, transition observation, and disposal.\n * The observation API (`subscribeToTransitions`, `waitForState`, `waitForStatus`)\n * matches the surface of the former `ClientStateMachine<S>`.\n */\nexport interface ObservableHandle<Msg, Model> {\n  /** Dispatch a message into the program. */\n  dispatch: Dispatch<Msg>\n\n  /** Get the current model synchronously. */\n  getState(): Model\n\n  /**\n   * Subscribe to state transitions.\n   *\n   * Transitions are delivered synchronously after each update.\n   * Returns an unsubscribe function.\n   */\n  subscribeToTransitions(listener: TransitionListener<Model>): () => void\n\n  /**\n   * Wait for a specific state.\n   *\n   * Resolves immediately if the current state matches the predicate.\n   * Otherwise waits for a transition that matches.\n   */\n  waitForState(\n    predicate: (state: Model) => boolean,\n    options?: { timeoutMs?: number },\n  ): Promise<Model>\n\n  /**\n   * Wait for a specific status string on a model with a `status` discriminant.\n   *\n   * Convenience wrapper around `waitForState()`.\n   */\n  waitForStatus<S extends { status: string }>(\n    this: ObservableHandle<Msg, S>,\n    status: S[\"status\"],\n    options?: { timeoutMs?: number },\n  ): Promise<S>\n\n  /**\n   * Dispose the program — stops dispatch and calls `program.done`.\n   */\n  dispose(): void\n}\n\n// ---------------------------------------------------------------------------\n// createObservableProgram\n// ---------------------------------------------------------------------------\n\n/**\n * Run a program with data effects and state observation.\n *\n * Like `runtime()`, but instead of executing closure effects directly,\n * it delegates to a custom `executor` for each data effect. This enables\n * programs whose effects are inspectable data types (not opaque closures).\n *\n * The runtime:\n * 1. Extracts `[model, ...effects]` from `program.init`.\n * 2. Executes each initial effect via `executor(effect, dispatch)`.\n * 3. On `dispatch(msg)`: calls `update(msg, state)`, updates state,\n *    notifies transition listeners, executes effects.\n * 4. Re-entrant dispatch (effect calls dispatch) is queued and processed\n *    after the current dispatch cycle completes.\n * 5. `dispose()` stops dispatch and calls `program.done`.\n *\n * @param program - The program algebra: init, update, done.\n * @param executor - Interprets data effects as I/O.\n * @returns An observable handle for the running program.\n */\nexport function createObservableProgram<Msg, Model, Fx>(\n  program: Program<Msg, Model, Fx>,\n  executor: (effect: Fx, dispatch: Dispatch<Msg>) => void,\n  options?: { lease?: Lease; label?: string },\n): ObservableHandle<Msg, Model> {\n  let state: Model\n  let isRunning = true\n  const listeners = new Set<TransitionListener<Model>>()\n\n  // --------------------------------------------------------------------------\n  // Transition notification\n  // --------------------------------------------------------------------------\n\n  function notifyTransition(from: Model, to: Model): void {\n    if (from === to) return\n\n    const transition: StateTransition<Model> = {\n      from,\n      to,\n      timestamp: Date.now(),\n    }\n\n    for (const listener of listeners) {\n      try {\n        listener(transition)\n      } catch {\n        // Swallow listener errors — observers must not break dispatch.\n      }\n    }\n  }\n\n  // --------------------------------------------------------------------------\n  // Dispatch\n  // --------------------------------------------------------------------------\n\n  const handle = createDispatcher<Msg>(\n    (msg, redispatch) => {\n      if (!isRunning) return\n      const prev = state\n      const [newModel, ...effects] = program.update(msg, state)\n      state = newModel\n      notifyTransition(prev, state)\n      for (const effect of effects) {\n        executor(effect, redispatch)\n      }\n    },\n    { lease: options?.lease, label: options?.label ?? \"observable\" },\n  )\n\n  function dispatch(msg: Msg): void {\n    if (!isRunning) return\n    handle.dispatch(msg)\n  }\n\n  // --------------------------------------------------------------------------\n  // Observation\n  // --------------------------------------------------------------------------\n\n  function getState(): Model {\n    return state\n  }\n\n  function subscribeToTransitions(\n    listener: TransitionListener<Model>,\n  ): () => void {\n    listeners.add(listener)\n    return () => {\n      listeners.delete(listener)\n    }\n  }\n\n  function waitForState(\n    predicate: (state: Model) => boolean,\n    options?: { timeoutMs?: number },\n  ): Promise<Model> {\n    // Resolve immediately if already matching\n    if (predicate(state)) {\n      return Promise.resolve(state)\n    }\n\n    return new Promise((resolve, reject) => {\n      let timeoutId: unknown\n\n      const unsubscribe = subscribeToTransitions(transition => {\n        if (predicate(transition.to)) {\n          cleanup()\n          resolve(transition.to)\n        }\n      })\n\n      const cleanup = () => {\n        unsubscribe()\n        if (timeoutId !== undefined) {\n          clearTimeout(timeoutId)\n        }\n      }\n\n      if (options?.timeoutMs !== undefined) {\n        timeoutId = setTimeout(() => {\n          cleanup()\n          reject(\n            new Error(`Timeout waiting for state after ${options.timeoutMs}ms`),\n          )\n        }, options.timeoutMs)\n      }\n    })\n  }\n\n  function waitForStatus<S extends { status: string }>(\n    this: ObservableHandle<Msg, S>,\n    status: S[\"status\"],\n    options?: { timeoutMs?: number },\n  ): Promise<S> {\n    return this.waitForState((s: S) => s.status === status, options)\n  }\n\n  function dispose(): void {\n    if (!isRunning) return\n    isRunning = false\n    program.done?.(state)\n  }\n\n  // --------------------------------------------------------------------------\n  // Initialize\n  // --------------------------------------------------------------------------\n\n  const [initialModel, ...initialEffects] = program.init\n  state = initialModel\n  for (const effect of initialEffects) {\n    executor(effect, dispatch)\n  }\n\n  // --------------------------------------------------------------------------\n  // Return handle\n  // --------------------------------------------------------------------------\n\n  return {\n    dispatch,\n    getState,\n    subscribeToTransitions,\n    waitForState,\n    waitForStatus,\n    dispose,\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kyneta/machine",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "Universal Mealy machine algebra — Program, Effect, Dispatch, runtime",
   "author": "Duane Johnson",
   "license": "MIT",

package/src/__tests__/dispatcher.test.ts

@@ -5,6 +5,9 @@ import {
   BudgetExhaustedError,
   createDispatcher,
   createLease,
+  formatHistogram,
+  formatOrigin,
+  formatRecent,
   type Lease,
 } from "../dispatcher.js"
 
@@ -141,3 +144,154 @@ describe("createDispatcher", () => {
     expect(handle.queueDepth).toBe(0)
   })
 })
+
+// ---------------------------------------------------------------------------
+// Lease diagnostic state — origin frame and message-type histogram
+// ---------------------------------------------------------------------------
+
+describe("Lease diagnostic state", () => {
+  it("originStack is cleared when the owning drain exits cleanly", () => {
+    // Guards against a refactor of the cleanup block forgetting to
+    // clear originStack — stale stacks would bleed between cascades.
+    const lease = createLease()
+    const handle = createDispatcher<{ type: "n" }>(() => {}, { lease })
+    handle.dispatch({ type: "n" })
+    expect(lease.originStack).toBeUndefined()
+  })
+
+  it("originStack is captured once per cascade — re-entrant dispatches see the same frame", () => {
+    const lease = createLease()
+    const seen: (string | undefined)[] = []
+    const handle = createDispatcher<{ type: "n"; depth: number }>(
+      (msg, dispatch) => {
+        seen.push(lease.originStack)
+        if (msg.depth < 3) dispatch({ type: "n", depth: msg.depth + 1 })
+      },
+      { lease },
+    )
+    handle.dispatch({ type: "n", depth: 0 })
+    expect(new Set(seen).size).toBe(1)
+    expect(seen[0]).toBeDefined()
+  })
+
+  it("counts reset on owning drain exit so they don't accumulate across cascades", () => {
+    const lease = createLease()
+    const handle = createDispatcher<{ type: "n" }>(() => {}, {
+      lease,
+      label: "x",
+    })
+
+    handle.dispatch({ type: "n" })
+    expect(lease.counts.size).toBe(0)
+
+    handle.dispatch({ type: "n" })
+    expect(lease.counts.size).toBe(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// BudgetExhaustedError — diagnostic payload survives the cleanup unwind
+// ---------------------------------------------------------------------------
+
+describe("BudgetExhaustedError diagnostic payload", () => {
+  it("snapshots origin, counts, and history into the message and into err.lease", () => {
+    // One trip exercises the whole diagnostic pipeline: the entry-point
+    // stack is captured, the histogram accrues, the snapshot survives
+    // the owning drain's finally-block reset, and the message renders
+    // all three sections. Merging these assertions into one test keeps
+    // the cascade-trip cost paid once.
+    const lease = createLease({ budget: 5, historyCapacity: 4 })
+    const handle = createDispatcher<{ type: "tick" }>(
+      (msg, dispatch) => dispatch(msg),
+      { lease, label: "osc" },
+    )
+
+    let caught: unknown
+    try {
+      handle.dispatch({ type: "tick" })
+    } catch (err) {
+      caught = err
+    }
+    const err = caught as BudgetExhaustedError
+    expect(err).toBeInstanceOf(BudgetExhaustedError)
+
+    // Origin: snapshot present and names the test's call site.
+    expect(err.lease.originStack).toBeDefined()
+    expect(err.lease.originStack).toContain("dispatcher.test")
+
+    // Counts: Map snapshot is independent of the live lease (Map doesn't
+    // spread, so the snapshot must explicitly clone).
+    expect(err.lease.counts.get("osc:tick")).toBeGreaterThan(0)
+
+    // Message: contains the three diagnostic section headers and the
+    // dominant message type.
+    expect(err.message).toContain("cascade entered from:")
+    expect(err.message).toContain("top message types:")
+    expect(err.message).toContain("recent (")
+    expect(err.message).toContain("osc:tick")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Error-message formatters — pure, table-testable projections
+// ---------------------------------------------------------------------------
+
+describe("formatHistogram", () => {
+  it("returns the empty string when there is nothing to render", () => {
+    expect(formatHistogram(new Map(), 100, 5)).toBe("")
+    expect(formatHistogram(new Map([["a", 1]]), 0, 5)).toBe("")
+  })
+
+  it("sorts entries descending and truncates to top-N", () => {
+    const counts = new Map([
+      ["a", 50],
+      ["b", 30],
+      ["c", 20],
+    ])
+    const out = formatHistogram(counts, 100, 2)
+    const lines = out.trim().split("\n")
+    expect(lines[0]).toBe("top message types:")
+    expect(lines[1]).toMatch(/a\s+50\s+\(50\.0%\)/)
+    expect(lines[2]).toMatch(/b\s+30\s+\(30\.0%\)/)
+    expect(out).not.toContain("c ")
+  })
+
+  it("pads keys to the widest entry so the count column aligns", () => {
+    // Existing labels can reach 46+ chars (e.g.
+    // `synchronizer:sync:sync/synthetic-doc-removed-all`); a fixed pad
+    // width would mis-align the count column.
+    const counts = new Map([
+      ["short", 5],
+      ["a-much-longer-label-here", 3],
+    ])
+    const out = formatHistogram(counts, 10, 5)
+    const lines = out.trim().split("\n").slice(1)
+    const colOfFive = lines[0]!.indexOf("5  (")
+    const colOfThree = lines[1]!.indexOf("3  (")
+    expect(colOfFive).toBe(colOfThree)
+  })
+})
+
+describe("formatOrigin", () => {
+  it("drops the synthetic 'Error: cascade origin' header and indents the frames", () => {
+    // The header is the label of the Error we constructed solely to
+    // capture a stack; it's not a useful frame and would be misleading
+    // at the top of the rendered block.
+    const stack = "Error: cascade origin\n    at testFn (file.ts:42:3)"
+    const out = formatOrigin(stack)
+    expect(out).toContain("cascade entered from:")
+    expect(out).toContain("at testFn (file.ts:42:3)")
+    expect(out).not.toContain("Error: cascade origin")
+  })
+})
+
+describe("formatRecent", () => {
+  it("joins history entries as 'label:type' with the count in the header", () => {
+    const out = formatRecent([
+      { label: "a", type: "x" },
+      { label: "b", type: "y" },
+    ])
+    expect(out).toContain("recent (2):")
+    expect(out).toContain("a:x, b:y")
+  })
+})

package/src/dispatcher.ts

@@ -10,7 +10,16 @@
  *
  * A Lease is a plain mutable record. Dispatchers mutate its fields
  * directly; no methods. When `depth` goes 0→1 a dispatcher becomes the
- * owner and resets `iterations`/`history` on its eventual 1→0 exit.
+ * owner and resets `iterations`/`history`/`counts`/`originStack` on its
+ * eventual 1→0 exit.
+ *
+ * Diagnostic instrumentation (history, counts, originStack) supports
+ * `BudgetExhaustedError`'s message:
+ * - `history` — bounded ring buffer of recent `{label, type}` events.
+ * - `counts` — cumulative `${label}:${type}` → count over the whole drain.
+ * - `originStack` — captured at the cascade's entry point (depth 0→1).
+ *   Names the boundary where the dispatch system was re-entered from
+ *   outside (userland for client-side flows, transport for server-side).
  */
 export type Lease = {
   depth: number
@@ -18,6 +27,8 @@ export type Lease = {
   readonly budget: number
   history: { label: string; type: string }[]
   readonly historyCapacity: number
+  counts: Map<string, number>
+  originStack: string | undefined
 }
 
 export type LeaseOptions = {
@@ -32,21 +43,100 @@ export function createLease(options?: LeaseOptions): Lease {
     budget: options?.budget ?? 100_000,
     history: [],
     historyCapacity: options?.historyCapacity ?? 32,
+    counts: new Map(),
+    originStack: undefined,
   }
 }
 
+// ---------------------------------------------------------------------------
+// Diagnostic recording — single mutation site for history + counts
+// ---------------------------------------------------------------------------
+
+/**
+ * Single mutation site for the lease's diagnostic projections. Future
+ * additions (e.g. subscriber-call site) land here so `history` and
+ * `counts` can't drift out of sync with each other.
+ */
+function recordDispatch(lease: Lease, label: string, type: string): void {
+  if (lease.history.length >= lease.historyCapacity) lease.history.shift()
+  lease.history.push({ label, type })
+  const key = `${label}:${type}`
+  lease.counts.set(key, (lease.counts.get(key) ?? 0) + 1)
+}
+
+// ---------------------------------------------------------------------------
+// Pure formatters for BudgetExhaustedError's message sections
+// ---------------------------------------------------------------------------
+
+/**
+ * Pure formatter for the cascade-origin section of `BudgetExhaustedError`'s
+ * message. Strips the synthetic `Error: cascade origin` header from the
+ * captured stack — it's the label we used to *construct* the Error solely
+ * to grab a stack, not a meaningful frame.
+ */
+export function formatOrigin(originStack: string | undefined): string {
+  if (!originStack) return ""
+  const lines = originStack.split("\n")
+  const start = lines[0]?.startsWith("Error") ? 1 : 0
+  const frames = lines.slice(start).map(l => `    ${l.trim()}`)
+  return `  cascade entered from:\n${frames.join("\n")}\n`
+}
+
+/**
+ * Pure formatter for the histogram section. Width is computed per
+ * render because cooperating dispatchers produce labels as long as
+ * `synchronizer:sync:sync/synthetic-doc-removed-all` (46 chars) — a
+ * fixed `padEnd` width would mis-align the count column.
+ */
+export function formatHistogram(
+  counts: ReadonlyMap<string, number>,
+  total: number,
+  topN: number,
+): string {
+  if (counts.size === 0 || total <= 0) return ""
+  const entries = [...counts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, topN)
+  const maxKeyLen = Math.max(...entries.map(([k]) => k.length))
+  const rows = entries.map(([key, n]) => {
+    const pct = ((n / total) * 100).toFixed(1)
+    return `    ${key.padEnd(maxKeyLen)}  ${String(n).padStart(7)}  (${pct.padStart(4)}%)`
+  })
+  return `  top message types:\n${rows.join("\n")}\n`
+}
+
+export function formatRecent(
+  history: readonly { label: string; type: string }[],
+): string {
+  if (history.length === 0) return ""
+  const tail = history.map(h => `${h.label}:${h.type}`).join(", ")
+  return `  recent (${history.length}): ${tail}\n`
+}
+
+// ---------------------------------------------------------------------------
+// BudgetExhaustedError
+// ---------------------------------------------------------------------------
+
 export class BudgetExhaustedError extends Error {
   readonly lease: Lease
   readonly label: string
   constructor(label: string, lease: Lease) {
-    super(
-      `[dispatcher:${label}] iteration budget exhausted (${lease.iterations} > ${lease.budget}); ` +
-        `recent: ${lease.history.map(h => `${h.label}:${h.type}`).join(", ")}`,
-    )
+    const header = `[dispatcher:${label}] iteration budget exhausted (${lease.iterations} > ${lease.budget})`
+    const body =
+      formatOrigin(lease.originStack) +
+      formatHistogram(lease.counts, lease.iterations, 5) +
+      formatRecent(lease.history)
+    super(body.length > 0 ? `${header}\n${body}` : header)
     this.name = "BudgetExhaustedError"
-    // Snapshot the lease so the history survives the owning dispatcher's
-    // finally-block reset that runs as the exception unwinds.
-    this.lease = { ...lease, history: [...lease.history] }
+    // Snapshot the lease so the diagnostic state survives the owning
+    // dispatcher's finally-block reset that runs as the exception unwinds.
+    // `counts` is a Map and must be cloned explicitly — spread does not
+    // copy Map contents.
+    this.lease = {
+      ...lease,
+      history: [...lease.history],
+      counts: new Map(lease.counts),
+    }
     this.label = label
   }
 }
@@ -85,6 +175,13 @@ export function createDispatcher<Msg>(
 
     isDispatching = true
     const owns = lease.depth === 0
+    if (owns) {
+      // Capture the frame that opened this drain. Subscribers re-entering
+      // mid-cascade don't overwrite it — the owning drain resets it on
+      // exit. The frame names the *entry point* into the dispatch system
+      // (userland or transport), not necessarily user code.
+      lease.originStack = new Error("cascade origin").stack
+    }
     lease.depth += 1
     try {
       while (pending.length > 0) {
@@ -94,10 +191,7 @@ export function createDispatcher<Msg>(
           typeof next === "object" && next !== null && "type" in next
             ? String((next as { type: unknown }).type)
             : "<untyped>"
-        if (lease.history.length >= lease.historyCapacity) {
-          lease.history.shift()
-        }
-        lease.history.push({ label, type })
+        recordDispatch(lease, label, type)
         if (lease.iterations > lease.budget) {
           throw new BudgetExhaustedError(label, lease)
         }
@@ -108,6 +202,8 @@ export function createDispatcher<Msg>(
       if (owns) {
         lease.iterations = 0
         lease.history.length = 0
+        lease.counts.clear()
+        lease.originStack = undefined
       }
       isDispatching = false
     }