@statorjs/stator 2.9.1 → 2.10.0-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.9.1",
+  "version": "2.10.0-next.0",
   "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, loaded natively by its own toolchain — no build step.",
   "license": "MIT",
   "type": "module",
@@ -95,7 +95,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "2.9.1"
+    "@statorjs/stator": "2.10.0-next.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/build/artifact.ts

@@ -0,0 +1,182 @@
+import { cp, readFile, stat, writeFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+
+/**
+ * The dependency half of the deploy artifact: what `dist/` needs beside its code
+ * so the target can materialize `node_modules` itself.
+ *
+ * The framework never copies `node_modules` into `dist/`. Doing so would bake
+ * the build machine's platform into the artifact — `sharp` resolves to
+ * `@img/sharp-darwin-arm64` on a Mac and `@img/sharp-linux-x64` in a container,
+ * so a traced tree ships a binary that cannot load. Installing on the target is
+ * the correct move; the artifact's job is to make that install REPRODUCIBLE.
+ *
+ * Which means the lockfile is the thing that matters. Resolving dependencies at
+ * deploy time is how a deploy picks up a transitive version nobody tested:
+ * `npm install` in production is the bug, and `npm ci` (or a frozen `pnpm
+ * install`) against a real lockfile is the fix. So:
+ *
+ *   - **A lockfile beside the app's `package.json`** means the app is
+ *     self-contained. Both files are copied VERBATIM, and the target runs
+ *     `npm ci --omit=dev` (or `pnpm install --frozen-lockfile --prod`) against
+ *     exactly what was locked. A copied manifest also keeps a frozen `pnpm
+ *     install` happy, which compares the lockfile's importer manifest against
+ *     `package.json` and rejects a synthesized one.
+ *
+ *   - **No lockfile beside it** means a workspace member: the lockfile lives at
+ *     the monorepo root and covers every package, and the manifest may declare
+ *     `workspace:*` specifiers that no registry can install. Neither file can
+ *     travel, so a manifest is SYNTHESIZED instead — every reached dependency
+ *     pinned to the version actually installed at build time, `workspace:*`
+ *     included. Direct dependencies are then exact; transitives resolve at
+ *     install. That gap is real and is reported, not hidden: for full
+ *     reproducibility a workspace app should resolve at build time instead
+ *     (`pnpm deploy --prod`, or build inside the image).
+ *
+ * Pins come from the INSTALLED tree, never from declared ranges. `npm ci`
+ * validates the lockfile against the manifest and refuses a mismatch
+ * (`Invalid: lock file's debug@4.4.3 does not satisfy debug@4.3.4`), so a pin
+ * taken from a range would break the very install this exists to enable.
+ */
+
+/** Lockfiles, in the order a package manager would be inferred from them. */
+const LOCKFILES = [
+  'pnpm-lock.yaml',
+  'package-lock.json',
+  'npm-shrinkwrap.json',
+  'yarn.lock',
+  'bun.lock',
+  'bun.lockb',
+]
+
+/** How the target should install, per lockfile — a frozen install in each case. */
+const INSTALL_COMMAND: Record<string, string> = {
+  'pnpm-lock.yaml': 'pnpm install --frozen-lockfile --prod',
+  'package-lock.json': 'npm ci --omit=dev',
+  'npm-shrinkwrap.json': 'npm ci --omit=dev',
+  'yarn.lock': 'yarn install --immutable',
+  'bun.lock': 'bun install --frozen-lockfile --production',
+  'bun.lockb': 'bun install --frozen-lockfile --production',
+}
+
+export interface ArtifactDeps {
+  /** `copied` — the app's own manifest and lockfile travelled verbatim, so the
+   *  install on the target is fully locked. `generated` — a workspace member,
+   *  so a pinned manifest was synthesized and transitives resolve at install.
+   *  `none` — no `package.json` at the app root. */
+  kind: 'copied' | 'generated' | 'none'
+  /** Files written into dist, app-relative. */
+  files: string[]
+  /** The install to run in the artifact, ready to print. */
+  install?: string
+  /** Dependencies written into a generated manifest, name → exact version. */
+  pinned?: Record<string, string>
+  /** Reached packages whose installed version could not be read; the declared
+   *  range was used instead, so their install is not exactly reproducible. */
+  unpinned?: string[]
+}
+
+const exists = (p: string): Promise<boolean> =>
+  stat(p).then(
+    () => true,
+    () => false,
+  )
+
+/**
+ * The version actually installed, by walking `node_modules` up from the app
+ * root. Deliberately not `require.resolve`: a package with strict `exports` can
+ * refuse to expose its own `package.json`, and this needs to work for every
+ * dependency, not the well-behaved ones.
+ */
+async function installedVersion(root: string, name: string): Promise<string | undefined> {
+  let dir = root
+  for (;;) {
+    const manifest = join(dir, 'node_modules', name, 'package.json')
+    try {
+      const parsed = JSON.parse(await readFile(manifest, 'utf8')) as { version?: unknown }
+      if (typeof parsed.version === 'string') return parsed.version
+    } catch {
+      // not here — keep walking up
+    }
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+}
+
+/**
+ * Write the artifact's dependency manifest into `outDir`. `packages` is the set
+ * of direct dependencies the app's code reached (`CopySet.packages`).
+ */
+export async function writeArtifactDeps(opts: {
+  root: string
+  outDir: string
+  packages: readonly string[]
+}): Promise<ArtifactDeps> {
+  const root = resolve(opts.root)
+  const outDir = resolve(opts.outDir)
+  const manifestPath = join(root, 'package.json')
+  if (!(await exists(manifestPath))) return { kind: 'none', files: [] }
+
+  const lockfile = await (async () => {
+    for (const name of LOCKFILES) if (await exists(join(root, name))) return name
+    return undefined
+  })()
+
+  // Self-contained app: both files travel as they are, and the install on the
+  // target is locked to exactly what was tested.
+  if (lockfile) {
+    await cp(manifestPath, join(outDir, 'package.json'))
+    await cp(join(root, lockfile), join(outDir, lockfile))
+    return {
+      kind: 'copied',
+      files: ['package.json', lockfile],
+      install: INSTALL_COMMAND[lockfile],
+    }
+  }
+
+  // Workspace member: synthesize a manifest whose pins come from the installed
+  // tree, so `workspace:*` becomes a real version and nothing is left to
+  // resolve for the direct dependencies.
+  const app = JSON.parse(await readFile(manifestPath, 'utf8')) as {
+    name?: string
+    version?: string
+    dependencies?: Record<string, string>
+    devDependencies?: Record<string, string>
+  }
+  const pinned: Record<string, string> = {}
+  const unpinned: string[] = []
+  for (const name of [...opts.packages].sort()) {
+    const version = await installedVersion(root, name)
+    if (version) {
+      pinned[name] = version
+      continue
+    }
+    // Nothing installed to read: fall back to whatever the app declared, and
+    // say so — this dependency's install is not exactly reproducible.
+    const declared = app.dependencies?.[name] ?? app.devDependencies?.[name]
+    if (declared && !declared.startsWith('workspace:')) pinned[name] = declared
+    else pinned[name] = '*'
+    unpinned.push(name)
+  }
+
+  const generated = {
+    name: app.name ?? 'stator-app',
+    version: app.version ?? '0.0.0',
+    private: true,
+    // dist has no package.json of its own today, so Node walks up and inherits
+    // the app's `type`. Once the artifact is the deploy root there is nothing
+    // above it to inherit from.
+    type: 'module',
+    dependencies: pinned,
+    scripts: { start: 'stator start' },
+  }
+  await writeFile(join(outDir, 'package.json'), `${JSON.stringify(generated, null, 2)}\n`)
+  return {
+    kind: 'generated',
+    files: ['package.json'],
+    install: 'npm install --omit=dev',
+    pinned,
+    ...(unpinned.length > 0 ? { unpinned } : {}),
+  }
+}

package/src/build/build.ts

@@ -1,8 +1,11 @@
 import { randomUUID } from 'node:crypto'
-import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises'
-import { dirname, join, relative, resolve, sep } from 'node:path'
+import { cp, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { dirname, join, relative, resolve } from 'node:path'
 import { compile, regionResolverFor } from '../compiler/index.ts'
 import { hashMachines } from '../server/machine-hash.ts'
+import { type ArtifactDeps, writeArtifactDeps } from './artifact.ts'
+import { type CopySet, resolveCopySet } from './copy-set.ts'
 import { bundleIslands, routeIslandMap, walkFiles } from './islands.ts'
 import { sourceId } from './source-id.ts'
 
@@ -10,7 +13,9 @@ import { sourceId } from './source-id.ts'
  * Production build: compile a `.stator` app to a `dist/` of plain `.ts` that the
  * existing `createApp` + tsx runtime serves with no Vite.
  *
- *   1. copy machines / routes / templates / static into dist
+ *   1. copy what the app's module graph reaches (see `resolveCopySet`) — the
+ *      directories its routes/machines/hooks import from, the root-level files
+ *      they open, and `static/`
  *   2. compile each `*.stator` → a sibling `*.stator.ts`, delete the `.stator`,
  *      accumulate scoped CSS; for client components also write the generated
  *      client entry as a sibling `*.stator.client.ts`
@@ -34,11 +39,16 @@ export interface BuildConfig {
   root: string
   /** Output directory. Wiped and recreated. */
   outDir: string
-  /** Subdirectories to copy into dist. Defaults to every top-level directory
-   *  in the app root except node_modules, tests, hidden dirs, and the outDir
-   *  itself — machines and routes import freely from sibling dirs (lib/,
-   *  data/), so dist must mirror the app's source shape. */
+  /** Override the copied directories entirely. Normally omitted: the copy set
+   *  is derived from the app's own module graph — see `resolveCopySet`. */
   dirs?: string[]
+  /** Extra app-relative paths to copy verbatim — the escape hatch for what no
+   *  import graph can see (a directory reached through a runtime-built path). */
+  include?: string[]
+  /** What to do about an `import()` no static analysis can follow. `error`
+   *  (the default) fails the build naming each one: a copy set that silently
+   *  omits a lazily-imported module is a production 500. */
+  untracedImports?: 'error' | 'warn'
 }
 
 export interface BuildResult {
@@ -56,6 +66,12 @@ export interface BuildResult {
    *  previous build's manifest — their sessions reset on deploy. `undefined`
    *  when there was no previous manifest to compare against. */
   resetMachines?: string[]
+  /** What the module graph said `dist/` needs, and what it left behind. The
+   *  CLI prints this — a copy set derived from code should be visible, not
+   *  inferred from what shows up in `dist/`. */
+  copySet: CopySet
+  /** How the artifact declares its dependencies, and how to install them. */
+  deps: ArtifactDeps
 }
 
 /** Shape of `dist/stator-manifest.json` (always written — carries `buildId`). */
@@ -71,27 +87,38 @@ export interface StatorManifest {
    *  `stator start` for the snapshot hydration policy; the build fails if a
    *  machine's closure cannot be bundled, so this lands in CI, not at boot. */
   machines: Record<string, string>
+  /** The config file copied into the artifact, or `null` when the app has none.
+   *  `stator start` reads config from the artifact and nowhere else, so it needs
+   *  to tell "this app has no config" from "the config didn't make the trip" —
+   *  the second is a partial copy and must fail loudly rather than silently
+   *  falling back to in-memory persistence. Absent on a dist built before this
+   *  existed, which is itself the signal to rebuild. */
+  config: string | null
+  /** The `@statorjs/stator` version that produced this artifact. */
+  statorVersion: string
 }
 
-const NEVER_COPY = new Set(['node_modules', 'tests', 'test', '__tests__'])
-
-/** Every top-level directory that can hold app source. Machines/routes
- *  import from arbitrary sibling dirs, so dist mirrors the source tree. */
-async function discoverSourceDirs(root: string, outDir: string): Promise<string[]> {
-  const outBase = relative(root, outDir).split(sep)[0]
-  const entries = await readdir(root, { withFileTypes: true })
-  return entries
-    .filter(
-      (e) =>
-        e.isDirectory() && !e.name.startsWith('.') && !NEVER_COPY.has(e.name) && e.name !== outBase,
-    )
-    .map((e) => e.name)
-}
+const statorVersion: string = (
+  createRequire(import.meta.url)('../../package.json') as { version: string }
+).version
 
 export async function buildApp(config: BuildConfig): Promise<BuildResult> {
   const root = resolve(config.root)
   const outDir = resolve(config.outDir)
-  const dirs = config.dirs ?? (await discoverSourceDirs(root, outDir))
+
+  // What dist needs, from the app's own graph rather than a directory denylist.
+  const copySet = await resolveCopySet({ root, include: config.include })
+  if (copySet.untraced.length > 0 && (config.untracedImports ?? 'error') === 'error') {
+    const where = copySet.untraced.map((u) => `  ${u.file}:${u.line}  ${u.source}`).join('\n')
+    throw new Error(
+      `stator build: ${copySet.untraced.length} dynamic import${
+        copySet.untraced.length === 1 ? '' : 's'
+      } cannot be traced, so the build cannot know what to copy:\n${where}\n` +
+        `Use a string literal (or a template literal with a fixed prefix, which is expanded), ` +
+        `list the directories it reaches in \`build.include\`, or set \`build.untracedImports: 'warn'\` to ship anyway.`,
+    )
+  }
+  const dirs = config.dirs ?? copySet.dirs
 
   // Remember the previous build's machine hashes (if any) so the build can
   // report which machines' sessions this deploy resets.
@@ -106,13 +133,19 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
     if (await exists(src)) await cp(src, join(outDir, d), { recursive: true })
   }
 
-  // A root-level middleware.ts is a single file, not a source dir — copy it too
-  // (raw TS, run under tsx/native in prod like the rest of the server).
-  const middlewareSrc = join(root, 'middleware.ts')
-  if (await exists(middlewareSrc)) await cp(middlewareSrc, join(outDir, 'middleware.ts'))
-  // Same for a root-level boot.ts (the once-at-startup hook).
-  const bootSrc = join(root, 'boot.ts')
-  if (await exists(bootSrc)) await cp(bootSrc, join(outDir, 'boot.ts'))
+  // Root-level files the graph reached: the single-file hooks (middleware.ts,
+  // boot.ts, stator.config.*) and any data file a module opens by path — an
+  // `import.meta.url`-relative SQLite file being the case that used to be
+  // missed entirely, since the old copy step only ever handled directories.
+  for (const file of copySet.files) {
+    const src = join(root, file)
+    if (!(await exists(src))) continue
+    const dest = join(outDir, file)
+    // `build.include` may name a nested file, and cp() will not create its
+    // parent for us.
+    if (file.includes('/')) await mkdir(dirname(dest), { recursive: true })
+    await cp(src, dest)
+  }
 
   // Compile every .stator into a sibling .stator.ts; collect CSS and islands.
   // The sources are deleted only after the whole set compiles — cross-file
@@ -169,12 +202,33 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
     ? Object.keys(machines).filter((k) => previous[k] !== machines[k])
     : undefined
 
+  // The dependency half of the artifact: the app's own manifest + lockfile when
+  // it has one, else a pinned manifest. Written after the tree so a generated
+  // package.json cannot be clobbered by the copy step.
+  const deps = await writeArtifactDeps({ root, outDir, packages: copySet.packages })
+
   // Always write the manifest — it carries the build-id even for an app with no
   // islands (a live route without islands still needs the reload handshake).
+  // The config file the artifact carries, by name — `copySet.files` holds it if
+  // the app has one, since the graph walk treats it as an entry point.
+  const configFile = copySet.files.find((f) => /^stator\.config\.(ts|mts|js|mjs)$/.test(f)) ?? null
   const manifest: StatorManifest =
     islands.length > 0
-      ? { buildId: randomUUID(), ...(await buildClientAssets(outDir, islands)), machines }
-      : { buildId: randomUUID(), islands: {}, routes: {}, machines }
+      ? {
+          buildId: randomUUID(),
+          ...(await buildClientAssets(outDir, islands)),
+          machines,
+          config: configFile,
+          statorVersion,
+        }
+      : {
+          buildId: randomUUID(),
+          islands: {},
+          routes: {},
+          machines,
+          config: configFile,
+          statorVersion,
+        }
   await writeFile(join(outDir, 'stator-manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
 
   return {
@@ -185,6 +239,8 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
     machines: machineFiles.length,
     machineHashMs,
     ...(resetMachines ? { resetMachines } : {}),
+    copySet,
+    deps,
   }
 }
 

package/src/build/copy-set.ts

@@ -0,0 +1,349 @@
+import { type Dirent, realpathSync } from 'node:fs'
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { builtinModules } from 'node:module'
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { build } from 'esbuild'
+import { compile, regionResolverFor } from '../compiler/index.ts'
+
+/**
+ * What `stator build` copies into `dist/` — derived from the app's own module
+ * graph, not from a list of directory names.
+ *
+ * The build used to copy every top-level directory that wasn't on a denylist,
+ * which meant runtime data (an uploads dir, a JSON cache a deploy script
+ * maintains) landed in the artifact, while a root-level file a module actually
+ * reads — `new URL('../app.db', import.meta.url)` — did not. Both failures come
+ * from the same place: guessing at the app's shape instead of asking the code.
+ *
+ * So one esbuild pass walks the graph from the entry points the FRAMEWORK
+ * itself loads — the route and machine files, plus the root single-file hooks —
+ * and everything else is copied because it was reached. `templates/`, `lib/`,
+ * `components/` are not names this module knows; they are consequences. The
+ * pass parses nothing itself: resolution is esbuild's, so tsconfig `paths`,
+ * extensionless specifiers, index files and `exports` maps behave exactly as
+ * they do at runtime, and `.stator` files are compiled on load so frontmatter
+ * imports are in the graph like any other import.
+ *
+ * Copying is DIRECTORY-granular on purpose. A module's data files — a template
+ * read with `readFile`, a fixture JSON — are invisible to any import graph, so
+ * a reached module brings its whole top-level directory along. The cost is
+ * copying a few unreferenced siblings; the alternative is a dist that is
+ * missing files nothing declared.
+ *
+ * Nothing from `node_modules` is traced or copied. A bare specifier is recorded
+ * as a direct dependency and left external, so the walk stops there and never
+ * descends into a dependency's own imports — `dist/` holds no `node_modules`,
+ * and the recorded list is the app's own dependency set, which is exactly what
+ * a manifest should declare.
+ */
+
+/** Directories whose files are entry points, by framework convention. */
+const ENTRY_DIRS = ['routes', 'machines']
+/** Root-level single-file entry points. Each is optional. */
+const ENTRY_FILES = [
+  'middleware.ts',
+  'boot.ts',
+  'stator.config.ts',
+  'stator.config.mts',
+  'stator.config.js',
+  'stator.config.mjs',
+]
+/** Directories the framework serves by path rather than importing. */
+const SERVED_DIRS = ['static']
+/** Never app source, so never worth reporting as an uncopied candidate. */
+const NEVER_SOURCE = new Set(['node_modules', 'dist', 'tests', 'test', '__tests__'])
+
+const CODE = /\.(ts|tsx|mts|cts|js|mjs|cjs|jsx|stator)$/
+const BUILTIN = new Set([...builtinModules, ...builtinModules.map((m) => `node:${m}`)])
+/** `new URL('./x', import.meta.url)` — invisible to the bundler, so read the
+ *  literal directly. Same limit as the client seam: relative string literals.
+ *  (Injecting an import instead does NOT work: esbuild's TS loader elides an
+ *  import whose binding is unused, so the injected one disappears.) */
+const URL_ASSET_RE = /new\s+URL\(\s*(['"])(\.{1,2}\/[^'"\n]+)\1\s*,\s*import\.meta\.url\s*\)/g
+/** A `node_modules` path segment, either separator. Anything under one is a
+ *  dependency, never app source — and a real app's `node_modules` sits INSIDE
+ *  its root, so root containment alone cannot tell them apart. */
+const NODE_MODULES = /[\\/]node_modules[\\/]/
+/** `import(` not followed by a string or template literal. */
+const OPAQUE_IMPORT_RE = /(?<![.\w$])import\s*\(\s*([^'"`)\s])/g
+
+const norm = (p: string): string => p.replace(/\\/g, '/')
+
+export interface UntracedImport {
+  /** App-relative file. */
+  file: string
+  line: number
+  /** The call as written, truncated. */
+  source: string
+}
+
+export interface CopySetOptions {
+  /** App source root. */
+  root: string
+  /** Extra app-relative paths (directories or files) to copy verbatim — the
+   *  escape hatch for what no import graph can see, e.g. a directory read
+   *  through a runtime-built path. */
+  include?: string[]
+}
+
+export interface CopySet {
+  /** Top-level directories to copy whole. */
+  dirs: string[]
+  /** Root-level files to copy. */
+  files: string[]
+  /** Top-level directories present in the root that nothing reached. */
+  unused: string[]
+  /** Direct dependencies: the package name behind every bare specifier the
+   *  app's own code reached. NOT transitive — a dependency is external, so it
+   *  is never loaded and its own imports are never resolved. That is the right
+   *  granularity for a generated manifest (a package manager resolves
+   *  transitives from each dependency's own package.json) and for checking
+   *  runtime imports against `dependencies` rather than `devDependencies`:
+   *  a type-only import is elided before resolution, so it never lands here. */
+  packages: string[]
+  /** Reached files outside the app root — impossible to place in `dist/`. */
+  external: string[]
+  /** Specifiers esbuild could not resolve. Not fatal here: `stator check`
+   *  typechecks the same graph and is the gate for a genuinely broken import. */
+  unresolved: string[]
+  /** `import()` calls no static analysis can follow. */
+  untraced: UntracedImport[]
+  /** App-local files the graph reached, app-relative. */
+  reached: string[]
+  ms: number
+}
+
+const exists = (p: string): Promise<boolean> =>
+  stat(p).then(
+    () => true,
+    () => false,
+  )
+
+async function walk(dir: string, match: (f: string) => boolean): Promise<string[]> {
+  const out: string[] = []
+  let entries: Dirent[]
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const e of entries) {
+    const full = join(dir, e.name)
+    if (e.isDirectory()) out.push(...(await walk(full, match)))
+    else if (match(full)) out.push(full)
+  }
+  return out
+}
+
+/**
+ * Walk the app's server graph and report what `dist/` needs. Writes nothing and
+ * runs no app code — `.stator` is compiled, everything else is only parsed.
+ */
+export async function resolveCopySet(opts: CopySetOptions): Promise<CopySet> {
+  const root = resolve(opts.root)
+  // esbuild reports REAL paths (on macOS /var is a symlink to /private/var), so
+  // classify against the real root or every reached file looks external and
+  // nothing gets copied. Same lesson as `hashMachines`.
+  const realRoot = ((): string => {
+    try {
+      return realpathSync(root)
+    } catch {
+      return root
+    }
+  })()
+  /**
+   * Is this absolute path inside the app root? `path.relative` is the only
+   * correct test on Windows: paths there are case-insensitive and esbuild's
+   * spelling of a drive letter need not match ours, so comparing normalized
+   * strings with `startsWith` reports a perfectly good in-root file as
+   * external — and across drives `relative` returns an ABSOLUTE path, which a
+   * `..` check alone would miss. (win32's `relative` lowercases before
+   * comparing; posix is unaffected.)
+   */
+  const insideRoot = (abs: string): boolean => {
+    const rel = relative(realRoot, abs)
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel)
+  }
+
+  const t0 = performance.now()
+
+  const entries: string[] = []
+  for (const dir of ENTRY_DIRS) entries.push(...(await walk(join(root, dir), (f) => CODE.test(f))))
+  for (const name of ENTRY_FILES) {
+    const p = join(root, name)
+    if (await exists(p)) entries.push(p)
+  }
+  if (entries.length === 0) {
+    throw new Error(
+      `stator build: no entry points found — expected ${ENTRY_DIRS.map((d) => `${d}/`).join(' or ')} under ${root}`,
+    )
+  }
+
+  const reached = new Set<string>()
+  const assets = new Set<string>()
+  const packages = new Set<string>()
+  const external = new Set<string>()
+  const unresolved = new Set<string>()
+  const untraced: UntracedImport[] = []
+
+  /** Record the non-import dependencies a source text carries. */
+  const scan = (text: string, file: string): string => {
+    for (const m of text.matchAll(URL_ASSET_RE)) assets.add(resolve(dirname(file), m[2]!))
+    for (const m of text.matchAll(OPAQUE_IMPORT_RE)) {
+      untraced.push({
+        file: norm(relative(realRoot, file)),
+        line: text.slice(0, m.index).split('\n').length,
+        source: `${text
+          .slice(m.index, m.index + 60)
+          .split('\n')[0]!
+          .trim()}…`,
+      })
+    }
+    return text
+  }
+
+  try {
+    await build({
+      // Unique synthetic output name per entry: a `routes/x.stator` +
+      // `routes/x.ts` pair (the GET/POST route merge) otherwise collides on one
+      // output path and fails the whole pass.
+      entryPoints: entries.map((f) => ({
+        in: f,
+        out: norm(relative(root, f)).replace(/[\\/]/g, '_').replace(/\./g, '-'),
+      })),
+      absWorkingDir: root,
+      bundle: true,
+      write: false,
+      format: 'esm',
+      platform: 'node',
+      target: 'node20',
+      outdir: join(root, '.stator-copy-set'), // virtual — write: false
+      logLevel: 'silent',
+      plugins: [
+        {
+          name: 'stator-copy-set',
+          setup(b) {
+            b.onResolve({ filter: /.*/ }, async (args) => {
+              if (args.kind === 'entry-point' || args.pluginData?.resolved) return null
+              if (BUILTIN.has(args.path)) return { path: args.path, external: true }
+
+              const r = await b.resolve(args.path, {
+                kind: args.kind,
+                importer: args.importer,
+                resolveDir: args.resolveDir,
+                pluginData: { resolved: true },
+              })
+              if (r.errors.length > 0) {
+                unresolved.add(`${args.path} (from ${norm(relative(realRoot, args.importer))})`)
+                return { path: args.path, external: true }
+              }
+              const abs = r.path
+              // Package or app file? Neither the path nor the specifier settles
+              // it alone, so both are consulted. A dependency installed the
+              // ordinary way lives UNDER the app root in `node_modules`, so
+              // containment cannot exclude it; a dependency reached through a
+              // workspace link resolves to a real path with no `node_modules`
+              // segment, so the path cannot exclude it either. Meanwhile a
+              // tsconfig `paths` alias looks exactly like a bare specifier and
+              // is app code. So: under node_modules is always a package, and
+              // outside the root a bare specifier is a package while a relative
+              // one is an app file `dist` cannot contain.
+              const bare = !args.path.startsWith('.') && !isAbsolute(args.path)
+              const inRoot = isAbsolute(abs) && insideRoot(abs)
+              if (NODE_MODULES.test(abs) || (!inRoot && bare)) {
+                if (bare) {
+                  packages.add(
+                    args.path.startsWith('@')
+                      ? args.path.split('/').slice(0, 2).join('/')
+                      : args.path.split('/')[0]!,
+                  )
+                }
+                return { path: abs, external: true }
+              }
+              if (!inRoot) {
+                external.add(norm(abs))
+                return { path: abs, external: true }
+              }
+              if (!CODE.test(abs)) {
+                assets.add(abs) // data file: recorded, never parsed
+                return { path: abs, external: true }
+              }
+              return { path: abs, pluginData: { resolved: true } }
+            })
+
+            b.onLoad({ filter: /\.stator$/ }, async (args) => {
+              reached.add(args.path)
+              const source = await readFile(args.path, 'utf8')
+              const kind = /[\\/]routes[\\/].*\.stator$/.test(args.path) ? 'route' : 'component'
+              const out = compile(source, {
+                id: args.path,
+                kind,
+                resolveRegions: regionResolverFor(args.path, source),
+              })
+              return {
+                contents: scan(out.serverCode, args.path),
+                loader: 'ts',
+                resolveDir: dirname(args.path),
+              }
+            })
+
+            b.onLoad({ filter: CODE }, async (args) => {
+              reached.add(args.path)
+              const source = await readFile(args.path, 'utf8')
+              return {
+                contents: scan(source, args.path),
+                loader: /\.(tsx|jsx)$/.test(args.path)
+                  ? 'tsx'
+                  : /\.(js|mjs|cjs)$/.test(args.path)
+                    ? 'js'
+                    : 'ts',
+                resolveDir: dirname(args.path),
+              }
+            })
+          },
+        },
+      ],
+    })
+  } catch (err) {
+    const errors = (err as { errors?: Array<{ text: string }> }).errors ?? []
+    throw new Error(
+      `stator build: could not walk the app's module graph — ${
+        errors.length > 0 ? errors.map((e) => e.text).join('; ') : (err as Error).message
+      }`,
+    )
+  }
+
+  const dirs = new Set<string>()
+  const files = new Set<string>()
+  for (const abs of [...reached, ...assets]) {
+    // Assets come from the `new URL` scan rather than resolution, so they get
+    // the same containment test the resolver hook applies.
+    if (!insideRoot(abs)) continue
+    const rel = norm(relative(realRoot, abs))
+    if (rel.includes('/')) dirs.add(rel.split('/')[0]!)
+    else files.add(rel)
+  }
+  for (const dir of SERVED_DIRS) if (await exists(join(root, dir))) dirs.add(dir)
+  for (const extra of opts.include ?? []) {
+    const rel = norm(extra).replace(/^\.\//, '').replace(/\/+$/, '')
+    if (!(await exists(join(root, rel)))) continue
+    if ((await stat(join(root, rel))).isDirectory() || !rel.includes('/')) dirs.add(rel)
+    else files.add(rel)
+  }
+
+  const topLevel = (await readdir(root, { withFileTypes: true }))
+    .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !NEVER_SOURCE.has(e.name))
+    .map((e) => e.name)
+
+  return {
+    dirs: [...dirs].sort(),
+    files: [...files].sort(),
+    unused: topLevel.filter((d) => !dirs.has(d) && d !== 'dist').sort(),
+    packages: [...packages].sort(),
+    external: [...external].sort(),
+    unresolved: [...unresolved].sort(),
+    untraced,
+    reached: [...reached].map((f) => norm(relative(realRoot, f))).sort(),
+    ms: Math.round(performance.now() - t0),
+  }
+}

package/src/build/head.ts

@@ -20,6 +20,13 @@ export async function loadProductionHead(distDir: string): Promise<{
    *  `machineHashes` so hydration compares against what was built. Absent on
    *  a dist built before hashes existed — `createApp` then hashes live. */
   machines?: Record<string, string>
+  /** The config file the artifact carries, `null` when the app has none, and
+   *  `undefined` when the manifest predates the field — which `stator start`
+   *  reads as "rebuild", since it cannot otherwise tell a config-less app from
+   *  a config that never made the trip. */
+  config?: string | null
+  /** The `@statorjs/stator` version that produced the artifact, if recorded. */
+  statorVersion?: string
 }> {
   const dist = resolve(distDir)
 
@@ -34,6 +41,8 @@ export async function loadProductionHead(distDir: string): Promise<{
   let routes: StatorManifest['routes'] = {}
   let buildId: string | undefined
   let machines: Record<string, string> | undefined
+  let config: string | null | undefined
+  let statorVersion: string | undefined
   try {
     const manifest = JSON.parse(
       await readFile(join(dist, 'stator-manifest.json'), 'utf8'),
@@ -41,6 +50,8 @@ export async function loadProductionHead(distDir: string): Promise<{
     routes = manifest.routes ?? {}
     buildId = manifest.buildId
     machines = manifest.machines
+    config = manifest.config
+    statorVersion = manifest.statorVersion
   } catch {
     // no manifest
   }
@@ -52,5 +63,11 @@ export async function loadProductionHead(distDir: string): Promise<{
       .filter(Boolean)
       .join('\n')
   }
-  return { headExtras, buildId, ...(machines ? { machines } : {}) }
+  return {
+    headExtras,
+    buildId,
+    ...(machines ? { machines } : {}),
+    ...(config !== undefined ? { config } : {}),
+    ...(statorVersion ? { statorVersion } : {}),
+  }
 }

package/src/build/index.ts

@@ -3,8 +3,12 @@
  * plain `.ts` the runtime serves with no Vite. See `buildApp`.
  */
 
+export type { ArtifactDeps } from './artifact.ts'
+export { writeArtifactDeps } from './artifact.ts'
 export type { BuildConfig, BuildResult, StatorManifest } from './build.ts'
 export { buildApp } from './build.ts'
+export type { CopySet, CopySetOptions, UntracedImport } from './copy-set.ts'
+export { resolveCopySet } from './copy-set.ts'
 export { loadProductionHead } from './head.ts'
 export type {
   BundleIslandsOptions,

package/src/cli/commands/build.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path'
 import { buildApp } from '../../build/index.ts'
+import { loadConfig } from '../config.ts'
 import type { CliContext } from '../run.ts'
 import { checkStack } from './check.ts'
 
@@ -7,12 +8,81 @@ import { checkStack } from './check.ts'
  *  server file fails the build instead of shipping silently. */
 export async function run(ctx: CliContext): Promise<void> {
   await checkStack(ctx.root)
-  const result = await buildApp({ root: ctx.root, outDir: resolve(ctx.root, 'dist') })
+  const config = await loadConfig(ctx.root)
+  const result = await buildApp({
+    root: ctx.root,
+    outDir: resolve(ctx.root, 'dist'),
+    include: config.build?.include,
+    untracedImports: config.build?.untracedImports,
+  })
+  const { copySet } = result
   process.stdout.write(
     `stator build: ${result.compiled} components → ${result.outDir}` +
       `${result.islands ? ` (${result.islands} island${result.islands === 1 ? '' : 's'})` : ''}` +
       ` · ${result.machines} machine${result.machines === 1 ? '' : 's'} hashed in ${result.machineHashMs} ms\n`,
   )
+  // What the module graph decided to copy. Printed because a copy set derived
+  // from code should be visible, not inferred from what turns up in dist/.
+  process.stdout.write(
+    `  copied: ${copySet.dirs.join(', ')}` +
+      `${copySet.files.length ? ` · ${copySet.files.length} root file${copySet.files.length === 1 ? '' : 's'} (${copySet.files.join(', ')})` : ''}` +
+      ` · graph walked in ${copySet.ms} ms\n`,
+  )
+  // How the artifact declares its dependencies — and, for a workspace member,
+  // that its transitives are not locked.
+  const { deps } = result
+  if (deps.kind === 'copied') {
+    process.stdout.write(
+      `  deps: ${deps.files.join(' + ')} copied · on the target run \`${deps.install}\`\n`,
+    )
+  } else if (deps.kind === 'generated') {
+    const n = Object.keys(deps.pinned ?? {}).length
+    process.stdout.write(
+      `  deps: no lockfile beside package.json (workspace app) — generated a package.json pinning ${n} direct dependenc${n === 1 ? 'y' : 'ies'}\n` +
+        `        on the target run \`${deps.install}\`; transitives are NOT locked, so prefer resolving at build time (\`pnpm deploy --prod\`, or build in the image)\n`,
+    )
+    if (deps.unpinned?.length) {
+      process.stdout.write(
+        `        warning: could not read an installed version for ${deps.unpinned.join(', ')} — used the declared range\n`,
+      )
+    }
+  }
+  // Layer 2 of the persistence story: whether the config DECLARES a session
+  // store is env-independent, so the build can say this soundly. Which store a
+  // declared one resolves to is not — that depends on the production
+  // environment, which a build machine does not have — so this is a notice
+  // about a shape, never a verdict about a value, and never an error: an app
+  // that wants in-memory made a real choice.
+  if (
+    result.copySet.files.some((f) => f.startsWith('stator.config.')) &&
+    !config.persistence?.session
+  ) {
+    process.stdout.write(
+      '  note: no session store configured — session state will not survive a restart' +
+        ' (see `persistence.session`, or `sessionStore({ redisUrl: process.env.REDIS_URL })`)\n',
+    )
+  }
+  if (copySet.unused.length > 0) {
+    process.stdout.write(
+      `  not copied: ${copySet.unused.join(', ')} — nothing in the app imports or opens them` +
+        ` (add to \`build.include\` if they're read at runtime)\n`,
+    )
+  }
+  if (copySet.untraced.length > 0) {
+    // Only reachable with `untracedImports: 'warn'` — the default throws.
+    process.stdout.write(
+      `  warning: ${copySet.untraced.length} untraceable dynamic import${copySet.untraced.length === 1 ? '' : 's'}` +
+        ` — dist may be missing what they load:\n${copySet.untraced
+          .map((u) => `    ${u.file}:${u.line}  ${u.source}\n`)
+          .join('')}`,
+    )
+  }
+  if (copySet.external.length > 0) {
+    process.stdout.write(
+      `  warning: ${copySet.external.length} file${copySet.external.length === 1 ? '' : 's'} reached outside the app root` +
+        ` — not copied, so dist is not self-contained:\n${copySet.external.map((f) => `    ${f}\n`).join('')}`,
+    )
+  }
   // Deploy awareness: which machines' sessions this build resets (see the
   // snapshot hydration policy — sessions never outlive the code that made them).
   if (result.resetMachines) {

package/src/cli/commands/start.ts

@@ -1,22 +1,88 @@
 import { stat } from 'node:fs/promises'
+import { createRequire } from 'node:module'
 import { resolve } from 'node:path'
 import { loadProductionHead } from '../../build/index.ts'
 import { createApp } from '../../server/index.ts'
 import { loadConfig, resolvePort } from '../config.ts'
 import type { CliContext } from '../run.ts'
 
-/** Serve a built `dist/` in production mode (no Vite). Same `stator.config.ts`
- *  as `dev` supplies the store/session/port. */
+const running: string = (
+  createRequire(import.meta.url)('../../../package.json') as { version: string }
+).version
+
+/** Same major.minor. A patch cannot change what the compiler emitted; a minor
+ *  can, and the artifact was emitted by one specific compiler. */
+const emitCompatible = (built: string, current: string): boolean =>
+  built.split('.').slice(0, 2).join('.') === current.split('.').slice(0, 2).join('.')
+
+const exists = (p: string): Promise<boolean> =>
+  stat(p).then(
+    () => true,
+    () => false,
+  )
+
+/**
+ * Serve a built artifact in production (no Vite).
+ *
+ * Everything comes from the artifact, `stator.config.ts` included. There is
+ * deliberately no fall back to the source tree: a config read from outside the
+ * artifact makes `dist/` a lie — the same build would then behave one way from
+ * a repo checkout and another way from a copied `dist/`, and a deploy that
+ * shipped only `dist/` would find no config at all and start on in-memory
+ * persistence without saying a word. It is also how two copies of a module end
+ * up live in one process: a root config importing `./lib/db.ts` while the
+ * machines import `dist/lib/db.ts` means two connections, two caches, and two
+ * versions of the same code.
+ */
 export async function run(ctx: CliContext): Promise<void> {
-  const dist = resolve(ctx.root, 'dist')
-  try {
-    await stat(resolve(dist, 'routes'))
-  } catch {
+  // The artifact can be the deploy root itself: point `--root` at a directory
+  // holding the manifest beside `routes/` and it is served in place, so `dist/`
+  // can be the only directory copied to a server.
+  const inPlace =
+    (await exists(resolve(ctx.root, 'stator-manifest.json'))) &&
+    (await exists(resolve(ctx.root, 'routes')))
+  const dist = inPlace ? resolve(ctx.root) : resolve(ctx.root, 'dist')
+
+  if (!(await exists(resolve(dist, 'routes')))) {
     throw new Error('no dist/ found — run `stator build` first')
   }
 
-  const config = await loadConfig(ctx.root)
-  const { headExtras, buildId, machines } = await loadProductionHead(dist)
+  const {
+    headExtras,
+    buildId,
+    machines,
+    config: configFile,
+    statorVersion: builtWith,
+  } = await loadProductionHead(dist)
+
+  // The artifact holds output emitted by one specific compiler. Running it
+  // against a different framework minor means the runtime and the emit
+  // disagree, and the failures are obscure — a template read that reports it
+  // was called outside a render, because two copies of the framework hold
+  // separate render state. An app whose lockfile pins an older version than
+  // the machine that built it produces exactly this, silently.
+  if (builtWith && !emitCompatible(builtWith, running)) {
+    throw new Error(
+      `this dist was compiled by @statorjs/stator ${builtWith} but ${running} is running — ` +
+        `rebuild with the installed version, or install ${builtWith} in the artifact`,
+    )
+  }
+
+  // An artifact built before the manifest recorded its config cannot be trusted
+  // to be complete: "no config" and "the config didn't travel" look identical,
+  // and guessing wrong silently downgrades persistence.
+  if (configFile === undefined) {
+    throw new Error(
+      'this dist was built by an older stator and does not record its config — run `stator build` again',
+    )
+  }
+  if (configFile !== null && !(await exists(resolve(dist, configFile)))) {
+    throw new Error(
+      `dist is incomplete: the build recorded ${configFile} but it is not in the artifact — copy the whole directory, or rebuild`,
+    )
+  }
+
+  const config = await loadConfig(dist)
   const app = await createApp({
     machinesDir: resolve(dist, 'machines'),
     routesDir: resolve(dist, 'routes'),

package/src/config.ts

@@ -73,6 +73,20 @@ export interface StatorConfig {
     /** Dev inspector toolbar (`dev` only). Default: on. */
     inspector?: boolean
   }
+  /** Production build policy (`build` only). What lands in `dist/` is derived
+   *  from the app's own module graph, so neither field is normally needed. */
+  build?: {
+    /** Extra app-relative paths (directories or files) to copy into `dist/`.
+     *  The escape hatch for what no import graph can see — a directory reached
+     *  through a runtime-built path, say `readFile('data/' + name)`. Anything
+     *  imported, or opened via a literal `new URL(..., import.meta.url)`, is
+     *  already found. */
+    include?: string[]
+    /** What to do about an `import()` whose specifier no static analysis can
+     *  follow. `error` (default) fails the build naming each one, because the
+     *  build cannot know what such a call needs; `warn` ships anyway. */
+    untracedImports?: 'error' | 'warn'
+  }
   /** Origins allowed to make cross-site writes despite the CSRF guard — exact
    *  (`https://app.example.com`) or wildcard-subdomain (`https://*.example.com`).
    *  Same-origin and same-site writes are already allowed; this is for decoupled

package/src/server/banner.ts

@@ -77,11 +77,18 @@ export function printDevBanner(info: {
  * "did it start, and where" is the one thing an operator always wants, distinct
  * from the per-request logs that `warn` intentionally suppresses.
  */
-export function printStartupNotice(info: { port: number; machines: number; routes: number }): void {
+export function printStartupNotice(info: {
+  port: number
+  machines: number
+  routes: number
+  /** Whether state survives a restart. Always shown: a deploy log should not
+   *  have to infer the persistence posture from the absence of a warning. */
+  persistence?: string
+}): void {
   const v = statorVersion()
-  const inv = `${info.machines} machine${info.machines === 1 ? '' : 's'} · ${info.routes} route${
-    info.routes === 1 ? '' : 's'
-  }`
+  const inv = `${info.machines} machine${info.machines === 1 ? '' : 's'} · ${
+    info.routes
+  } route${info.routes === 1 ? '' : 's'}${info.persistence ? ` · ${info.persistence}` : ''}`
   process.stdout.write(
     `  ${c.copper(c.bold('stator'))}${v ? c.dim(` v${v}`) : ''} ${c.dim('·')} ${c.cyan(
       `http://localhost:${info.port}/`,

package/src/server/create-app.ts

@@ -18,6 +18,7 @@ import { discoverMiddleware } from './middleware.ts'
 import { discoverRoutes } from './route-discovery.ts'
 import { setSessionSameSite } from './session.ts'
 import { InMemoryStore, type Store } from './store.ts'
+import { persistencePosture } from './store-intent.ts'
 
 export interface CreateAppConfig extends DeprecatedFlatConfig {
   machinesDir: string
@@ -169,7 +170,23 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
       return new Promise((resolveFn) => {
         const server = serve({ fetch: app.fetch, port, hostname: resolved.host }, async () => {
           // Always-on (level-independent) so `warn` prod still confirms boot.
-          printStartupNotice({ port, machines: defs.length, routes: routes.length })
+          // Persistence posture in the notice, and a warning for anything
+          // actually at risk. Silence about in-memory storage is the defect
+          // this closes: the app runs, looks healthy, and loses every session
+          // on restart.
+          const posture = persistencePosture({
+            session: sessionStore,
+            app: store.appStore,
+            machines: defs,
+            production: process.env.NODE_ENV === 'production',
+          })
+          printStartupNotice({
+            port,
+            machines: defs.length,
+            routes: routes.length,
+            persistence: posture.label,
+          })
+          for (const warning of posture.warnings) logger.warn({}, `stator: ${warning}`)
           // Run boot.ts once the server is up — its long-lived work (a poll, a
           // subscription) starts here, not during createApp, so tests that only
           // `app.fetch` never trigger it.

package/src/server/index.ts

@@ -136,3 +136,5 @@ export {
 } from './sse.ts'
 export type { Store } from './store.ts'
 export { InMemoryStore } from './store.ts'
+export type { StoreFromEnvOptions } from './store-intent.ts'
+export { appStore, sessionStore } from './store-intent.ts'

package/src/server/store-intent.ts

@@ -0,0 +1,175 @@
+import type { AppStore } from './app-store.ts'
+import { InMemoryAppStore } from './app-store.ts'
+import { CachedStore, type CachedStoreOptions } from './cached-store.ts'
+import { RedisAppStore, RedisStore } from './redis-store.ts'
+import { InMemoryStore, type Store } from './store.ts'
+
+/**
+ * Picking a store from the environment, without the silent downgrade.
+ *
+ * Every app that keeps state in Redis writes the same conditional: a URL from
+ * the environment, a durable store when it's there, in-memory when it isn't.
+ * That fallback is right for dev and for CI — a build machine has no business
+ * holding production credentials — and wrong in exactly one place, production,
+ * where it means the app runs, looks healthy, and quietly loses every session
+ * on restart. Written in userland the framework cannot tell that outcome from a
+ * deliberate choice, so it cannot say anything about it.
+ *
+ * Moving the conditional in here changes only that: the returned store carries
+ * whether in-memory was *chosen* or *fallen back to*, so startup can be silent
+ * in development and loud in production, naming the empty variable instead of
+ * reporting a generic posture.
+ *
+ * The environment stays in charge. A URL present means durable, wherever it
+ * comes from — so pointing CI at a test Redis is nothing special, it is just
+ * the variable being set. An empty or whitespace-only value counts as absent,
+ * which is what a CI system that defines every variable as `""` produces.
+ */
+
+/** Recorded on a fallback store so startup can tell it from a deliberate one.
+ *  Non-enumerable and internal: the value still satisfies `Store` exactly. */
+const INTENT = Symbol.for('stator.store.intent')
+
+interface StoreIntent {
+  /** What the app asked for. */
+  wanted: 'durable'
+  /** The config field that was empty, for the message. */
+  from: string
+}
+
+function mark<T extends object>(store: T, intent: StoreIntent): T {
+  Object.defineProperty(store, INTENT, { value: intent, enumerable: false })
+  return store
+}
+
+/** The recorded intent of a store, if it was built by these helpers. */
+export function storeIntent(store: unknown): StoreIntent | undefined {
+  if (store === null || typeof store !== 'object') return undefined
+  return (store as Record<symbol, StoreIntent | undefined>)[INTENT]
+}
+
+/** True for the framework's own in-memory adapters — the ones that do not
+ *  survive a restart. A store the app supplied is assumed durable; the
+ *  framework has no way to ask, and no business guessing. */
+export function isEphemeral(store: unknown): boolean {
+  return store instanceof InMemoryStore || store instanceof InMemoryAppStore
+}
+
+const blank = (url: string | undefined): boolean => url === undefined || url.trim() === ''
+
+export interface StoreFromEnvOptions {
+  /** Redis connection string, typically `process.env.REDIS_URL`. Absent, empty
+   *  or whitespace-only selects in-memory — normal in dev and CI, reported at
+   *  startup in production. */
+  redisUrl?: string
+  /** Wrap Redis in a write-through memory cache. Off by default: caching is a
+   *  performance decision, and this helper's job is the durable-or-not one. */
+  cache?: CachedStoreOptions | true
+  /** Key prefix, passed through to the Redis adapter. */
+  keyPrefix?: string
+  /** Name used in the startup report when the URL is empty. Default `REDIS_URL`. */
+  envName?: string
+}
+
+/**
+ * Session-machine storage from the environment: Redis when a URL is set,
+ * in-memory otherwise.
+ *
+ *   persistence: { session: sessionStore({ redisUrl: process.env.REDIS_URL }) }
+ *
+ * Call it with nothing (or omit `persistence.session` entirely) to choose
+ * in-memory deliberately — that is a real choice and is never reported.
+ */
+export function sessionStore(opts: StoreFromEnvOptions = {}): Store {
+  if (blank(opts.redisUrl)) {
+    // In-memory either way, but for two different reasons. Passing the key at
+    // all — `redisUrl: process.env.REDIS_URL` — says the app wants durability
+    // from the environment, so an empty value is worth reporting in production.
+    // Passing no key says in-memory was the choice, which is never reported.
+    return 'redisUrl' in opts
+      ? mark(new InMemoryStore(), { wanted: 'durable', from: opts.envName ?? 'REDIS_URL' })
+      : new InMemoryStore()
+  }
+  const redis = opts.keyPrefix
+    ? new RedisStore(opts.redisUrl as string, opts.keyPrefix)
+    : new RedisStore(opts.redisUrl as string)
+  if (!opts.cache) return redis
+  return new CachedStore(redis, opts.cache === true ? {} : opts.cache)
+}
+
+/**
+ * App-machine storage (`persist: true`) from the environment. Same rule as
+ * `sessionStore`.
+ */
+export function appStore(opts: StoreFromEnvOptions = {}): AppStore {
+  if (blank(opts.redisUrl)) {
+    return 'redisUrl' in opts
+      ? mark(new InMemoryAppStore(), { wanted: 'durable', from: opts.envName ?? 'REDIS_URL' })
+      : new InMemoryAppStore()
+  }
+  return opts.keyPrefix
+    ? new RedisAppStore(opts.redisUrl as string, opts.keyPrefix)
+    : new RedisAppStore(opts.redisUrl as string)
+}
+
+/** One machine's persistence-relevant shape. */
+export interface MachinePersistence {
+  lifecycle: string
+  persist: boolean
+}
+
+/**
+ * What to say about persistence at startup. The posture goes in the notice —
+ * printed at every level, so a deploy log always states whether state survives
+ * a restart — and anything worth alerting on comes back as a warning.
+ *
+ * Warnings fire in production only, and only when something is actually at
+ * risk: an app with no session machines has no session state to lose, and an
+ * app that deliberately chose in-memory made a real choice. Nothing here ever
+ * refuses to start; persistent storage is assumed to be wanted, never required.
+ */
+export function persistencePosture(input: {
+  session: unknown
+  app: unknown
+  machines: readonly MachinePersistence[]
+  production: boolean
+}): { label: string; warnings: string[] } {
+  const name = (store: unknown): string =>
+    isEphemeral(store)
+      ? 'in-memory'
+      : ((store as { constructor?: { name?: string } })?.constructor?.name ?? 'custom')
+
+  const sessionMachines = input.machines.filter((m) => m.lifecycle === 'session').length
+  const persistedApp = input.machines.filter((m) => m.lifecycle === 'app' && m.persist).length
+
+  let label = `sessions ${name(input.session)}`
+  if (persistedApp > 0) label += ` · app ${name(input.app)}`
+
+  const warnings: string[] = []
+  if (input.production) {
+    const sessionIntent = storeIntent(input.session)
+    if (isEphemeral(input.session) && sessionIntent) {
+      // The app configured a durable store and the variable was empty — the
+      // one case the framework can name precisely.
+      warnings.push(
+        `${sessionIntent.from} is empty, so session state is in memory and will not survive a restart`,
+      )
+    } else if (isEphemeral(input.session) && sessionMachines > 0) {
+      warnings.push(
+        `no durable session store is configured, so the state of ${sessionMachines} session machine${
+          sessionMachines === 1 ? '' : 's'
+        } will not survive a restart`,
+      )
+    }
+
+    const appIntent = storeIntent(input.app)
+    if (isEphemeral(input.app) && persistedApp > 0) {
+      warnings.push(
+        appIntent
+          ? `${appIntent.from} is empty, so ${persistedApp} persisted app machine${persistedApp === 1 ? '' : 's'} will not survive a restart`
+          : `no durable app store is configured, so ${persistedApp} persisted app machine${persistedApp === 1 ? '' : 's'} will not survive a restart`,
+      )
+    }
+  }
+  return { label, warnings }
+}