@statorjs/stator 1.0.0

package/src/server/logger.ts

@@ -0,0 +1,52 @@
+import { createRequire } from 'node:module'
+import pino, { type Logger } from 'pino'
+
+/**
+ * Framework logger. Pretty colored output in dev (auto-detected via
+ * NODE_ENV), JSON in production for log aggregators. Level controlled by
+ * LOG_LEVEL env (default 'info').
+ *
+ * Application code can use this module-level logger or call `child()` for
+ * scoped context. The framework uses scoped children for SSE events,
+ * fan-out, and HTTP request lines.
+ */
+/** pino-pretty is an optional nicety, not a framework dependency — apps add
+ *  it as a devDependency for colored dev output (the create-stator template
+ *  does). Without it, dev logs are plain JSON rather than a crash. */
+function hasPinoPretty(): boolean {
+  try {
+    createRequire(import.meta.url).resolve('pino-pretty')
+    return true
+  } catch {
+    return false
+  }
+}
+
+function buildLogger(): Logger {
+  const level = process.env.LOG_LEVEL ?? 'info'
+  const isProd = process.env.NODE_ENV === 'production'
+
+  if (isProd || !hasPinoPretty()) {
+    return pino({ level })
+  }
+
+  return pino({
+    level,
+    transport: {
+      target: 'pino-pretty',
+      options: {
+        colorize: true,
+        translateTime: 'HH:MM:ss.l',
+        ignore: 'pid,hostname',
+        singleLine: false,
+      },
+    },
+  })
+}
+
+export const logger: Logger = buildLogger()
+
+/** Child logger with a `scope` tag for filtering. */
+export function scopedLogger(scope: string): Logger {
+  return logger.child({ scope })
+}

package/src/server/machine-store.ts

