@statorjs/stator 1.4.1 → 1.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "Server-canonical web framework: business logic in composable state machines, UI as a thin renderer binding machine outputs to DOM positions. Ships TypeScript source (Vite/tsx-native by design).",
   "license": "MIT",
   "type": "module",
@@ -88,7 +88,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "1.4.1"
+    "@statorjs/stator": "1.5.1"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/build/sync.ts

@@ -2,6 +2,7 @@ import type { Dirent } from 'node:fs'
 import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { dirname, join, relative, sep } from 'node:path'
 import { generateDts } from '../compiler/dts.ts'
+import { toVirtualCode } from '../compiler/virtual-code.ts'
 
 /**
  * Type sync: generate a `<name>.stator.d.ts` for each component so editors and
@@ -16,35 +17,61 @@ import { generateDts } from '../compiler/dts.ts'
  *
  * Route pages (`routes/*.stator`) are skipped — they export `GET`, not a render
  * function.
+ *
+ * Sync ALSO emits each template's virtual TSX (the same code the language
+ * server typechecks in-editor) under `.stator/check/`, so plain `tsc --noEmit`
+ * covers TEMPLATE INTERNALS in CI — frontmatter/prop mismatches otherwise
+ * surface only as runtime ReferenceErrors. Opt-in per app: add
+ * ".stator/check" to `rootDirs` and its .tsx files to `include` (see the
+ * example tsconfigs); apps that don't are unaffected (the files sit ignored).
  */
 export interface SyncResult {
   /** Number of `.stator.d.ts` files written. */
   written: number
+  /** Number of `.check.tsx` virtual files written. */
+  checks: number
   /** The generated-types directory. */
   outDir: string
 }
 
 const TYPES_DIR = join('.stator', 'types')
