@ultimat3/cli 22.6.1 → 22.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.6.1",
+  "version": "22.7.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -38,33 +38,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "22.6.1",
-    "@ultimat3/admin": "22.6.1",
-    "@ultimat3/ai": "22.6.1",
-    "@ultimat3/auth": "22.6.1",
-    "@ultimat3/cache": "22.6.1",
-    "@ultimat3/core": "22.6.1",
-    "@ultimat3/db": "22.6.1",
-    "@ultimat3/entity": "22.6.1",
-    "@ultimat3/flags": "22.6.1",
-    "@ultimat3/http": "22.6.1",
-    "@ultimat3/i18n": "22.6.1",
-    "@ultimat3/jobs": "22.6.1",
-    "@ultimat3/mail": "22.6.1",
-    "@ultimat3/manifest": "22.6.1",
-    "@ultimat3/mcp": "22.6.1",
-    "@ultimat3/money": "22.6.1",
-    "@ultimat3/notify": "22.6.1",
-    "@ultimat3/policy": "22.6.1",
-    "@ultimat3/pwa": "22.6.1",
-    "@ultimat3/query": "22.6.1",
-    "@ultimat3/realtime": "22.6.1",
-    "@ultimat3/render": "22.6.1",
-    "@ultimat3/schema": "22.6.1",
-    "@ultimat3/seo": "22.6.1",
-    "@ultimat3/storage": "22.6.1",
-    "@ultimat3/testing": "22.6.1",
-    "@ultimat3/time": "22.6.1",
+    "@ultimat3/action": "22.7.0",
+    "@ultimat3/admin": "22.7.0",
+    "@ultimat3/ai": "22.7.0",
+    "@ultimat3/auth": "22.7.0",
+    "@ultimat3/cache": "22.7.0",
+    "@ultimat3/core": "22.7.0",
+    "@ultimat3/db": "22.7.0",
+    "@ultimat3/entity": "22.7.0",
+    "@ultimat3/flags": "22.7.0",
+    "@ultimat3/http": "22.7.0",
+    "@ultimat3/i18n": "22.7.0",
+    "@ultimat3/jobs": "22.7.0",
+    "@ultimat3/mail": "22.7.0",
+    "@ultimat3/manifest": "22.7.0",
+    "@ultimat3/mcp": "22.7.0",
+    "@ultimat3/money": "22.7.0",
+    "@ultimat3/notify": "22.7.0",
+    "@ultimat3/policy": "22.7.0",
+    "@ultimat3/pwa": "22.7.0",
+    "@ultimat3/query": "22.7.0",
+    "@ultimat3/realtime": "22.7.0",
+    "@ultimat3/render": "22.7.0",
+    "@ultimat3/schema": "22.7.0",
+    "@ultimat3/seo": "22.7.0",
+    "@ultimat3/storage": "22.7.0",
+    "@ultimat3/testing": "22.7.0",
+    "@ultimat3/time": "22.7.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-load.ts

@@ -6,12 +6,12 @@
 // Bun ships no `Bun.*` path API: `relative`/`sep` turn an absolute scan hit into the app-root-
 // relative POSIX path every finding and every manifest fact is keyed by.
 import { join, relative, resolve, sep } from 'node:path';
-import { listActions, registerActions } from '@ultimat3/action';
-import { describeEntities } from '@ultimat3/entity';
+import { isAction, isMutator, listActions, registerActions } from '@ultimat3/action';
+import { describeEntities, registeredEntities } from '@ultimat3/entity';
 import { localeConfig } from '@ultimat3/i18n';
-import { registeredJobs, registeredTasks } from '@ultimat3/jobs';
+import { isJobHandle, isTaskHandle, registeredJobs, registeredTasks } from '@ultimat3/jobs';
 import type { ErrorCodeFact } from '@ultimat3/manifest';
