@ultimat3/cli 20.2.1 → 22.0.0

package/src/prerender.ts

@@ -12,13 +12,16 @@ import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
 import type { RouteStats } from './budgets';
 import { measureDocumentJs, writeBuildStats } from './budgets';
-import { routeDocument } from './dev-render';
 import { errorPageDocument, STATIC_ERROR_PAGE } from './error-pages';
 import { FAVICON_PATH, faviconBytes } from './favicon';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands, writeIslands } from './island-bundle';
-import { measurementActor } from './measurement-actor';
+import { measureDatabase } from './measure-database';
+import { measurePaths } from './measure-paths';
+import { measureScope, withAppUrl } from './measure-scope';
+import { clearPrerenderOut } from './prerender-out';
 import { loadPwaArtifacts, WEB_MANIFEST_PATH, writePwaIcons } from './pwa-artifacts';
+import { routeDocument } from './runtime-render';
 import type { SkippedRoute, UnmeasuredRoute } from './static-report';
 import { skippedRoute, skipReasonFor, writeStaticReport } from './static-report';
 import { styleBundle, writeStyles } from './style-bundle';
@@ -142,6 +145,8 @@ const declaresBudget = (entry: RouteEntry): boolean => {
 export async function prerenderSite(options: PrerenderOptions): Promise<PrerenderReport> {
   // The same load `x dev` and `x manifest` perform: importing the app's modules IS what fills the
   // route registry, so there is no route table to prerender before this runs.
+  // Emptied FIRST: the export only ever gained files, so a deleted route's HTML kept shipping.
+  await clearPrerenderOut(options.out, options.root);
   await loadApp(options.root);
   const buildId = (await appManifest(options.root)).manifest.buildId;
   const origin = options.origin ?? DEFAULT_ORIGIN;
@@ -218,7 +223,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   }
 
   // Every render below goes through `routeDocument`, which is the function a REQUEST reaches — and
-  // a request arrives inside `runWithContext`, installed by the HTTP pipeline (`dev-render.ts`).
+  // a request arrives inside `runWithContext`, installed by the HTTP pipeline (`runtime-render.ts`).
   // Called bare, any route whose component, `load` or `meta` reads `useContext()` threw
   // `X_NO_CONTEXT`: measured against `examples/dummy`, `/posts/new` and `/settings` were filed
   // unmeasured for that reason alone, and a `render: 'static'` route reading it failed the whole
@@ -226,115 +231,129 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // documents, and this build's own id so a component reading `ctx.buildId` stamps the artifact
   // with the id the report and the stats carry.
   const ctx = createContext({ role: 'web', buildId });
-  // A SECOND context, for the branch below that renders only to weigh. Its actor holds every
-  // permission (`measurement-actor.ts`), because an `app/` page's `load` calls policy-guarded
-  // queries and denied the anonymous one with `X_UNAUTHENTICATED` — every authed page unmeasured.
-  // `renderStatic` keeps `ctx`: its output is a published file, and a `site/` load that a policy
-  // refuses must fail the build, never render another actor's rows into it.
-  const measureCtx = createContext({ role: 'web', buildId, actor: measurementActor() });
-  const documentAs = (
-    as: typeof ctx,
-    entry: RouteEntry,
-    data: { url: string; params: Record<string, string> },
-  ) =>
-    runWithContext(as, () =>
-      routeDocument(entry, data, {
-        resolveIsland: (file: string) => islands.resolverFor(file),
-        themeHead: theme.head,
-        ...(pwa === undefined ? {} : { pwaHead: pwa.head + (swHead ?? '') }),
-      }),
-    );
+  // A SECOND scope, for the branch below that renders only to weigh (`measure-scope.ts`): a
+  // request context holding the app's measurement actor, with the app's own API answered in
+  // process, because an `app/` page's `load` calls policy-guarded queries over its typed client
+  // and no server is listening during a build. `renderStatic` keeps `ctx`: its output is a
+  // published file, and a `site/` load a policy refuses must fail the build, never render another
+  // actor's rows into it.
+  const measure = await measureScope({ origin, buildId });
+  // Started on the first route that needs weighing, and released however the loop ends.
+  const database = measureDatabase(options.root);
+  const render = (entry: RouteEntry, data: { url: string; params: Record<string, string> }) =>
+    routeDocument(entry, data, {
+      resolveIsland: (file: string) => islands.resolverFor(file),
+      themeHead: theme.head,
+      ...(pwa === undefined ? {} : { pwaHead: pwa.head + (swHead ?? '') }),
+    });
   const document = (entry: RouteEntry, data: { url: string; params: Record<string, string> }) =>
-    documentAs(ctx, entry, data);
+    runWithContext(ctx, () => render(entry, data));
 
-  for (const entry of routeEntries()) {
-    const facts = { surface: entry.surface, render: entry.config.render, route: entry.path };
-    const reason = skipReasonFor(facts);
-    if (reason !== null) {
-      skipped.push(skippedRoute(facts, reason));
-      if (!declaresBudget(entry)) continue;
-      // Non-fatal, and that is deliberate: an ssr page's `load` may want a request, a session or a
-      // database this build does not have, and a `x build --target static` that started failing on
-      // routes it never used to touch would be a worse regression than the gap it closes. A route
-      // that will not render here is reported, gets no stats entry, and stays `X_BUDGET_UNMEASURED`.
-      try {
-        const html = await documentAs(measureCtx, entry, {
-          url: new URL(entry.path, origin).href,
-          params: {},
+  try {
+    for (const entry of routeEntries()) {
+      const facts = { surface: entry.surface, render: entry.config.render, route: entry.path };
+      const reason = skipReasonFor(facts);
+      if (reason !== null) {
+        skipped.push(skippedRoute(facts, reason));
+        if (!declaresBudget(entry)) continue;
+        // Non-fatal, and that is deliberate: an ssr page's `load` may want a request, a session or a
+        // database this build does not have, and a `x build --target static` that started failing on
+        // routes it never used to touch would be a worse regression than the gap it closes. A route
+        // that will not render here is reported, gets no stats entry, and stays `X_BUDGET_UNMEASURED`.
+        try {
+          // A dynamic route is rendered at the paths its own `prerender()` lists, and the row holds
+          // the heaviest — a static route's rule. One that lists none is its own finding.
+          // Inside the measuring scope: a route's `prerender()` lists its paths by reading the app's
+          // own data, the same way its `load` does.
+          await database.ready();
+          const plan = await withAppUrl(origin, () => measure.run(() => measurePaths(entry)));
+          if ('unmeasured' in plan) {
+            unmeasured.push(plan.unmeasured);
+            continue;
+          }
+          let row: RouteStats | undefined;
+          for (const { path, params } of plan.paths) {
+            const data = { url: new URL(path, origin).href, params };
+            const html = await withAppUrl(origin, () => measure.run(() => render(entry, data)));
+            const measured = await measureDocumentJs(html, options.out);
+            if (row !== undefined && measured.jsBytes <= row.jsBytes) continue;
+            const chain = heaviestSource(islands, measured.entries);
+            row = {
+              path: entry.path,
+              jsBytes: measured.jsBytes,
+              frameworkJsBytes: measured.frameworkBytes,
+              ...(chain === undefined ? {} : { heaviestChain: chain }),
+            };
+          }
+          if (row !== undefined) routes.push(row);
+        } catch (error) {
+          // `renderThrowable`, never `String(error)`: this is a caught unknown, and a hostile
+          // `toString` here would take the whole build down instead of one route's measurement.
+          // A framework error rides along with its code, cause and fix: `checkBudgets` reports
+          // `X_ISLAND_PROPS_INVALID` under its own name, because that sentence — the island, the
+          // prop, its bytes — is the finding, and `X_BUDGET_UNMEASURED` pointing at this list was
+          // a second command between the author and it.
+          unmeasured.push({
+            path: entry.path,
+            reason: renderThrowable(error),
+            ...(isUltimateError(error)
+              ? { code: error.code, cause: error.cause, fix: error.fix }
+              : {}),
+          });
+        }
+        continue;
+      }
+      const artifacts = await renderStatic(
+        entry,
+        ({ path, params }) => document(entry, { url: new URL(path, origin).href, params }),
+        { buildId },
+      );
+      // `enumeratePrerender` answers `[]` for a dynamic route with no `prerender()`, so a
+      // `render: 'static'` route with a param writes nothing and used to be reported NOWHERE — past
+      // the skip branch by its mode, absent from `pages` by its zero artifacts. A route in neither
+      // list is the defect this report exists to close, wearing its other shape.
+      if (artifacts.length === 0) {
+        skipped.push(skippedRoute(facts, 'no-prerender-paths'));
+        continue;
+      }
+      // One stats row per ROUTE, holding its heaviest page. `checkBudgets` looks a route up by
+      // `route.url`, which is the manifest's DECLARED pattern (`/blog/:slug`), and this pushed the
+      // FILLED path (`/blog/hello`) — so no dynamic static route has ever been weighed: every one
+      // was `X_BUDGET_UNMEASURED` and `X_BUDGET_EXCEEDED` could not fire for the whole class. The
+      // heaviest page and not the first, because a budget is a ceiling: the page that breaks it is
+      // the one the route has to answer for. `pages` below still names every filled path.
+      let heaviest: RouteStats | undefined;
+      for (const artifact of artifacts) {
+        const file = join(options.out, artifact.outputPath);
+        const bytes = await Bun.write(file, artifact.html);
+        pages.push({
+          route: entry.path,
+          path: artifact.path,
+          file: artifact.outputPath,
+          hash: artifact.hash,
+          bytes,
         });
-        const measured = await measureDocumentJs(html, options.out);
+        // `artifact.hash` is `contentHash(html)` — the same identity that becomes this page's ETag,
+        // so the precache revision and the HTTP validator can never disagree about one document.
+        // Keyed by the FILLED path, which for a non-dynamic route is the declared one; a dynamic
+        // route is not precached as a single URL anyway (`buildPrecacheManifest` skips it).
+        documents.set(artifact.path, { revision: artifact.hash, bytes });
+        // Measured from the document that was just written, so the `budgets` step compares a
+        // declared budget against bytes that exist on disk rather than against a graph's estimate.
+        const measured = await measureDocumentJs(artifact.html, options.out);
         const chain = heaviestSource(islands, measured.entries);
-        routes.push({
+        if (heaviest !== undefined && heaviest.jsBytes >= measured.jsBytes) continue;
+        heaviest = {
           path: entry.path,
           jsBytes: measured.jsBytes,
           frameworkJsBytes: measured.frameworkBytes,
           ...(chain === undefined ? {} : { heaviestChain: chain }),
-        });
-      } catch (error) {
-        // `renderThrowable`, never `String(error)`: this is a caught unknown, and a hostile
-        // `toString` here would take the whole build down instead of one route's measurement.
-        // A framework error rides along with its code, cause and fix: `checkBudgets` reports
-        // `X_ISLAND_PROPS_INVALID` under its own name, because that sentence — the island, the
-        // prop, its bytes — is the finding, and `X_BUDGET_UNMEASURED` pointing at this list was
-        // a second command between the author and it.
-        unmeasured.push({
-          path: entry.path,
-          reason: renderThrowable(error),
-          ...(isUltimateError(error)
-            ? { code: error.code, cause: error.cause, fix: error.fix }
-            : {}),
-        });
+        };
       }
-      continue;
-    }
-    const artifacts = await renderStatic(
-      entry,
-      ({ path, params }) => document(entry, { url: new URL(path, origin).href, params }),
-      { buildId },
-    );
-    // `enumeratePrerender` answers `[]` for a dynamic route with no `prerender()`, so a
-    // `render: 'static'` route with a param writes nothing and used to be reported NOWHERE — past
-    // the skip branch by its mode, absent from `pages` by its zero artifacts. A route in neither
-    // list is the defect this report exists to close, wearing its other shape.
-    if (artifacts.length === 0) {
-      skipped.push(skippedRoute(facts, 'no-prerender-paths'));
-      continue;
-    }
-    // One stats row per ROUTE, holding its heaviest page. `checkBudgets` looks a route up by
-    // `route.url`, which is the manifest's DECLARED pattern (`/blog/:slug`), and this pushed the
-    // FILLED path (`/blog/hello`) — so no dynamic static route has ever been weighed: every one
-    // was `X_BUDGET_UNMEASURED` and `X_BUDGET_EXCEEDED` could not fire for the whole class. The
-    // heaviest page and not the first, because a budget is a ceiling: the page that breaks it is
-    // the one the route has to answer for. `pages` below still names every filled path.
-    let heaviest: RouteStats | undefined;
-    for (const artifact of artifacts) {
-      const file = join(options.out, artifact.outputPath);
-      const bytes = await Bun.write(file, artifact.html);
-      pages.push({
-        route: entry.path,
-        path: artifact.path,
-        file: artifact.outputPath,
-        hash: artifact.hash,
-        bytes,
-      });
-      // `artifact.hash` is `contentHash(html)` — the same identity that becomes this page's ETag,
-      // so the precache revision and the HTTP validator can never disagree about one document.
-      // Keyed by the FILLED path, which for a non-dynamic route is the declared one; a dynamic
-      // route is not precached as a single URL anyway (`buildPrecacheManifest` skips it).
-      documents.set(artifact.path, { revision: artifact.hash, bytes });
-      // Measured from the document that was just written, so the `budgets` step compares a
-      // declared budget against bytes that exist on disk rather than against a graph's estimate.
-      const measured = await measureDocumentJs(artifact.html, options.out);
-      const chain = heaviestSource(islands, measured.entries);
-      if (heaviest !== undefined && heaviest.jsBytes >= measured.jsBytes) continue;
-      heaviest = {
-        path: entry.path,
-        jsBytes: measured.jsBytes,
-        frameworkJsBytes: measured.frameworkBytes,
-        ...(chain === undefined ? {} : { heaviestChain: chain }),
-      };
+      if (heaviest !== undefined) routes.push(heaviest);
     }
-    if (heaviest !== undefined) routes.push(heaviest);
+  } finally {
+    await database.close();
   }
   // The worker, LAST: every document it precaches has now been rendered, hashed and weighed. A
   // static host runs no route table, so both files go into the artifact — a

package/src/pwa-artifacts.ts

@@ -7,7 +7,7 @@
 // `<link rel="manifest">`, no `theme-color` and no apple-touch icon — and no browser has ever
 // offered to install one, however the config was written.
 //
-// WHY HERE. `dev-assets.ts`'s reason exactly: three packages declare what an installable app is and
+// WHY HERE. `runtime-assets.ts`'s reason exactly: three packages declare what an installable app is and
 // none of them can read a config file off disk. This one composes tier 0's `pwa` block with tier
 // 4's generator and hands both served surfaces and the static export the same two strings.
 //
@@ -16,11 +16,11 @@
 // manifest is not, so the worker lands behind a real browser check rather than beside this.
 
 // why: Bun exposes no synchronous file-existence primitive, and this read is the same one
-// `app-auth.ts` and `dev-cache.ts` each make before importing an app's config — a root with no
+// `app-auth.ts` and `runtime-cache.ts` each make before importing an app's config — a root with no
 // `app.config.ts` is an ordinary answer here (a scratch root, `x build` outside an app).
 import { existsSync } from 'node:fs';
 // why: Bun exposes no path-join primitive, and `APP_CONFIG_FILE` is app-root-relative — the same
-// necessity `favicon.ts` and `dev-assets.ts` each record for their own root-relative constant.
+// necessity `favicon.ts` and `runtime-assets.ts` each record for their own root-relative constant.
 import { join } from 'node:path';
 import type { PwaColors, PwaOfflineConfig } from '@ultimat3/core';
 import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';

package/src/realtime-browser-probe-fixture.ts

@@ -4,6 +4,6 @@
 // Bundled AND imported by `realtime-browser-barrel.test.ts` — the import is what gives it an lcov
 // record, since `Bun.build()` reads this file without evaluating it.
 
-import { useLive } from '@ultimat3/realtime';
+import { useQuery } from '@ultimat3/realtime';
 
-export const probeUseLive = useLive;
+export const probeUseQuery = useQuery;

package/src/reexport-manifest.ts

@@ -3,7 +3,8 @@
 // none: its length is a function of the package's API size, so the ceiling measures the wrong
 // thing there. One added statement of logic disqualifies it and re-arms the ceiling on the spot.
 
-import { CLOSERS, maskLiterals, OPENERS } from './ts-scan';
+import { maskLiterals } from '@ultimat3/core';
+import { CLOSERS, OPENERS } from './ts-scan';
 
 /** Every statement a manifest may hold begins with one of these two words. */
 const IMPORT_OR_EXPORT = /^(?:import|export)\b/;

package/src/registry.ts

@@ -1,34 +1,42 @@
 // The command registry: the one list the parser, the help catalogue and the dispatcher all read.
 // A command that is not here does not exist — there is no second place to register one.
+//
+// LAZY, `As of 2026-09-23`: every declaration is static (`cmd-<name>-spec.ts`) and every body is
+// `await import()`ed when that command runs. Importing all 28 bodies to answer one of them was
+// the CLI's whole startup: `x --help` paid for `sass`, Babel, every framework package and the
+// dev server it never started (plan 101 slice 12 d).
 
-import { affectedCommand } from './cmd-affected';
-import { buildCommand } from './cmd-build';
-import { ciCommand } from './cmd-ci';
-import { dbCommand } from './cmd-db';
-import { deployCommand } from './cmd-deploy';
-import { devCommand } from './cmd-dev';
-import { docsCommand } from './cmd-docs';
-import { doctorCommand } from './cmd-doctor';
-import { envCommand } from './cmd-env';
-import { errorsCommand } from './cmd-errors';
-import { fixCommand } from './cmd-fix';
-import { generateCommand } from './cmd-generate';
+import { affectedSpec } from './cmd-affected-spec';
+import { buildSpec } from './cmd-build-spec';
+import { ciSpec } from './cmd-ci-spec';
+import { dbSpec } from './cmd-db-spec';
+import { deploySpec } from './cmd-deploy-spec';
+import { devSpec } from './cmd-dev-spec';
+import { docsSpec } from './cmd-docs-spec';
+import { doctorSpec } from './cmd-doctor-spec';
+import { envSpec } from './cmd-env-spec';
+import { errorsSpec } from './cmd-errors-spec';
+import { fixSpec } from './cmd-fix-spec';
+import { generateSpec } from './cmd-generate-spec';
+// Registered here, not by whichever command body happens to load: `dispatch` renders a CLI code's
+// title for a refusal raised before any body is imported.
+import './error-codes';
 import { createHelpCommand, createVersionCommand } from './cmd-help';
-import { i18nCommand } from './cmd-i18n';
-import { jobsCommand } from './cmd-jobs';
-import { manifestCommand } from './cmd-manifest';
-import { mcpCommand } from './cmd-mcp';
-import { newCommand } from './cmd-new';
+import { i18nSpec } from './cmd-i18n-spec';
+import { jobsSpec } from './cmd-jobs-spec';
+import { manifestSpec } from './cmd-manifest-spec';
+import { mcpSpec } from './cmd-mcp-spec';
+import { newSpec } from './cmd-new-spec';
 import { plannedCommands } from './cmd-planned';
-import { policyCommand } from './cmd-policy';
-import { prCommand } from './cmd-pr';
-import { actionsCommand, entitiesCommand, queriesCommand } from './cmd-registries';
-import { routesCommand } from './cmd-routes';
-import { secretsCommand } from './cmd-secrets';
-import { shotCommand } from './cmd-shot';
-import { tasksCommand } from './cmd-tasks';
-import { testCommand } from './cmd-test';
-import { verifyCommand } from './cmd-verify';
+import { policySpec } from './cmd-policy-spec';
+import { prSpec } from './cmd-pr-spec';
+import { actionsSpec, entitiesSpec, queriesSpec } from './cmd-registries-spec';
+import { routesSpec } from './cmd-routes-spec';
+import { secretsSpec } from './cmd-secrets-spec';
+import { shotSpec } from './cmd-shot-spec';
+import { tasksSpec } from './cmd-tasks-spec';
+import { testSpec } from './cmd-test-spec';
+import { verifySpec } from './cmd-verify-spec';
 import type { CliCommand } from './command';
 import type { CommandSpec } from './parse';
 import { loadVersion } from './version-loader';
@@ -48,35 +56,51 @@ export function cliVersion(): string {
   return cliVersionCache;
 }
 
-const CORE: readonly CliCommand[] = [
-  newCommand,
-  devCommand,
-  buildCommand,
-  testCommand,
-  verifyCommand,
-  generateCommand,
-  dbCommand,
-  mcpCommand,
-  doctorCommand,
-  deployCommand,
-  envCommand,
-  secretsCommand,
-  manifestCommand,
-  routesCommand,
-  actionsCommand,
-  queriesCommand,
-  entitiesCommand,
-  jobsCommand,
-  tasksCommand,
-  policyCommand,
-  i18nCommand,
-  errorsCommand,
-  docsCommand,
-  fixCommand,
-  affectedCommand,
-  shotCommand,
-  prCommand,
-  ciCommand,
+/**
+ * A command whose body loads on first run. The spec is the module's own (`cmd-<name>.ts` reads
+ * the same `cmd-<name>-spec.ts`), so the parser and the body can never describe two commands.
+ */
+export interface LazyCommand extends CliCommand {
+  /** The body module's own command — what `run` delegates to, exposed so a test can hold them equal. */
+  load(): Promise<CliCommand>;
+}
+
+const lazy = (spec: CommandSpec, load: () => Promise<CliCommand>): LazyCommand => ({
+  spec,
+  load,
+  run: async (ctx) => (await load()).run(ctx),
+});
+
+/** The shipped commands, each a static declaration plus the body it loads on first run. */
+export const LAZY_COMMANDS: readonly LazyCommand[] = [
+  lazy(newSpec, async () => (await import('./cmd-new')).newCommand),
+  lazy(devSpec, async () => (await import('./cmd-dev')).devCommand),
+  lazy(buildSpec, async () => (await import('./cmd-build')).buildCommand),
+  lazy(testSpec, async () => (await import('./cmd-test')).testCommand),
+  lazy(verifySpec, async () => (await import('./cmd-verify')).verifyCommand),
+  lazy(generateSpec, async () => (await import('./cmd-generate')).generateCommand),
+  lazy(dbSpec, async () => (await import('./cmd-db')).dbCommand),
+  lazy(mcpSpec, async () => (await import('./cmd-mcp')).mcpCommand),
+  lazy(doctorSpec, async () => (await import('./cmd-doctor')).doctorCommand),
+  lazy(deploySpec, async () => (await import('./cmd-deploy')).deployCommand),
+  lazy(envSpec, async () => (await import('./cmd-env')).envCommand),
+  lazy(secretsSpec, async () => (await import('./cmd-secrets')).secretsCommand),
+  lazy(manifestSpec, async () => (await import('./cmd-manifest')).manifestCommand),
+  lazy(routesSpec, async () => (await import('./cmd-routes')).routesCommand),
+  lazy(actionsSpec, async () => (await import('./cmd-registries')).actionsCommand),
+  lazy(queriesSpec, async () => (await import('./cmd-registries')).queriesCommand),
+  lazy(entitiesSpec, async () => (await import('./cmd-registries')).entitiesCommand),
+  lazy(jobsSpec, async () => (await import('./cmd-jobs')).jobsCommand),
+  lazy(tasksSpec, async () => (await import('./cmd-tasks')).tasksCommand),
+  lazy(policySpec, async () => (await import('./cmd-policy')).policyCommand),
+  lazy(i18nSpec, async () => (await import('./cmd-i18n')).i18nCommand),
+  lazy(errorsSpec, async () => (await import('./cmd-errors')).errorsCommand),
+  lazy(docsSpec, async () => (await import('./cmd-docs')).docsCommand),
+  lazy(fixSpec, async () => (await import('./cmd-fix')).fixCommand),
+  lazy(affectedSpec, async () => (await import('./cmd-affected')).affectedCommand),
+  lazy(shotSpec, async () => (await import('./cmd-shot')).shotCommand),
+  lazy(prSpec, async () => (await import('./cmd-pr')).prCommand),
+  lazy(ciSpec, async () => (await import('./cmd-ci')).ciCommand),
 ];
 
 /**
@@ -85,7 +109,7 @@ const CORE: readonly CliCommand[] = [
  * facts, and only one of them is true — see `cmd-planned.ts`.
  */
 export const COMMANDS: readonly CliCommand[] = [
-  ...CORE,
+  ...LAZY_COMMANDS,
   ...plannedCommands(),
   createHelpCommand(() => SPECS),
   createVersionCommand(cliVersion),

package/src/role-realtime.ts

@@ -0,0 +1,36 @@
+// `realtime.enabled`, obeyed where the roles are chosen. Until 22.0.0 no boot read it: `x dev`
+// started a `sync` node and `ROLE=sync` served one whatever the key said, so `enabled: false` was
+// documentation. Off now means no `sync` node, no replicator and — with no node to feed — no live
+// feed wiring (`runtime-live-feed.ts` starts nothing for a null node).
+
+import type { RealtimeConfig, Role } from '@ultimat3/core';
+import { ConfigInvalidError, logger } from '@ultimat3/core';
+
+/** The roles that exist only to serve realtime. `web` publishes too, but serves pages first. */
+const REALTIME_ROLES: readonly Role[] = ['sync', 'replicator'];
+
+/**
+ * The roles this process may start. Disabled drops the realtime roles and keeps the rest, which is
+ * what `x dev`'s default set needs on an app that opted out (`enabled: false`; the default is on).
+ * A selection that was NOTHING but realtime roles is refused instead: that is `ROLE=sync` on an app
+ * that turned realtime off, a container that would bind nothing and restart behind its probe.
+ */
+export function rolesUnderRealtime(
+  selected: readonly Role[],
+  realtime: Pick<RealtimeConfig, 'enabled'>,
+): readonly Role[] {
+  // The key is read only when a realtime role was asked for, so a selection without one never
+  // depends on it — a hand-built runtime in a test that starts `web` alone included.
+  const dropped = selected.filter((role) => REALTIME_ROLES.includes(role));
+  if (dropped.length === 0 || realtime.enabled) return selected;
+  const kept = selected.filter((role) => !REALTIME_ROLES.includes(role));
+  if (kept.length === 0) {
+    throw new ConfigInvalidError({
+      cause: `role ${dropped.join(',')} was asked for and realtime.enabled is false in app.config.ts, so this process would serve nothing`,
+      fix: `set realtime: { enabled: true } in app.config.ts, or run a role that is not realtime: x dev --role web,worker,scheduler`,
+      meta: { key: 'realtime.enabled', roles: dropped },
+    });
+  }
+  logger.info(`realtime.enabled is false in app.config.ts: not starting ${dropped.join(', ')}`);
+  return kept;
+}

package/src/{dev-replicator.ts → role-replicator.ts}

@@ -7,8 +7,8 @@ import { describeEntities } from '@ultimat3/entity';
 import { ReplicatorSlotHeldError } from '@ultimat3/realtime';
 import type { Replicator, Transport } from '@ultimat3/realtime/server';
 import { createReplicator, replicatorLockKey, selectChangeFeed } from '@ultimat3/realtime/server';
-import type { DevServices, Env } from './dev-services';
 import { BadFlagError } from './errors';
+import type { DevServices, Env } from './runtime-bindings';
 
 export interface StartReplicatorOptions {
   readonly services: DevServices;

package/src/{dev-roles-fixture.ts → role-start-fixture.ts}

@@ -1,4 +1,4 @@
-// The one `RunningServices` every `dev-roles` test file boots roles against, and the one reset
+// The one `RunningServices` every `role-start` test file boots roles against, and the one reset
 // between them. Shared rather than copied, for the reason `policy-fixture.ts` gives: three files
 // start the same roles, and a second copy of the runtime drifts while each file keeps passing.
 //
@@ -6,7 +6,7 @@
 // `*.test.ts` — a fixture written there is one `tsc` never reads.
 
 import { noopPurgeDriver } from '@ultimat3/cache';
-import { resetLifecycle } from '@ultimat3/core';
+import { type RealtimeConfig, resetLifecycle } from '@ultimat3/core';
 import { resetHttpConfig } from '@ultimat3/http';
 import {
   createMemoryDriver,
@@ -19,8 +19,8 @@ import {
 import { createMemoryDriver as createMemoryMailDriver } from '@ultimat3/mail';
 import { DEFAULT_PRESENCE_TTL_MS, InProcessTransport } from '@ultimat3/realtime/server';
 import { defineStorage, localDriver } from '@ultimat3/storage';
-import type { RunningServices } from './dev-runtime';
-import { resolveServices } from './dev-services';
+import { resolveServices } from './runtime-bindings';
+import type { RunningServices } from './runtime-services';
 
 /**
  * Every service a role touches, embedded but real — no PGlite boot for a role-wiring test.
@@ -28,7 +28,10 @@ import { resolveServices } from './dev-services';
  * `root` is a parameter and not a constant: each test file owns its own directory and deletes it,
  * so two files sharing one on-disk storage root cannot leave the other's fixture half-removed.
  */
-export function fixtureRuntime(root: string): RunningServices {
+/** Enabled, in-process: the section every role test before 22.0.0 was implicitly booting. */
+const REALTIME_ON: RealtimeConfig = { enabled: true, transport: 'memory', urlEnv: undefined };
+
+export function fixtureRuntime(root: string, realtime = REALTIME_ON): RunningServices {
   const services = resolveServices(root, {});
   const transport = new InProcessTransport();
   return {
@@ -41,6 +44,7 @@ export function fixtureRuntime(root: string): RunningServices {
     outbox: createMemoryOutboxStore(),
     events: createMemoryEventBus(),
     transport,
+    realtime,
     transportDetail: 'in-process fanout',
     // The sync role reads this to build its `PresenceRegistry`; the default is what a boot with no
     // `NATS_URL` resolves to, so the fixture is the real number rather than a rounder one.