@ultimat3/cli 24.0.0 → 25.1.0

package/src/cmd-shot.ts

@@ -8,6 +8,7 @@
 import { mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { renderFixShellArg } from '@ultimat3/core';
+import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import { IDLE_HYDRATE_TIMEOUT_MS } from '@ultimat3/render';
 import { requireAppRoot } from './app-root';
 import { appBrowser } from './browser-launcher';
@@ -23,7 +24,13 @@ import {
   refuseSweepWithRoute,
   refuseSweepWithState,
 } from './cmd-shot-island';
-import { MATRIX_DIR, matrixRoutes, planShotMatrix, runShotMatrix } from './cmd-shot-matrix';
+import {
+  MATRIX_DIR,
+  matrixRoutes,
+  planShotMatrix,
+  refuseMatrixWithComponent,
+  runShotMatrix,
+} from './cmd-shot-matrix';
 import { shotSpec } from './cmd-shot-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, MissingPositionalError } from './errors';
@@ -33,12 +40,7 @@ import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
 import { shotBrowserChoice } from './shot-browser';
 import { readCookieFlag, type ShotCookiePair, shotCookies } from './shot-cookie';
-import {
-  acceptLanguageHeaders,
-  loadShotLocales,
-  localizedShotPath,
-  readLocaleFlag,
-} from './shot-locale';
+import { acceptLanguageHeaders, localizedShotPath, readLocaleFlag } from './shot-locale';
 import type { BootDevServer, ShotServer } from './shot-server';
 import { allowHostsFrom, devServerFor, SHOT_DIR } from './shot-server';
 import { SETTLE_POLL_MS, settleIslands } from './shot-settle';
@@ -53,21 +55,12 @@ import {
   shotSummary,
   verdictJson,
 } from './shot-verdict';
+import { parseViewports, refuseViewportWithComponent, runShotViewports } from './shot-viewport';
 
 /** Kernel-picked by default: :3000 is usually another project's dev server, not a free port. */
 const DEFAULT_PORT = 0;
 
-/**
- * How long the page is left alone after `load` before it is photographed: exactly the
- * `requestIdleCallback` deadline `@ultimat3/render`'s hydration runtime gives an `idle` island —
- * shoot sooner and the verdict reports `booted: 0` for a page that hydrates perfectly. READ from
- * that runtime rather than restated, because two copies of one number that must agree is the drift
- * axiom 2 refuses: the settle window is not "2 seconds", it is "the deadline the runtime uses".
- */
-export const DEFAULT_SETTLE_MS = IDLE_HYDRATE_TIMEOUT_MS;
-
-// Re-exported, not re-declared: `cmd-shot.test.ts` and the island path both name them, and a
-// second declaration of a path or an allow-list rule is a second answer.
+// Re-exported, not re-declared: a second declaration of a path or a host rule is a second answer.
 export type { BootDevServer, ShotServer };
 export { allowHostsFrom, devServerFor, SHOT_DIR };
 
@@ -372,7 +365,8 @@ export const shotCommand: CliCommand = {
     const sweep = flagBool(ctx.args, 'all-islands');
     const matrix = flagBool(ctx.args, 'matrix');
     const cookies = readCookieFlag(flagString(ctx.args, 'cookie'));
-    const app = await loadShotLocales(root);
+    const viewports = parseViewports(flagString(ctx.args, 'viewport'));
+    const app = await appLocaleSet(root);
     const locale = readLocaleFlag(flagString(ctx.args, 'locale'), app);
     // Every ambiguous pair refused BY NAME, before a value is read: a reader who typed two
     // subjects has a belief about which one runs, and half of them would be wrong.
@@ -385,14 +379,9 @@ export const shotCommand: CliCommand = {
     }
     const component = sweep || (island !== undefined && island !== '');
     // The matrix photographs ROUTES; a component beside it is two subjects.
-    if (matrix && component) {
-      throw new BadFlagError({
-        flag: 'matrix',
-        command: 'shot',
-        reason: 'photographs every site route; --island and --all-islands photograph components',
-        fix: 'x shot --matrix --json',
-      });
-    }
+    if (matrix && component) refuseMatrixWithComponent();
+    // An island state declares its own size, so a size asked for beside one is a second answer.
+    if (component && viewports !== undefined) refuseViewportWithComponent();
     // An island is photographed in BOTH themes by the harness, which owns its `data-theme` and
     // carries no boot script — so a theme asked for beside one is a request nothing could honour.
     if (component && locale !== undefined) {
@@ -414,7 +403,12 @@ export const shotCommand: CliCommand = {
     // `--matrix` alone is every site route; a route beside it narrows the matrix to that one.
     const route = component || (matrix && positional === undefined) ? '' : readRoute(positional);
     const port = intFlag(ctx.args, 'port', PORT_RANGE.min, DEFAULT_PORT, PORT_RANGE.max);
-    const settleMs = intFlag(ctx.args, 'settle', 0, DEFAULT_SETTLE_MS);
+    // How long the page is left alone after `load` before it is photographed: exactly the
+    // `requestIdleCallback` deadline `@ultimat3/render`'s hydration runtime gives an `idle` island —
+    // shoot sooner and the verdict reports `booted: 0` for a page that hydrates perfectly. The
+    // runtime's own constant, under its own name: the settle window is not "2 seconds", it is "the
+    // deadline the runtime uses", and a second name for it is a second import path.
+    const settleMs = intFlag(ctx.args, 'settle', 0, IDLE_HYDRATE_TIMEOUT_MS);
     const timeoutMs = intFlag(ctx.args, 'timeout', 1, DEFAULT_PAGE_TIMEOUT_MS);
     // Read only when given: its absence means "any 2xx", which no single default number can say.
     const expectStatus =
@@ -473,22 +467,24 @@ export const shotCommand: CliCommand = {
         locales: locale === undefined ? app.locales : [locale],
         defaultLocale: app.defaultLocale,
         ...(theme === undefined ? {} : { themes: [theme] }),
+        ...(viewports === undefined ? {} : { viewports }),
       });
       const outDir = shotOutDir(ctx.cwd, out, join(root, MATRIX_DIR));
       return runShotMatrix({ cells, outDir, boot, shoot: runShot, base });
     }
     const shown = locale ?? app.defaultLocale;
     const path = localizedShotPath(route, shown, app.defaultLocale);
-    return shotResult(
-      await runShot({
-        ...base,
-        route: path,
-        outDir: shotOutDir(ctx.cwd, out, join(root, SHOT_DIR, shotSlug(path))),
-        boot,
-        // Pinned whether or not `--locale` was given: the default locale, never the box's own.
-        acceptLanguage: shown,
-        ...(theme === undefined ? {} : { colorScheme: theme }),
-      }),
-    );
+    const single = {
+      ...base,
+      route: path,
+      // Pinned whether or not `--locale` was given: the default locale, never the box's own.
+      acceptLanguage: shown,
+      ...(theme === undefined ? {} : { colorScheme: theme }),
+    };
+    const outDir = shotOutDir(ctx.cwd, out, join(root, SHOT_DIR, shotSlug(path)));
+    if (viewports !== undefined) {
+      return runShotViewports({ viewports, outDir, boot, shoot: runShot, base: single });
+    }
+    return shotResult(await runShot({ ...single, outDir, boot }));
   },
 };

