@statorjs/stator 2.5.1 → 2.6.0

package/src/server/machine-hash.ts

@@ -0,0 +1,195 @@
+import { createHash } from 'node:crypto'
+import { realpathSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { isAbsolute, relative, resolve } from 'node:path'
+import { build, version as esbuildVersion } from 'esbuild'
+import type { AnyMachineDef } from '../engine/index.ts'
+
+/**
+ * The per-machine code hash — the fingerprint behind "sessions never outlive
+ * the code that made them" (spec `machine-state-is-working-state-snapshot-
+ * hydration-policy`).
+ *
+ * Each machine file is bundled by esbuild — tree-shaken, minified, in memory —
+ * and the bundle is hashed. The hash therefore changes exactly when code that
+ * can execute as part of the machine changes: a guard, action, effect,
+ * selector, state, event key or context default, in the machine file or in any
+ * module it reaches. Comments, whitespace and exports the machine never uses
+ * don't move it. The bundle is a MEASUREMENT, never written or run: what runs
+ * stays plain modules with shared instances.
+ *
+ * External (never bundled, never hashed by content):
+ *  - bare specifiers — the framework and node_modules; their versions are hash
+ *    inputs instead, so an engine or transform-engine upgrade counts once;
+ *  - `.stator` files (a machine has no business importing a template).
+ *
+ * Sibling machines are NOT external: a machine that imports another often
+ * takes values from it (`weather.ts` mirrors `DEFAULT_CLOCK` from
+ * `settings.ts` into its own context), and a default changed in the sibling
+ * must reset the importer too. The cost is over-reset — a machine imported only
+ * for identity (`subscribes: [{ from: Sibling }]`) still resets its importers
+ * when it changes — which the principle permits; a missed reset it does not.
+ *
+ * One esbuild invocation hashes every machine, so build-time cost does not
+ * scale with the number of calls; `stator build` fails on a machine whose
+ * closure cannot be bundled (an import problem that belongs in CI, not at a
+ * production boot).
+ */
+
+export interface MachineHash {
+  hash: string
+  /** Absolute paths of every source module bundled into this machine. */
+  inputs: string[]
+}
+
+export interface HashMachinesOptions {
+  /** The conventional machines directory. Kept for the stable ids of
+   *  externalized `.stator` imports; siblings are bundled, not external. */
+  machinesDir: string
+}
+
+const statorVersion: string = (
+  createRequire(import.meta.url)('../../package.json') as { version: string }
+).version
+
+const OUTDIR = '/__stator_machine_hash__'
+
+/** Hash every machine file in one esbuild pass. Throws if any closure cannot
+ *  be bundled — the error names the machine. */
+export async function hashMachines(
+  files: readonly string[],
+  opts: HashMachinesOptions,
+): Promise<Map<string, MachineHash>> {
+  const out = new Map<string, MachineHash>()
+  if (files.length === 0) return out
+  // esbuild reports real paths (macOS: /var → /private/var); key everything by
+  // realpath and hand results back under the caller's own spelling.
+  const real = (p: string): string => {
+    try {
+      return realpathSync(p)
+    } catch {
+      return resolve(p)
+    }
+  }
+  const machinesDir = real(opts.machinesDir)
+  const wanted = new Map(files.map((f) => [real(f), f]))
+  const cwd = process.cwd()
+
+  const result = await build({
+    entryPoints: [...wanted.keys()],
+    absWorkingDir: cwd,
+    bundle: true,
+    // Strip whitespace and fold syntax, but do NOT rename identifiers: esbuild
+    // allocates minified names across the whole module set, so a dead export
+    // in an imported module can shift the names in the bundle — and the hash
+    // would move for code that never runs. Keeping source identifiers makes the
+    // output a function of the reachable code only.
+    minifyWhitespace: true,
+    minifySyntax: true,
+    minifyIdentifiers: false,
+    write: false,
+    metafile: true,
+    format: 'esm',
+    platform: 'node',
+    target: 'node20',
+    outdir: OUTDIR,
+    entryNames: '[dir]/[name]',
+    legalComments: 'none',
+    sourcemap: false,
+    logLevel: 'silent',
+    plugins: [
+      {
+        name: 'stator-machine-hash-externals',
+        setup(b) {
+          b.onResolve({ filter: /.*/ }, (args) => {
+            if (args.kind === 'entry-point') return null
+            // Bare specifier: a package — external, its version is a hash input.
+            if (!args.path.startsWith('.') && !isAbsolute(args.path)) {
+              return { path: args.path, external: true }
+            }
+            const abs = real(resolve(args.resolveDir, args.path))
+            // Externals keep their specifier in the bundle, so give a template a
+            // STABLE id (relative to machinesDir), never an absolute path — or the
+            // hash would change with the checkout directory.
+            if (abs.endsWith('.stator')) {
+              return {
+                path: `stator:${relative(machinesDir, abs).replace(/\\/g, '/')}`,
+                external: true,
+              }
+            }
+            return null
+          })
+        },
+      },
+    ],
+  }).catch((err: unknown) => {
+    const msg = err instanceof Error ? err.message : String(err)
+    throw new Error(`stator: cannot hash machine closure — ${msg}`)
+  })
+
+  // Map each output bundle back to its entry via the metafile.
+  for (const file of result.outputFiles) {
+    const key = relative(cwd, file.path).replace(/\\/g, '/')
+    const meta = result.metafile.outputs[key]
+    if (!meta?.entryPoint) continue
+    const entry = wanted.get(real(resolve(cwd, meta.entryPoint)))
+    if (entry === undefined) continue
+    const hash = createHash('sha256')
+      .update(file.contents)
+      .update('\0')
+      .update(statorVersion)
+      .update('\0')
+      .update(esbuildVersion)
+      .digest('hex')
+    // The closure comes from the resolved import GRAPH (`metafile.inputs`),
+    // not from `outputs[*].inputs` — that lists only modules that contributed
+    // bytes, and a module whose only used export is a constant the minifier
+    // inlined contributes none while still being code the machine depends on.
+    out.set(entry, { hash, inputs: closureOf(meta.entryPoint, result.metafile.inputs, cwd) })
+  }
+  for (const f of files) {
+    if (!out.has(f)) throw new Error(`stator: no bundle produced for machine ${f}`)
+  }
+  return out
+}
+
+function closureOf(
+  entryKey: string,
+  inputs: Record<string, { imports: Array<{ path: string; external?: boolean }> }>,
+  cwd: string,
+): string[] {
+  const seen = new Set<string>()
+  const stack = [entryKey]
+  while (stack.length) {
+    const key = stack.pop()!
+    if (seen.has(key)) continue
+    seen.add(key)
+    for (const imp of inputs[key]?.imports ?? []) if (!imp.external) stack.push(imp.path)
+  }
+  return [...seen].map((k) => resolve(cwd, k))
+}
+
+// ── Def registry ─────────────────────────────────────────────────────────────
+// Discovery attaches each def's hash here; hydration reads it. A WeakMap keyed
+// by the def object keeps the def type untouched and needs no plumbing —
+// whoever has the def has the hash.
+const hashes = new WeakMap<AnyMachineDef, { hash: string; inputs: readonly string[] }>()
+
+export function setCodeHash(
+  def: AnyMachineDef,
+  hash: string,
+  inputs: readonly string[] = [],
+): void {
+  hashes.set(def, { hash, inputs })
+}
+
+export function codeHashOf(def: AnyMachineDef): string | undefined {
+  return hashes.get(def)?.hash
+}
+
+/** Absolute paths of the modules in the def's hashed closure (empty when the
+ *  hash came from a manifest). The dev servers use it to decide whether an
+ *  edit touches a machine at all. */
+export function codeInputsOf(def: AnyMachineDef): readonly string[] {
+  return hashes.get(def)?.inputs ?? []
+}

package/src/server/machine-store.ts

@@ -7,6 +7,7 @@ import { createInstanceProxy, type InstanceHandle } from './instance-proxy.ts'
 import { scopedLogger } from './logger.ts'
 import { serverReadsResolver } from './reads-helpers.ts'
 import { RESERVED_KEY_PREFIX } from './session.ts'
+import { reconcileSnapshot, stampSnapshot } from './snapshot-policy.ts'
 import type { Store } from './store.ts'
 import { APP_SCOPE, armAfterTimers, cancelAfterTimers } from './timers.ts'
 
@@ -316,7 +317,10 @@ export class MachineStore {
       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
+      // Hydration policy: written by different code / newer format / vanished
+      // state ⇒ boot fresh (logged by the policy).
+      const def = this.defs.get(name)
+      return def ? reconcileSnapshot(def, snap, APP_SCOPE) : snap
     } catch (err) {
       storeLog.error(
         { machine: name, err: String(err) },
@@ -339,7 +343,10 @@ export class MachineStore {
     if (def?.lifecycle !== 'app' || !def.persist) return
     const handle = this.appInstances.get(name)
     if (!handle) return
-    await this.appStore.saveAppMachine(name, handle.actor.getPersistedSnapshot())
+    await this.appStore.saveAppMachine(
+      name,
+      stampSnapshot(def, handle.actor.getPersistedSnapshot()),
+    )
   }
 
   /** Wire app→app subscription listeners. Session-involved subscriptions

package/src/server/session-runtime.ts

@@ -1,10 +1,11 @@
-import { createActor, type EffectInvocation, type Snapshot } from '../engine/index.ts'
+import { createActor, type EffectInvocation } from '../engine/index.ts'
 import type { AnyMachineDef } from './define-machine.ts'
 import { type DispatchContext, recordTouch, withDispatchContext } from './dispatch-context.ts'
 import { abortEntryEffects, isEffectInFlight } from './effects.ts'
 import { createInstanceProxy, type InstanceHandle } from './instance-proxy.ts'
 import { buildDispatchEvent, MAX_CASCADE_DEPTH, type MachineStore } from './machine-store.ts'
 import { serverReadsResolver } from './reads-helpers.ts'
+import { reconcileSnapshot, stampSnapshot } from './snapshot-policy.ts'
 import { armAfterTimers, cancelAfterTimers } from './timers.ts'
 
 /**
@@ -64,7 +65,9 @@ export class SessionRuntime {
   private async loadOne(def: AnyMachineDef): Promise<void> {
     const persisted = await this.store.persistence.get(this.sessionId, def.name)
     const actor = createActor(def, {
-      snapshot: persisted !== null ? (persisted as Snapshot<object>) : undefined,
+      // Hydration policy: a snapshot written by different code (or in a newer
+      // format, or naming a vanished state) is discarded — fresh start, logged.
+      snapshot: reconcileSnapshot(def, persisted, this.sessionId),
       resolveHelpers: serverReadsResolver(def),
       // Server plane: never run effects inline — queue them for the entry
       // point to schedule after persist + lock release.
@@ -114,7 +117,7 @@ export class SessionRuntime {
     if (def?.lifecycle !== 'session' || !this.actors.has(name)) return
     const persisted = await this.store.persistence.get(this.sessionId, def.name)
     const actor = createActor(def, {
-      snapshot: persisted !== null ? (persisted as Snapshot<object>) : undefined,
+      snapshot: reconcileSnapshot(def, persisted, this.sessionId),
       resolveHelpers: serverReadsResolver(def),
       onEffect: (invocation) => this.pendingEffects.push(invocation),
     }).start()
@@ -263,7 +266,9 @@ export class SessionRuntime {
         await this.store.persistAppMachine(name)
         continue
       }
-      const snapshot = handle.actor.getPersistedSnapshot()
+      // Stamped with the format and the writing machine's code hash, so a
+      // later hydration can tell whether the code that wrote it still runs.
+      const snapshot = stampSnapshot(this.store.getDef(name), handle.actor.getPersistedSnapshot())
       // A ttlSeconds-bearing set refreshes the session's whole expiry — the
       // user is active, so all of their machines stay alive together. TTL-less
       // sets (machine-driven work) leave the expiry untouched.

package/src/server/snapshot-policy.ts

@@ -0,0 +1,110 @@
+import type { AnyMachineDef, Snapshot } from '../engine/index.ts'
+import { scopedLogger } from './logger.ts'
+import { codeHashOf } from './machine-hash.ts'
+
+/**
+ * Snapshot hydration policy — "sessions never outlive the code that made them"
+ * (spec `machine-state-is-working-state-snapshot-hydration-policy`).
+ *
+ * The host stamps every persisted snapshot with the snapshot `format` and the
+ * writing machine's code hash (`stampSnapshot`), and reconciles a persisted
+ * snapshot against the running def before building an actor
+ * (`reconcileSnapshot`): a snapshot written by different code, in a newer
+ * format, or naming a state the chart no longer has, is discarded and the
+ * machine starts fresh — identically in dev and prod, for any Store.
+ *
+ * Resets are logged at `warn`, rate-limited per machine per process (first
+ * occurrence, then every power of ten) so a deploy across a large store stays
+ * visible without flooding.
+ */
+
+/** The current persisted-snapshot format. Bump when the shape changes. */
+export const SNAPSHOT_FORMAT = 1
+
+const log = scopedLogger('hydrate')
+
+export type ResetReason = 'code-changed' | 'format-newer' | 'state-missing' | 'shape-invalid'
+
+/** Stamp a snapshot for persistence with the format and the def's code hash.
+ *  A def with no registered hash (a store assembled from defs directly, not
+ *  via discovery) stamps no hash — and is never reset for it. */
+export function stampSnapshot<C>(
+  def: AnyMachineDef | undefined,
+  snapshot: Snapshot<C>,
+): Snapshot<C> {
+  const code = def ? codeHashOf(def) : undefined
+  return { ...snapshot, format: SNAPSHOT_FORMAT, ...(code ? { code } : {}) }
+}
+
+/** Why a persisted snapshot cannot be hydrated under `def`, or null if it can. */
+export function snapshotResetReason(def: AnyMachineDef, persisted: unknown): ResetReason | null {
+  const snap = persisted as Partial<Snapshot<unknown>> | null
+  if (
+    !snap ||
+    typeof snap !== 'object' ||
+    !Array.isArray(snap.value) ||
+    typeof snap.context !== 'object' ||
+    snap.context === null
+  ) {
+    return 'shape-invalid'
+  }
+  if ((snap.format ?? SNAPSHOT_FORMAT) > SNAPSHOT_FORMAT) return 'format-newer'
+  const expected = codeHashOf(def)
+  if (expected !== undefined && snap.code !== expected) return 'code-changed'
+  const state = snap.value[0]
+  if (state === undefined || !(state in def.states)) return 'state-missing'
+  return null
+}
+
+/**
+ * The persisted snapshot to hydrate from, or `undefined` to start fresh.
+ * `null` persisted (nothing stored) is a fresh start with no log; a stored
+ * snapshot that cannot be used is a reset, logged.
+ */
+export function reconcileSnapshot(
+  def: AnyMachineDef,
+  persisted: unknown,
+  scope: string,
+): Snapshot<object> | undefined {
+  if (persisted === null || persisted === undefined) return undefined
+  const reason = snapshotResetReason(def, persisted)
+  if (reason === null) return persisted as Snapshot<object>
+  logReset(def, persisted as Partial<Snapshot<unknown>>, reason, scope)
+  return undefined
+}
+
+const resetCounts = new Map<string, number>()
+
+function logReset(
+  def: AnyMachineDef,
+  snap: Partial<Snapshot<unknown>>,
+  reason: ResetReason,
+  scope: string,
+): void {
+  const n = (resetCounts.get(def.name) ?? 0) + 1
+  resetCounts.set(def.name, n)
+  // 1, 10, 100, 1000, … — the first reset is the news; the count is the scale.
+  if (n !== 1 && !Number.isInteger(Math.log10(n))) return
+  log.warn(
+    {
+      machine: def.name,
+      scope,
+      reason,
+      resets: n,
+      ...(reason === 'code-changed' ? { from: snap.code ?? null, to: codeHashOf(def) } : {}),
+      ...(reason === 'state-missing' ? { state: snap.value?.[0] ?? null } : {}),
+    },
+    reason === 'code-changed'
+      ? 'machine code changed since this snapshot was written — starting fresh'
+      : reason === 'format-newer'
+        ? 'snapshot written in a newer format than this server understands — starting fresh'
+        : reason === 'state-missing'
+          ? 'snapshot names a state the machine no longer has — starting fresh'
+          : 'persisted snapshot has an invalid shape — starting fresh',
+  )
+}
+
+/** Test hook: forget rate-limit counts. */
+export function resetSnapshotPolicyCounters(): void {
+  resetCounts.clear()
+}

package/src/vite/index.ts

@@ -1,6 +1,12 @@
 /**
- * Vite integration for `.stator` single-file components.
- * `import { stator } from '@statorjs/stator/vite'` and add it to `plugins`.
+ * INTERNAL — the framework's own Vite glue: the `.stator` plugin the island
+ * bundler (and the transitional Vite dev server) uses and the machine-import
+ * stub. Not a plugin
+ * surface: Stator never reads a user `vite.config.*` and accepts no bundler
+ * plugins (a plugin would reach client islands and nothing else, silently
+ * splitting the app into a tier where it applies and a tier where it doesn't).
+ * What to do instead — global CSS, Tailwind, images, WASM — is documented under
+ * "Styling and assets" in the docs.
  */
-export { stator } from './plugin.ts'
-export { machineStub } from './stub.ts'
+export { CLIENT_QUERY, stator } from './plugin.ts'
+export { MACHINE_STUB_PREFIX, machineStub } from './stub.ts'

package/src/vite/plugin.ts

@@ -1,35 +1,7 @@
-import { readFileSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { dirname, resolve } from 'node:path'
 import { transform } from 'esbuild'
 import type { Plugin } from 'vite'
-import {
-  CompileError,
-  type CompileResult,
-  compile,
-  componentImportSpecifier,
-  declaredRegions,
-  splitStator,
-} from '../compiler/index.ts'
-
-/** Build a region resolver for a file: maps a component identifier used in
- *  `file` to the named regions its imported `.stator` declares. Reads sibling
- *  files synchronously (resolution happens mid-compile). Returns null when the
- *  identifier isn't a `.stator` default import or the file can't be read. */
-function regionResolverFor(file: string, source: string) {
-  const { frontmatter } = splitStator(source)
-  return (componentName: string): Set<string> | null => {
-    const spec = componentImportSpecifier(frontmatter, componentName)
-    if (!spec) return null
-    const target = spec.startsWith('.') ? resolve(dirname(file), spec) : null
-    if (!target) return null
-    try {
-      return declaredRegions(readFileSync(target, 'utf8'))
-    } catch {
-      return null
-    }
-  }
-}
+import { CompileError, type CompileResult, compile, regionResolverFor } from '../compiler/index.ts'
 
 /** Map a `CompileError` to a Vite/Rollup-friendly error so the dev overlay and
  *  terminal show file:line:column with a code frame. */
@@ -57,8 +29,16 @@ function toViteError(err: unknown): unknown {
  * The plugin does no CSS or JSX parsing itself — that's all in the compiler.
  */
 
+/** A `.stator` module id: the extension proper, optionally followed by a query.
+ *  Precise on purpose — `x.stator.client.ts` / `x.stator.ts` (compiled output
+ *  in a dist tree) must NOT match, or the bundler would recompile them. */
+const STATOR_ID = /\.stator(?:\?|$)/
+
 const STYLE_QUERY = 'stator&type=style&lang.css'
-const CLIENT_QUERY = 'stator&type=client'
+/** Query that selects a `.stator` file's generated client entry module (the
+ *  island's `<script>`); `bundleIslands` feeds island sources to Vite as
+ *  `<file>?${CLIENT_QUERY}` so one plugin serves dev and build alike. */
+export const CLIENT_QUERY = 'stator&type=client'
 
 export function stator(): Plugin {
   const cache = new Map<string, CompileResult>()
@@ -87,7 +67,7 @@ export function stator(): Plugin {
     name: 'vite-plugin-stator',
 
     resolveId(id, importer) {
-      if (!id.includes('.stator')) return null
+      if (!STATOR_ID.test(id)) return null
       const qIdx = id.indexOf('?')
       const path = qIdx === -1 ? id : id.slice(0, qIdx)
       const query = qIdx === -1 ? '' : id.slice(qIdx)
@@ -99,7 +79,7 @@ export function stator(): Plugin {
     },
 
     async load(id) {
-      if (!id.includes('.stator')) return null
+      if (!STATOR_ID.test(id)) return null
       const qIdx = id.indexOf('?')
       const file = qIdx === -1 ? id : id.slice(0, qIdx)
       const query = qIdx === -1 ? '' : id.slice(qIdx + 1)

package/src/vite/stub.ts

@@ -20,7 +20,10 @@ import type { Plugin } from 'vite'
  * discovery already imports them all).
  */
 
-const STUB_PREFIX = '\0stator-machine-stub:'
+/** Virtual-id prefix of a stubbed server-machine import (exported so the
+ *  island bundler can map a stub back to the machine file it stands for). */
+export const MACHINE_STUB_PREFIX = '\0stator-machine-stub:'
+const STUB_PREFIX = MACHINE_STUB_PREFIX
 
 export function machineStub(opts: { machinesDir: string }): Plugin {
   const machinesDir = resolve(opts.machinesDir)