toiljs 0.0.59 → 0.0.61

package/src/cli/create.ts

@@ -40,6 +40,38 @@ import { isPackageManager, isValidName, resolveProjectDir } from './validate.js'
 
 export type Template = 'app' | 'minimal';
 
+/**
+ * The `server/migrations/` README, scaffolded by `create` and ensured by `doctor`/`update`. ToilDB
+ * migrations are enforced by convention: a `@migrate` function MUST live in a `*.migration.ts` file
+ * under a `migrations/` folder (the toilscript compiler raises a compile error otherwise), and the
+ * build auto-discovers every such file. Keeping the convention documented next to the folder means a
+ * fresh project ships with a place to evolve `@data` value types from day one.
+ */
+export const MIGRATIONS_README =
+    '# migrations/\n\n' +
+    'ToilDB schema migrations. One file per evolving `@data` value type, named `<Type>.migration.ts`\n' +
+    '(e.g. `User.migration.ts`).\n\n' +
+    'Each file keeps the OLD `@data` shapes (e.g. `UserV1`) alongside the `@migrate` transform(s) that\n' +
+    'carry old records forward, and imports the CURRENT value type from the app. The build\n' +
+    'auto-discovers every `*.migration.ts` under the project.\n\n' +
+    'Do NOT put `@migrate` anywhere else: a `@migrate` outside a `*.migration.ts` file in a\n' +
+    '`migrations/` folder is a compile error.\n\n' +
+    '## Example\n\n' +
+    '`User.migration.ts`:\n\n' +
+    '```ts\n' +
+    "import { User } from '../models/User';\n\n" +
+    '// The previous on-disk shape of a User record.\n' +
+    '@data\n' +
+    'export class UserV1 {\n' +
+    "    name: string = '';\n" +
+    '}\n\n' +
+    '// Carry a UserV1 forward into the current User. Runs once per record on read.\n' +
+    '@migrate\n' +
+    'export function up(old: UserV1, into: User): void {\n' +
+    '    into.name = old.name;\n' +
+    '}\n' +
+    '```\n';
+
 /** Human label for each preprocessor in the styling picker. */
 const PREPROCESSOR_LABEL: Record<Preprocessor, string> = {
     css: 'Plain CSS',
@@ -114,7 +146,7 @@ function scaffold(
         '@types/react-dom': '^19.2.3',
         eslint: '^10.2.0',
         prettier: '^3.8.1',
-        toilscript: '^0.1.36',
+        toilscript: '^0.1.37',
         typescript: '^6.0.3',
     };
     for (const dep of requiredPackages(features).sort()) {
@@ -163,9 +195,9 @@ function scaffold(
         // Generated files don't need formatting. (toilscript server decorators like @main /
         // @remote-on-functions are handled by the toiljs/prettier-plugin, so server/ is not ignored.)
         '.prettierignore':
-            'node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\nserver/_emails.ts\nserver/toil-server-env.d.ts\n',
+            'node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\nserver/_emails.ts\nserver/_ssr/\nserver/toil-server-env.d.ts\n',
         '.gitignore':
-            'node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\nhosts/*/_tmpl/\n# Local dev env vars/secrets (never commit)\n.env\n.env.secrets\n',
+            'node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\nserver/_ssr/\nhosts/*/_tmpl/\n# Local dev env vars/secrets (never commit)\n.env\n.env.secrets\n',
         // Use the project's pinned TypeScript (node_modules) instead of VS Code's bundled
         // version, and prompt to switch, so the editor loads the toilscript LS plugin wired
         // in server/tsconfig.json (which clears the @database / @data editor false positives).
@@ -259,6 +291,10 @@ function scaffold(
             '    npm run build',
             '',
         ].join('\n'),
+        // ToilDB migrations live under server/migrations/ (folder + `*.migration.ts` is enforced by
+        // the compiler; the build auto-discovers them). Ship the folder, documented, with no live
+        // *.migration.ts: a @migrate referencing types a fresh project lacks would break the build.
+        'server/migrations/README.md': MIGRATIONS_README,
     };
 
     // The `app` template's client UI + server are copied from examples/basic at runtime; `minimal`
@@ -377,6 +413,7 @@ function minimalServer(): Record<string, string> {
             '| `main.ts` | The entry point: wires the handler and imports the surface modules. |\n' +
             '| `core/` | The request handler and shared app logic (state, helpers). |\n' +
             '| `models/` | `@data` classes, the typed wire model shared by HTTP and RPC. One type per file. |\n' +
+            '| `migrations/` | ToilDB schema migrations: a `<Type>.migration.ts` per evolving `@data` value type, holding the old shapes + the `@migrate` transform. |\n' +
             '| `routes/` | `@rest` controllers (HTTP). One controller per file, named after its class. |\n' +
             '| `services/` | `@service` classes and free `@remote` functions (typed RPC). |\n' +
             '| `scheduled/` | Reserved for scheduled tasks (not shipped yet). |\n\n' +

package/src/cli/db.ts

@@ -0,0 +1,158 @@
+/**
+ * `toiljs db <action>` — manage the dev server's on-disk ToilDB data.
+ *
+ * Under `toiljs dev`, the in-process ToilDB emulator persists every family
+ * (records / views / unique / events / membership / counter / capacity) plus each
+ * row's schema_version to `<root>/.toil/devdata.json` (so data + migrations survive
+ * restarts). These subcommands let you inspect, reset, snapshot, and restore that
+ * store from outside a running server — handy for fixtures, sharing repro data, or
+ * wiping a corrupt dev state. The snapshot is the exact JSON the dev DB writes, so
+ * an exported file imports cleanly (and a hand-crafted one seeds the dev DB).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { accent, bold, danger, dim, success, warn } from './ui.js';
+
+export interface DbOptions {
+    /** Project root (where `.toil/` lives); defaults to the current directory. */
+    root?: string;
+}
+
+/** The top-level families a valid snapshot carries (mirrors DbSnapshot). */
+const FAMILIES = ['store', 'views', 'members', 'counters', 'events', 'eventDedup', 'capacity'] as const;
+
+function devdataPath(opts: DbOptions): string {
+    return path.join(path.resolve(opts.root ?? process.cwd()), '.toil', 'devdata.json');
+}
+
+function out(line: string): void {
+    process.stdout.write(line + '\n');
+}
+
+/** Per-family key counts for a snapshot file, or null if unreadable. */
+function familyCounts(file: string): Record<string, number> | null {
+    let snap: Record<string, unknown>;
+    try {
+        snap = JSON.parse(fs.readFileSync(file, 'utf8')) as Record<string, unknown>;
+    } catch {
+        return null;
+    }
+    const counts: Record<string, number> = {};
+    for (const f of FAMILIES) {
+        const fam = snap[f];
+        counts[f] = fam && typeof fam === 'object' ? Object.keys(fam).length : 0;
+    }
+    return counts;
+}
+
+function isSnapshot(v: unknown): boolean {
+    return typeof v === 'object' && v !== null && FAMILIES.every((f) => f in (v as object));
+}
+
+/** Run `toiljs db <action> [fileArg]`. */
+export function runDb(action: string | undefined, fileArg: string | undefined, opts: DbOptions): void {
+    const file = devdataPath(opts);
+    const rel = path.relative(process.cwd(), file) || file;
+
+    switch (action) {
+        case 'reset':
+        case 'purge': {
+            if (!fs.existsSync(file)) {
+                out(dim(`  dev database already empty (${rel} not found)`));
+                return;
+            }
+            fs.rmSync(file);
+            out(success('  ✓ ') + 'dev database reset ' + dim(`(${rel} deleted)`));
+            return;
+        }
+
+        case 'export': {
+            if (!fs.existsSync(file)) {
+                out(warn('  ! ') + `nothing to export (${rel} not found)`);
+                process.exitCode = 1;
+                return;
+            }
+            let pretty: string;
+            try {
+                pretty = JSON.stringify(JSON.parse(fs.readFileSync(file, 'utf8')), null, 2) + '\n';
+            } catch {
+                out(danger('  ✗ ') + `the dev database at ${rel} is unreadable`);
+                process.exitCode = 1;
+                return;
+            }
+            if (fileArg === undefined) {
+                process.stdout.write(pretty); // no banner/prefix -> pipe-friendly
+                return;
+            }
+            fs.writeFileSync(path.resolve(fileArg), pretty);
+            out(success('  ✓ ') + 'exported dev database to ' + dim(fileArg));
+            return;
+        }
+
+        case 'import': {
+            if (fileArg === undefined) {
+                out(danger('  ✗ ') + 'usage: ' + dim('toiljs db import <file>'));
+                process.exitCode = 1;
+                return;
+            }
+            let parsed: unknown;
+            try {
+                parsed = JSON.parse(fs.readFileSync(path.resolve(fileArg), 'utf8'));
+            } catch (e) {
+                out(danger('  ✗ ') + `cannot read/parse ${fileArg}: ${(e as Error).message}`);
+                process.exitCode = 1;
+                return;
+            }
+            if (!isSnapshot(parsed)) {
+                out(danger('  ✗ ') + `${fileArg} is not a toiljs dev database snapshot`);
+                process.exitCode = 1;
+                return;
+            }
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, JSON.stringify(parsed)); // compact: the dev DB's on-disk form
+            out(success('  ✓ ') + `imported dev database from ${dim(fileArg)} ` + dim(`(${rel})`));
+            return;
+        }
+
+        case 'path':
+            out(file); // bare path, scriptable
+            return;
+
+        case 'status':
+        case 'info': {
+            out(bold('  dev database') + dim(`  ${rel}`));
+            if (!fs.existsSync(file)) {
+                out(dim('  (empty — no data written yet; run the dev server to populate it)'));
+                return;
+            }
+            const counts = familyCounts(file);
+            if (counts === null) {
+                out(danger('  ✗ unreadable snapshot'));
+                process.exitCode = 1;
+                return;
+            }
+            out(dim(`  ${(fs.statSync(file).size / 1024).toFixed(1)} KiB`));
+            const nonEmpty = FAMILIES.filter((f) => counts[f] > 0);
+            if (nonEmpty.length === 0) out(dim('  (no rows)'));
+            else for (const f of nonEmpty) out('  ' + accent(f.padEnd(12)) + String(counts[f]));
+            return;
+        }
+
+        default:
+            out(
+                [
+                    bold('Usage') + '  ' + dim('toiljs db') + ' <action>',
+                    '',
+                    bold('Actions'),
+                    '  ' + accent('status'.padEnd(16)) + dim('show the dev DB path + per-family row counts'),
+                    '  ' + accent('reset'.padEnd(16)) + dim('delete all dev data (alias: purge)'),
+                    '  ' + accent('export [file]'.padEnd(16)) + dim('write a snapshot to <file> (or stdout)'),
+                    '  ' + accent('import <file>'.padEnd(16)) + dim('replace the dev DB with a snapshot'),
+                    '  ' + accent('path'.padEnd(16)) + dim('print the devdata.json path'),
+                ].join('\n'),
+            );
+            if (action !== undefined) process.exitCode = 1; // unknown action
+            return;
+    }
+}

package/src/cli/diagnostics.ts

@@ -521,6 +521,25 @@ export function checkServerTsPlugin(present: boolean): Check {
           };
 }
 