+const CHECK_DIR = join('.stator', 'check')
 
 export async function syncTypes(root: string): Promise<SyncResult> {
   const outDir = join(root, TYPES_DIR)
+  const checkDir = join(root, CHECK_DIR)
   await rm(outDir, { recursive: true, force: true })
+  await rm(checkDir, { recursive: true, force: true })
 
   const files = await walk(root)
   let written = 0
+  let checks = 0
   for (const file of files) {
-    const kind = file.split(sep).includes('routes') ? 'route' : 'component'
-    const dts = generateDts(await readFile(file, 'utf8'), { kind })
-    if (dts === null) continue
-    // Mirror the source path under .stator/types: templates/x.stator →
-    // .stator/types/templates/x.stator.d.ts.
+    const source = await readFile(file, 'utf8')
     const rel = relative(root, file)
-    const target = join(outDir, `${rel}.d.ts`)
-    await mkdir(dirname(target), { recursive: true })
-    await writeFile(target, dts)
-    written++
+
+    const kind = file.split(sep).includes('routes') ? 'route' : 'component'
+    const dts = generateDts(source, { kind })
+    if (dts !== null) {
+      // Mirror the source path under .stator/types: templates/x.stator →
+      // .stator/types/templates/x.stator.d.ts.
+      const target = join(outDir, `${rel}.d.ts`)
+      await mkdir(dirname(target), { recursive: true })
+      await writeFile(target, dts)
+      written++
+    }
+
+    // Same mirroring for the virtual TSX — the exact code the editor
+    // typechecks, HTML→TSX compatibility included (see compiler/virtual-code
+    // appendTemplateTsx). Relative imports resolve through the app's
+    // `rootDirs`; ambient Stator/JSX scaffolding is self-contained per file.
+    const virtual = toVirtualCode(source)
+    const checkTarget = join(checkDir, `${rel}.check.tsx`)
+    await mkdir(dirname(checkTarget), { recursive: true })
+    await writeFile(checkTarget, virtual.tsx.code)
+    checks++
   }
-  return { written, outDir }
+  return { written, checks, outDir }
 }
 
 async function walk(dir: string): Promise<string[]> {

package/src/compiler/dts.ts

@@ -1,4 +1,5 @@
 import ts from 'typescript'
+import { analyzeScriptClasses } from './client-script.ts'
 import { splitStator } from './split.ts'
 
 /**
@@ -19,11 +20,36 @@ export function generateDts(
 ): string | null {
   if ((opts.kind ?? 'component') === 'route') return null
 
-  const { frontmatter, template } = splitStator(source)
+  const { frontmatter, template, scripts } = splitStator(source)
   const { hoisted, propsType } = extractFrontmatterTypes(frontmatter)
-  const propsT = componentPropsType(propsType, template)
+  let propsT = componentPropsType(propsType, template)
+  let needsReadResult = false
+
+  // Client islands declare their surface with `static attrs`, not
+  // `Stator.props`. Each attr accepts its coerced kind OR a live `read()`
+  // binding — the compiler lowers read() island props to live attr bindings,
+  // so the type surface must admit both.
+  if (!propsType && scripts.length > 0) {
+    const attrs = new Map<string, string>()
+    for (const cls of analyzeScriptClasses(scripts.join('\n'))) {
+      for (const [key, kind] of cls.staticAttrs) attrs.set(key, kind)
+    }
+    if (attrs.size > 0) {
+      needsReadResult = true
+      const fields = [...attrs]
+        .map(([key, kind]) => `${key}?: ${kind} | __SReadResult<${kind}>`)
+        .join('; ')
+      // Declared attrs are typed strictly; the open tail admits the richer
+      // props an island's SERVER-rendered markup may consume (they never
+      // cross the attr wire, so `static attrs` can't know about them).
+      propsT = `{ ${fields} } & { [prop: string]: unknown }`
+    }
+  }
 
   const lines = ["import type { HtmlFragment } from '@statorjs/stator/template'"]
+  if (needsReadResult) {
+    lines.push("import type { ReadResult as __SReadResult } from '@statorjs/stator/template'")
+  }
   if (hoisted) lines.push(hoisted)
   lines.push('')
   lines.push(`declare const _default: (props: ${propsT}) => HtmlFragment`)

package/src/compiler/virtual-code.ts

@@ -180,13 +180,137 @@ function buildServerTsx(regions: ScannedRegions): VirtualFile {
     code += `${seg.text}\n`
   }
   code += '  return (<>'
-  push(mappings, tplOffset, code.length, tpl.length)
-  code += tpl
+  code = appendTemplateTsx(code, mappings, tpl, tplOffset)
   code += '</>);\n}\n'
 
   return { lang: 'tsx', code, mappings }
 }
 
+/** HTML void elements — legal unclosed in templates, not in TSX. */
+const VOID_TAGS = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'source',
+  'track',
+  'wbr',
+])
+
+/**
+ * Append the template to the virtual TSX with HTML→TSX compatibility applied
+ * AND offset mappings kept exact around every edit:
+ *   - HTML comments: dropped (not JSX),
+ *   - `is:inline` scripts: body blanked to `<script />` (raw JS can't parse
+ *     as JSX children, and typechecking it as TSX would be meaningless),
+ *   - void elements: self-closed (`<input>` → `<input />`).
+ * The walk is brace- and quote-aware so attribute expressions
+ * (`checked={(t) => t.done}`, `title="a > b"`) are never rewritten. Verbatim
+ * runs get 1:1 mappings; inserted text maps to nothing; dropped source simply
+ * has no generated counterpart. Both the editor (Volar) and the emitted
+ * `.stator/check` files share this one surface.
+ */
+function appendTemplateTsx(
+  code: string,
+  mappings: VirtualMapping[],
+  tpl: string,
+  tplOffset: number,
+): string {
+  let out = code
+  let i = 0
+  let runStart = 0
+
+  const flush = (end: number): void => {
+    if (end > runStart) {
+      push(mappings, tplOffset + runStart, out.length, end - runStart)
+      out += tpl.slice(runStart, end)
+    }
+  }
+
+  while (i < tpl.length) {
+    if (tpl.startsWith('<!--', i)) {
+      flush(i)
+      const end = tpl.indexOf('-->', i)
+      i = end === -1 ? tpl.length : end + 3
+      runStart = i
+      continue
+    }
+    if (/^<script\b/i.test(tpl.slice(i, i + 8))) {
+      flush(i)
+      const end = tpl.toLowerCase().indexOf('</script>', i)
+      out += '<script />'
+      i = end === -1 ? tpl.length : end + '</script>'.length
+      runStart = i
+      continue
+    }
+    if (tpl[i] === '{') {
+      i = expressionEnd(tpl, i)
+      continue
+    }
+    if (tpl[i] === '<' && /[a-zA-Z]/.test(tpl[i + 1] ?? '')) {
+      const tag = /^[a-zA-Z][\w-]*/.exec(tpl.slice(i + 1))![0]
+      let j = i + 1 + tag.length
+      while (j < tpl.length) {
+        const ch = tpl[j]!
+        if (ch === '"' || ch === "'") {
+          const q = tpl.indexOf(ch, j + 1)
+          j = q === -1 ? tpl.length : q + 1
+          continue
+        }
+        if (ch === '{') {
+          j = expressionEnd(tpl, j)
+          continue
+        }
+        if (ch === '>') break
+        j++
+      }
+      if (VOID_TAGS.has(tag.toLowerCase()) && j < tpl.length) {
+        // Self-close unless the author already did.
+        let k = j - 1
+        while (k > i && /\s/.test(tpl[k]!)) k--
+        if (tpl[k] !== '/') {
+          flush(j)
+          out += ' /'
+          runStart = j // continue the run at the original `>`
+        }
+      }
+      i = j + 1
+      continue
+    }
+    i++
+  }
+  flush(tpl.length)
+  return out
+}
+
+/** Index just past the `}` closing the expression opened at `start` (which
+ *  must point at `{`), respecting nested braces and string/template literals. */
+function expressionEnd(tpl: string, start: number): number {
+  let depth = 0
+  let quote: string | null = null
+  for (let i = start; i < tpl.length; i++) {
+    const ch = tpl[i]!
+    if (quote !== null) {
+      if (ch === '\\') i++
+      else if (ch === quote) quote = null
+      continue
+    }
+    if (ch === '"' || ch === "'" || ch === '`') quote = ch
+    else if (ch === '{') depth++
+    else if (ch === '}') {
+      depth--
+      if (depth === 0) return i + 1
+    }
+  }
+  return tpl.length
+}
+
 interface FmSegment {
   sourceOffset: number
   text: string

package/src/engine/actor.ts

@@ -31,6 +31,12 @@ export interface Actor<C, E extends EventObject> {
   ): () => void
   /** Compact snapshot for the Store / client hydration seed. */
   getPersistedSnapshot(): Snapshot<C>
+  /** Host acknowledgment that the entry effect `effectId` SETTLED (completion
+   *  delivered or null-resolved): clears the snapshot's pendingEntry marker so
+   *  hydration stops re-invoking it. No-op on mismatch (the state moved on and
+   *  the marker already belongs to a different invocation). Returns whether a
+   *  marker was cleared — the host persists when true. */
+  settleEntry(effectId: string): boolean
 }
 
 /** The "top type" for an actor — same variance argument as `AnyMachineDef`:
@@ -68,8 +74,19 @@ export interface CreateActorOptions<C> {
    *  config; `ctx` is the current context (for context-dependent delays). */
   onStateEnter?: (stateKey: string, ctx: C) => void
   /** Host hook: a state was LEFT (a value-changing transition). The server uses
-   *  it to cancel that state's `after` timers. */
+   *  it to cancel that state's `after` timers and abort its entry effect. */
   onStateExit?: (stateKey: string) => void
