@ultimat3/cli 19.0.0 → 19.1.0

package/CLAUDE.md

@@ -4,7 +4,7 @@ Tier 5. May import tiers 0–4. Nothing imports this except `create-ultimate`.
 
 | Rule | Detail |
 |---|---|
-| Entry | `src/bin.ts` (`#!/usr/bin/env bun`) — argv, stdout, exit code only |
+| Entry | `src/bin.ts` (`#!/usr/bin/env bun`) — argv, stdout, exit code only. Before `dispatch`, `local-cli.ts` decides whether THIS process is the app's own CLI: a global `x` inside an app re-executes `node_modules/@ultimat3/cli/src/bin.ts` when that is a different realpath, because a second module instance of `@ultimat3/entity` is an empty registry (a zero-entity manifest, green, 2026-09-05). Same realpath (a workspace symlink), no app, a compiled binary, or `ULTIMATE_KEEP_GLOBAL_CLI` set: no hand-over |
 | stdout | `write-line.ts`'s `writeLine` — synchronous fd 1, never `process.stdout.write`, which truncates at the 64KB pipe buffer when `process.exit` follows. Exported, because `create-ultimate`'s entry point needs the same one |
 | stderr | `write-line.ts`'s `writeErrorLine` — the same loop on fd 2, for a line that is not the command's answer. A `CommandResult` declaring `stream: 'stderr'` is routed there by `dispatch.ts`'s `sinkFor`, and `x mcp serve --transport stdio` is the one case: its fd 1 carries JSON-RPC frames, so the `✓ mcp stdio serving 13 tools` line rendered after the loop was a malformed frame. Neither renderer carries `stream`, exactly like `hold` |
 | Boot logs under `--json` | `dispatch.ts` calls core's `setLogStream('stderr')` when `args.json` is set, once, for all thirty commands. `x db migrate --json` printed the boot logger's `ultimate migrate applied` and then the command's own object, so `json.load` raised on the second document. A server's stdout stays its log stream; this is the CLI process only |

package/README.md

@@ -34,6 +34,25 @@ Everything in [CLI reference](../../wiki/CLI-Reference.md)'s planned table is al
 and exits `X_NOT_IMPLEMENTED` with a `fix:` naming the closest shipped command — "not built yet"
 and "not a command" are different facts.
 
+## Which `x` runs
+
+**The app's own.** `x` is a workspace dependency, and `bunx x` / the `package.json` scripts resolve
+`node_modules/.bin/x`. A **globally** installed `x` — `bun link` of a checkout, `bun add -g` — is
+a second copy of every `@ultimat3/*` package, and a second copy of `@ultimat3/entity` is a second,
+**empty** registry: the app's entities register into the instance under its `node_modules`, and
+only the CLI under that same `node_modules` can see them. Measured 2026-09-05, in an app run with a
+linked checkout's `x`: `x entities list` answered `0 entities`, `x policy list` answered
+`0 permission(s), 0 role(s)`, and `x manifest` wrote a manifest with **zero entities and zero
+actions** — exit 0, green — which `x db gen` then read as "drop every table".
+
+So a global `x` inside an app **hands over** to `node_modules/@ultimat3/cli/src/bin.ts` when that
+is a different file (`local-cli.ts`), prints one line on stderr saying so, and exits with the
+child's code; fd 1 is the child's alone, so a `--json` consumer sees one document. A workspace
+symlink resolves to the same file and is not handed over (both tracked apps, and every scaffold
+CI installs), and a compiled `x` keeps itself — its own path is not one `realpath` can resolve.
+`ULTIMATE_KEEP_GLOBAL_CLI=1` keeps the CLI that was invoked, for the one deliberate case: running a
+checkout's `x` against an app pinned to an older release to see what the next one would say.
+
 ## The output contract
 
 Every command returns one `CommandResult`; the human renderer and the JSON renderer are