+/**
+ * Whether the server has a `migrations/` folder. ToilDB `@migrate` functions MUST live in a
+ * `*.migration.ts` file under `migrations/` (the toilscript compiler enforces folder + extension as
+ * a compile error), and the build auto-discovers them, so a server project should keep the folder
+ * ready. Older projects predate the convention, so this WARNS (does not fail) and points at the
+ * one-command fix (`toiljs update` creates it).
+ */
+export function checkMigrationsDir(exists: boolean): Check {
+    return exists
+        ? { id: 'migrations-dir', label: 'server/migrations/ directory', status: 'pass' }
+        : {
+              id: 'migrations-dir',
+              label: 'server/migrations/ directory',
+              status: 'warn',
+              detail: 'no server/migrations/ folder; ToilDB @migrate functions must live in a *.migration.ts file under it',
+              fix: 'Create server/migrations/ (one <Type>.migration.ts per evolving @data value type), or run `toiljs update` to add it.',
+          };
+}
+
 // --- Security -------------------------------------------------------------------------------------
 
 /** Whether the project uses the auth primitive, and whether its session secret is configured. */

package/src/cli/doctor.ts

@@ -27,6 +27,7 @@ import {
     checkDir,
     checkDuplicatePatterns,
     type CheckGroup,
+    checkMigrationsDir,
     checkMountSlots,
     checkNode,
     checkPackageManager,
@@ -279,6 +280,24 @@ function serverTsconfigPath(root: string, toilconfig: Record<string, unknown> |
     return null;
 }
 
+/**
+ * Whether a `migrations/` folder exists under any server dir (the dir of a toilconfig entry,
+ * conventionally `server/`). ToilDB `@migrate` functions live in `*.migration.ts` files there, and
+ * the build auto-discovers them; a missing folder is a warn, not a fail (older projects predate it).
+ */
+function serverMigrationsExist(root: string, toilconfig: Record<string, unknown> | null): boolean {
+    const dirs = new Set<string>();
+    const entries = Array.isArray(toilconfig?.entries)
+        ? (toilconfig.entries as unknown[]).filter((e): e is string => typeof e === 'string')
+        : [];
+    for (const e of entries) dirs.add(path.dirname(path.resolve(root, e)));
+    if (dirs.size === 0) dirs.add(path.join(root, 'server'));
+    for (const dir of dirs) {
+        if (fs.existsSync(path.join(dir, 'migrations'))) return true;
+    }
+    return false;
+}
+
 /** Whether a parsed tsconfig's `compilerOptions.plugins` references the toilscript LS plugin. */
 function tsconfigHasToilPlugin(tsconfig: Record<string, unknown> | null): boolean {
     const plugins = asRecord(tsconfig?.compilerOptions)?.plugins;
@@ -840,6 +859,7 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
                       checkRestDispatch(restFacts),
                       checkPrettierPlugin(prettierPresent),
                       checkServerTsPlugin(serverTsPluginPresent),
+                      checkMigrationsDir(serverMigrationsExist(root, toilconfig)),
                   ]
                 : [checkToilconfig(false)],
         },

