@kyneta/machine 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Duane Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,265 @@
+# @kyneta/machine
+
+Universal Mealy machine algebra — pure state transitions with effect outputs.
+
+## Overview
+
+`@kyneta/machine` provides `Program`, a minimal algebraic type for state machines: an initial state, a pure update function, and optionally a teardown hook. Each transition returns a new state plus zero or more effects. The `runtime()` function interprets programs whose effects are closures.
+
+This is the same architecture as [raj](https://github.com/andrejewski/raj) and the Elm Architecture, distilled to its core algebra. The key difference: `Program` is parameterized over its effect type `Fx`, so the same shape works for both closure-based effects (interpreted by `runtime()`) and data effects (interpreted by a custom executor).
+
+## Install
+
+```/dev/null/shell.sh#L1
+pnpm add @kyneta/machine
+```
+
+## Quick Start
+
+A counter that increments every second and stops at 5:
+
+```/dev/null/counter.ts#L1-25
+import { type Program, runtime } from "@kyneta/machine"
+
+type Msg = "tick"
+type Model = { count: number }
+
+const tick: Program<Msg, Model> = {
+  init: [
+    { count: 0 },
+    (dispatch) => {
+      const id = setInterval(() => dispatch("tick"), 1000)
+      // effect is fire-and-forget; cleanup goes in `done`
+      ;(globalThis as any).__intervalId = id
+    },
+  ],
+  update(_msg, model) {
+    return [{ count: model.count + 1 }]
+  },
+  done() {
+    clearInterval((globalThis as any).__intervalId)
+  },
+}
+
+const dispose = runtime(tick, (model) => {
+  console.log(`count: ${model.count}`)
+  if (model.count >= 5) dispose()
+})
+```
+
+## Data Effects
+
+When `Fx` is a data type instead of a closure, `runtime()` no longer applies — you write a custom executor that pattern-matches on the effect values. This is the free monad interpreter pattern.
+
+```/dev/null/data-effects.ts#L1-30
+import type { Program } from "@kyneta/machine"
+
+// Effects as data
+type Fx =
+  | { type: "http"; url: string }
+  | { type: "log"; message: string }
+
+type Msg = { type: "fetched"; data: string }
+type Model = { status: string }
+
+const app: Program<Msg, Model, Fx> = {
+  init: [{ status: "loading" }, { type: "http", url: "/api" }],
+  update(msg, _model) {
+    return [{ status: msg.data }, { type: "log", message: "done" }]
+  },
+}
+
+// Custom executor — you control how effects are interpreted
+function run(program: Program<Msg, Model, Fx>) {
+  let [state, ...effects] = program.init
+  function dispatch(msg: Msg) {
+    const [next, ...fxs] = program.update(msg, state)
+    state = next
+    fxs.forEach(execute)
+  }
+  function execute(fx: Fx) {
+    if (fx.type === "http") fetch(fx.url).then((r) => r.text()).then((data) => dispatch({ type: "fetched", data }))
+    if (fx.type === "log") console.log(fx.message)
+  }
+  effects.forEach(execute)
+}
+```
+
+The Synchronizer in `@kyneta/exchange` uses exactly this pattern: `Program<SynchronizerMessage, SynchronizerModel, Command>` with a batched interpreter that coalesces network sends.
+
+## API Reference
+
+### `Program<Msg, Model, Fx = Effect<Msg>>`
+
+```/dev/null/types.ts#L1-5
+type Program<Msg, Model, Fx = Effect<Msg>> = {
+  init: [Model, ...Fx[]]
+  update(msg: Msg, model: Model): [Model, ...Fx[]]
+  done?(model: Model): void
+}
+```
+
+The universal Mealy machine algebra. `init` provides the initial state and startup effects. `update` is a pure transition function. `done` is an optional teardown hook called when the runtime is disposed.
+
+### `Effect<Msg>`
+
+```/dev/null/types.ts#L1
+type Effect<Msg> = (dispatch: Dispatch<Msg>) => void
+```
+
+A continuation that may asynchronously dispatch messages back into the program. This is the default `Fx` type — opaque closures executed by `runtime()`.
+
+### `Dispatch<Msg>`
+
+```/dev/null/types.ts#L1
+type Dispatch<Msg> = (msg: Msg) => void
+```
+
+### `Disposer`
+
+```/dev/null/types.ts#L1
+type Disposer = () => void
+```
+
+Returned by `runtime()`. Calling it stops message processing and invokes `program.done`.
+
+### `StateTransition<S>`
+
+```/dev/null/types.ts#L1-5
+type StateTransition<S> = {
+  from: S
+  to: S
+  timestamp: number
+}
+```
+
+A state transition event emitted after each `update` call. `from` and `to` are the model before and after the transition. `timestamp` is `Date.now()` at the moment of transition. Transitions where `from === to` (referential identity) are suppressed.
+
+### `TransitionListener<S>`
+
+```/dev/null/types.ts#L1
+type TransitionListener<S> = (transition: StateTransition<S>) => void
+```
+
+Callback type for `subscribeToTransitions`. Listeners fire synchronously after each state transition. Listener exceptions are swallowed — observers must not break dispatch.
+
+### `ObservableHandle<Msg, Model>`
+
+```/dev/null/types.ts#L1-8
+interface ObservableHandle<Msg, Model> {
+  dispatch: Dispatch<Msg>
+  getState(): Model
+  subscribeToTransitions(listener: TransitionListener<Model>): () => void
+  waitForState(predicate: (state: Model) => boolean, options?: { timeoutMs?: number }): Promise<Model>
+  waitForStatus(status: string, options?: { timeoutMs?: number }): Promise<Model>
+  dispose(): void
+}
+```
+
+Handle returned by `createObservableProgram`. Methods:
+
+- **`dispatch(msg)`** — send a message into the program. Re-entrant dispatches (effects calling dispatch) are queued and processed after the current cycle.
+- **`getState()`** — synchronous access to the current model.
+- **`subscribeToTransitions(listener)`** — register a `TransitionListener`. Returns an unsubscribe function.
+- **`waitForState(predicate, options?)`** — returns a `Promise` that resolves with the first model matching `predicate`. Resolves immediately if the current state matches. Rejects on timeout if `timeoutMs` is set.
+- **`waitForStatus(status, options?)`** — convenience wrapper for models with a `status` discriminant. Equivalent to `waitForState(s => s.status === status)`.
+- **`dispose()`** — stops dispatch and calls `program.done`.
+
+### `runtime(program, view?)`
+
+```/dev/null/types.ts#L1-4
+function runtime<Msg, Model>(
+  program: Program<Msg, Model>,
+  view?: (model: Model, dispatch: Dispatch<Msg>) => void,
+): Disposer
+```
+
+Interprets a program whose effects are `Effect<Msg>` closures. Dispatch is synchronous; re-entrant dispatches are queued and processed in order. Effects execute immediately after each state transition. The optional `view` callback fires after every transition (including init).
+
+### `createObservableProgram(program, executor)`
+
+```/dev/null/types.ts#L1-4
+function createObservableProgram<Msg, Model, Fx>(
+  program: Program<Msg, Model, Fx>,
+  executor: (effect: Fx, dispatch: Dispatch<Msg>) => void,
+): ObservableHandle<Msg, Model>
+```
+
+The data-effect counterpart to `runtime()`. Where `runtime()` executes closure effects (`Effect<Msg>`) directly, `createObservableProgram` delegates each effect to a custom `executor` — enabling programs whose effects are inspectable data types rather than opaque closures. It also provides state observation via `subscribeToTransitions`, `waitForState`, and `waitForStatus`.
+
+The runtime lifecycle:
+1. Extracts `[model, ...effects]` from `program.init`.
+2. Executes each initial effect via `executor(effect, dispatch)`.
+3. On `dispatch(msg)`: calls `update(msg, state)`, updates state, notifies transition listeners, executes effects.
+4. Re-entrant dispatch is queued and processed after the current cycle.
+5. `dispose()` stops dispatch and calls `program.done`.
+
+```/dev/null/observable-example.ts#L1-42
+import { type Program, createObservableProgram } from "@kyneta/machine"
+
+// Effects as data
+type Fx =
+  | { type: "http"; url: string }
+  | { type: "log"; message: string }
+
+type Msg = { type: "loaded"; data: string }
+type Model = { status: "loading" | "ready"; data?: string }
+
+const app: Program<Msg, Model, Fx> = {
+  init: [{ status: "loading" }, { type: "http", url: "/api" }],
+  update(msg, _model) {
+    return [
+      { status: "ready", data: msg.data },
+      { type: "log", message: "done" },
+    ]
+  },
+}
+
+// Executor interprets data effects as I/O
+function executor(fx: Fx, dispatch: (msg: Msg) => void) {
+  switch (fx.type) {
+    case "http":
+      fetch(fx.url)
+        .then((r) => r.text())
+        .then((data) => dispatch({ type: "loaded", data }))
+      break
+    case "log":
+      console.log(fx.message)
+      break
+  }
+}
+
+const handle = createObservableProgram(app, executor)
+
+// Observe transitions
+const unsub = handle.subscribeToTransitions(({ from, to }) => {
+  console.log(`${from.status} → ${to.status}`)
+})
+
+// Wait for a specific status
+await handle.waitForStatus("ready", { timeoutMs: 5000 })
+console.log(handle.getState()) // { status: "ready", data: "..." }
+handle.dispose()
+```
+
+**`runtime()` vs `createObservableProgram()`** — `runtime()` is for closure effects (`Effect<Msg>`) where effects are opaque fire-and-forget continuations. `createObservableProgram()` is for data effects (`Fx`) where effects are inspectable values interpreted by a custom executor. Both share the same `Program` algebra; only the effect interpretation differs. `createObservableProgram` additionally provides state observation, making it the right choice when external code needs to react to state changes.
+
+## Design Decisions
+
+**View is external to Program.** The `Program` type is pure algebra — it knows nothing about rendering. View is an optional callback passed to `runtime()`, keeping the state machine testable without mocks.
+
+**Variadic effects.** Transitions return `[Model, ...Fx[]]` rather than `[Model, Fx[]]`. Zero effects is `[model]`, one is `[model, fx]`, many is `[model, fx1, fx2]`. This eliminates empty-array noise at call sites.
+
+**Fx parameterization.** The third type parameter `Fx` defaults to `Effect<Msg>` for the common closure case, but accepts any type. This single generic makes the same `Program` shape work for both `runtime()`-interpreted programs and programs with data effects that use a custom executor — no wrapper types, no separate interfaces.
+
+## Relationship to the Synchronizer
+
+The Synchronizer in `@kyneta/exchange` is a `Program<SynchronizerMessage, SynchronizerModel, Command>` where `Command` is a discriminated union of data effects (send message, build offer, apply snapshot, etc.). Its interpreter batches commands and executes them against live channels and substrates. The pure `update` function is tested exhaustively without any I/O.
+
+## Peer Dependencies
+
+None.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+/** Dispatch a message into a running program. */
+type Dispatch<Msg> = (msg: Msg) => void;
+/** An effect is a continuation that may dispatch messages. */
+type Effect<Msg> = (dispatch: Dispatch<Msg>) => void;
+/**
+ * A Mealy machine — pure state transitions with effect outputs.
+ *
+ * `Fx` defaults to `Effect<Msg>` (closure effects) but can be any
+ * data type for programs with custom effect executors.
+ *
+ * - `init`: initial state and zero or more effects to execute at startup.
+ * - `update`: pure transition — given a message and the current state,
+ *   return the new state and zero or more effects.
+ * - `done`: optional teardown hook, called with the final state when
+ *   the runtime is disposed.
+ */
+type Program<Msg, Model, Fx = Effect<Msg>> = {
+    init: [Model, ...Fx[]];
+    update(msg: Msg, model: Model): [Model, ...Fx[]];
+    done?(model: Model): void;
+};
+/** Dispose a running program — stops message processing and calls `done`. */
+type Disposer = () => void;
+/**
+ * Run a program whose effects are `Effect<Msg>` closures.
+ *
+ * The runtime:
+ * 1. Extracts `[model, ...effects]` from `program.init`.
+ * 2. Executes each initial effect with `dispatch`.
+ * 3. Calls `view(model, dispatch)` if provided.
+ * 4. On `dispatch(msg)`: calls `update(msg, state)`, updates state,
+ *    executes effects, calls `view`.
+ * 5. Returns a `Disposer` that stops dispatch and calls `program.done`.
+ *
+ * Effects are executed synchronously in order. An effect may call
+ * `dispatch` re-entrantly — the runtime processes re-entrant messages
+ * after the current dispatch cycle completes (queue-based).
+ */
+declare function runtime<Msg, Model>(program: Program<Msg, Model>, view?: (model: Model, dispatch: Dispatch<Msg>) => void): Disposer;
+
+/**
+ * A state transition event — from one model to another.
+ *
+ * Generic over the model type. This is the machine-level primitive;
+ * transport packages re-export or alias it for their specific state types.
+ */
+type StateTransition<S> = {
+    from: S;
+    to: S;
+    timestamp: number;
+};
+/**
+ * Listener for state transitions.
+ */
+type TransitionListener<S> = (transition: StateTransition<S>) => void;
+/**
+ * Handle for a running observable program.
+ *
+ * Provides dispatch, state access, transition observation, and disposal.
+ * The observation API (`subscribeToTransitions`, `waitForState`, `waitForStatus`)
+ * matches the surface of the former `ClientStateMachine<S>`.
+ */
+interface ObservableHandle<Msg, Model> {
+    /** Dispatch a message into the program. */
+    dispatch: Dispatch<Msg>;
+    /** Get the current model synchronously. */
+    getState(): Model;
+    /**
+     * Subscribe to state transitions.
+     *
+     * Transitions are delivered synchronously after each update.
+     * Returns an unsubscribe function.
+     */
+    subscribeToTransitions(listener: TransitionListener<Model>): () => void;
+    /**
+     * Wait for a specific state.
+     *
+     * Resolves immediately if the current state matches the predicate.
+     * Otherwise waits for a transition that matches.
+     */
+    waitForState(predicate: (state: Model) => boolean, options?: {
+        timeoutMs?: number;
+    }): Promise<Model>;
+    /**
+     * Wait for a specific status string on a model with a `status` discriminant.
+     *
+     * Convenience wrapper around `waitForState()`.
+     */
+    waitForStatus<S extends {
+        status: string;
+    }>(this: ObservableHandle<Msg, S>, status: S["status"], options?: {
+        timeoutMs?: number;
+    }): Promise<S>;
+    /**
+     * Dispose the program — stops dispatch and calls `program.done`.
+     */
+    dispose(): void;
+}
+/**
+ * Run a program with data effects and state observation.
+ *
+ * Like `runtime()`, but instead of executing closure effects directly,
+ * it delegates to a custom `executor` for each data effect. This enables
+ * programs whose effects are inspectable data types (not opaque closures).
+ *
+ * The runtime:
+ * 1. Extracts `[model, ...effects]` from `program.init`.
+ * 2. Executes each initial effect via `executor(effect, dispatch)`.
+ * 3. On `dispatch(msg)`: calls `update(msg, state)`, updates state,
+ *    notifies transition listeners, executes effects.
+ * 4. Re-entrant dispatch (effect calls dispatch) is queued and processed
+ *    after the current dispatch cycle completes.
+ * 5. `dispose()` stops dispatch and calls `program.done`.
+ *
+ * @param program - The program algebra: init, update, done.
+ * @param executor - Interprets data effects as I/O.
+ * @returns An observable handle for the running program.
+ */
+declare function createObservableProgram<Msg, Model, Fx>(program: Program<Msg, Model, Fx>, executor: (effect: Fx, dispatch: Dispatch<Msg>) => void): ObservableHandle<Msg, Model>;
+
+export { type Dispatch, type Disposer, type Effect, type ObservableHandle, type Program, type StateTransition, type TransitionListener, createObservableProgram, runtime };

package/dist/index.js

@@ -0,0 +1,143 @@
+// src/machine.ts
+function runtime(program, view) {
+  let state;
+  let isRunning = true;
+  const pending = [];
+  let isDispatching = false;
+  function dispatch(msg) {
+    if (!isRunning) return;
+    pending.push(msg);
+    if (isDispatching) return;
+    isDispatching = true;
+    try {
+      while (pending.length > 0) {
+        const next = pending.shift();
+        const [newModel, ...effects] = program.update(next, state);
+        state = newModel;
+        for (const effect of effects) {
+          effect(dispatch);
+        }
+        if (view) view(state, dispatch);
+      }
+    } finally {
+      isDispatching = false;
+    }
+  }
+  const [initialModel, ...initialEffects] = program.init;
+  state = initialModel;
+  for (const effect of initialEffects) {
+    effect(dispatch);
+  }
+  if (view) view(state, dispatch);
+  return () => {
+    if (!isRunning) return;
+    isRunning = false;
+    program.done?.(state);
+  };
+}
+
+// src/observable.ts
+function createObservableProgram(program, executor) {
+  let state;
+  let isRunning = true;
+  const pending = [];
+  let isDispatching = false;
+  const listeners = /* @__PURE__ */ new Set();
+  function notifyTransition(from, to) {
+    if (from === to) return;
+    const transition = {
+      from,
+      to,
+      timestamp: Date.now()
+    };
+    for (const listener of listeners) {
+      try {
+        listener(transition);
+      } catch {
+      }
+    }
+  }
+  function dispatch(msg) {
+    if (!isRunning) return;
+    pending.push(msg);
+    if (isDispatching) return;
+    isDispatching = true;
+    try {
+      while (pending.length > 0) {
+        const next = pending.shift();
+        const prev = state;
+        const [newModel, ...effects] = program.update(next, state);
+        state = newModel;
+        notifyTransition(prev, state);
+        for (const effect of effects) {
+          executor(effect, dispatch);
+        }
+      }
+    } finally {
+      isDispatching = false;
+    }
+  }
+  function getState() {
+    return state;
+  }
+  function subscribeToTransitions(listener) {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+  function waitForState(predicate, options) {
+    if (predicate(state)) {
+      return Promise.resolve(state);
+    }
+    return new Promise((resolve, reject) => {
+      let timeoutId;
+      const unsubscribe = subscribeToTransitions((transition) => {
+        if (predicate(transition.to)) {
+          cleanup();
+          resolve(transition.to);
+        }
+      });
+      const cleanup = () => {
+        unsubscribe();
+        if (timeoutId !== void 0) {
+          clearTimeout(timeoutId);
+        }
+      };
+      if (options?.timeoutMs !== void 0) {
+        timeoutId = setTimeout(() => {
+          cleanup();
+          reject(
+            new Error(`Timeout waiting for state after ${options.timeoutMs}ms`)
+          );
+        }, options.timeoutMs);
+      }
+    });
+  }
+  function waitForStatus(status, options) {
+    return this.waitForState((s) => s.status === status, options);
+  }
+  function dispose() {
+    if (!isRunning) return;
+    isRunning = false;
+    program.done?.(state);
+  }
+  const [initialModel, ...initialEffects] = program.init;
+  state = initialModel;
+  for (const effect of initialEffects) {
+    executor(effect, dispatch);
+  }
+  return {
+    dispatch,
+    getState,
+    subscribeToTransitions,
+    waitForState,
+    waitForStatus,
+    dispose
+  };
+}
+export {
+  createObservableProgram,
+  runtime
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/machine.ts","../src/observable.ts"],"sourcesContent":["/** 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 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): ObservableHandle<Msg, Model> {\n  let state: Model\n  let isRunning = true\n  const pending: Msg[] = []\n  let isDispatching = false\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  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 prev = state\n        const [newModel, ...effects] = program.update(next, state)\n        state = newModel\n        notifyTransition(prev, state)\n        for (const effect of effects) {\n          executor(effect, dispatch)\n        }\n      }\n    } finally {\n      isDispatching = false\n    }\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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","names":[]}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@kyneta/machine",
+  "version": "1.3.0",
+  "description": "Universal Mealy machine algebra — Program, Effect, Dispatch, runtime",
+  "author": "Duane Johnson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/halecraft/kyneta",
+    "directory": "packages/machine"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./src": "./src/index.ts",
+    "./src/*": "./src/*"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^4.0.17"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "verify logic",
+    "verify": "verify"
+  }
+}