+  /** Host hook: a HYDRATED actor started — the state was restored, not entered.
+   *  The server uses it to re-arm `after` timers with elapsed credit
+   *  (`enteredAt`) and, when `pendingEntry` reports an unsettled entry effect,
+   *  to re-invoke it via `refireEntry` (same effectId — idempotency keys hold
+   *  across the retry). `pendingEntry` is only reported when the restored state
+   *  still declares an entry effect. */
+  onStateRestore?: (
+    stateKey: string,
+    ctx: C,
+    info: { enteredAt?: number; pendingEntry?: { effectId: string }; refireEntry: () => void },
+  ) => void
 }
 
 /** Unique per-invocation effect id — usable as an idempotency key, so it must
@@ -104,9 +121,12 @@ export function createActor<C extends object, E extends EventObject, S extends s
     ? (structuredClone(opts.snapshot.context) as C)
     : (structuredClone(def.context) as C)
   // Hydrated actors have already lived: their current state's entry effect fired
-  // when it was entered, so `start()` must NOT re-fire it. Fresh actors (no
-  // snapshot) enter their initial state for the first time.
+  // when it was entered, so `start()` must NOT blanket-re-fire it — the host
+  // decides via `onStateRestore` (re-invoke only while `pendingEntry` reports
+  // an unsettled completion). Fresh actors enter their initial state for real.
   const hydrated = opts.snapshot !== undefined
+  let enteredAt: number | undefined = opts.snapshot?.enteredAt
+  let pendingEntry: { effectId: string } | undefined = opts.snapshot?.pendingEntry
 
   const subscribers = new Set<(s: Snapshot<C>) => void>()
   const emitListeners = new Map<string, Set<(e: EmittedEvent) => void>>()
@@ -116,7 +136,12 @@ export function createActor<C extends object, E extends EventObject, S extends s
 
   let commits = 0
 
-  const snapshot = (): Snapshot<C> => ({ value: [...value], context })
+  const snapshot = (): Snapshot<C> => ({
+    value: [...value],
+    context,
+    ...(enteredAt !== undefined ? { enteredAt } : {}),
+    ...(pendingEntry !== undefined ? { pendingEntry } : {}),
+  })
 
   const notify = (): void => {
     const snap = snapshot()
@@ -128,15 +153,20 @@ export function createActor<C extends object, E extends EventObject, S extends s
   // event. Firing does NOT bump `commits` (an entry is not a committed
   // transition); the server persists an entry-firing machine via the host's
   // pending-effects queue instead (see server/session-runtime.ts).
-  const fireEntryEffect = (stateKey: string): void => {
+  const fireEntryEffect = (stateKey: string, reuseEffectId?: string): void => {
     const entry = def.states[stateKey]?.entry
     if (!entry) return
-    const effectId = newEffectId()
+    // A re-invocation keeps its logical id, so idempotency keys threaded to
+    // external calls hold across the retry.
+    const effectId = reuseEffectId ?? newEffectId()
+    pendingEntry = { effectId }
     const ctxSnapshot = structuredClone(context)
     const invocation: EffectInvocation = {
       machineName: def.name,
       effectId,
-      run: () => Promise.resolve(entry(ctxSnapshot, { effectId })),
+      kind: 'entry',
+      stateKey,
+      run: (signal) => Promise.resolve(entry(ctxSnapshot, { effectId, signal })),
     }
     if (opts.onEffect) {
       opts.onEffect(invocation)
@@ -144,6 +174,7 @@ export function createActor<C extends object, E extends EventObject, S extends s
       void invocation
         .run()
         .then((completion) => {
+          actor.settleEntry(effectId)
           if (completion) actor.send(completion as E)
         })
         .catch((err) => {
@@ -164,11 +195,23 @@ export function createActor<C extends object, E extends EventObject, S extends s
       if (!started) {
         started = true
         notify() // let subscribe-before-start consumers sync initial state
-        // Fresh initial-state entry (a hydrated actor already fired its).
+        const current = value[value.length - 1]!
         if (!hydrated) {
-          const initial = value[value.length - 1]!
-          fireEntryEffect(initial)
-          opts.onStateEnter?.(initial, context)
+          // Fresh initial-state entry.
+          enteredAt = Date.now()
+          fireEntryEffect(current)
+          opts.onStateEnter?.(current, context)
+        } else if (opts.onStateRestore) {
+          // Restored, not entered: hand the host what it needs to re-arm
+          // timers (elapsed credit) and recover an unsettled entry effect.
+          const pending = pendingEntry && def.states[current]?.entry ? pendingEntry : undefined
+          opts.onStateRestore(current, context, {
+            enteredAt,
+            pendingEntry: pending,
+            refireEntry: () => {
+              if (pending) fireEntryEffect(current, pending.effectId)
+            },
+          })
         }
       }
       return actor
@@ -258,7 +301,9 @@ export function createActor<C extends object, E extends EventObject, S extends s
         const invocation: EffectInvocation = {
           machineName: def.name,
           effectId,
-          run: () => Promise.resolve(effect(ctxSnapshot, evSnapshot as never, { effectId })),
+          kind: 'transition',
+          run: (signal) =>
+            Promise.resolve(effect(ctxSnapshot, evSnapshot as never, { effectId, signal })),
         }
         if (opts.onEffect) {
           opts.onEffect(invocation)
@@ -283,6 +328,8 @@ export function createActor<C extends object, E extends EventObject, S extends s
       // timers (self-transitions and action-only transitions do neither).
       if (config.to && config.to !== stateKey) {
         opts.onStateExit?.(stateKey)
+        enteredAt = Date.now()
+        pendingEntry = undefined // the old state's marker dies with it
         fireEntryEffect(config.to)
         opts.onStateEnter?.(config.to, context)
       }
@@ -294,6 +341,12 @@ export function createActor<C extends object, E extends EventObject, S extends s
     getPersistedSnapshot: snapshot,
     getCommitCount: () => commits,
 
+    settleEntry(effectId: string) {
+      if (pendingEntry?.effectId !== effectId) return false
+      pendingEntry = undefined
+      return true
+    },
+
     subscribe(listener) {
       subscribers.add(listener)
       return {

package/src/engine/types.ts

@@ -53,10 +53,14 @@ export type Guard<C, E extends EventObject, R = Record<string, any>> = (
 ) => boolean
 
 /** Passed to an effect alongside the snapshots. `effectId` is unique per
- *  invocation — thread it to external calls as an idempotency key (1.x
- *  durability implies at-least-once) and use it for log correlation. */
+ *  LOGICAL invocation — a re-invoked entry effect keeps its id, so threading it
+ *  to external calls as an idempotency key holds across retries. `signal`
+ *  aborts when the owning state is exited (entry effects only — command-role
+ *  transition effects are never aborted); wire it into fetch/etc. to stop
+ *  wasted work at the source. */
 export interface EffectMeta {
   effectId: string
+  signal?: AbortSignal
 }
 
 /**
@@ -86,10 +90,14 @@ export type Effect<C, E extends EventObject, EAll extends EventObject = EventObj
 /**
  * A state ENTRY effect: async I/O the host schedules when a state is *entered* —
  * a fresh start at the initial state, or a transition that changes the state
- * value; never on hydration. Same host-scheduled, off-lock, at-most-once
- * pipeline as a transition `Effect`, minus the event argument (a state entry has
- * no triggering event). Returns the completion event to dispatch (annotate the
- * return with your machine's event union, exactly as for `Effect`), or null.
+ * value. Entry effects are the LOAD role: how a state gets its data. The host
+ * may RE-INVOKE one on hydration when its completion never settled (a process
+ * died mid-flight), and aborts its `meta.signal` when the state is exited — so
+ * write them as re-runnable reads and put non-idempotent external writes in
+ * transition effects (the command role) instead. Same host-scheduled, off-lock
+ * pipeline as a transition `Effect`, minus the event argument (a state entry
+ * has no triggering event). Returns the completion event to dispatch (annotate
+ * the return with your machine's event union, exactly as for `Effect`), or null.
  */
 export type EntryEffect<C, EAll extends EventObject = EventObject> = (
   ctx: C,
@@ -109,11 +117,17 @@ export interface AfterEntry<C, EAll extends EventObject = EventObject> {
 }
 
 /** A scheduled effect surfaced to the host: everything needed to run it and
- *  dispatch its completion. `run` closes over the commit-time snapshots. */
+ *  dispatch its completion. `run` closes over the commit-time snapshots; the
+ *  host may pass an AbortSignal, forwarded to the effect's meta. `kind`
+ *  carries the role split — entry = re-runnable load (abortable on state
+ *  exit), transition = at-most-once command (never aborted, never re-run). */
 export interface EffectInvocation {
   machineName: string
   effectId: string
-  run: () => Promise<EventObject | null>
+  kind: 'entry' | 'transition'
+  /** The owning state — set for entry effects, for exit-abort targeting. */
+  stateKey?: string
+  run: (signal?: AbortSignal) => Promise<EventObject | null>
 }
 
 /** Object form of a transition. A bare `Action` is sugar for `{ do: fn }`.
@@ -193,6 +207,15 @@ export interface Snapshot<C> {
   /** State path. Depth-1 today (`['idle']`); extensible to hierarchy. */
   value: string[]
   context: C
+  /** Epoch ms when the current state was entered. Lets a hydrating host re-arm
+   *  `after` timers with elapsed credit (deadline = enteredAt + delay). Absent
+   *  in pre-existing snapshots — hosts treat unknown as "restart full delay". */
+  enteredAt?: number
+  /** Present while the current state's entry effect has fired but its
+   *  completion has not settled. A hydrating host uses it to re-invoke the
+   *  effect (the load role is re-runnable by contract) instead of leaving the
+   *  machine wedged waiting for a completion that died with another process. */
+  pendingEntry?: { effectId: string }
 }
 
 export type Lifecycle = 'app' | 'session'