package/src/cli/index.ts

@@ -8,6 +8,7 @@ import { build, dev, start } from 'toiljs/compiler';
 
 import { runConfigure } from './configure.js';
 import { runCreate, type Template } from './create.js';
+import { runDb } from './db.js';
 import { runDoctor } from './doctor.js';
 import { notifyIfOutdated } from './notify.js';
 import { runUpdate } from './update.js';
@@ -132,6 +133,7 @@ function printHelp(): void {
             cmd('start', 'self-host the built app (hyper-express / uWS)'),
             cmd('doctor', 'diagnose project setup and dependencies'),
             cmd('update', 'check for and apply dependency updates'),
+            cmd('db <action>', 'manage dev DB data (status | reset | export | import)'),
             '',
             bold('Options'),
             cmd('--root <dir>', 'project root (default: current directory)'),
@@ -255,6 +257,14 @@ async function main(): Promise<void> {
             });
             break;
 
+        case 'db': {
+            // `toiljs db <action> [file]` — no banner so `path`/`export` pipe cleanly.
+            const action = rest[0];
+            const fileArg = rest[1] !== undefined && !rest[1].startsWith('-') ? rest[1] : undefined;
+            runDb(action, fileArg, { root: flags.root });
+            break;
+        }
+
         case 'help':
         case '--help':
         case '-h':