@@ -0,0 +1,355 @@
+import { createActor, type EffectInvocation, type Snapshot } from '../engine/index.ts'
+import { type AppStore, InMemoryAppStore } from './app-store.ts'
+import type { AnyMachineDef, SubscribeEvent } from './define-machine.ts'
+import { recordTouch } from './dispatch-context.ts'
+import { createInstanceProxy, type InstanceHandle } from './instance-proxy.ts'
+import { scopedLogger } from './logger.ts'
+import { serverReadsResolver } from './reads-helpers.ts'
+import type { Store } from './store.ts'
+
+const storeLog = scopedLogger('machine-store')
+
+/** Hard backstop for synchronous emit→subscribe cascades. Deep enough for
+ *  any legitimate finite ping-pong; shallow enough to abort a cycle long
+ *  before the call stack does, with a diagnosable trail. */
+export const MAX_CASCADE_DEPTH = 32
+
+/**
+ * Compose the event a subscriber actually receives. Order of precedence:
+ *   1. Payload from the source's emit selector (fields like `productId`, `items`).
+ *   2. Subscriber's `dispatch` declaration (`type` and any static fields it adds).
+ *   3. `sourceSessionId` when injected — set by the caller for cross-lifecycle
+ *      subscriptions only.
+ * Subscriber-side fields override source payload fields on collision; the
+ * subscriber owns the shape of its own inbox.
+ */
+export function buildDispatchEvent(
+  emitted: { type?: string; [k: string]: unknown } | undefined,
+  dispatch: SubscribeEvent,
+  sourceSessionId?: string,
+): { type: string; [k: string]: unknown } {
+  const { type: _emitType, ...payload } = emitted ?? {}
+  const dispatchBase = typeof dispatch === 'string' ? { type: dispatch } : dispatch
+  return {
+    ...payload,
+    ...dispatchBase,
+    ...(sourceSessionId !== undefined ? { sourceSessionId } : {}),
+  }
+}
+
+/**
+ * Machine registry + long-lived app-machine actors + persistence adapter.
+ *
+ * Session-lifecycle machine actors are *not* held here anymore — they are
+ * created transiently inside a SessionRuntime per request, hydrated from
+ * the Store, and dropped when the request completes. This keeps server
+ * memory bounded by (open SSE connections + active in-flight requests)
+ * rather than (every session ever seen).
+ */
+export class MachineStore {
+  private appInstances = new Map<string, InstanceHandle>()
+  private defs = new Map<string, AnyMachineDef>()
+  /** Reverse index over `subscribes`: for each emit source, the list of
+   *  subscribing machines + which event they care about + what to dispatch.
+   *  Computed once at construction so SessionRuntime.wireSubscriptions is
+   *  a single Map lookup per session-machine. */
+  private subscribersBySource = new Map<
+    string,
+    Array<{
+      targetName: string
+      event: string
+      dispatch: { type: string; [k: string]: unknown }
+    }>
+  >()
+
+  /** Default per-session TTL in seconds. Applied on every persistTouched
+   *  so a session stays alive as long as the user keeps interacting; idle
+   *  sessions expire as a whole. Adapters honor this on `set()`. */
+  readonly sessionTtlSeconds: number
+
+  /** Persistence for `persist: true` APP machines (no TTL, one blob per
+   *  machine). Defaults to in-memory (restart-wipe) — pass RedisAppStore for
+   *  durable app state. */
+  readonly appStore: AppStore
+
+  /** Host-injected scheduler for app-machine effects (see server/effects.ts
+   *  wireAppEffects). Set after construction to avoid an import cycle;
+   *  unwired effects are dropped loudly. */
+  private appEffectScheduler: ((invocation: EffectInvocation) => void) | null = null
+
+  constructor(
+    defs: AnyMachineDef[],
+    readonly persistence: Store,
+    opts?: { sessionTtlSeconds?: number; appStore?: AppStore },
+  ) {
+    this.sessionTtlSeconds = opts?.sessionTtlSeconds ?? 86400
+    this.appStore = opts?.appStore ?? new InMemoryAppStore()
+    for (const def of defs) {
+      if (this.defs.has(def.name)) {
+        throw new Error(`stator: duplicate machine name "${def.name}"`)
+      }
+      this.defs.set(def.name, def)
+    }
+    this.validateSubscriptions()
+    this.buildSubscriberIndex()
+    this.buildReaderIndex()
+    this.warnOnSubscriptionCycles()
+  }
+
+  /** Reverse index over `reads:`: for each machine, which machines' SELECTORS
+   *  may derive from it. Drives touched-set expansion so display state that
+   *  reads across machines re-diffs when its dependencies change. */
+  private readersBySource = new Map<string, string[]>()
+
+  private buildReaderIndex(): void {
+    for (const def of this.defs.values()) {
+      for (const r of def.reads) {
+        let list = this.readersBySource.get(r.name)
+        if (!list) {
+          list = []
+          this.readersBySource.set(r.name, list)
+        }
+        list.push(def.name)
+      }
+    }
+  }
+
+  /**
+   * Expand a touched set through the reverse-reads graph (transitively):
+   * if A's selectors read B and B changed, A's bindings must re-diff even
+   * though A's own state didn't move. Returns the expansion (machines whose
+   * DERIVED views changed) separately from the direct touches — callers
+   * scope them differently (derived session machines re-diff for every
+   * connection, no rehydration; direct session touches belong to one
+   * session).
+   */
+  expandTouchedForRecompute(touched: ReadonlySet<string>): {
+    all: Set<string>
+    derived: Set<string>
+  } {
+    const all = new Set(touched)
+    const derived = new Set<string>()
+    const queue = [...touched]
+    while (queue.length > 0) {
+      const name = queue.shift()!
+      for (const reader of this.readersBySource.get(name) ?? []) {
+        if (!all.has(reader)) {
+          all.add(reader)
+          derived.add(reader)
+          queue.push(reader)
+        }
+      }
+    }
+    return { all, derived }
+  }
+
+  /**
+   * Machine-level cycles in the `subscribes:` graph, one representative path
+   * per cycle (`['A', 'B', 'A']`). A machine-level cycle is a *potential*
+   * runtime loop, not a certain one — guards or state targeting may break it
+   * — so construction warns rather than rejects; the runtime cascade depth
+   * cap (see SessionRuntime.wireSubscriptions) is the hard backstop.
+   */
+  findSubscriptionCycles(): string[][] {
+    const cycles: string[][] = []
+    const visiting = new Set<string>()
+    const done = new Set<string>()
+    const path: string[] = []
+
+    const visit = (name: string): void => {
+      if (done.has(name)) return
+      if (visiting.has(name)) {
+        cycles.push([...path.slice(path.indexOf(name)), name])
+        return
+      }
+      visiting.add(name)
+      path.push(name)
+      for (const sub of this.subscribersOf(name)) visit(sub.targetName)
+      path.pop()
+      visiting.delete(name)
+      done.add(name)
+    }
+
+    for (const name of this.defs.keys()) visit(name)
+    return cycles
+  }
+
+  private warnOnSubscriptionCycles(): void {
+    for (const cycle of this.findSubscriptionCycles()) {
+      storeLog.warn(
+        { cycle: cycle.join(' → ') },
+        'stator: subscription cycle — emits between these machines can cascade in a loop. ' +
+          'Ensure a guard breaks the chain; the runtime aborts cascades deeper than ' +
+          `${MAX_CASCADE_DEPTH} hops.`,
+      )
+    }
+  }
+
+  private validateSubscriptions(): void {
+    for (const def of this.defs.values()) {
+      for (const sub of def.subscribes) {
+        if (sub.from == null) {
+          // The classic cause: a circular import between machine modules.
+          // Bundler/loader interop (Vite SSR, tsx) resolves the mid-cycle
+          // binding to `undefined` SILENTLY — no TDZ error — so this check
+          // is where the mistake first becomes visible. Name it properly.
+          throw new Error(
+            `stator: machine "${def.name}" declares a subscription whose \`from\` is undefined. ` +
+              `This is almost always a circular import between machine modules — the module ` +
+              `defining "${def.name}" and the module defining its subscription source import ` +
+              `each other, and the loader resolved the mid-cycle binding to undefined. ` +
+              `Break the module cycle (e.g. move one machine or the subscription), ` +
+              `or define the mutually-subscribing machines in one module.`,
+          )
+        }
+        if (!this.defs.has(sub.from.name)) {
+          throw new Error(
+            `stator: machine "${def.name}" subscribes to unknown machine "${sub.from.name}"`,
+          )
+        }
+        if (sub.from.lifecycle === 'app' && def.lifecycle === 'session') {
+          throw new Error(
+            `stator: app-lifecycle source "${sub.from.name}" cannot deliver to ` +
+              `session-lifecycle target "${def.name}" yet — app→session needs the ` +
+              `inbox model (see .chisel/specs/active/app-to-session-subscriptions-via-inbox.md). ` +
+              `Use session→app or same-lifecycle subscriptions for now.`,
+          )
+        }
+        const emitNames = Object.keys(sub.from.emits)
+        if (emitNames.length > 0 && !(sub.event in sub.from.emits)) {
+          throw new Error(
+            `stator: machine "${def.name}" subscribes to "${sub.from.name}.${sub.event}", ` +
+              `but "${sub.from.name}" does not declare "${sub.event}" in its emits.`,
+          )
+        }
+      }
+    }
+  }
+
+  private buildSubscriberIndex(): void {
+    for (const def of this.defs.values()) {
+      for (const sub of def.subscribes) {
+        const dispatch = typeof sub.dispatch === 'string' ? { type: sub.dispatch } : sub.dispatch
+        let list = this.subscribersBySource.get(sub.from.name)
+        if (!list) {
+          list = []
+          this.subscribersBySource.set(sub.from.name, list)
+        }
+        list.push({ targetName: def.name, event: sub.event, dispatch })
+      }
+    }
+  }
+
+  async bootAppMachines(): Promise<void> {
+    for (const def of this.defs.values()) {
+      if (def.lifecycle === 'app' && !this.appInstances.has(def.name)) {
+        const snapshot = def.persist ? await this.loadAppSnapshot(def.name) : undefined
+        const actor = createActor(def, {
+          snapshot,
+          resolveHelpers: serverReadsResolver(def),
+          // App effects run through the host scheduler wired by
+          // wireAppEffects (server/effects.ts) — injected post-construction
+          // to avoid an import cycle. Unwired: dropped loudly rather than
+          // half-run without fan-out or persistence.
+          onEffect: (invocation) => {
+            if (this.appEffectScheduler) this.appEffectScheduler(invocation)
+            else
+              storeLog.warn(
+                { machine: invocation.machineName, effectId: invocation.effectId },
+                'app-machine effect dropped — no scheduler wired (call wireAppEffects(store))',
+              )
+          },
+        }).start()
+        this.appInstances.set(
+          def.name,
+          // App machines resolve selector reads among app instances only —
+          // "which session?" has no answer at app scope.
+          createInstanceProxy(def, actor, (name) => this.appInstance(name)?.proxy),
+        )
+      }
+    }
+    this.wireAppSubscriptions()
+  }
+
+  /** Load + validate a persisted app snapshot. Corrupt or unloadable state
+   *  logs loud and boots fresh — restart-fresh is the safe default. */
+  private async loadAppSnapshot(name: string): Promise<Snapshot<object> | undefined> {
+    try {
+      const raw = await this.appStore.loadAppMachine(name)
+      if (raw === null) return undefined
+      const snap = raw as Snapshot<object>
+      if (!Array.isArray(snap.value) || typeof snap.context !== 'object' || snap.context === null) {
+        throw new Error('snapshot shape invalid (expected { value: string[], context: object })')
+      }
+      return snap
+    } catch (err) {
+      storeLog.error(
+        { machine: name, err: String(err) },
+        'persisted app-machine snapshot unusable — booting fresh',
+      )
+      return undefined
+    }
+  }
+
+  /** Install the app-effect scheduler (see server/effects.ts wireAppEffects). */
+  setAppEffectScheduler(scheduler: (invocation: EffectInvocation) => void): void {
+    this.appEffectScheduler = scheduler
+  }
+
+  /** Persist one app machine's snapshot, if it opted in. Safe no-op for
+   *  session machines, non-persist app machines, and unknown names — callers
+   *  pass raw touched-set entries. */
+  async persistAppMachine(name: string): Promise<void> {
+    const def = this.defs.get(name)
+    if (def?.lifecycle !== 'app' || !def.persist) return
+    const handle = this.appInstances.get(name)
+    if (!handle) return
+    await this.appStore.saveAppMachine(name, handle.actor.getPersistedSnapshot())
+  }
+
+  /** Wire app→app subscription listeners. Session-involved subscriptions
+   *  (session→session, session→app) are wired per-request inside
+   *  SessionRuntime. Same-lifecycle so no sourceSessionId injection. */
+  private wireAppSubscriptions(): void {
+    for (const targetHandle of this.appInstances.values()) {
+      const targetName = targetHandle.def.name
+      for (const sub of targetHandle.def.subscribes) {
+        const sourceHandle = this.appInstances.get(sub.from.name)
+        if (!sourceHandle) continue
+        sourceHandle.actor.on(sub.event as never, (emitted) => {
+          targetHandle.actor.send(buildDispatchEvent(emitted, sub.dispatch) as never)
+          recordTouch(targetName)
+        })
+      }
+    }
+  }
+
+  appInstance(name: string): InstanceHandle | undefined {
+    return this.appInstances.get(name)
+  }
+
+  getDef(name: string): AnyMachineDef | undefined {
+    return this.defs.get(name)
+  }
+
+  allDefs(): AnyMachineDef[] {
+    return [...this.defs.values()]
+  }
+
+  /** Subscribers (target machine + dispatch info) for a given source machine. */
+  subscribersOf(sourceName: string): ReadonlyArray<{
+    targetName: string
+    event: string
+    dispatch: { type: string; [k: string]: unknown }
+  }> {
+    return this.subscribersBySource.get(sourceName) ?? []
+  }
+
+  hasMachine(name: string): boolean {
+    return this.defs.has(name)
+  }
+
+  async disposeSession(sessionId: string): Promise<void> {
+    await this.persistence.deleteSession(sessionId)
+  }
+}