-import { listQueries, registerQueries } from '@ultimat3/query';
+import { isQuery, listQueries, registerQueries } from '@ultimat3/query';
 import type { RouteConfig } from '@ultimat3/render';
 import {
   isRouteConfig,
@@ -28,6 +28,13 @@ import {
 // accident one refactor away from compiling every app's `.tsx` to `React.createElement`. The named
 // import is a value import, so the side effect holds without the bare line it replaced.
 import { setStylesheetRoot } from '@ultimat3/render/server';
+import {
+  evictChanged,
+  pinModule,
+  resetReloadGraph,
+  trackModule,
+  trackStylesheets,
+} from './app-reload-graph';
 import { API_INDEX, APP_CONFIG_FILE } from './app-root';
 import { collectDeclaredCodes } from './error-contract';
 import type { Finding } from './output';
@@ -89,30 +96,29 @@ export interface LoadedApp {
 
 // A module is imported and registered once per PROCESS: `import()` caches, and a registry rejects
 // a second registration of a name. So a rescan refreshes the facts DERIVED from the registries —
-// the manifest and its build id — and, for exactly one kind of module, the primitive itself. A
-// ROUTE module whose source changed is imported again under `?x-reload=<hash>`, the one cache key
-// Bun honours, and `registerRoute` replaces the entry for the same file; its own imports resolve
-// to the modules already cached, which is what makes it safe. An action, a query or an entity
-// stays registered once: its exports are held by every module that imported it, a second instance
-// would be a duplicate name in its registry, and no re-import can rebind the importers — those
-// edits need a restart. Until 2026-09-07 the route module took the same rule, so a save re-bundled
-// the island (`buildIslands` reads the disk) and kept the FIRST page component — a new island
-// rendering under an old page's props, which is the mixed generation `x dev` served.
+// the manifest and its build id — and, for exactly one kind of module, the registration itself. A
+// rescan first evicts every changed module, and everything that imports it, from Bun's registry
+// (`app-reload-graph.ts`), so the loop's own `import()` evaluates the new chain; a ROUTE module
+// that comes back as a different instance has its entry replaced. A module that defines a
+// primitive (an action, a query, an entity, a job, a task) is pinned instead — its exports are held
+// by every importer and a second instance would be a duplicate name in its registry — so those
+// edits still need a restart. Until 2026-09-27 only the route module itself was re-imported, under
+// `?x-reload=<hash>`, and every component it imports stayed the cached one: `x dev` logged
+// "reloaded" and served the old component.
 const registered = new Set<string>();
 // A registration failure is sticky: the file is never retried, so the finding is replayed.
 const failures = new Map<string, Finding>();
-// Route modules only: the hash of the source each one registered from, which is what a rescan
-// compares the disk against. A save that leaves the bytes alone re-imports nothing.
-const routeSources = new Map<string, bigint>();
-
-/** The query a re-imported route module carries. `module-loader.ts`'s filter admits it. */
-const RELOAD_QUERY = 'x-reload';
+// Route modules only: the module instance each one registered from. A rescan that imports the same
+// instance registers nothing; a different one (the file or something it imports was evicted) is
+// the page the author saved.
+const routeModules = new Map<string, Record<string, unknown>>();
 
 /** Test seam, and what `x dev` would call if it ever restarted the registries in-process. */
 export function resetAppLoad(): void {
   registered.clear();
   failures.clear();
-  routeSources.clear();
+  routeModules.clear();
+  resetReloadGraph();
 }
 
 /**
@@ -156,6 +162,9 @@ export async function loadApp(root: string): Promise<LoadedApp> {
   setAssetResolver((path) => assets.resolve(path).url);
   const files: string[] = [];
   const findings: Finding[] = [];
+  // A rescan: whatever changed on disk since the last one, and everything importing it, leaves
+  // Bun's module registry before the loop below imports it again.
+  if (registered.size > 0) await evictChanged(root);
 
   for (const absolute of await appModulePaths(root)) {
     // A SEGMENT, never a substring: an app checked out under
@@ -168,13 +177,16 @@ export async function loadApp(root: string): Promise<LoadedApp> {
     if (ENTRY_POINT.test(file) || CLIENT_ENTRY_POINT.test(file) || STATES_FILE.test(file)) {
       continue;
     }
-    // The source is read BEFORE the import, and only on the file's first pass — a rescan of a
-    // registered module reads nothing here. A route entry is bound to the bytes the module was
-    // evaluated from, and a read AFTER the import cannot know which bytes those were: a save
-    // landing between the two bound V1's component to V2's hash, so the next scan saw nothing to
-    // do and served V1 until the save after. Read first, the worst case is one re-import the
-    // next tick, of a file that did change.
-    const snapshot = registered.has(absolute) ? undefined : await Bun.file(absolute).text();
+    // The source is read BEFORE the import, on the file's first pass and for every route module —
+    // a rescan of any other registered module reads nothing here. What is recorded is bound to the
+    // bytes the module was evaluated from, and a read AFTER the import cannot know which bytes
+    // those were: a save landing between the two bound V1's component to V2's hash, so the next
+    // scan saw nothing to do and served V1 until the save after. Read first, the worst case is one
+    // re-import the next tick, of a file that did change.
+    const first = !registered.has(absolute) && !failures.has(absolute);
+    const snapshot =
+      first || routeModules.has(absolute) ? await Bun.file(absolute).text() : undefined;
+    if (first && snapshot !== undefined) await trackModule(absolute, snapshot, root);
     let module: Record<string, unknown>;
     try {
       module = (await import(absolute)) as Record<string, unknown>;
@@ -188,6 +200,7 @@ export async function loadApp(root: string): Promise<LoadedApp> {
   }
 
   files.sort();
+  await trackStylesheets(root);
   // An app that imported NOTHING and reported nothing is a registry every later step reads as
   // empty-and-fine. With an `app.config.ts` beside it, that is never what the author meant.
   if (
@@ -226,8 +239,8 @@ const emptyAppFinding = (root: string): Finding => ({
 
 /**
  * Registers a module once; every later call replays whatever the first one reported — except for
- * a route module, which a later call re-registers from disk when its source has changed.
- * `snapshot` is the source read before the module's first import, and absent on every later call.
+ * a route module, which a later call re-registers when the import handed back a new instance.
+ * `snapshot` is the source read before this import: always for a first pass and a route module.
  */
 async function register(
   absolute: string,
@@ -237,16 +250,18 @@ async function register(
 ): Promise<Finding | undefined> {
   const previous = failures.get(absolute);
   if (previous !== undefined) return previous;
-  if (snapshot === undefined) return reloadRoute(absolute, file);
+  if (registered.has(absolute)) return reloadRoute(absolute, file, module, snapshot);
   registered.add(absolute);
   try {
     const config = module['config'];
     const route = isRouteConfig(config) ? config : undefined;
-    if (route !== undefined) registerRouteModule(file, module, route, snapshot);
+    if (route !== undefined && snapshot !== undefined) {
+      registerRouteModule(file, module, route, snapshot);
+      routeModules.set(absolute, module);
+    }
+    if (definesPrimitive(module, route !== undefined) || file === API_INDEX) pinModule(absolute);
     registerActions(module);
     registerQueries(module);
-    // Only a route module is ever re-imported, so only a route module's hash is worth keeping.
-    if (route !== undefined) routeSources.set(absolute, Bun.hash.wyhash(snapshot));
     return undefined;
   } catch (error) {
     const finding: Finding = { ...findingFrom(error), at: file };
@@ -255,6 +270,31 @@ async function register(
   }
 }
 
+/**
+ * A module whose instance must be the one every importer and every registry holds. A route module
+ * may export an action beside its page — it has always been re-imported, and its actions stayed
+ * registered from the first instance — so only an entity, a job or a task pins a route.
+ */
+function definesPrimitive(module: Record<string, unknown>, route: boolean): boolean {
+  // The registry holds an entry per entity; the value a module exports is the entry's `core`.
+  const entities = new Set<unknown>(registeredEntities().flatMap((entry) => [entry, entry.core]));
+  const defines = (value: unknown): boolean =>
+    entities.has(value) ||
+    isJobHandle(value) ||
+    isTaskHandle(value) ||
+    (!route && (isAction(value) || isQuery(value) || isMutator(value)));
+  return Object.values(module).some((value) => {
+    // A brand check reads a property, and an export may be a proxy whose every read throws until
+    // the env is set — examples/dummy's typed client throws X_ENV_MISSING without APP_URL. A value
+    // that cannot be asked is not a primitive: every primitive is a plain branded object.
+    try {
+      return defines(value);
+    } catch {
+      return false;
+    }
+  });
+}
+
 /**
  * The route half of a registration, and the whole of a re-registration. `source` is the text the
  * module was imported from — read by the caller BEFORE the import, never here after it — and the
@@ -283,25 +323,26 @@ function registerRouteModule(
 }
 
 /**
- * A registered route module, on a rescan: imported again if the file no longer hashes to what it
- * registered from, and left alone otherwise. A save that will not import is a finding at the file
- * and NOT a sticky one — the next save is tried again — and the entry it would have replaced stays
- * registered, so the last page that did import is the one served meanwhile.
+ * A registered route module, on a rescan: re-registered when the import handed back a different
+ * instance — the file or something it imports was evicted — and left alone otherwise. A save that
+ * will not import never reaches here (the loop reports it, not sticky), so the last page that did
+ * import is the one served meanwhile.
  */
-async function reloadRoute(absolute: string, file: string): Promise<Finding | undefined> {
-  const registeredFrom = routeSources.get(absolute);
-  if (registeredFrom === undefined) return undefined;
-  const source = await Bun.file(absolute).text();
-  const hash = Bun.hash.wyhash(source);
-  if (hash === registeredFrom) return undefined;
+function reloadRoute(
+  absolute: string,
+  file: string,
+  module: Record<string, unknown>,
+  source: string | undefined,
+): Finding | undefined {
+  const held = routeModules.get(absolute);
+  if (held === undefined || held === module || source === undefined) return undefined;
   try {
-    const module = (await import(`${absolute}?${RELOAD_QUERY}=${hash}`)) as Record<string, unknown>;
     const config = module['config'];
     // A file that stopped being a route is not un-registered — the table has no verb for it, and a
-    // deleted file needs a restart either way. Its hash is recorded so the same save is not
-    // re-imported on every later tick.
+    // deleted file needs a restart either way. Its instance is recorded so the same save is not
+    // re-registered on every later tick.
     if (isRouteConfig(config)) registerRouteModule(file, module, config, source);
-    routeSources.set(absolute, hash);
+    routeModules.set(absolute, module);
     return undefined;
   } catch (error) {
     return { ...findingFrom(error), at: file };

package/src/app-reload-graph.ts

@@ -0,0 +1,228 @@
+// Which modules a rescan must evaluate again, and making Bun do it. `import()` caches by path for
+// the life of the process, so a re-import sees the edited file only once that path has left Bun's
+// module registry (`delete require.cache[path]`, which Bun 1.4 honours for ES modules too). Until
+// 2026-09-27 `x dev` re-imported only the edited ROUTE module, under `?x-reload=<hash>`, and every
+// module that route imports resolved to the instance already cached: a save to a component, its
+// `.module.scss` or a helper logged "reloaded" and rendered the old code until a restart
+// (notificado.co: the panel's balance card and the home page, observed twice on one day).
+//
+// The rule is a reverse-dependency closure. A rescan hashes every file this graph knows; each
+// changed file, and every module that imports it transitively, leaves the registry, and the scan's
+// own `import()` of each app module then evaluates the new chain. Evicting the entry — rather than
+// a query per save — is also what keeps the process flat: the replaced instance has no referrer
+// once the route table holds the new page, and is collected. A query key is a new registry entry
+// per save, never freed.
+//
+// A module that DEFINES a primitive is PINNED and never leaves the registry: its exports are held
+// by every importer and by a registry that refuses a second definition of one name (an entity is
+// `X_ENTITY_DUPLICATE`; a second action instance is a handler nobody routes to). The closure stops
+// at a pinned module, and an edit to one still needs a restart — exactly what it needed before.
+
+// why: Bun ships no path API; import specifiers resolve against the importing file's directory.
+import { dirname, resolve } from 'node:path';
+import { registeredStylesheets } from '@ultimat3/render/server';
+import { hasPathSegment } from './path-segments';
+
+type Kind = 'script' | 'style' | 'data';
+
+interface Node {
+  readonly kind: Kind;
+  /** `null`: the file is gone. A deleted file is a change too — its importers must fail loudly. */
+  hash: bigint | null;
+  /** The in-app files this one imports (a sheet: the partials its compilation read). */
+  deps: Set<string>;
+}
+
+const nodes = new Map<string, Node>();
+/** Reverse edges: file → the files that import it. */
+const importers = new Map<string, Set<string>>();
+const pinned = new Set<string>();
+/**
+ * Edges cost a transpile scan and a resolve per import (~300 ms over notificado.co's 1200 modules),
+ * so only the one process that rescans pays it: `x dev` turns this on before its first scan. Off,
+ * a rescan still re-evaluates each changed module itself — a route saved in place reloads — but
+ * nothing it is imported by.
+ */
+let tracking = false;
+
+export function enableReloadTracking(on: boolean): void {
+  tracking = on;
+}
+
+/** Test seam, and `resetAppLoad`'s: forget every file, edge and pin. */
+export function resetReloadGraph(): void {
+  nodes.clear();
+  importers.clear();
+  pinned.clear();
+}
+
+/** Marks a module that defines a primitive: never evicted, and the closure stops at it. */
+export function pinModule(absolute: string): void {
+  pinned.add(absolute);
+}
+
+const SCRIPT = /\.(?:[cm]?[jt]sx?)$/;
+const STYLE = /\.(?:s[ac]ss|css)$/;
+
+const kindOf = (path: string): Kind =>
+  SCRIPT.test(path) ? 'script' : STYLE.test(path) ? 'style' : 'data';
+
+const transpilers = {
+  ts: new Bun.Transpiler({ loader: 'ts' }),
+  tsx: new Bun.Transpiler({ loader: 'tsx' }),
+};
+
+const readText = async (path: string): Promise<string | null> => {
+  try {
+    return await Bun.file(path).text();
+  } catch {
+    return null;
+  }
+};
+
+const hashOf = (text: string | null): bigint | null =>
+  text === null ? null : BigInt(Bun.hash.wyhash(text));
+
+/** The in-app files `source` imports — a package under `node_modules` is not the app's to reload. */
+function importsOf(path: string, source: string, root: string): string[] {
+  let specifiers: readonly { readonly path: string }[];
+  try {
+    const transpiler = path.endsWith('x') ? transpilers.tsx : transpilers.ts;
+    specifiers = transpiler.scanImports(source);
+  } catch {
+    // A file that will not parse imports nothing yet; its own hash still changes on the fix.
+    return [];
+  }
+  const found: string[] = [];
+  for (const { path: specifier } of specifiers) {
+    let target: string;
+    try {
+      target = Bun.resolveSync(specifier, dirname(path));
+    } catch {
+      continue;
+    }
+    if (target.startsWith(`${root}/`) && !hasPathSegment(target, 'node_modules')) {
+      found.push(target);
+    }
+  }
+  return found;
+}
+
+function link(from: string, to: string): void {
+  let set = importers.get(to);
+  if (set === undefined) {
+    set = new Set();
+    importers.set(to, set);
+  }
+  set.add(from);
+}
+
+function unlink(from: string, node: Node): void {
+  for (const dep of node.deps) importers.get(dep)?.delete(from);
+  node.deps = new Set();
+}
+
+async function edges(path: string, node: Node, source: string, root: string): Promise<void> {
+  unlink(path, node);
+  for (const dep of importsOf(path, source, root)) {
+    node.deps.add(dep);
+    link(path, dep);
+    if (!nodes.has(dep)) await track(dep, await readText(dep), root);
+  }
+}
+
+/**
+ * Records `absolute` as it reads NOW — `source` is the text the caller is about to import, read
+ * before the import, so a save landing mid-import is a change on the next rescan rather than a
+ * hash bound to bytes that were never evaluated.
+ */
+export async function trackModule(absolute: string, source: string, root: string): Promise<void> {
+  await track(absolute, source, resolve(root));
+}
+
+async function track(path: string, source: string | null, root: string): Promise<void> {
+  const node: Node = nodes.get(path) ?? { kind: kindOf(path), hash: null, deps: new Set() };
+  nodes.set(path, node);
+  node.hash = hashOf(source);
+  if (tracking && node.kind === 'script' && source !== null) await edges(path, node, source, root);
+}
+
+/**
+ * After a scan: every sheet the loader compiled, and an edge from each partial it read to it. A
+ * partial is not a module — nothing imports it — so this is the only place its edits are seen.
+ */
+export async function trackStylesheets(root: string): Promise<void> {
+  if (!tracking) return;
+  const base = resolve(root);
+  const inApp = (path: string): boolean =>
+    path.startsWith(`${base}/`) && !hasPathSegment(path, 'node_modules');
+  for (const sheet of registeredStylesheets()) {
+    if (!inApp(sheet.file)) continue;
+    if (!nodes.has(sheet.file)) await track(sheet.file, await readText(sheet.file), base);
+    const node = nodes.get(sheet.file);
+    if (node === undefined) continue;
+    for (const dep of sheet.dependencies) {
+      if (!inApp(dep)) continue;
+      node.deps.add(dep);
+      link(sheet.file, dep);
+      if (!nodes.has(dep)) await track(dep, await readText(dep), base);
+    }
+  }
+}
+
+/** Every file that changed since it was recorded, re-recorded as it reads now. */
+async function changedFiles(root: string): Promise<string[]> {
+  const known = [...nodes.keys()];
+  const texts = await Promise.all(known.map(readText));
+  const changed: string[] = [];
+  for (const [index, path] of known.entries()) {
+    const node = nodes.get(path);
+    const text = texts[index] ?? null;
+    if (node === undefined || hashOf(text) === node.hash) continue;
+    changed.push(path);
+    await track(path, text, root);
+  }
+  return changed;
+}
+
+/** `changed` and everything above it, stopping at — and excluding — every pinned module. */
+function closure(changed: readonly string[]): Set<string> {
+  const dirty = new Set<string>();
+  const stack = changed.filter((path) => !pinned.has(path));
+  while (stack.length > 0) {
+    const path = stack.pop();
+    if (path === undefined || dirty.has(path)) continue;
+    dirty.add(path);
+    for (const importer of importers.get(path) ?? []) {
+      if (!pinned.has(importer)) stack.push(importer);
+    }
+  }
+  return dirty;
+}
+
+/**
+ * The start of a rescan: evicts every changed module and its importers from Bun's registry, so
+ * the scan's `import()` evaluates them again. A sheet is re-imported here as well, because a
+ * partial's edit changes no importer's text — the loader's `onLoad` is what re-registers its CSS.
+ * Returns the evicted paths.
+ */
+export async function evictChanged(root: string): Promise<ReadonlySet<string>> {
+  const dirty = closure(await changedFiles(resolve(root)));
+  const reloadSheets: string[] = [];
+  for (const path of dirty) {
+    // A sheet the process never loaded (a partial) has nothing for its own import to refresh.
+    if (nodes.get(path)?.kind === 'style' && path in require.cache) reloadSheets.push(path);
+    // Unconditionally: a module whose import FAILED is absent from `require.cache` and still held
+    // by Bun's loader — measured on 1.4.0, the fixed file kept throwing the old parse error until
+    // this delete, which clears that entry too.
+    delete require.cache[path];
+  }
+  for (const sheet of reloadSheets) {
+    try {
+      await import(sheet);
+    } catch {
+      // Reported where it matters: the module that imports the sheet fails its import, at its file.
+    }
+  }
+  return dirty;
+}

package/src/cmd-build-spec.ts

@@ -6,11 +6,18 @@ import type { CommandSpec } from './parse';
 export const buildSpec: CommandSpec = {
   name: 'build',
   summary: 'build a container image, a single binary, or a prerendered static site',
-  usage: 'x build --target docker|binary|static [--tag name] [--out path] [--json]',
+  usage:
+    'x build --target docker|binary|static [--tag name] [--out path] [--no-preflight] [--json]',
   requiresApp: true,
   flags: [
     { name: 'target', type: 'string', summary: 'docker | binary | static', default: 'docker' },
     { name: 'tag', type: 'string', summary: 'image tag (docker target)' },
     { name: 'out', type: 'string', summary: 'output path (binary and static targets)' },
+    {
+      name: 'preflight',
+      type: 'boolean',
+      summary:
+        '--no-preflight skips the six static gate steps (typecheck, lint, boundaries, filesize, package-shape, errors) — only when `x verify` runs right after, as in `x build --no-preflight && x verify`',
+    },
   ],
 };

package/src/cmd-build.ts

@@ -184,6 +184,16 @@ export function buildResult(input: {
   };
 }
 
+/** The static steps `x build` runs before it builds, and `--no-preflight` leaves to the gate. */
+export const PREFLIGHT_STEPS: readonly string[] = [
+  'typecheck',
+  'lint',
+  'boundaries',
+  'filesize',
+  'package-shape',
+  'errors',
+];
+
 export const buildCommand: CliCommand = {
   spec: buildSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
@@ -194,14 +204,19 @@ export const buildCommand: CliCommand = {
     // an agent spends on the wrong question.
     requireEntry(root, target);
 
-    // Run static verify steps before building.
-    const staticSteps = ['typecheck', 'lint', 'boundaries', 'filesize', 'package-shape', 'errors'];
-    const verifySteps = (await import('./cmd-verify')).VERIFY_STEPS.filter((step) =>
-      staticSteps.includes(step.name),
-    );
-    const verifyResult = await runVerify(verifySteps, { root, runner: ctx.runner, env: ctx.env });
-    if (!verifyResult.ok) {
-      return preflightResult(verifyResult);
+    // Run static verify steps before building — unless the caller is a gate that runs the same
+    // six steps itself right after (`bin/check`: `x build --no-preflight && x verify`), where the
+    // preflight was the same ~17 s of typecheck/lint/scans paid twice per run. The default stays
+    // safe: a bare `x build` never ships an artifact from a tree that does not typecheck.
+    const preflight = ctx.args.flags.get('preflight') !== false;
+    if (preflight) {
+      const verifySteps = (await import('./cmd-verify')).VERIFY_STEPS.filter((step) =>
+        PREFLIGHT_STEPS.includes(step.name),
+      );
+      const verifyResult = await runVerify(verifySteps, { root, runner: ctx.runner, env: ctx.env });
+      if (!verifyResult.ok) {
+        return preflightResult(verifyResult);
+      }
     }
 
     // A relative `--out` is a path the caller typed from where they stand, so it resolves against

package/src/cmd-dev-fixture.ts

@@ -129,6 +129,32 @@ export const config = defineRoute({
 export function Page() {
   return <p>generation one</p>;
 }
+`,
+
+  // An ISR page whose body is a COMPONENT in another file — the shape every real page has. What the
+  // component-reload test rewrites: the page module's own bytes never change, so only evicting what
+  // imports the component re-evaluates it, and only clearing the ISR store stops the first render
+  // from answering for the rest of the process (notificado.co, 2026-09-27).
+  'apps/web/site/news/headline.tsx': `export function Headline() {
+  return <h1>headline one</h1>;
+}
+`,
+
+  'apps/web/site/news/page.tsx': `import { defineRoute } from '@ultimat3/render';
+import { Headline } from './headline';
+
+export const config = defineRoute({
+  render: 'isr',
+  revalidate: { ttl: '1h' },
+  offline: 'runtime',
+  hydrate: 'never',
+  budget: { js: '0kb' },
+  meta: () => ({ title: 'News', description: 'A page whose component is edited while x dev runs' }),
+});
+
+export function Page() {
+  return <main><Headline /></main>;
+}
 `,
 
   // A stylesheet the page imports, because that import is what registers it — and the document's