package/src/cli/update.ts

@@ -9,6 +9,7 @@ import path from 'node:path';
 
 import { cancel, intro, isCancel, multiselect, note, outro, spinner } from '@clack/prompts';
 
+import { MIGRATIONS_README } from './create.js';
 import { capture, run } from './proc.js';
 import { buildRows, type Bump, parseNcuJson, type UpdateRow } from './updates.js';
 import { accent, danger, dim, success, warn } from './ui.js';
@@ -49,6 +50,53 @@ function readDependencies(pkgPath: string): Record<string, string> {
     return { ...merge(pkg.dependencies), ...merge(pkg.devDependencies) };
 }
 
+/**
+ * The server dir(s) of a project: the directories of the toilconfig.json `entries`, conventionally
+ * `server/`. Falls back to `<root>/server` when there is no toilconfig (or it has no string entries),
+ * matching how `doctor` locates the server tree.
+ */
+function serverDirs(root: string): string[] {
+    const dirs = new Set<string>();
+    try {
+        const parsed: unknown = JSON.parse(
+            fs.readFileSync(path.join(root, 'toilconfig.json'), 'utf8'),
+        );
+        const entries =
+            typeof parsed === 'object' &&
+            parsed !== null &&
+            Array.isArray((parsed as { entries?: unknown }).entries)
+                ? (parsed as { entries: unknown[] }).entries.filter(
+                      (e): e is string => typeof e === 'string',
+                  )
+                : [];
+        for (const e of entries) dirs.add(path.dirname(path.resolve(root, e)));
+    } catch {
+        // no/unreadable toilconfig.json: fall back to the conventional server/ below
+    }
+    if (dirs.size === 0) dirs.add(path.join(root, 'server'));
+    return [...dirs];
+}
+
+/**
+ * Ensures the ToilDB `migrations/` folder exists under each server dir that exists. `@migrate`
+ * functions MUST live in a `*.migration.ts` file under `migrations/` (folder + extension is a
+ * compile error otherwise) and the build auto-discovers them, so an up-to-date project keeps the
+ * folder ready. Idempotent: only writes the folder + README where the server dir exists and the
+ * folder is absent. Returns the project-relative paths created (for the note), empty if nothing.
+ */
+function ensureMigrationsDirs(root: string): string[] {
+    const created: string[] = [];
+    for (const dir of serverDirs(root)) {
+        if (!fs.existsSync(dir)) continue;
+        const migrations = path.join(dir, 'migrations');
+        if (fs.existsSync(migrations)) continue;
+        fs.mkdirSync(migrations, { recursive: true });
+        fs.writeFileSync(path.join(migrations, 'README.md'), MIGRATIONS_README);
+        created.push(path.relative(root, migrations) || 'migrations');
+    }
+    return created;
+}
+
 function bumpColor(bump: Bump, text: string): string {
     if (bump === 'major') return danger(text);
     if (bump === 'minor') return warn(text);
@@ -85,6 +133,16 @@ export async function runUpdate(opts: UpdateOptions): Promise<void> {
 
     intro(accent('toiljs update'));
 
+    // Bring the project's structure up to date: ensure the ToilDB migrations folder exists (it is
+    // newer than some projects, and the compiler requires @migrate functions to live under it).
+    const createdMigrations = ensureMigrationsDirs(root);
+    if (createdMigrations.length > 0) {
+        note(
+            createdMigrations.map((p) => `${dim('+')} ${p}/`).join('\n'),
+            'Created ToilDB migrations folder',
+        );
+    }
+
     const s = spinner();
     s.start('Checking the registry for updates');
     const res = await capture('npx', ncuArgs(['--jsonUpgraded']), root);

package/src/client/index.ts

@@ -102,5 +102,5 @@ export { Slot } from './components/Slot.js';
 export type { SlotProps } from './components/Slot.js';
 export { Server } from './rpc.js';
 export { parseError } from './errors.js';
-export { Hole, RawHtml, Repeat, Island, __setSsrBuild, __isSsrBuild } from './ssr/markers.js';
+export { Hole, RawHtml, Repeat, Island, attr, __setSsrBuild, __isSsrBuild } from './ssr/markers.js';
 export type { HoleProps, RawHtmlProps, RepeatProps, IslandProps } from './ssr/markers.js';

package/src/client/routing/mount.tsx

@@ -65,9 +65,15 @@ export function mount(
     // branch, and the dev-only imports, are dead-code-eliminated and tree-shaken from production.
     if ((import.meta as unknown as { env: { DEV: boolean } }).env.DEV) {
         initDevErrorOverlay();
-        createRoot(el).render(
+        // Dev tools (error overlay + toolbar) render into their OWN body-level
+        // container, never inside #root, so they don't perturb #root's markup.
+        // That lets a dev SSR document hydrate cleanly (the server only rendered
+        // the app into #root), and is harmless for a plain client-rendered page.
+        const devEl = document.createElement('div');
+        devEl.id = '__toil_dev';
+        document.body.appendChild(devEl);
+        createRoot(devEl).render(
             <>
-                <DevErrorBoundary>{app}</DevErrorBoundary>
                 <DevErrorOverlay />
                 <DevToolbar
                     routes={routes}
@@ -75,6 +81,16 @@ export function mount(
                 />
             </>,
         );
+        const tree = <DevErrorBoundary>{app}</DevErrorBoundary>;
+        if (isSsrDocument()) {
+            // Dev edge-SSR: the dev server served real server-rendered markup
+            // (guest `render` + splice); hydrate it in place, same as production,
+            // instead of client-rendering from scratch.
+            seedSsrHydration(routes);
+            hydrateRoot(el, tree);
+        } else {
+            createRoot(el).render(tree);
+        }
     } else if (isSsrDocument()) {
         // Edge-SSR: the document already holds server-rendered markup. Seed the
         // loader cache from `#__toil_state` and hydrate in place (reuse the DOM)

package/src/client/ssr/markers.tsx

@@ -76,6 +76,28 @@ export function Hole(props: HoleProps): ReactNode {
     return createElement(Fragment, null, props.children);
 }
 
+/**
+ * An attribute-value hole. Unlike the child markers, an attribute is not a child
+ * node, so this is a *function* used in attribute position rather than a JSX
+ * element:
+ *
+ * ```tsx
+ * <a href={attr('profileUrl', d.url)} class={attr('cls', d.cls)}>…</a>
+ * ```
+ *
+ * Browser: returns `value` unchanged, so the attribute renders normally. Build:
+ * returns a PUA sentinel token, so the extractor records an `attr` slot at the
+ * attribute's byte offset (the token sits between the quotes and strips to zero
+ * bytes). The guest fills it per request with the React-escaped value (kind
+ * `attr`), which the host splices at that offset — exactly like a text hole, but
+ * inside an attribute. It composes with surrounding literal text
+ * (`` `btn ${attr('x', v)}` ``), and `setAttr`/`HtmlBuilder.attr` produce the
+ * value on the server side.
+ */
+export function attr(id: string, value: string): string {
+    return ssrBuild ? token(HoleKindChar.Attr, id) : value;
+}
+
 export interface RawHtmlProps {
     id: string;
     /** Raw HTML string. The author owns sanitisation (same as React

package/src/compiler/config.ts

@@ -97,8 +97,32 @@ export interface ClientConfig {
 }
 
 /**
- * Server-side (toilscript → WASM) configuration. Reserved: the compiler does not yet
- * build the server target via `toil build`; today it is compiled by `toilscript` directly.
+ * Dev node mode: which layer the single dev process emulates. `hot` runs only the
+ * request path (today's behavior); `regional`/`continental` would run streams off
+ * `release-hot.wasm` (Phase 4); `daemon` runs `release-cold.wasm`; `all` runs every
+ * surface in one process (the default for a full local run). DEV / self-host knob;
+ * the production edge reads the authoritative role from per-host TCF + the plan.
+ */
+export type DevNodeMode = 'hot' | 'regional' | 'continental' | 'daemon' | 'all';
+
+/** Daemon (L4) config mirror (dev / self-host). All optional. */
+export interface DaemonConfig {
+    /** Region the daemon is pinned to (informational in dev; the dev process is leader). */
+    readonly region?: string;
+    /** Warm standby region (informational in dev). */
+    readonly standbyRegion?: string;
+    /** Default `@scheduled` interval (ms) when a task declares none. Default 60000. */
+    readonly defaultIntervalMs?: number;
+    /** Per-tick wall-clock budget (ms) before the dev scheduler logs an overrun. Default 30000. */
+    readonly tickBudgetMs?: number;
+    /** Per-tick gas cap (dev stub; charged-then-ignored). Mirrors `plan.gas_scheduled`. */
+    readonly gasTick?: number;
+    /** Max number of `@scheduled` tasks (mirrors `max_scheduled_tasks`). Default 64. */
+    readonly maxTasks?: number;
+}
+
+/**
+ * Server-side (toilscript → WASM) configuration.
  */
 export interface ServerConfig {
     /** Server source directory, relative to root. Default `server`. */
@@ -114,6 +138,20 @@ export interface ServerConfig {
      * the per-tenant env store); this drives `toiljs dev` / self-host.
      */
     readonly email?: EmailBackendConfig;
+    /** Which layer the dev process emulates. Default `all`. */
+    readonly nodeMode?: DevNodeMode;
+    /** Daemon (L4) config mirror (dev / self-host). */
+    readonly daemon?: DaemonConfig;
+}
+
+/** Fully-resolved {@link DaemonConfig}; every field non-optional, defaults applied. */
+export interface ResolvedDaemonConfig {
+    readonly region: string | null;
+    readonly standbyRegion: string | null;
+    readonly defaultIntervalMs: number;
+    readonly tickBudgetMs: number;
+    readonly gasTick: number;
+    readonly maxTasks: number;
 }
 
 /**
@@ -157,6 +195,10 @@ export interface ResolvedToilConfig {
     readonly seo: SeoConfig | null;
     /** The `server.email` backend config (dev / self-host), or `null` when unset. */
     readonly email: EmailBackendConfig | null;
+    /** Which layer the dev process emulates (dev / self-host). Default `all`. */
+    readonly nodeMode: DevNodeMode;
+    /** Daemon (L4) config mirror (dev / self-host), every field resolved. */
+    readonly daemon: ResolvedDaemonConfig;
     /** Absolute path to the framework client runtime (`toiljs/client`). */
     readonly runtimePath: string;
     readonly vite: InlineConfig;
@@ -229,7 +271,51 @@ export async function loadConfig(
                 : null,
         seo: client.seo ?? null,
         email: user.server?.email ?? null,
+        nodeMode: resolveNodeMode(user.server?.nodeMode),
+        daemon: resolveDaemonConfig(user.server?.daemon),
         runtimePath: resolveRuntimePath(),
         vite: client.vite ?? {},
     };
 }
+
+const DEV_NODE_MODES: readonly DevNodeMode[] = [
+    'hot',
+    'regional',
+    'continental',
+    'daemon',
+    'all',
+];
+
+/** A `nodeMode` outside the enum falls back to `all` with a warning (fail-soft:
+ *  the authoritative role is the edge's TCF + plan, so dev never bricks on it). */
+function resolveNodeMode(mode: DevNodeMode | undefined): DevNodeMode {
+    if (mode === undefined) return 'all';
+    if (DEV_NODE_MODES.includes(mode)) return mode;
+    process.stdout.write(
+        `  ! server.nodeMode '${mode}' is not a valid node mode; falling back to 'all'\n`,
+    );
+    return 'all';
+}
+
+/** Resolve the daemon config with defaults + light, fail-soft clamping (never
+ *  throws; the authoritative caps are the edge's). */
+function resolveDaemonConfig(d: DaemonConfig | undefined): ResolvedDaemonConfig {
+    // The dev scheduler uses setInterval; a sub-second loop floods the console.
+    let defaultIntervalMs = d?.defaultIntervalMs ?? 60000;
+    if (defaultIntervalMs < 1000) {
+        process.stdout.write(
+            `  ! server.daemon.defaultIntervalMs ${String(defaultIntervalMs)} < 1000; clamping to 1000\n`,
+        );
+        defaultIntervalMs = 1000;
+    }
+    let maxTasks = d?.maxTasks ?? 64;
+    if (maxTasks <= 0 || maxTasks > 1024) maxTasks = Math.min(1024, Math.max(1, maxTasks || 64));
+    return {
+        region: d?.region ?? null,
+        standbyRegion: d?.standbyRegion ?? null,
+        defaultIntervalMs,
+        tickBudgetMs: d?.tickBudgetMs ?? 30000,
+        gasTick: d?.gasTick ?? 0,
+        maxTasks,
+    };
+}