package/src/server/dev-lint.ts

@@ -0,0 +1,112 @@
+import type { TransitionConfig } from '../engine/index.ts'
+import type { AnyMachineDef } from './define-machine.ts'
+
+/**
+ * Dev-plane lints over the machine graph. Pure analysis — the dev server logs
+ * the findings; production builds never run this.
+ */
+
+export interface PollLoopFinding {
+  machine: string
+  state: string
+  event: string
+  /** One representative cycle, e.g. ['ready', 'revalidating', 'ready']. */
+  cycle: string[]
+}
+
+/**
+ * Detect self-rescheduling poll loops on SESSION machines: a state's `after`
+ * timer sends an event whose transitions leave the state and eventually return
+ * to it, with an entry effect somewhere on the loop. That shape re-arms its
+ * own timer on every lap — server-side polling that runs for sessions nobody
+ * is watching (and, before the TTL guard, kept them alive doing it).
+ *
+ * Deliberately NOT flagged, by construction:
+ *   - after-rescue (the timer fires once into an error/terminal state — no
+ *     path back, no cycle),
+ *   - action-only or same-state `after` handlers (no state change means no
+ *     re-entry, so the timer never re-arms — not a loop),
+ *   - app machines (process housekeeping is the legitimate home for
+ *     non-durable server clocks).
+ *
+ * The steer for a real finding: put the clock on the client and the staleness
+ * policy in a guard — see the effects guide, "Who owns the clock".
+ */
+export function findPollLoops(defs: readonly AnyMachineDef[]): PollLoopFinding[] {
+  const findings: PollLoopFinding[] = []
+
+  for (const def of defs) {
+    if (def.lifecycle !== 'session') continue
+
+    // State graph over value-changing transitions only (engine semantics: a
+    // missing or same-state `to` never re-enters, so it can't re-arm).
+    const edges = new Map<string, Set<string>>()
+    for (const [stateKey, node] of Object.entries(def.states)) {
+      const targets = new Set<string>()
+      for (const raw of Object.values(node.on ?? {})) {
+        const candidates = Array.isArray(raw) ? raw : [raw]
+        for (const c of candidates) {
+          const to =
+            typeof c === 'function' ? undefined : (c as TransitionConfig<object, never, string>).to
+          if (to && to !== stateKey) targets.add(to)
+        }
+      }
+      edges.set(stateKey, targets)
+    }
+
+    const hasEntry = (s: string): boolean => def.states[s]?.entry !== undefined
+
+    for (const [stateKey, node] of Object.entries(def.states)) {
+      for (const after of node.after ?? []) {
+        const event = (after.send as { type: string }).type
+        const raw = node.on?.[event]
+        if (!raw) continue
+        const candidates = Array.isArray(raw) ? raw : [raw]
+        for (const c of candidates) {
+          const to =
+            typeof c === 'function' ? undefined : (c as TransitionConfig<object, never, string>).to
+          if (!to || to === stateKey) continue
+
+          // BFS from the after-target: can we get back to stateKey?
+          const parent = new Map<string, string>()
+          const queue = [to]
+          const seen = new Set([to])
+          let found = false
+          while (queue.length > 0 && !found) {
+            const cur = queue.shift()!
+            for (const next of edges.get(cur) ?? []) {
+              if (next === stateKey) {
+                parent.set(next, cur)
+                found = true
+                break
+              }
+              if (!seen.has(next)) {
+                seen.add(next)
+                parent.set(next, cur)
+                queue.push(next)
+              }
+            }
+          }
+          if (!found) continue
+
+          // Reconstruct one lap and require an entry effect somewhere on it —
+          // a data-load somewhere in the loop is what makes it a POLL.
+          const path: string[] = []
+          let cursor: string | undefined = stateKey
+          while (cursor !== undefined) {
+            path.push(cursor)
+            if (cursor === to) break
+            cursor = parent.get(cursor)
+          }
+          path.reverse() // [to, ..., stateKey]
+          const lap = [stateKey, ...path]
+          if (!lap.some(hasEntry)) continue
+
+          findings.push({ machine: def.name, state: stateKey, event, cycle: lap })
+        }
+      }
+    }
+  }
+
+  return findings
+}