@@ -95,6 +114,11 @@ is held to the same error contract shipped source is (`X_GUARD_INVALID`, `X_GUAR
 | `cmd-*.ts` | one command group each |
 | `templates/` | scaffolding as typed string modules, not copied fixtures |
 | `app-load.ts` | import an app's modules so the framework registries hold it |
+| `app-mcp.ts` | the app's own MCP endpoint: `apps/<app>/mcp.ts` exports `mcp`, and both boots mount `POST config.ai.mcp.path` through this one call |
+| `app-runtime.ts` | the app's `RuntimeOverrides`: `apps/<app>/runtime.ts` exports `runtime`, read by `x dev` and by `runRole` when its caller passed none |
+| `local-cli.ts` | which `x` runs: a global CLI inside an app hands over to the app's own, because a second module instance is an empty registry |
+| `measurement-actor.ts` | the actor a weigh-and-discard render runs as — every permission, never served |
+| `dev-live-feed.ts` | what feeds the sync node this process booted: the in-process row observer under the embedded database, the WAL decoder with a real one, nothing without the role — `live=` on the ready line |
 | `app-manifest.ts` | `x.manifest.json`, projected by `@ultimat3/manifest` |
 | `app-openapi.ts` | `openapi.json`, projected by `@ultimat3/action` |
 | `app-boundaries.ts` | app import boundaries, over `@ultimat3/render`'s surface check |

package/package.json

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

package/src/app-mcp.ts

@@ -0,0 +1,152 @@
+// The app's own MCP endpoint, mounted by the web role. `defineAppMcp` built `mcp.route` — a
+// `POST` handler with token auth and per-class rate limits — and `app.config.ts` declared
+// `ai: { mcp: { expose: true, path: '/mcp' } }` by DEFAULT, and nothing between the two served it:
+// neither `x dev` nor `runRole` mounted the route, so `POST /mcp` answered `X_ROUTE_NOT_FOUND` in
+// every app ever scaffolded (measured 2026-09-05). The contract is one file: `apps/<app>/mcp.ts`
+// exports `mcp`, an `AppMcp`; this module finds it, and both boots mount what it carries.
+
+// why: a directory's existence — `Bun.file().exists()` answers for files, and `apps/` is a directory.
+import { existsSync } from 'node:fs';
+// why: Bun exposes no path-join primitive; the config file and each candidate are joined to root.
+import { join } from 'node:path';
+import { logger } from '@ultimat3/core';
+import type { Route } from '@ultimat3/http';
+import { type AppMcp, McpAppUnmountedError } from '@ultimat3/mcp';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+
+/** The one file an app writes, per app directory. */
+export const APP_MCP_GLOB = 'apps/*/mcp.ts';
+/** The export that file makes — an `AppMcp`, the value `defineAppMcp` returns. */
+export const APP_MCP_EXPORT = 'mcp';
+/** What the boot line and `/_x` call the route. */
+export const APP_MCP_ROUTE_NAME = 'mcp';
+
+export interface AppMcpMount {
+  /** `[]` when `expose` is false, when nothing exports `mcp`, or when the export has no route. */
+  readonly routes: readonly Route[];
+  /** `POST <path>` when mounted, else `null` — the boot line prints it. */
+  readonly path: string | null;
+  /** Set exactly when `expose` is true and `routes` is empty: the reason, as an instruction. */
+  readonly warning: McpAppUnmountedError | undefined;
+}
+
+interface ExposeDeclaration {
+  readonly expose: boolean;
+  readonly path: string;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * `config.ai.mcp`, off the app's own resolved config — the exported `config` is what
+ * `defineConfig` returned, so both keys are present and defaulted. Read the same way
+ * `loadSignInPath` reads `auth.signInPath`: the config file is imported, never re-parsed.
+ * An app with no config file has nothing exposed and nothing to warn about.
+ */
+async function exposeDeclaration(root: string): Promise<ExposeDeclaration | undefined> {
+  const configPath = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(configPath).exists())) return undefined;
+  const module = (await import(configPath)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  if (!isRecord(config) || !isRecord(config['ai']) || !isRecord(config['ai']['mcp'])) {
+    return undefined;
+  }
+  const mcp = config['ai']['mcp'];
+  const path = mcp['path'];
+  return {
+    expose: mcp['expose'] === true,
+    path: typeof path === 'string' && path.startsWith('/') ? path : '/mcp',
+  };
+}
+
+const isAppMcp = (value: unknown): value is AppMcp =>
+  isRecord(value) && 'server' in value && 'tools' in value && 'route' in value;
+
+/** Every `apps/<app>/mcp.ts`, app-root-relative and sorted, so two apps answer in one order. */
+async function candidates(root: string): Promise<readonly string[]> {
+  // A root with no `apps/` is an app with no MCP file, never a boot failure — the scan's ENOENT
+  // is answered as "none", and the warning below says which file to write.
+  if (!existsSync(join(root, 'apps'))) return [];
+  const files: string[] = [];
+  for await (const file of new Bun.Glob(APP_MCP_GLOB).scan({ cwd: root })) files.push(file);
+  return files.sort();
+}
+
+/**
+ * The route to mount, or the reason there is none. Pure over the filesystem it is pointed at;
+ * `mountAppMcp` below is the one place the warning becomes a log line.
+ *
+ * `meta.auth: 'public'` and `enforcedBy: 'handler'` — the http pipeline must not pre-judge:
+ * `mcp.route.handle` is the one evaluation, and it reads `Authorization: Bearer` through the
+ * `resolveToken` the app gave `defineAppMcp`, then decides per tool through the same policy every
+ * other surface evaluates. A pipeline `auth: 'required'` would demand a session cookie an agent
+ * does not have and answer 401 before the token was ever read.
+ */
+export async function appMcpMount(root: string): Promise<AppMcpMount> {
+  const declared = await exposeDeclaration(root);
+  if (declared === undefined || !declared.expose)
+    return { routes: [], path: null, warning: undefined };
+  const files = await candidates(root);
+  const fallbackFile = 'apps/web/mcp.ts';
+  if (files.length === 0) {
+    return {
+      routes: [],
+      path: null,
+      warning: new McpAppUnmountedError({
+        reason: 'missing',
+        path: declared.path,
+        file: fallbackFile,
+      }),
+    };
+  }
+  for (const file of files) {
+    const module = (await import(join(root, file))) as Record<string, unknown>;
+    const exported = module[APP_MCP_EXPORT];
+    if (!isAppMcp(exported)) continue;
+    const route = exported.route;
+    if (route === undefined) {
+      return {
+        routes: [],
+        path: null,
+        warning: new McpAppUnmountedError({ reason: 'no-route', path: declared.path, file }),
+      };
+    }
+    return {
+      routes: [
+        {
+          method: 'POST',
+          path: declared.path,
+          handler: (request) => route.handle(request.raw),
+          meta: { name: APP_MCP_ROUTE_NAME, auth: 'public', enforcedBy: 'handler' },
+        },
+      ],
+      path: declared.path,
+      warning: undefined,
+    };
+  }
+  return {
+    routes: [],
+    path: null,
+    warning: new McpAppUnmountedError({
+      reason: 'missing',
+      path: declared.path,
+      file: files[0] ?? fallbackFile,
+    }),
+  };
+}
+
+/**
+ * The boot's call: the routes to spread into the table, with the warning already logged ONCE and
+ * the mount announced. Both `x dev` and `runRole` go through here, so a developer's terminal and a
+ * container's log say the same thing about the same endpoint.
+ */
+export async function mountAppMcp(root: string): Promise<AppMcpMount> {
+  const mount = await appMcpMount(root);
+  if (mount.warning !== undefined) {
+    logger.warn(`${mount.warning.code}: ${mount.warning.cause} — fix: ${mount.warning.fix}`);
+  }
+  if (mount.path !== null) logger.info('app mcp mounted', { method: 'POST', path: mount.path });
+  return mount;
+}

package/src/app-runtime.ts

@@ -0,0 +1,39 @@
+// The app's `RuntimeOverrides`, found rather than handed over. `runRole({ runtime })` has taken
+// them since the seam existed, and the scaffolded `apps/web/server.ts` passes none — so an app's
+// own middleware reached no process the framework boots, and `x dev` had no parameter to reach at
+// all (measured 2026-09-05: `x dev` passed only the read-replica override). The contract is one
+// file: `apps/<app>/runtime.ts` exports `runtime`, a `RuntimeOverrides`; `x dev` reads it, and
+// `runRole` reads it when its caller passed nothing, so the two boots compose the same chain.
+
+// why: a directory's existence — `Bun.file().exists()` answers for files, and `apps/` is a directory.
+import { existsSync } from 'node:fs';
+// why: Bun exposes no path-join primitive; each candidate is joined to the app root.
+import { join } from 'node:path';
+import type { RuntimeOverrides } from './runtime-overrides';
+
+/** The one file an app writes, per app directory. */
+export const APP_RUNTIME_GLOB = 'apps/*/runtime.ts';
+/** The export that file makes — a `RuntimeOverrides`. */
+export const APP_RUNTIME_EXPORT = 'runtime';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * The first `apps/<app>/runtime.ts` exporting `runtime`, or `undefined` when no app declares one.
+ * Sorted, so two apps answer in one order; the object is handed on as declared, because every key
+ * of `RuntimeOverrides` already means "replace the resolved default" wherever a boot reads it.
+ */
+export async function loadAppRuntime(root: string): Promise<RuntimeOverrides | undefined> {
+  // A root with no `apps/` — a bare test fixture, a directory that does not exist — is no app
+  // declaring an override, never a boot failure: the scan's ENOENT is answered as "none".
+  if (!existsSync(join(root, 'apps'))) return undefined;
+  const files: string[] = [];
+  for await (const file of new Bun.Glob(APP_RUNTIME_GLOB).scan({ cwd: root })) files.push(file);
+  for (const file of files.sort()) {
+    const module = (await import(join(root, file))) as Record<string, unknown>;
+    const exported = module[APP_RUNTIME_EXPORT];
+    if (isRecord(exported)) return exported as RuntimeOverrides;
+  }
+  return undefined;
+}

package/src/bin.ts

@@ -3,12 +3,30 @@
 // dispatch.ts, so the whole CLI is testable without spawning a process.
 
 import { dispatch } from './dispatch';
+import { resolveLocalCli } from './local-cli';
 // The writes themselves are `write-line.ts`: `create-ultimate`'s entry point needs the identical
 // one, and a second copy of a note about pipe truncation is a second copy that drifts. Two sinks,
 // because fd 1 is not always this process's to write on — `x mcp serve --transport stdio` hands it
 // to the protocol, and `dispatch` addresses that result to the second.
 import { writeErrorLine, writeLine } from './write-line';
 
+// An app's own CLI sees the app's entity registry; a global one does not. Hand over before
+// deciding anything — see local-cli.ts for the zero-entity manifest this prevents. On fd 2, so a
+// `--json` consumer reading fd 1 sees exactly the child's one document. `process.execPath` is the
+// Bun that is already running, never a `PATH` lookup: the child's `import.meta.path` resolves to
+// the app's file, so its own `resolveLocalCli` answers "same file" and the chain stops at one hop.
+const local = resolveLocalCli({ cwd: process.cwd(), selfPath: import.meta.path, env: Bun.env });
+if (local !== undefined) {
+  writeErrorLine(`x: using the app's own @ultimat3/cli at ${local}`);
+  const child = Bun.spawn([process.execPath, local, ...Bun.argv.slice(2)], {
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+    env: Bun.env,
+  });
+  process.exit(await child.exited);
+}
+
 const code = await dispatch({
   argv: Bun.argv.slice(2),
   cwd: process.cwd(),

package/src/budgets.ts

@@ -111,7 +111,7 @@ export function checkBudgets(
     if (js !== null && measured.jsBytes > js) {
       findings.push({
         code: 'X_BUDGET_EXCEEDED',
-        cause: `${route.url} ships ${formatBytes(measured.jsBytes)} of JS over a ${formatBytes(js)} budget via ${chainOf(measured)}`,
+        cause: `${route.url} ships ${formatBytes(measured.jsBytes)} of JS (minified, uncompressed) over a ${formatBytes(js)} budget via ${chainOf(measured)}`,
         fix: `x routes --json to see the chain, then move the heavy import behind hydrate: 'interaction'`,
         docs: ERROR_DOCS_URL,
         at: route.url,

package/src/cmd-dev-fixture.ts

@@ -0,0 +1,147 @@
+// The app `x dev` boots in its tests, and the one place it is declared: every assertion that
+// needs a booted app lives in `cmd-dev.test.ts`, because a process has ONE lifecycle — the second
+// in-process boot is refused (X_LIFECYCLE_DRAINED) — and the coverage gate runs a package in one
+// process. So the fixture is a module of its own, and that file keeps its line budget for tests.
+//
+// What the app declares, and what each declaration is here to prove:
+//   app.config.ts               the root marker a real `x dev` cannot start without; `ai.mcp` by default
+//   apps/web/mcp.ts             the app's own MCP endpoint, mounted by the web role
+//   apps/web/runtime.ts         the app's middleware, reaching a development process
+//   apps/web/app/notes/*        a memory-backed entity and a live query, fed by the in-process bridge
+//   apps/web/app/posts/*        an action, a policy and a query, mounted as HTTP routes
+//   apps/web/site/pricing/*     a static page with its own stylesheet, under the CSP `x dev` sends
+import { resetRegistry as resetActions } from '@ultimat3/action';
+import { clearRegistry as clearEntities } from '@ultimat3/entity';
+import { resetJobs, resetTasks } from '@ultimat3/jobs';
+import { clearPermissions, clearRoles } from '@ultimat3/policy';
+import { resetRegistry as resetQueries } from '@ultimat3/query';
+import type { Frame } from '@ultimat3/realtime';
+import { decode } from '@ultimat3/realtime';
+import type { WsLike } from '@ultimat3/realtime/server';
+import { clearRoutes } from '@ultimat3/render';
+import { resetAppLoad } from './app-load';
+
+export const DEV_FIXTURE_FILES: Readonly<Record<string, string>> = {
+  'package.json': JSON.stringify({ name: 'dev-fixture', version: '1.4.0' }),
+
+  // The root marker a real `x dev` cannot start without, and where `ai.mcp` is declared — by
+  // default `{ expose: true, path: '/mcp' }`, which is what the MCP mount reads.
+  'app.config.ts': `import { defineConfig } from '@ultimat3/core';
+export const config = defineConfig({ name: 'dev-fixture' });
+`,
+
+  // The app's own MCP endpoint, in the contract `app-mcp.ts` reads. `resolveToken` answering
+  // `null` rejects every bearer, which is enough to prove the ROUTE is mounted (401, not 404).
+  'apps/web/mcp.ts': `import { defineAppMcp } from '@ultimat3/mcp';
+export const mcp = defineAppMcp({ include: 'exposed', resolveToken: () => null });
+`,
+
+  // The app's own middleware, in the contract `app-runtime.ts` reads: a header on every response
+  // is the cheapest proof that the chain `x dev` composed is the app's and not only the replica's.
+  'apps/web/runtime.ts': `const stamp = async (request, ctx, next) => {
+  const response = await next(request, ctx);
+  const headers = new Headers(response.headers);
+  headers.set('x-dev-runtime', 'app');
+  return new Response(response.body, { status: response.status, headers });
+};
+export const runtime = { middleware: [stamp] };
+`,
+
+  // A memory-backed entity, so the fixture needs no migration: the row observer sits on
+  // `database()`'s repo wrapper, the same seam a Postgres-backed repo writes through.
+  'apps/web/app/notes/entity.ts': `import { database, entity, memoryDriver, text, uuid } from '@ultimat3/entity';
+export const notes = entity('notes', { columns: { id: uuid().primaryKey(), title: text() } });
+export const db = database({ notes }, { driver: memoryDriver() });
+`,
+  'apps/web/app/notes/live.ts': `import { allow } from '@ultimat3/policy';
+import { from, query, t } from '@ultimat3/query';
+import { db } from './entity';
+export const liveNotes = query({
+  input: t.object({}),
+  policy: allow('public'),
+  live: true,
+  subscribes: ['notes'],
+  sql: () =>
+    from<{ id: string; title: string }>('notes', () => db.notes.where({}).all())
+      .orderBy('id')
+      .limit(50),
+});
+`,
+
+  'apps/web/app/posts/policy.ts': `import { allow, can, definePermissions, defineRoles } from '@ultimat3/policy';
+export const permissions = definePermissions(['post:publish'] as const);
+export const roles = defineRoles({
+  author: { grants: ['post:publish'] },
+  reader: { grants: [] },
+});
+export const canPostWrite = can('post:publish');
+export const anyone = allow();
+`,
+
+  'apps/web/app/posts/actions.ts': `import { action, t } from '@ultimat3/action';
+import { anyone, canPostWrite } from './policy';
+
+export const publishPost = action({
+  input: t.object({ id: t.uuid }),
+  output: t.object({ id: t.uuid }),
+  policy: canPostWrite,
+  async handle({ input }) {
+    return { id: input.id };
+  },
+});
+
+export const echoPost = action({
+  input: t.object({ word: t.string }),
+  output: t.object({ word: t.string }),
+  policy: anyone,
+  async handle({ input }) {
+    return { word: input.word };
+  },
+});
+`,
+
+  // A stylesheet the page imports, because that import is what registers it — and the document's
+  // inline `<style>` is what the CSP has to name. Without one this file served no styled page and
+  // could not have caught the policy that blanked every deployed app.
+  'apps/web/site/pricing/page.module.scss': `.price { color: #123456; }
+`,
+
+  'apps/web/site/pricing/page.tsx': `import { defineRoute } from '@ultimat3/render';
+import './page.module.scss';
+
+export const config = defineRoute({
+  render: 'static',
+  offline: 'precache',
+  hydrate: 'never',
+  budget: { js: '0kb' },
+  meta: () => ({ title: 'Pricing', description: 'What it costs' }),
+});
+`,
+};
+
+export const resetRegistries = (): void => {
+  resetActions();
+  resetQueries();
+  clearEntities();
+  clearRoutes();
+  resetJobs();
+  resetTasks();
+  clearPermissions();
+  clearRoles();
+  resetAppLoad();
+};
+
+/** A `WsLike` that keeps every frame the node sends, decoded — what a live assertion reads. */
+export class FakeWs implements WsLike {
+  readonly frames: Frame[] = [];
+  send(data: string): number {
+    this.frames.push(decode(data));
+    return data.length;
+  }
+  close(): void {}
+  subscribe(): void {}
+  unsubscribe(): void {}
+  getBufferedAmount(): number {
+    return 0;
+  }
+}

package/src/cmd-dev.ts

@@ -19,11 +19,14 @@ import { apiRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
 import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
+import { mountAppMcp } from './app-mcp';
 import { requireAppRoot } from './app-root';
+import { loadAppRuntime } from './app-runtime';
 import type { CliCommand, CommandContext } from './command';
 import { assetRoutes } from './dev-assets';
 import type { DevDashboardInput, DevStatus } from './dev-dashboard';
 import { devDashboardRoutes, devPanels } from './dev-dashboard';
+import { liveFeedLabel } from './dev-live-feed';
 import { clearLock, preflight, writeLock } from './dev-lock';
 import { createStatementLedger } from './dev-n-plus-one';
 import { appRoutes } from './dev-render';
@@ -71,6 +74,8 @@ export interface DevServer {
   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 own MCP endpoint, or `null` when nothing was mounted. */
+  readonly mcp: string | null;
   stop(): Promise<void>;
 }
 
@@ -188,11 +193,16 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
       ? undefined
       : serviceWorkerArtifacts({ pwa, buildId, routes: describeRoutes(), islands: state.islands });
 
+  // The app's own MCP endpoint, discovered from `apps/<app>/mcp.ts` and mounted through the SAME
+  // call `runRole` makes — `POST /mcp` answered 404 in every process the framework booted until
+  // one of them asked. Warned once here when `expose` is true and nothing can be mounted.
+  const mcpMount = await mountAppMcp(options.root);
   const routes: readonly Route[] = [
     ...devDashboardRoutes(dashboard),
     // The same API table the container serves: a read that answers here and 404s in production
     // is exactly the drift one composition exists to prevent.
     ...apiRoutes(),
+    ...mcpMount.routes,
     // The image pipeline's only HTTP surface: the icons the web manifest declares, and the
     // variants every `srcset` promises. Mounted before the app's own routes so a page route can
     // never shadow `/icons` or `/media`.
@@ -222,7 +232,14 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     }),
   ];
 
-  const replicaOverride = replicaOverrides(undefined, services.db, options.env);
+  // 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(
+    await loadAppRuntime(options.root),
+    services.db,
+    options.env,
+  );
   const running = await startRoles({
     roles: options.roles ?? DEV_ROLES,
     port: options.port,
@@ -278,6 +295,7 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     url: running.url ?? `http://localhost:${options.port}`,
     services,
     roles: running.roles,
+    mcp: mcpMount.path,
     get buildId(): string {
       return state.manifest.buildId;
     },
@@ -380,7 +398,7 @@ export const devCommand: CliCommand = {
         panels: server.panels.length,
         // Rendered text, so the mail and CDN halves come from the catalog; `data` below carries the
         // status values a script parses, which is why the two are different calls and not one.
-        services: `${describeServices(server.services)} ${mailLabel(server.runtime)} ${cdnLabel(server.runtime)}`,
+        services: `${describeServices(server.services)} ${mailLabel(server.runtime)} ${cdnLabel(server.runtime)} ${liveFeedLabel(server.running.liveFeed)}`,
       }),
       findings: server.findings,
       // Every fact `lines` prints is a fact `--json` carries, `manifest` included — or the two
@@ -405,10 +423,15 @@ export const devCommand: CliCommand = {
         // on one database is the one topology mistake that cannot be seen from the outside, so the
         // slot is a scriptable fact rather than a line in a log.
         replicationSlot: server.running.replicator?.slot ?? null,
+        // Which change feed the sync node has: `in-process` under the embedded database, where
+        // this process's own writes reach subscribers; `replication` with a real one; `none`
+        // when no sync role runs here. The label on the ready line is this same fact.
+        liveFeed: server.running.liveFeed,
         buildId: server.buildId,
         manifest: join(root, MANIFEST_FILENAME),
         introspect: `${server.url}/_x`,
         panels: [...server.panels],
+        mcp: server.mcp,
       },
       lines: [
         // A hard kill leaves the lock behind; clearing it is normal and worth one line, never a
@@ -418,6 +441,9 @@ export const devCommand: CliCommand = {
         msg('cli.dev.panels', { panels: server.panels.join(', ') }),
         msg('cli.dev.manifest', { path: join(root, MANIFEST_FILENAME) }),
         msg('cli.dev.introspect', { url: `${server.url}/_x` }),
+        // Only when something was mounted: the unmounted case has already said why, once, as a
+        // warning with a fix, and a summary line reading `mcp none` would be a second copy of it.
+        ...(server.mcp === null ? [] : [msg('cli.dev.mcp', { path: server.mcp })]),
       ],
     };
     await writeLock(services.stateDir, {

package/src/dev-live-feed.ts

@@ -0,0 +1,61 @@
+// Where a `sync` node's changes come from when this process boots one. Production decodes the
+// write-ahead log (`x dev --role replicator`, `PgLogicalReplicationFeed`, a real `DATABASE_URL`).
+// The embedded database has no walsender, and until 2026-09-05 nothing stood in for it: a live
+// subscription under `x dev` took its snapshot and then heard nothing, so every `--live` query in
+// every scaffolded app was dead in development — which is where an author first tries one.
+//
+// The bridge is `@ultimat3/testing`'s `startLiveReplicator`, the same in-process row observer the
+// framework's own live tests run on: a repository write in THIS process becomes a `ChangeEvent`
+// shaped exactly as the WAL decoder shapes one, fanned into the node's registry. Its honest bound
+// is stated there and repeated here — a write another process makes is invisible — and `x dev` is
+// the one boot where that bound holds by construction: every role runs in this one process.
+
+import { logger, renderThrowable } from '@ultimat3/core';
+import type { LiveReplicator } from '@ultimat3/testing';
+import { startLiveReplicator } from '@ultimat3/testing';
+import type { ServiceMode } from './dev-services';
+import type { RunningSync } from './dev-sync';
+
+/** What feeds the sync node, said out loud on the boot line and in `--json`. */
+export type LiveFeed = 'in-process' | 'replication' | 'none';
+
+export interface RunningLiveFeed {
+  readonly feed: LiveFeed;
+  /** The installed bridge, so a test can await `settled()`; `null` for the other two feeds. */
+  readonly bridge: LiveReplicator | null;
+  stop(): void;
+}
+
+export interface LiveFeedInput {
+  /** The sync node this process booted, or `null` when the role was not selected. */
+  readonly sync: RunningSync | null;
+  /** The database's binding: `embedded` is PGlite, which has no log to decode. */
+  readonly dbMode: ServiceMode;
+}
+
+/** The label the `x dev` boot line carries beside `db=`, `events=` and `storage=`. */
+export const liveFeedLabel = (feed: LiveFeed): string => `live=${feed}`;
+
+/**
+ * `embedded` → the in-process bridge; anything else → replication, which is the WAL decoder's
+ * job whether the replicator role runs in this process or another. Never both: with a real
+ * database the decoder already delivers this process's own writes, and a bridge beside it would
+ * deliver every one of them twice. No sync node, no feed to speak of.
+ */
+export async function startLiveFeed(input: LiveFeedInput): Promise<RunningLiveFeed> {
+  if (input.sync === null) return { feed: 'none', bridge: null, stop: () => undefined };
+  if (input.dbMode !== 'embedded') {
+    return { feed: 'replication', bridge: null, stop: () => undefined };
+  }
+  const bridge = await startLiveReplicator({
+    registry: input.sync.registry,
+    // Logged, never thrown: one change nobody could fan out must not take the dev server down.
+    onError: (error) =>
+      logger.warn('live.bridge_delivery_failed', { error: renderThrowable(error) }),
+  });
+  logger.info('live feed in-process', {
+    detail:
+      'the embedded database has no walsender; repository writes in this process reach subscribers',
+  });
+  return { feed: 'in-process', bridge, stop: () => bridge.stop() };
+}

package/src/dev-roles.ts

@@ -26,7 +26,11 @@ import {
   jobDriver,
   pgSchedulerState,
 } from '@ultimat3/jobs';
+import type { LiveQueryRegistry } from '@ultimat3/realtime/server';
+import type { LiveReplicator } from '@ultimat3/testing';
 import { devHooks } from './dev-hooks';
+import type { LiveFeed } from './dev-live-feed';
+import { startLiveFeed } from './dev-live-feed';
 import { pgExecutorFor } from './dev-queue';
 import type { RunningReplicator } from './dev-replicator';
 import { startReplicator } from './dev-replicator';
@@ -130,6 +134,12 @@ export interface RunningRoles {
   readonly scheduler: Scheduler | null;
   /** The slot and feed this process holds; null when the replicator was not selected. */
   readonly replicator: RunningReplicator | null;
+  /** What feeds the sync node: this process's own writes, the WAL decoder, or nothing. */
+  readonly liveFeed: LiveFeed;
+  /** The in-process bridge when `liveFeed` is `in-process`, so a test can await `settled()`. */
+  readonly liveBridge: LiveReplicator | null;
+  /** The sync node's registry, so a test can hold a real subscription; null without the role. */
+  readonly liveRegistry: LiveQueryRegistry | null;
   stop(): Promise<void>;
 }
 
@@ -426,6 +436,12 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
       : null;
     if (replicator !== null) started.push(() => replicator.stop());
 
+    // What feeds the sync node this process booted. The embedded database has no log to decode,
+    // so under it the node is fed by this process's own repository writes (`dev-live-feed.ts`);
+    // with a real database the WAL decoder above is the feed, here or in another process.
+    const live = await startLiveFeed({ sync, dbMode: options.runtime.services.db.mode });
+    started.push(async () => live.stop());
+
     return {
       roles: selected,
       url: server === null ? null : server.url(),
@@ -435,8 +451,12 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
       worker,
       scheduler,
       replicator,
+      liveFeed: live.feed,
+      liveBridge: live.bridge,
+      liveRegistry: sync?.registry ?? null,
       async stop() {
         // Reverse boot order, so the slot is released before the bus it published to closes.
+        live.stop();
         await replicator?.stop();
         await scheduler?.stop();
         // Before the worker, so nothing publishes into a queue whose consumer has already gone —

package/src/dev-sync.ts

@@ -96,6 +96,8 @@ export function syncPortFor(port: number): number {
 /** What `startRoles` holds on to: where the node listens, and how to take it down. */
 export interface RunningSync {
   readonly url: string;
+  /** The node's registry, so the boot can hand it a change feed the database cannot produce. */
+  readonly registry: LiveQueryRegistry;
   stop(): Promise<void>;
 }
 
@@ -154,9 +156,10 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
   // override is how a deployment states a window its credential already declares (a token's
   // `exp`), or resolves identity from a header the adapter deliberately does not retain.
   const authenticate = options.overrides?.syncAuthenticate ?? syncAuthenticator(options.buildId);
+  const registry = registerLiveQueries(options);
   const node = createSyncNode({
     hub,
-    registry: registerLiveQueries(options),
+    registry,
     transport: options.runtime.transport,
     buildId: options.buildId,
     sockets,
@@ -177,6 +180,7 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
     const listener = listenSyncNode(node, { port });
     return {
       url: listener.url,
+      registry,
       stop: async () => {
         listener.stop();
         await node.stop();

package/src/local-cli.ts

@@ -0,0 +1,71 @@
+// A globally installed `x` defers to the app's own `@ultimat3/cli` when the two are different
+// files. Measured 2026-09-05 in an app whose global `x` was a `bun link` of this checkout: the
+// global CLI's `@ultimat3/entity` was a second module instance with an EMPTY registry, so `x g`,
+// `x db gen` and `x manifest` wrote a manifest with zero entities and proposed dropping every
+// table — silently, with a green exit code. The app's entities register into the instance under
+// its `node_modules`; only the CLI under that same `node_modules` can see them. So the rule is the
+// one `tsc` and `eslint` follow: the project-local binary wins, and the global one only says so.
+//
+// The same registry split is what turned `x verify` green over that app: `@ultimat3/policy`'s
+// `isKnownPermission` deliberately checks nothing while no permission is declared, and the global
+// CLI's instance had none declared — so the `policy` step that exists to refuse an undeclared
+// grant (`app-permissions.ts`) had an empty set to refuse against. One process, one registry.
+
+// why: `realpathSync` is the whole decision — Bun ships no symlink-resolving stat of its own, and
+// `Bun.file(path).exists()` follows a link without saying where it went.
+import { existsSync, realpathSync } from 'node:fs';
+// why: Bun exposes no path-join primitive; the local bin is assembled from the app root.
+import { join } from 'node:path';
+import { findAppRoot } from './app-root';
+
+/**
+ * Set to any value to keep the CLI that was invoked. Nothing in this repository's CI needs it —
+ * both tracked apps symlink `node_modules/@ultimat3/cli` to `packages/cli`, so the realpath test
+ * below already answers "same file" — it exists for the one deliberate case: running a checkout's
+ * CLI against an app that pins an older release, to see what the next release would say.
+ */
+export const KEEP_GLOBAL_CLI_ENV = 'ULTIMATE_KEEP_GLOBAL_CLI';
+
+export const LOCAL_CLI_BIN = join('node_modules', '@ultimat3', 'cli', 'src', 'bin.ts');
+
+export interface LocalCliIo {
+  exists(path: string): boolean;
+  realpath(path: string): string;
+}
+
+const nodeIo: LocalCliIo = {
+  exists: existsSync,
+  realpath: (path) => realpathSync(path),
+};
+
+/**
+ * The app-local `bin.ts` to re-execute, or undefined when this process already IS the app's CLI
+ * (a workspace symlink resolves to the same file), when there is no app, when this process is a
+ * compiled binary, or when the caller opted out. Pure over the injected filesystem so the
+ * decision has a test without a checkout.
+ *
+ * A compiled `x` (`x build --target binary`, the container's `/app/x`) has an `import.meta.path`
+ * inside Bun's virtual `/$bunfs/` — no such file exists on disk, so `realpath` throws. That is
+ * the keep case, not the hand-over case: the binary is the deliberate artifact, and the runtime
+ * image carries no `bun` to hand over to. The other unresolvable side — a `node_modules` entry
+ * that exists but whose link is dangling — is kept for the same reason: nothing there can run.
+ */
+export function resolveLocalCli(
+  input: {
+    readonly cwd: string;
+    readonly selfPath: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+  },
+  io: LocalCliIo = nodeIo,
+): string | undefined {
+  if (input.env[KEEP_GLOBAL_CLI_ENV] !== undefined) return undefined;
+  const root = findAppRoot(input.cwd);
+  if (root === undefined) return undefined;
+  const local = join(root.dir, LOCAL_CLI_BIN);
+  if (!io.exists(local)) return undefined;
+  try {
+    return io.realpath(local) === io.realpath(input.selfPath) ? undefined : local;
+  } catch {
+    return undefined;
+  }
+}

package/src/measurement-actor.ts

@@ -0,0 +1,26 @@
+// The actor a route is rendered AS when the render exists only to be weighed. `app/` pages are
+// authed by construction: a `load` that calls a policy-guarded query denies an anonymous actor with
+// `X_UNAUTHENTICATED`, so under the anonymous build context every authed page was reported
+// `X_BUDGET_UNMEASURED` and a real app could not pass the `budgets` step (measured 2026-09-05).
+// Weighing bytes needs no data authority — the rendered document is discarded — so this actor holds
+// every permission. It is handed ONLY to the weigh-and-discard branch of `prerender.ts`, never to
+// `renderStatic`: a `site/` artifact is published to everyone, and a guarded query inside its `load`
+// must keep failing the build rather than rendering another actor's rows into a file.
+
+import type { Actor } from '@ultimat3/core';
+
+/** The id every trace and log line under a measurement render carries, so it is recognisable. */
+export const MEASUREMENT_ACTOR_ID = 'x-build-measure';
+
+/**
+ * `kind: 'service'` and not `'user'`: an app's own `requireMember()`-style helper that resolves a
+ * user to a row has nothing to resolve here, and the honest kind says so. `'*'` is the grant
+ * `actorHas` reads as everything — the same spelling a role map uses for a superuser.
+ */
+export const measurementActor = (): Actor => ({
+  kind: 'service',
+  id: MEASUREMENT_ACTOR_ID,
+  roles: [],
+  scopes: [],
+  permissions: ['*'],
+});

package/src/messages.ts

@@ -83,6 +83,7 @@ const CATALOG = {
   'cli.dev.panels': '  panels {panels}',
   'cli.dev.introspect': '  introspect {url}',
   'cli.dev.manifest': '  manifest {path}',
+  'cli.dev.mcp': '  mcp POST {path}',
   'cli.deploy.plan': 'containers only: {images} image, roles {roles}',
   'cli.doctor.clean': 'no findings — environment is shippable',
   'cli.doctor.findings': '{count} finding(s)',

package/src/prerender.ts

@@ -17,6 +17,7 @@ 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 { loadPwaArtifacts, WEB_MANIFEST_PATH, writePwaIcons } from './pwa-artifacts';
 import type { SkippedRoute, UnmeasuredRoute } from './static-report';
 import { skippedRoute, skipReasonFor, writeStaticReport } from './static-report';
@@ -194,13 +195,25 @@ 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 });
-  const document = (entry: RouteEntry, data: { url: string; params: Record<string, string> }) =>
-    runWithContext(ctx, () =>
+  // 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),
         ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
       }),
     );
+  const document = (entry: RouteEntry, data: { url: string; params: Record<string, string> }) =>
+    documentAs(ctx, entry, data);
 
   for (const entry of routeEntries()) {
     const facts = { surface: entry.surface, render: entry.config.render, route: entry.path };
@@ -213,7 +226,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       // 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 document(entry, {
+        const html = await documentAs(measureCtx, entry, {
           url: new URL(entry.path, origin).href,
           params: {},
         });

package/src/serve.ts

@@ -26,6 +26,8 @@ import { apiRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
 import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
+import { mountAppMcp } from './app-mcp';
+import { loadAppRuntime } from './app-runtime';
 import { acceptCreatedTables } from './db-accept-created';
 import { assetRoutes } from './dev-assets';
 import { startQueue } from './dev-queue';
@@ -252,7 +254,22 @@ export async function releaseBoot(
  * table is the same three contributions minus the dashboard — a `/_x` in production would expose
  * the app's policy matrix, its outbox and its spans to the internet.
  */
-export async function serveApp(options: ServeOptions): Promise<ServedApp> {
+/**
+ * A caller's `runtime` wins; with none, the app's own `apps/<app>/runtime.ts` is what this boot
+ * reads — the SAME file `x dev` reads — so the two boots compose one middleware chain, one
+ * rate-limit store, one ISR store, rather than a development set and a production set. Resolved
+ * ONCE, at each public entry, so every reader below (`startServices`, `startQueue`, the asset and
+ * ISR seams, the replica override) sees one object: a per-read fallback would be the partial read
+ * this repository names as its most repeated defect.
+ */
+export async function withAppRuntime(options: ServeOptions): Promise<ServeOptions> {
+  if (options.runtime !== undefined) return options;
+  const runtime = await loadAppRuntime(options.root);
+  return runtime === undefined ? options : { ...options, runtime };
+}
+
+export async function serveApp(input: ServeOptions): Promise<ServedApp> {
+  const options = await withAppRuntime(input);
   const role = options.role ?? roleFromEnv(options.env);
   const runtime = await startServices(
     resolveServices(options.root, options.env),
@@ -313,8 +330,11 @@ async function bootRoles(boot: {
     pwa === undefined
       ? undefined
       : serviceWorkerArtifacts({ pwa, buildId, routes: describeRoutes(), islands });
+  // The app's own MCP endpoint, through the same call `x dev` makes — see `app-mcp.ts`.
+  const mcpMount = await mountAppMcp(options.root);
   const routes: readonly Route[] = [
     ...apiRoutes(),
+    ...mcpMount.routes,
     ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
     ...assetRoutes({
       root: options.root,
@@ -386,8 +406,11 @@ async function bootRoles(boot: {
  * holds for every other role until core's drain completes, so SIGTERM from a rolling restart takes
  * the three-phase path (stop accepting, finish in-flight, close) instead of killing a query.
  */
-export async function runRole(options: ServeOptions): Promise<StartedApp> {
-  const role = options.role ?? roleFromEnv(options.env);
+export async function runRole(input: ServeOptions): Promise<StartedApp> {
+  // The role FIRST: a bad `ROLE` is refused before the root is read at all, so a boot that was
+  // always going to fail creates nothing under it — the same order `resolveServices` is held to.
+  const role = input.role ?? roleFromEnv(input.env);
+  const options = await withAppRuntime(input);
   if (role === 'migrate') {
     const migrated = await runMigrations({ ...options, role });
     // The release phase has one channel — the exit code — so drift is thrown here rather than

package/src/source-files.ts

@@ -29,12 +29,24 @@ export const isGenerated = (path: string): boolean => path.endsWith('.d.ts');
 /** Every opt-in suffix (`*.{contract,live,job,eval,e2e}.test.ts`) still ends `.test.ts`. */
 export const isTest = (path: string): boolean => /\.test\.tsx?$/.test(path);
 
-/** Every source file under `root`, repo-relative and deduplicated across the globs. */
+/**
+ * Every source file under `root`, repo-relative and deduplicated across the globs — in a SORTED
+ * order per pattern, `As of 2026-09-05`. `Bun.Glob.scan` yields in the filesystem's `readdir`
+ * order, which ext4 hashes: the first offender a scan names was `index.ts` on one machine and
+ * `tools.ts` on a GitHub runner, so a finding's `cause` depended on which disk held the checkout
+ * (`workspace-graph.test.ts`, red on CI and green everywhere else). Code-unit compare, never
+ * `localeCompare`, for the reason `describeRoutes` states: one order on every machine.
+ */
 export async function* eachSourceFile(root: string): AsyncGenerator<string> {
   const seen = new Set<string>();
   for (const pattern of SOURCE_GLOBS) {
+    const matches: string[] = [];
     for await (const path of new Bun.Glob(pattern).scan({ cwd: root, absolute: false })) {
-      if (isVendored(path) || seen.has(path)) continue;
+      if (!isVendored(path)) matches.push(path);
+    }
+    matches.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+    for (const path of matches) {
+      if (seen.has(path)) continue;
       seen.add(path);
       yield path;
     }

package/src/templates/entity.ts

@@ -27,6 +27,13 @@ import { entity, invariant, money, text, timestamp, uuid } from '@ultimat3/entit
 export const ${name.camel} = entity('${table}', {
   // Naming the tenant column is what turns tenancy on: a read without an org predicate then
   // fails with X_TENANCY_UNSCOPED instead of leaking another org's rows.
+  //
+  // SINGLE-TENANT APP? There is no flag: \`x g action\`, \`x g query\` and \`x g policy\` decide on
+  // \`orgId\` too, so the edit is per slice and it is this: delete \`tenant: 'orgId'\` and the
+  // \`orgId: uuid()\` column below, drop \`'orgId'\` from \`indexes\`, and in repo.ts turn
+  // \`listByOrg(orgId, limit)\` into \`list(limit)\` with no \`org_id\` predicate and no \`org_id\` in
+  // the insert. entity.test.ts then expects \`$tenantColumn\` null and \`orgScoped\` false, and its
+  // \`row()\` fixture loses \`orgId\`. Nothing else reads the column.
   tenant: 'orgId',
   columns: {
     id: uuid().primaryKey(),

package/src/ts-scan.ts

@@ -30,120 +30,17 @@ export interface CodeScan {
   readonly unresolved: readonly UnresolvedCodeSite[];
 }
 
+// The masking itself — `QUOTES`, `endOfLiteral`, `stripComments`, `maskLiterals` — lives in
+// `@ultimat3/core`'s `source-mask.ts` since 2026-09-05, because `@ultimat3/i18n`'s key extractor
+// (tier 1) needed it and could not reach a tier-5 package. Re-exported here so every scanner in
+// this package, and this package's public API, keep the names they had.
+import { endOfLiteral, maskLiterals, QUOTES, stripComments } from '@ultimat3/core';
+
+export { endOfLiteral, maskLiterals, QUOTES, stripComments };
+
 // `ReadonlySet`, so a consumer cannot mutate what every scan in this package reads.
-export const QUOTES: ReadonlySet<string> = new Set(["'", '"', '`']);
 export const OPENERS: ReadonlySet<string> = new Set(['(', '[', '{']);
 export const CLOSERS: ReadonlySet<string> = new Set([')', ']', '}']);
-const WORD = /[\w$]/;
-
-/** After one of these words a `/` opens a regex; after any other identifier it divides. */
-const REGEX_AFTER_WORDS = new Set(
-  'await case delete do else in instanceof new of return throw typeof void yield'.split(' '),
-);
-
-/**
- * Index just past the closing quote of the literal opening at `from`, or `from + 1` when a `'`/`"`
- * does not close on its own line — which makes it text, not a literal. Only a template literal may
- * span a newline, so the apostrophe in `<p>Don't panic</p>` is JSX text; read as an opener it ran
- * forward to the next `'` in the FILE (the next `fix:` line) and blanked every declaration between,
- * silently emptying the `errors` gate for the whole file. Same rule `endOfRegex` applies to a `/`.
- * An escaped newline is still a continuation: the escape is consumed before the line test.
- */
-export function endOfLiteral(text: string, from: number): number {
-  const quote = text[from] as string;
-  const spansLines = quote === '`';
-  for (let i = from + 1; i < text.length; i += 1) {
-    if (text[i] === '\\') i += 1;
-    else if (text[i] === quote) return i + 1;
-    else if (!spansLines && text[i] === '\n') return from + 1;
-  }
-  return spansLines ? text.length : from + 1;
-}
-
-/**
- * Whether the `/` at `at` opens a regex rather than divides — the call no scanner without a parser
- * avoids. A regex cannot follow what ends an expression: an identifier that is not one of the words
- * above, a number, `)`, `]`, a string's closing quote. Every other position is an operator's and
- * opens one; `</` and `/>` are JSX delimiters. Read from the masked prefix, so a comment is space.
- */
-function opensRegex(out: readonly string[], at: number): boolean {
-  if (out[at + 1] === '>') return false;
-  let i = at - 1;
-  while (i >= 0 && /\s/.test(out[i] as string)) i -= 1;
-  if (i < 0) return true;
-  const ch = out[i] as string;
-  if (ch === '<' || ch === ')' || ch === ']' || QUOTES.has(ch)) return false;
-  if (!WORD.test(ch)) return true;
-  let start = i;
-  while (start >= 0 && WORD.test(out[start] as string)) start -= 1;
-  return REGEX_AFTER_WORDS.has(out.slice(start + 1, i + 1).join(''));
-}
-
-/**
- * Index just past the closing `/` of the regex opening at `from`, or `from + 1` when it does not
- * close on its own line — a literal may not span one, so an unterminated candidate was a division
- * or a JSX delimiter after all. A `/` inside a `[…]` class does not close the literal.
- */
-function endOfRegex(text: string, from: number): number {
-  let inClass = false;
-  let escaped = false;
-  for (let i = from + 1; i < text.length; i += 1) {
-    const ch = text[i];
-    if (ch === '\n') break;
-    if (escaped) escaped = false;
-    else if (ch === '\\') escaped = true;
-    else if (inClass) inClass = ch !== ']';
-    else if (ch === '[') inClass = true;
-    else if (ch === '/') return i + 1;
-  }
-  return from + 1;
-}
-
-/**
- * Comments — and optionally string contents — replaced by spaces, newlines kept so line numbers
- * survive and quote delimiters kept so the caller can still find where a literal starts and ends.
- * A regex body is masked the same way: `/(['"`])/` holds three quotes that delimit nothing, and
- * reading one as an opening quote desyncs every literal after it.
- */
-function blankRegions(text: string, strings: boolean): string {
-  // `split('')` and NOT `[...text]`: the spread yields one element per CODE POINT while every
-  // index below runs over UTF-16 units (`text.length`, `text[i]`). One astral character — an emoji
-  // in a fixture, `piñata 🎉` — and `out` is shorter than `text`, so every write past it lands a
-  // slot early and the returned mask no longer aligns with the input. Measured: 22 files in this
-  // tree desynced, shipped source included, and eight rules read this mask.
-  const out = text.split('');
-  const blank = (from: number, to: number): void => {
-    for (let n = from; n < to; n += 1) if (out[n] !== '\n') out[n] = ' ';
-  };
-  let i = 0;
-  while (i < text.length) {
-    const ch = text[i] as string;
-    if (ch === '/' && (text[i + 1] === '/' || text[i + 1] === '*')) {
-      const line = text[i + 1] === '/';
-      const end = line ? text.indexOf('\n', i) : text.indexOf('*/', i + 2);
-      const stop = end === -1 ? text.length : line ? end : end + 2;
-      blank(i, stop);
-      i = stop;
-      continue;
-    }
-    // Not code: a regex body or a literal. `end === i + 1` blanks nothing and steps one char.
-    const end =
-      ch === '/' && opensRegex(out, i)
-        ? endOfRegex(text, i)
-        : QUOTES.has(ch)
-          ? endOfLiteral(text, i)
-          : i + 1;
-    if (strings) blank(i + 1, end - 1);
-    i = end;
-  }
-  return out.join('');
-}
-
-/** Comments gone, string literals intact — what a scan for declared codes reads. */
-export const stripComments = (text: string): string => blankRegions(text, false);
-
-/** Comments and string contents gone, delimiters kept — what a scan for code structure reads. */
-export const maskLiterals = (text: string): string => blankRegions(text, true);
 
 /**
  * Line numbers for one text, in one pass. Counting newlines per lookup is O(index), which a scan