package/src/cmd-test.ts

@@ -5,6 +5,7 @@
 // there, because it is a fact about a git diff and not about a path: what the diff touches is
 // `affected.ts`, and this file only maps that answer onto the paths discovery yields.
 
+import { TEST_TYPES } from '@ultimat3/testing';
 import type { AffectedScope } from './affected';
 import { affectedScope, affectedScopeJson, DEFAULT_BASE, inScope } from './affected';
 import { testSpec } from './cmd-test-spec';
@@ -37,7 +38,6 @@ import {
 } from './test-workers';
 import { readVerifyFloor } from './verify-floor';
 import type { TestType } from './verify-tests';
-import { TEST_TYPES } from './verify-tests';
 
 /**
  * `--workers`. `Number.parseInt` alone accepted `4abc` and `4.9` as four, while `cmd-verify.ts`'s

package/src/coverage-lcov.ts

@@ -4,7 +4,7 @@
 
 /** One `SF:` record, as written: its own totals and every `DA:` line. */
 export interface LcovRecord {
-  /** The `SF:` path, verbatim — Bun writes it relative to the directory the run started in. */
+  /** The `SF:` path with `/` separators — Bun writes it relative to the directory the run started in. */
   readonly file: string;
   /** `LF` / `LH` / `FNF` / `FNH`. Bun's lcov carries no `FN:` lines, so functions are counts only. */
   readonly linesFound: number;
@@ -25,7 +25,9 @@ export function parseLcov(text: string): readonly LcovRecord[] {
   let lines = new Map<number, number>();
   for (const line of text.split('\n')) {
     if (line.startsWith('SF:')) {
-      file = line.slice(3);
+      // `/` on every OS: Bun on Windows writes `apps\web\…`, and the app's source walk keys its
+      // files with `/`, so no record matched and the floor read 0% of a fully tested app.
+      file = line.slice(3).replaceAll('\\', '/');
       lf = 0;
       lh = 0;
       fnf = 0;

package/src/db-backfill.ts

@@ -10,7 +10,7 @@
 // which names were asked for, whether `--write` was passed, and what `x_migrations` says.
 
 import type { Environment } from '@ultimat3/core';
-import { createContext } from '@ultimat3/core';
+import { ctxOf } from '@ultimat3/core';
 import { db, isLedgerMissing, readLedger } from '@ultimat3/db';
 import type {
   BackfillDeclaration,
@@ -218,7 +218,7 @@ async function remainingFor(declaration: BackfillDeclaration): Promise<number |
   const count = handle === undefined ? undefined : backfillOrigin(handle)?.count;
   if (count === undefined) return null;
   try {
-    return await count({ ctx: createContext({ role: 'migrate' }) });
+    return await count({ ctx: ctxOf({ role: 'migrate' }) });
   } catch {
     return null;
   }

package/src/db-replay-engine.ts

@@ -6,13 +6,7 @@
 // why: Bun ships no path joiner.
 import { join } from 'node:path';
 import type { DbClient, LinkedExtensions, Migration } from '@ultimat3/db';
-import {
-  createPgliteClient,
-  createPostgresClient,
-  DbError,
-  linkPgliteExtensions,
-  raw,
-} from '@ultimat3/db';
+import { DbError, linkPgliteExtensions, pgliteClient, postgresClient, raw } from '@ultimat3/db';
 import { migrationExtensions } from './migration-extensions';
 
 type Env = Readonly<Record<string, string | undefined>>;
@@ -73,14 +67,14 @@ async function withPostgresScratch<T>(
   work: (client: DbClient) => Promise<T>,
 ): Promise<T> {
   const database = scratchName();
-  const admin = createPostgresClient({ url: adminUrl });
+  const admin = postgresClient({ url: adminUrl });
   try {
     // `template0`: the server's `template1` may carry objects an operator put there, and they
     // would be dumped as the app's.
     await admin.execute(raw(`create database ${database} template template0`));
     const target = new URL(adminUrl);
     target.pathname = `/${database}`;
-    const client = createPostgresClient({ url: target.toString() });
+    const client = postgresClient({ url: target.toString() });
     try {
       return await work(client);
     } finally {
@@ -103,7 +97,7 @@ export async function withScratchDatabase<T>(
   work: (client: DbClient) => Promise<T>,
 ): Promise<T> {
   if (engine.kind === 'postgres') return withPostgresScratch(engine.adminUrl, work);
-  const client = createPgliteClient({
+  const client = pgliteClient({
     extensions: engine.extensions,
     ...(stateDir === undefined ? {} : { snapshotDir: join(stateDir, 'cache') }),
   });

package/src/db-subscribes.ts

@@ -1,6 +1,6 @@
-// Single responsibility: which tables `x db gen` must grant `REPLICA IDENTITY FULL` — the live
-// queries' DECLARED `subscribes:` plus the `records` tables of every channel with params — and the
-// refusal for a declared name no entity's table matches. Only this tier holds all the registries.
+// Single responsibility: which tables `x db gen` must grant `REPLICA IDENTITY FULL` — the `records`
+// tables of every channel with params, and since #518 never a live query's `subscribes:` — and the
+// refusal for a declared `subscribes:` name no entity's table matches. Only this tier holds both.
 
 import { UltimateError } from '@ultimat3/core';
 import { paramsChannelTables } from '@ultimat3/realtime/server';
@@ -29,11 +29,10 @@ function offer(tables: ReadonlySet<string>): string {
 /**
  * A live read declares a relation this app has no entity for.
  *
- * Refused rather than dropped, and that is the whole point of the check: `@ultimat3/db` keeps only
- * the declared names an entity's table matches (`replica-identity.ts`), so an EXTRA name is
- * discarded in silence — and `@ultimat3/query` has no table catalog, so its own `subscribes:`
- * assertions cannot see one either. A typo therefore granted `REPLICA IDENTITY FULL` to nothing
- * while its author read the declaration as granted, which is the failure #357 exists to end.
+ * Refused rather than dropped: `@ultimat3/query` has no table catalog, so its own `subscribes:`
+ * assertions cannot see a name no table has — and a typo there is a declaration its author reads
+ * as true. Until #518 the list also chose which tables got `REPLICA IDENTITY FULL`, so the typo
+ * granted it to nothing (#357); the grant is gone, the declaration's honesty still matters.
  *
  * The name goes in the `cause` and never into a command: it is a string from the app's own source,
  * and the remedy is an edit to a field rather than anything to paste at a shell.
@@ -47,8 +46,8 @@ export class QuerySubscribesUnknownError extends UltimateError {
         'declares a table with that name',
       fix:
         `edit subscribes: on the query "${input.query}" to name a table this app declares ` +
-        `(${offer(input.tables)}), or drop the name — x db gen grants REPLICA IDENTITY FULL to ` +
-        'exactly the tables it lists, and would have granted it to nothing',
+        `(${offer(input.tables)}), or drop the name, then x db gen "fix subscribes" --json — a ` +
+        'name no table has can never match what the read selects from (X_QUERY_SUBSCRIBES_DRIFT)',
       meta: { query: input.query, table: input.table },
     });
   }
@@ -57,13 +56,19 @@ export class QuerySubscribesUnknownError extends UltimateError {
 /**
  * The tables to hand `GenerateOptions.replicaIdentityFull`, deduped and sorted.
  *
+ * A live query's `subscribes:` is VALIDATED here and never granted (#518, owner decision O-518):
+ * every entity has a primary key — `entity()` refuses one without — and a live query over a keyed
+ * table is correct on DEFAULT identity, because the shared window holds the whole row the
+ * in/out/delete decision needs (`realtime/src/pg-identity-window.live.test.ts`, on real WAL). FULL
+ * there only made every UPDATE and DELETE log the whole old row. A table already on FULL keeps it:
+ * `replica-identity.ts` never reverts, and the drift step reads a recorded FULL as agreement.
+ *
  * Sorted so the same app generates the same bytes whatever order its modules registered in — the
  * rule `@ultimat3/db`'s own `pending()` states one layer down, kept here too because a caller that
  * ordered by registration would put a diff in a file for nothing.
  *
- * Every name is checked against `tables` BEFORE any of them is returned: a run that emitted the
- * good half and refused afterwards would leave an author with a migration that is right for one
- * table and silently absent for the other.
+ * Every `subscribes:` name is checked against `tables` BEFORE anything is returned, so a refused
+ * declaration never leaves a migration half-written behind it.
  *
  * `channelTables` defaults to what the declared channels need (`paramsChannelTables()`): a channel
  * with params routes a DELETE to the topic the OLD row names, and under the default identity that
@@ -76,14 +81,12 @@ export function replicaIdentityTables(
   tables: ReadonlySet<string>,
   channelTables: readonly string[] = paramsChannelTables(),
 ): readonly string[] {
-  const wanted = new Set<string>(channelTables.filter((table) => tables.has(table)));
   for (const query of queries) {
     for (const table of query.subscribes ?? []) {
       if (!tables.has(table)) {
         throw new QuerySubscribesUnknownError({ query: query.name, table, tables });
       }
-      wanted.add(table);
     }
   }
-  return [...wanted].sort();
+  return [...new Set(channelTables.filter((table) => tables.has(table)))].sort();
 }

package/src/dev-boot.ts

@@ -0,0 +1,290 @@
+// `x dev`'s boot: every role in one Bun process, embedded Postgres/events/storage started for real,
+// the app's own modules loaded into the framework's registries, the route table they hold served
+// over HTTP with `/_x` beside it, and the watcher that rebuilds on save (`dev-rebuild.ts`). The
+// command that prints it and holds the process is `cmd-dev.ts`.
+
+import { devShellStyle } from '@ultimat3/admin/dev';
+import type { Role } from '@ultimat3/core';
+import { configureTelemetry, noopExporter } from '@ultimat3/core';
+import { setStatementObserver } from '@ultimat3/db';
+import type { OverlayNotice, RequestContext } from '@ultimat3/http';
+import { asCtx } from '@ultimat3/http';
+import { loadSignInPath } from './app-auth';
+import { appManifest } from './app-manifest';
+import type { StalePin } from './app-reload-graph';
+import { enableReloadTracking } from './app-reload-graph';
+import { loadAppRuntime } from './app-runtime';
+import type { DevDashboardInput, DevStatus } from './dev-dashboard';
+import { devPanels } from './dev-dashboard';
+import { declareDevEnvironment, needsDevEnvironmentDeclaration } from './dev-environment';
+import { createStatementLedger } from './dev-n-plus-one';
+import type { DevState } from './dev-rebuild';
+import { devRebuilder } from './dev-rebuild';
+import { devRouteTable } from './dev-route-table';
+import { createTraceRecorder } from './dev-traces';
+import { watchTree } from './dev-watch-tree';
+import { buildIslands } from './island-bundle';
+import { FRAME_STYLE } from './island-harness';
+import type { Finding } from './output';
+import type { RunningRoles } from './role-start';
+import { DEV_ROLES, startRoles } from './role-start';
+import type { DevServices } from './runtime-bindings';
+import { resolveServices, withRealtimeEvents } from './runtime-bindings';
+import { attachedIsr } from './runtime-isr';
+import type { RuntimeOverrides } from './runtime-overrides';
+import { replicaOverrides } from './runtime-replica';
+import type { RunningServices } from './runtime-services';
+import { releaseOrThrow, startServices } from './runtime-services';
+import { metricsPortFor, releaseBoot } from './serve';
+import { loopFacts, loopFinding, loopNotice } from './statement-loop';
+
+export interface DevServer {
+  readonly url: string;
+  readonly services: DevServices;
+  readonly roles: readonly Role[];
+  /**
+   * `BUILD_ID` when stamped — the id every response carries. Otherwise the manifest as it stands
+   * now, so a reload that registers a new route moves it.
+   */
+  readonly buildId: string;
+  /**
+   * Modules that would not import, primitives that would not register, reloads that would not
+   * build — and the statement loops this process has counted so far, which is what puts an N+1 in
+   * `x dev`'s own output and in `--json` without a channel of its own.
+   */
+  readonly findings: readonly Finding[];
+  readonly running: RunningRoles;
+  readonly runtime: RunningServices;
+  /** Panel keys `/_x` mounted, in tab order. Reported so `--json` names what is reachable. */
+  readonly panels: readonly string[];
+  /** `POST <path>` of the app's default MCP endpoint, or `null` when nothing was mounted. */
+  readonly mcp: string | null;
+  /** `POST <path>` of every mounted MCP endpoint, default first — `[]` when none was. */
+  readonly mcpPaths: readonly string[];
+  stop(): Promise<void>;
+}
+
+export interface StartDevOptions {
+  readonly root: string;
+  readonly port: number;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly roles?: readonly Role[];
+  readonly onReload?: (file: string, durationMs: number) => void;
+  /**
+   * A save reached a module that defines a primitive, so this process cannot serve it
+   * (`takeStalePins`). Given, it is called INSTEAD of `onReload` — `x dev`'s child drains and exits
+   * for its supervisor to boot a fresh one. Absent, the save is `X_DEV_RESTART_REQUIRED` on `/_x`.
+   */
+  readonly onRestart?: (pins: readonly StalePin[]) => void;
+}
+
+/**
+ * The environment `devDashboard` refuses to mount in. Spread conditionally rather than passed as
+ * `undefined`: `exactOptionalPropertyTypes` makes "absent" and "explicitly undefined" different
+ * answers, and only the absent one lets the dashboard read the process environment itself.
+ */
+const envOf = (env: StartDevOptions['env']): { env?: string } => {
+  const value = env['NODE_ENV'] ?? env['X_ENV'];
+  return value === undefined ? {} : { env: value };
+};
+
+/**
+ * Boot order is the production order: services first, then the app's modules (importing them IS
+ * the registration), then the roles that serve what those modules registered. A module that
+ * fails to import becomes a finding rather than a dead process — the point of the dev loop is to
+ * still be reachable while something is broken.
+ */
+export async function startDev(options: StartDevOptions): Promise<DevServer> {
+  // EVERY boot: a scratch server (`x shot`, `ui.shot`) boots here too, and without this a
+  // fail-closed dev actor installs nothing — the picture is of a 401. Idempotent.
+  declareDevEnvironment(options.env);
+  // Before the first scan: the watcher's rescans evict a saved module AND everything importing it,
+  // and that needs the import graph recorded as each module is first loaded (`app-reload-graph.ts`).
+  enableReloadTracking(true);
+  // The declaration lands on `process.env`; the env this boot passes on must carry it too, or every
+  // service resolved from `options.env` still reads no `ULTIMATE_ENV`.
+  const env = needsDevEnvironmentDeclaration(options.env)
+    ? { ...options.env, ULTIMATE_ENV: 'development' }
+    : options.env;
+  const resolved = resolveServices(options.root, env);
+  // The app's `apps/<app>/runtime.ts`, read ONCE and handed to `startServices` exactly as
+  // `serve.ts`'s `withAppRuntime` does — so the disks (`storage`), the queue, the mail driver and
+  // every other override a deployment declares are the ones development runs too. Until 22.4 this
+  // boot passed nothing here and built its own embedded disk, so an app's `/_storage` routes and its
+  // actions wrote to two different places in `x dev` and to one in production.
+  const appRuntime = await loadAppRuntime(options.root);
+  const runtime: RunningServices = await startServices(resolved, env, appRuntime);
+  // The events binding the boot line reports is the bus the runtime chose, read off it.
+  const services = withRealtimeEvents(resolved, env, runtime.realtime);
+  // `serve.ts`'s `releaseBoot` shape: everything acquired from here on is released, newest first,
+  // if the boot throws — a failed `x dev` left PGlite holding `.x/pgdata` for the retry to meet.
+  const acquired: (() => void | Promise<void>)[] = [() => runtime.stop()];
+  try {
+    return await bootDev(options, services, runtime, acquired, appRuntime);
+  } catch (error) {
+    await releaseBoot(acquired);
+    throw error;
+  }
+}
+
+async function bootDev(
+  options: StartDevOptions,
+  services: ReturnType<typeof resolveServices>,
+  runtime: RunningServices,
+  acquired: (() => void | Promise<void>)[],
+  appRuntime: RuntimeOverrides | undefined,
+): Promise<DevServer> {
+  // Installed before the app loads, so a span opened during registration is already recorded.
+  // Tracing is always on in the framework and free until an exporter is configured; `x dev` is
+  // what configures one, which is the whole reason `/_x/timeline` has anything to draw.
+  const traces = createTraceRecorder();
+  configureTelemetry({ exporter: traces.exporter });
+  acquired.push(() => {
+    configureTelemetry({ exporter: noopExporter });
+    traces.reset();
+  });
+  // Installed at the same moment and for the same reason: an observer is the single switch that
+  // turns statement instrumentation on at all (`@ultimat3/db`'s `observe.ts`), so the timeline's
+  // SQL rows and the repeat counts arrive together rather than through two toggles. `serve.ts`
+  // installs neither — a production process pays the one `undefined` branch the seam costs
+  // uninstalled, and nothing more (axiom 6).
+  const statements = createStatementLedger();
+  setStatementObserver(statements.observer);
+  acquired.push(() => {
+    setStatementObserver(undefined);
+    statements.reset();
+  });
+  // ONE load at boot, the same call the rebuild below makes: the manifest and the findings are
+  // two projections of one scan. Until 2026-09-07 this was `loadApp` for the findings and then
+  // `appManifest` — which loads again — for the manifest, so a save landing between the two put
+  // `/_x`'s findings and its manifest on different registration states.
+  const app = await appManifest(options.root);
+  const state: DevState = {
+    manifest: app.manifest,
+    reloads: 0,
+    reloadFinding: undefined,
+    appFindings: app.findings,
+    islands: await buildIslands(options.root),
+  };
+  // The manifest's build id is a content hash of every fact below it, so a dev document's
+  // `x-ultimate-build` header names the exact shape the client was served against. Pinned at
+  // boot on purpose: the header is handed to the HTTP config and the render modes once, and a
+  // reload cannot re-pin it — `state.manifest.buildId` is what `/_x` and `--json` report, so a
+  // divergence between the two is visible rather than silent, and a restart closes it.
+  // `BUILD_ID` wins when set — `serve.ts`'s rule, so an e2e `deploy.newBuild()` can restart `x dev`
+  // as a new build with the same sources.
+  // Stamped, it is ALSO what `server.buildId` answers below: the process serves no other build.
+  const rawStamp = options.env['BUILD_ID'];
+  const stamped = rawStamp !== undefined && rawStamp !== '' ? rawStamp : undefined;
+  const buildId = stamped ?? state.manifest.buildId;
+
+  let server: DevServer;
+  // Read at request time, never captured at boot: `/_x/services` must report the reload counter
+  // and the findings as they are now, not as they were when the route table was built.
+  const dashboard: DevDashboardInput = {
+    root: options.root,
+    runtime,
+    status: (): DevStatus => ({
+      url: server.url,
+      services: server.services,
+      roles: server.roles,
+      findings: server.findings,
+      reloads: state.reloads,
+    }),
+    traces,
+    statements,
+    ...envOf(options.env),
+  };
+  const panels = devPanels(dashboard).map((panel) => panel.key);
+
+  // `x dev`'s own, so a reload can empty it (a save otherwise kept a page's first render for its
+  // ttl); attached, so a tag bust reaches it too. Released with the roles.
+  const { isr, release: releaseIsr } = attachedIsr({ buildId });
+  acquired.push(releaseIsr);
+  const { routes, theme, speculation, inlineStyles, mcpPath, mcpPaths } = await devRouteTable({
+    isr,
+    root: options.root,
+    env: options.env,
+    buildId,
+    storage: runtime.storage,
+    dashboard,
+    islands: () => state.islands,
+    realtime: runtime.realtime,
+    rateLimitStore: appRuntime?.rateLimitStore ?? runtime.rateLimitStore,
+    appRoutes: appRuntime?.routes,
+    images: appRuntime?.images,
+  });
+
+  // The app's `apps/<app>/runtime.ts`, composed exactly as `runRole` composes a caller's
+  // `runtime`: the replica scope in front, the app's own middleware behind it. Before this the
+  // first argument was `undefined` here and an app's middleware reached no development process.
+  const replicaOverride = replicaOverrides(appRuntime, services.db, options.env);
+  const running = await startRoles({
+    roles: options.roles ?? DEV_ROLES,
+    port: options.port,
+    // `serve.ts`'s expression, called rather than restated: `METRICS_PORT` was read in the
+    // container and ignored here, so the scrape port an operator moved was the one port `x dev`
+    // could not move — and the second `x dev` on a box died binding the hardcoded 9090.
+    metricsPort: metricsPortFor(options.env, options.port),
+    buildId,
+    runtime,
+    routes,
+    env: options.env,
+    // Read from `app.config.ts` rather than threaded through `DevOptions`: `x dev` and `serve.ts`
+    // must not be able to disagree about where the app's sign-in page is.
+    signInPath: await loadSignInPath(options.root),
+    // The same seam `serve.ts` passes: the app's own error page is a FILE under this root.
+    root: options.root,
+    // The `/_x` shell, the harness's frame, the app's own error pages and its brand — the inline
+    // bodies this process serves; the app's surfaces are content-hashed files `'self'` admits.
+    inlineStyles: [await devShellStyle(), FRAME_STYLE, ...inlineStyles],
+    inlineScripts: [theme.cspSource, ...(speculation === undefined ? [] : [speculation.cspSource])],
+    // The overlay renders this request's own loops under the error it is already showing.
+    // `serve.ts` boots through the same `startRoles` and passes nothing (axiom 6).
+    devNotices: (ctx: RequestContext): readonly OverlayNotice[] =>
+      statements.repeatsFor(asCtx(ctx)).map(loopFacts).map(loopNotice),
+    // The read-replica scope, opened per request. Absent for every app that names no
+    // `DATABASE_REPLICA_URL` — which is every embedded boot by construction, since PGlite has no
+    // standby — so this key does not exist on a homework app's boot at all.
+    ...(replicaOverride === undefined ? {} : { overrides: replicaOverride }),
+  });
+  acquired.push(() => running.stop());
+
+  const rebuild = devRebuilder(options, state, isr);
+  // Watched one directory at a time, so an ignored one costs no descriptor at all — `dev-watch.ts`
+  // decides which, from the app's own `.gitignore`. A recursive watch on the root registered one
+  // inotify descriptor per directory in the tree, `.git/`, `node_modules/` and the `.x/` this
+  // process writes to included, and filtered the events afterwards.
+  const watcher = watchTree({ root: options.root, onChange: rebuild });
+
+  server = {
+    url: running.url ?? `http://localhost:${options.port}`,
+    services,
+    roles: running.roles,
+    mcp: mcpPath,
+    mcpPaths,
+    get buildId(): string {
+      return stamped ?? state.manifest.buildId;
+    },
+    // A getter, not a snapshot: `/_x` and `--json` must show the reload that just failed and the
+    // loop the last request tripped, not the findings as they were when the route table was built.
+    // The loops come last and carry their request id, so a boot report reads as a boot report and
+    // a diagnostic that arrived a minute later reads as one too.
+    get findings(): readonly Finding[] {
+      const loops = statements.repeats().map(loopFacts).map(loopFinding);
+      return state.reloadFinding === undefined
+        ? [...state.appFindings, ...loops]
+        : [...state.appFindings, state.reloadFinding, ...loops];
+    },
+    running,
+    runtime,
+    panels,
+    // The boot's own unwind list IS the stop list — one list, so the two cannot drift — plus the
+    // watcher. Every step runs and the first failure is rethrown (`releaseOrThrow`): one refused
+    // role stop used to leave PGlite's lock held for the next `x dev`. Newest first: the watcher,
+    // the roles, ISR, the statement ledger and the exporter (after the roles, so an in-flight
+    // request still has both), then the services.
+    stop: () => releaseOrThrow([...acquired, () => watcher.close()]),
+  };
+  return server;
+}