package/src/server/dev.ts

@@ -139,6 +139,17 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
     // initial-state entry effect fires during boot and needs a live scheduler.
     runtime.wireAppEffects(store)
     await store.bootAppMachines()
+    // Dev-only lint: a session machine whose `after` timer drives a loop with
+    // a data-loading entry effect is server-side polling that runs for
+    // sessions nobody is watching. Warn with the steer, don't block.
+    for (const f of runtime.findPollLoops(defs)) {
+      console.warn(
+        `stator: session machine "${f.machine}" self-reschedules through \`after\` ` +
+          `(${f.cycle.join(' → ')} via ${f.event}) with a data-loading entry effect on the loop. ` +
+          `This polls upstream for sessions nobody is watching. Prefer a client-owned clock ` +
+          `with a staleness guard — see the effects guide, "Who owns the clock".`,
+      )
+    }
   }
   const rebuildRoutes = async (): Promise<void> => {
     routes = await runtime.discoverRoutes(routesDir, loader)

package/src/server/effects.ts

@@ -8,6 +8,46 @@ import { fanOut } from './sse.ts'
 
 const effectLog = scopedLogger('effect')
 
+/**
+ * Process-wide registry of IN-FLIGHT effect invocations. Two consumers:
+ *   - hydration re-invoke dampening: a restore hook only re-fires a pending
+ *     entry effect when its id is NOT already running in this process (normal
+ *     request traffic hydrates constantly; only a post-crash hydration finds a
+ *     pending marker with no live invocation),
+ *   - exit-abort: leaving a state aborts its entry effect's signal, stopping
+ *     wasted upstream work at the source (command-role transition effects are
+ *     never aborted).
+ * In-memory and non-durable by design — it dies with the process, exactly like
+ * the work it tracks.
+ */
+interface InFlightEffect {
+  controller: AbortController
+  scope: string
+  machineName: string
+  kind: 'entry' | 'transition'
+  stateKey?: string
+}
+const inFlight = new Map<string, InFlightEffect>()
+
+export function isEffectInFlight(effectId: string): boolean {
+  return inFlight.has(effectId)
+}
+
+/** Abort the entry effect(s) owned by (scope, machine, state) — called from the
+ *  host's state-exit hook alongside timer cancellation. */
+export function abortEntryEffects(scope: string, machineName: string, stateKey: string): void {
+  for (const fx of inFlight.values()) {
+    if (
+      fx.kind === 'entry' &&
+      fx.scope === scope &&
+      fx.machineName === machineName &&
+      fx.stateKey === stateKey
+    ) {
+      fx.controller.abort()
+    }
+  }
+}
+
 /**
  * Install the APP-plane effect scheduler on a MachineStore (injected
  * post-construction — see MachineStore.setAppEffectScheduler). App
@@ -26,26 +66,48 @@ export function wireAppEffects(store: MachineStore): void {
 
 async function runAppEffect(invocation: EffectInvocation, store: MachineStore): Promise<void> {
   const { machineName, effectId } = invocation
-  let completion: Awaited<ReturnType<EffectInvocation['run']>>
-  try {
-    completion = await invocation.run()
-  } catch (err) {
-    effectLog.error(
-      { machine: machineName, effectId, err: String(err) },
-      'effect threw — effects must catch and return their failure event; dropped',
-    )
-    return
-  }
-  if (!completion) return
+  const controller = new AbortController()
+  inFlight.set(effectId, {
+    controller,
+    scope: '@app',
+    machineName,
+    kind: invocation.kind,
+    stateKey: invocation.stateKey,
+  })
+  // The registry entry lives until the LOGICAL invocation settles — including
+  // completion delivery — so a hydration racing the completion sees it in
+  // flight and does not re-invoke.
   try {
-    const def = store.getDef(machineName)
-    if (!def) return // graph changed under us (dev reload) — drop
-    await dispatchToApp(store, def as AnyMachineDef, completion as never)
-  } catch (err) {
-    effectLog.error(
-      { machine: machineName, effectId, err: String(err) },
-      'effect completion dispatch failed',
-    )
+    let completion: Awaited<ReturnType<EffectInvocation['run']>>
+    try {
+      completion = await invocation.run(controller.signal)
+    } catch (err) {
+      effectLog.error(
+        { machine: machineName, effectId, err: String(err) },
+        'effect threw — effects must catch and return their failure event; dropped',
+      )
+      return
+    }
+    // Settle the resident app actor's pendingEntry marker directly (persisted
+    // when the machine opted in), then dispatch any completion.
+    if (invocation.kind === 'entry') {
+      if (store.appInstance(machineName)?.actor.settleEntry(effectId)) {
+        await store.persistAppMachine(machineName)
+      }
+    }
+    if (!completion) return
+    try {
+      const def = store.getDef(machineName)
+      if (!def) return // graph changed under us (dev reload) — drop
+      await dispatchToApp(store, def as AnyMachineDef, completion as never)
+    } catch (err) {
+      effectLog.error(
+        { machine: machineName, effectId, err: String(err) },
+        'effect completion dispatch failed',
+      )
+    }
+  } finally {
+    inFlight.delete(effectId)
   }
 }
 
@@ -80,30 +142,86 @@ async function runSessionEffect(
   sessionId: string,
 ): Promise<void> {
   const { machineName, effectId } = invocation
-  let completion: Awaited<ReturnType<EffectInvocation['run']>>
+  const controller = new AbortController()
+  inFlight.set(effectId, {
+    controller,
+    scope: sessionId,
+    machineName,
+    kind: invocation.kind,
+    stateKey: invocation.stateKey,
+  })
+  // The registry entry lives until the LOGICAL invocation settles — including
+  // completion delivery — so a hydration racing the completion (e.g. the
+  // completion's own re-entry) sees it in flight and does not re-invoke.
   try {
-    completion = await invocation.run()
-  } catch (err) {
-    // Backstop only — the type contract asks effects to catch and return
-    // their failure event. Never crashes the host.
-    effectLog.error(
-      { machine: machineName, effectId, err: String(err) },
-      'effect threw — effects must catch and return their failure event; dropped',
-    )
-    return
-  }
-  if (!completion) return
+    let completion: Awaited<ReturnType<EffectInvocation['run']>>
+    try {
+      completion = await invocation.run(controller.signal)
+    } catch (err) {
+      // Backstop only — the type contract asks effects to catch and return
+      // their failure event. Never crashes the host.
+      effectLog.error(
+        { machine: machineName, effectId, err: String(err) },
+        'effect threw — effects must catch and return their failure event; dropped',
+      )
+      return
+    }
+    // An entry effect that settled with no completion still clears its marker —
+    // otherwise every later hydration would re-invoke a fire-and-forget load.
+    const settles = invocation.kind === 'entry' ? effectId : undefined
+    if (!completion) {
+      if (settles) {
+        try {
+          await settleSessionEntry(store, sessionId, machineName, settles)
+        } catch (err) {
+          effectLog.error(
+            { machine: machineName, effectId, err: String(err) },
+            'entry-effect settle failed',
+          )
+        }
+      }
+      return
+    }
 
-  try {
-    await reenterSessionEvent(store, sessionId, machineName, completion)
-  } catch (err) {
-    effectLog.error(
-      { machine: machineName, effectId, err: String(err) },
-      'effect completion dispatch failed',
-    )
+    try {
+      await reenterSessionEvent(store, sessionId, machineName, completion, { settles })
+    } catch (err) {
+      effectLog.error(
+        { machine: machineName, effectId, err: String(err) },
+        'effect completion dispatch failed',
+      )
+    }
+  } finally {
+    inFlight.delete(effectId)
   }
 }
 
+/** Clear a session machine's pendingEntry marker with no event to deliver —
+ *  the null-completion settle path. Lock + hydrate + settle + persist (no TTL
+ *  refresh: this is machine activity, not user activity). */
+async function settleSessionEntry(
+  store: MachineStore,
+  sessionId: string,
+  machineName: string,
+  effectId: string,
+): Promise<void> {
+  await withSessionLock(sessionId, async () => {
+    const def = store.getDef(machineName)
+    if (!def) return
+    if ((await store.persistence.get(sessionId, machineName)) === null) return
+    const runtime = new SessionRuntime(sessionId, store)
+    try {
+      await runtime.loadGraph([def])
+      const handle = runtime.handleFor(machineName)
+      if (handle?.actor.settleEntry(effectId)) {
+        await runtime.persistTouched(new Set([machineName]), { refreshTtl: false })
+      }
+    } finally {
+      runtime.dispose()
+    }
+  })
+}
+
 /**
  * Re-enter an out-of-band event (an effect completion, or an `after` timeout)
  * through the full session event path: fresh lock, hydrate the machine (the
@@ -117,18 +235,39 @@ export async function reenterSessionEvent(
   sessionId: string,
   machineName: string,
   event: EventObject,
+  opts?: { settles?: string },
 ): Promise<void> {
   await withSessionLock(sessionId, async () => {
+    const def = store.getDef(machineName)
+    if (!def) return // machine graph changed under us (dev reload) — drop
+    // Resurrection guard: a timer or completion outliving its session must not
+    // birth a fresh machine (whose initial entry effect would fire and persist
+    // a zombie). No snapshot ⇒ the session is gone ⇒ drop.
+    if ((await store.persistence.get(sessionId, machineName)) === null) {
+      effectLog.debug(
+        { sid: sessionId, machine: machineName, event: event.type },
+        'out-of-band event for expired session dropped',
+      )
+      return
+    }
     const runtime = new SessionRuntime(sessionId, store)
     try {
-      const def = store.getDef(machineName)
-      if (!def) return // machine graph changed under us (dev reload) — drop
       // loadGraph pulls reads + subscribers transitively, so emits reach
       // cross-machine listeners like any other event.
       await runtime.loadGraph([def])
       runtime.wireSubscriptions()
       const touched = runtime.processEvent(machineName, event)
-      await runtime.persistTouched(new Set([...touched, ...runtime.entryFiredMachines()]))
+      // Settle the entry-effect marker this completion belongs to (no-op if
+      // the state moved on and the marker died with it).
+      const settled =
+        opts?.settles !== undefined &&
+        (runtime.handleFor(machineName)?.actor.settleEntry(opts.settles) ?? false)
+      const toPersist = new Set([...touched, ...runtime.entryFiredMachines()])
+      if (settled) toPersist.add(machineName)
+      // Machine activity must not extend the session's life — only real user
+      // requests refresh the TTL. Without this, a self-rescheduling machine
+      // keeps its own session immortal.
+      await runtime.persistTouched(toPersist, { refreshTtl: false })
       await fanOut(touched, { sessionId })
       // A transition or entry effect chained off this event surfaces here.
       scheduleSessionEffects(runtime, store, sessionId)

package/src/server/index.ts

@@ -22,6 +22,8 @@ export type {
   SubscribeEvent,
 } from './define-machine.ts'
 export { defineMachine, isStatorMachine } from './define-machine.ts'
+export type { PollLoopFinding } from './dev-lint.ts'
+export { findPollLoops } from './dev-lint.ts'
 export type { DiscoveryResult } from './discovery.ts'
 export { discoverMachines } from './discovery.ts'
 export type { DispatchContext } from './dispatch-context.ts'

package/src/server/machine-store.ts

@@ -2,6 +2,7 @@ import { createActor, type EffectInvocation, type Snapshot } from '../engine/ind
 import { type AppStore, InMemoryAppStore } from './app-store.ts'
 import type { AnyMachineDef, SubscribeEvent } from './define-machine.ts'
 import { recordTouch } from './dispatch-context.ts'
+import { abortEntryEffects, isEffectInFlight } from './effects.ts'
 import { createInstanceProxy, type InstanceHandle } from './instance-proxy.ts'
 import { scopedLogger } from './logger.ts'
 import { serverReadsResolver } from './reads-helpers.ts'
@@ -199,8 +200,11 @@ export class MachineStore {
               `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.`,
+              `Break the module cycle: move the DISPLAY selectors into a third machine ` +
+              `that \`reads:\` both sides (the read/write split — see the weather example's ` +
+              `PanelsMachine), or move one machine or the subscription. Note that defining ` +
+              `both machines in one module does NOT work with directory discovery, which ` +
+              `registers default exports only.`,
           )
         }
         if (!this.defs.has(sub.from.name)) {
@@ -265,7 +269,24 @@ export class MachineStore {
           // through dispatchToApp — no session, wall-clock only (revalidation,
           // circuit breakers). See armAfterTimers.
           onStateEnter: (stateKey, ctx) => armAfterTimers(this, APP_SCOPE, def, stateKey, ctx),
-          onStateExit: (stateKey) => cancelAfterTimers(APP_SCOPE, def.name, stateKey),
+          onStateExit: (stateKey) => {
+            cancelAfterTimers(APP_SCOPE, def.name, stateKey)
+            abortEntryEffects(APP_SCOPE, def.name, stateKey)
+          },
+          // A persisted app machine restoring at boot gets the same work-
+          // lifetime semantics as a hydrating session machine: timers re-arm
+          // with elapsed credit, and an unsettled entry effect re-invokes
+          // (fresh process ⇒ nothing can be in flight, but the check keeps the
+          // contract uniform).
+          onStateRestore: (stateKey, ctx, info) => {
+            armAfterTimers(this, APP_SCOPE, def, stateKey, ctx, {
+              restore: true,
+              enteredAt: info.enteredAt,
+            })
+            if (info.pendingEntry && !isEffectInFlight(info.pendingEntry.effectId)) {
+              info.refireEntry()
+            }
+          },
         }).start()
         this.appInstances.set(
           def.name,

package/src/server/session-runtime.ts

@@ -1,6 +1,7 @@
 import { createActor, type EffectInvocation, type Snapshot } 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'
@@ -72,7 +73,26 @@ export class SessionRuntime {
       // process-wide registry (server/timers.ts), not this transient runtime.
       onStateEnter: (stateKey, ctx) =>
         armAfterTimers(this.store, this.sessionId, def, stateKey, ctx),
-      onStateExit: (stateKey) => cancelAfterTimers(this.sessionId, def.name, stateKey),
+      // Exiting a state also aborts its in-flight entry effect (load role) —
+      // the completion would be guard-dropped anyway; this stops the work.
+      onStateExit: (stateKey) => {
+        cancelAfterTimers(this.sessionId, def.name, stateKey)
+        abortEntryEffects(this.sessionId, def.name, stateKey)
+      },
+      // Restored (hydrated) state: re-arm timers with elapsed credit — the
+      // deadline is enteredAt + delay, so per-request re-arms are idempotent
+      // and a deadline that passed while no process was alive fires promptly.
+      // A pendingEntry marker with no live invocation in this process is a
+      // crashed load: re-invoke it (same effectId; load role is re-runnable).
+      onStateRestore: (stateKey, ctx, info) => {
+        armAfterTimers(this.store, this.sessionId, def, stateKey, ctx, {
+          restore: true,
+          enteredAt: info.enteredAt,
+        })
+        if (info.pendingEntry && !isEffectInFlight(info.pendingEntry.effectId)) {
+          info.refireEntry()
+        }
+      },
     }).start()
     this.actors.set(
       def.name,
@@ -225,8 +245,15 @@ export class SessionRuntime {
 
   /** Write the current persisted snapshot for each touched machine back to
    *  its store: session machines to the session Store, app machines (touched
-   *  via session→app subscriptions) to the AppStore when they opted in. */
-  async persistTouched(touched: ReadonlySet<string>): Promise<void> {
+   *  via session→app subscriptions) to the AppStore when they opted in.
+   *  `refreshTtl: false` (machine-driven re-entries: timers, effect
+   *  completions) persists without extending the session's expiry — only real
+   *  user requests count as user activity. */
+  async persistTouched(
+    touched: ReadonlySet<string>,
+    opts?: { refreshTtl?: boolean },
+  ): Promise<void> {
+    const refreshTtl = opts?.refreshTtl !== false
     const ttlSeconds = this.store.sessionTtlSeconds
     for (const name of touched) {
       const handle = this.actors.get(name)
@@ -237,11 +264,15 @@ export class SessionRuntime {
         continue
       }
       const snapshot = handle.actor.getPersistedSnapshot()
-      // Every set refreshes the session's whole expiry — the user is
-      // active, so all of their machines stay alive together.
-      await this.store.persistence.set(this.sessionId, name, snapshot, {
-        ttlSeconds,
-      })
+      // 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.
+      await this.store.persistence.set(
+        this.sessionId,
+        name,
+        snapshot,
+        refreshTtl ? { ttlSeconds } : undefined,
+      )
     }
   }
 

package/src/server/timers.ts

@@ -33,9 +33,17 @@ export function cancelAfterTimers(scope: string, machineName: string, stateKey:
   timers.delete(k)
 }
 
+/** Floor for a re-armed timer whose deadline already passed while no process
+ *  was watching — fires promptly, but after the arming request's lock work. */
+const OVERDUE_FIRE_MS = 40
+
 /**
  * Arm the `after` timers declared on `stateKey` (a no-op if it declares none).
- * The host calls this when a machine ENTERS the state. Each timer, on elapse,
+ * The host calls this when a machine ENTERS the state — or, with
+ * `opts.enteredAt`, when a hydrating runtime RESTORES it: the delay is then
+ * credited with time already served (deadline = enteredAt + delay, so re-arms
+ * across requests are deadline-idempotent, and a deadline that passed while no
+ * process was alive fires promptly instead of never). Each timer, on elapse,
  * dispatches its `send` event back through the machine's normal event path —
  * a session machine through the session re-entry (fresh lock + hydrate), an app
  * machine through `dispatchToApp` (no lock; the long-lived instance is sent
@@ -49,13 +57,25 @@ export function armAfterTimers(
   def: AnyMachineDef,
   stateKey: string,
   ctx: object,
+  opts?: { restore: true; enteredAt?: number },
 ): void {
   const after = def.states[stateKey]?.after
   if (!after || after.length === 0) return
-  cancelAfterTimers(scope, def.name, stateKey)
   const k = key(scope, def.name, stateKey)
+  // Restore mode: an arm-set already ticking in this process is authoritative
+  // (same deadline by construction) — re-arming here would RESET an overdue
+  // timer's short fuse on every hydration, and a hot session could starve it
+  // forever. Restore only fills the void after a restart or lost timer. This
+  // holds even for pre-upgrade snapshots with no enteredAt (unknown elapsed
+  // time restarts the full delay — once, not per request).
+  if (opts?.restore && timers.has(k)) return
+  cancelAfterTimers(scope, def.name, stateKey)
   const handles = after.map((entry) => {
-    const delay = typeof entry.delay === 'function' ? entry.delay(ctx as never) : entry.delay
+    const declared = typeof entry.delay === 'function' ? entry.delay(ctx as never) : entry.delay
+    const delay =
+      opts?.restore && opts.enteredAt !== undefined
+        ? Math.max(declared - (Date.now() - opts.enteredAt), OVERDUE_FIRE_MS)
+        : declared
     const h = setTimeout(() => {
       timers.delete(k) // a state has one arm-set; drop the whole key on fire
       const fire =