package/src/server/reads-helpers.ts

@@ -0,0 +1,40 @@
+import type { ActionHelpers, AnyMachineDef } from '../engine/index.ts'
+import { getDispatchContext } from './dispatch-context.ts'
+
+/**
+ * Server-side resolver for an action/guard's `reads` helper. The engine is
+ * host-agnostic (it imports no server module); the *server* supplies how reads
+ * are resolved — through the active dispatch context's runtime, exactly as the
+ * POC did. A reads-free machine never invokes this; a machine that dereferences
+ * reads outside an active dispatch gets a clear error (matching prior behavior).
+ */
+export function serverReadsResolver(def: AnyMachineDef): () => ActionHelpers {
+  return () => {
+    const dc = getDispatchContext()
+    if (!dc) {
+      return {
+        reads: new Proxy({} as Record<string, unknown>, {
+          get(_t, prop) {
+            throw new Error(
+              `stator: "${def.name}" accessed reads.${String(prop)} outside an active dispatch — ` +
+                `actions/guards that use reads must run through store.processEvent(...) ` +
+                `(or actor.send() inside a subscription handler), not a bare send.`,
+            )
+          },
+        }),
+      }
+    }
+    const reads: Record<string, unknown> = {}
+    for (const r of def.reads) {
+      const proxy = dc.runtime.proxyFor(r.name)
+      if (!proxy) {
+        throw new Error(
+          `stator: "${def.name}" declares reads on "${r.name}" but it's not loaded ` +
+            `in the active runtime — loadGraph(...) should pull it in transitively.`,
+        )
+      }
+      reads[r.name] = proxy
+    }
+    return { reads }
+  }
+}