@ultimat3/cli 22.14.0 → 23.0.0

package/src/output.ts

@@ -37,7 +37,12 @@ export interface StepResult {
   readonly durationMs: number;
   readonly skipped?: boolean;
   readonly findings: readonly Finding[];
-  /** Captured stdout/stderr, shown on failure or with --verbose. */
+  /**
+   * Captured stdout/stderr, for a reader working out what a step DID — carried by both renderers
+   * on failure or with `--verbose`, and by neither on a quiet green run. Never the home of a fact:
+   * a number a passing step must report by default goes in `CommandResult.data` (the `unit` step's
+   * coverage is `data.coverage.unit`), where `--json` and the terminal both always have it.
+   */
   readonly output?: string;
   /** Worker processes the step used; `1` means it ran serially. Absent for a non-test step. */
   readonly workers?: number;
@@ -208,6 +213,10 @@ const why = (step: StepResult): string => {
   return `  ${msg('cli.verify.allSkipped', { skipped: tests.skipped })}`;
 };
 
+/** The one rule for a step's captured output, so the two renderers cannot answer differently. */
+const showsOutput = (step: StepResult, verbose: boolean): boolean =>
+  step.output !== undefined && step.output.length > 0 && (verbose || !step.ok);
+
 export function renderHuman(result: CommandResult, verbose = false): string {
   const out: string[] = [];
   for (const step of result.steps ?? []) {
@@ -218,8 +227,8 @@ export function renderHuman(result: CommandResult, verbose = false): string {
     // NOT escaped, and that is the one exception: `output` is this process's own captured
     // subprocess stdout — `bun test`'s colour is the reason a human reads it at all, and it is
     // already split on its real newlines rather than carrying them inside one entry.
-    if (step.output !== undefined && step.output.length > 0 && (verbose || !step.ok)) {
-      for (const line of step.output.trimEnd().split('\n')) out.push(`      | ${line}`);
+    if (showsOutput(step, verbose)) {
+      for (const line of (step.output ?? '').trimEnd().split('\n')) out.push(`      | ${line}`);
     }
   }
   // Every free-text line through the SAME `singleLine` the 3-line format runs, because this is
@@ -234,7 +243,7 @@ export function renderHuman(result: CommandResult, verbose = false): string {
   return out.join('\n');
 }
 
-export function renderJson(result: CommandResult): string {
+export function renderJson(result: CommandResult, verbose = false): string {
   const steps = (result.steps ?? []).map((step) => ({
     name: step.name,
     ok: step.ok,
@@ -261,10 +270,10 @@ export function renderJson(result: CommandResult): string {
     // fix line — the failing test's name and its assertion diff existed and were thrown away, so
     // the only way to learn what broke was to re-run it somewhere else. CI output is a prompt:
     // whoever reads it next, agent or human, must be able to act without reproducing first.
-    // Success stays quiet (`--verbose` is the human's opt-in) so a green run is not a wall of text.
-    ...(step.ok || step.output === undefined || step.output.length === 0
-      ? {}
-      : { output: step.output }),
+    // Success stays quiet so a green run is not a wall of text — unless `--verbose` asked, which
+    // is the same opt-in the terminal honours: a green step's output used to be reachable from the
+    // human render and from nowhere under `--json`.
+    ...(showsOutput(step, verbose) ? { output: step.output } : {}),
   }));
   const payload = {
     ok: result.ok,
@@ -278,7 +287,7 @@ export function renderJson(result: CommandResult): string {
 }
 
 export function render(result: CommandResult, json: boolean, verbose = false): string {
-  return json ? renderJson(result) : renderHuman(result, verbose);
+  return json ? renderJson(result, verbose) : renderHuman(result, verbose);
 }
 
 export function exitCodeFor(result: CommandResult): number {

package/src/page-speculation.ts

@@ -0,0 +1,124 @@
+// Speculation Rules for the documents that carry NO client router, composed ONCE for `x dev`, the
+// container and the static export: `navigation.speculation` from `app.config.ts`, the pages the
+// route table knows to be a pure read, the one `<script type="speculationrules">` every such
+// document carries, and the `script-src` source that admits exactly that body. A browser fetches
+// the next page's document on pointer rest, so a full-page navigation between prerendered pages
+// paints from memory — and the page still ships 0kb of JavaScript (axiom 6).
+
+// why: Bun exposes no path-join primitive, and the config path is app-root-relative — the same
+// necessity `theme-boot.ts` records.
+import { join } from 'node:path';
+import type { NavigationSurface, SpeculationConfig } from '@ultimat3/core';
+import { DEFAULT_SPECULATION, localeSegment, resolveSpeculation } from '@ultimat3/core';
+import { cspHashSource } from '@ultimat3/http';
+import { localeConfig, routedLocales } from '@ultimat3/i18n';
+import type { RouteDescriptor, RouteEntry } from '@ultimat3/render';
+import {
+  describeRoutes,
+  renderHead,
+  routeEntries,
+  speculationPattern,
+  speculationRulesBody,
+  speculationRulesTag,
+} from '@ultimat3/render';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * `navigation.speculation` — the default (on, `'moderate'`) when the app says nothing or has no
+ * config file. Structural, for `loadThemeMode`'s reason, and so possibly NOT what `defineConfig`
+ * validated: what it finds goes through core's `resolveSpeculation`, the one validator, which
+ * REFUSES (`X_CONFIG_INVALID`) a value `defineConfig` would refuse. Never coerced: an `'eager'`
+ * quietly served as `'moderate'` is a rule the app did not write.
+ */
+export async function loadSpeculation(root: string): Promise<SpeculationConfig> {
+  const configPath = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(configPath).exists())) return DEFAULT_SPECULATION;
+  const module = (await import(configPath)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  const navigation = isRecord(config) ? config['navigation'] : undefined;
+  return resolveSpeculation(isRecord(navigation) ? navigation['speculation'] : undefined);
+}
+
+/**
+ * Whether a browser may fetch this page before anyone asked for it. An ALLOW-list, never "every
+ * link but these": a prefetch is a real GET with the visitor's cookies, so the only safe candidates
+ * are pages the table itself says are a pure read.
+ *
+ * - On a surface WITHOUT the client router: a prerendered, shareable document — `static` or `isr`,
+ *   no policy, no `no-store`. Such a page ran its `load` at build time, for nobody. An `ssr` page
+ *   there has no way to declare that its GET records something (`navigation` is refused on a
+ *   surface that did not opt in), so it is never a candidate.
+ * - On a client-routed surface: only a page that declared `navigation: 'prefetch'` — the app's own
+ *   statement that its GET is a pure read, the same one the router's prefetch obeys.
+ * - Never an `api/` route, a `navigation: 'document'` page, or an `offline: 'network-only'` one.
+ */
+export function speculationCandidate(
+  entry: Pick<RouteEntry, 'surface' | 'config'>,
+  described: Pick<RouteDescriptor, 'mode' | 'offline' | 'personal'>,
+  client: ReadonlySet<string>,
+): boolean {
+  if (entry.surface !== 'site' && entry.surface !== 'app') return false;
+  if (entry.config.navigation === 'document' || described.offline === 'network-only') return false;
+  if (client.has(entry.surface)) return entry.config.navigation === 'prefetch';
+  return (described.mode === 'static' || described.mode === 'isr') && !described.personal;
+}
+
+export interface PageSpeculation {
+  /** The rendered `<script type="speculationrules">`, for `DocumentOptions.speculationHead`. */
+  readonly head: string;
+  /** The text between its tags — what a browser hashes. */
+  readonly body: string;
+  /** The `script-src` source that admits exactly that body. */
+  readonly cspSource: string;
+}
+
+export interface PageSpeculationInput {
+  readonly config: SpeculationConfig;
+  /** `navigation.client`: the surfaces whose documents carry the router instead. */
+  readonly client: readonly NavigationSurface[];
+  readonly entries?: readonly RouteEntry[];
+  readonly described?: readonly RouteDescriptor[];
+  /** The NON-default routed locales' URL segments. Read from `@ultimat3/i18n` when absent. */
+  readonly localeSegments?: readonly string[];
+}
+
+const otherLocaleSegments = (): readonly string[] => {
+  const fallback = localeSegment(localeConfig().fallback);
+  return routedLocales()
+    .map(localeSegment)
+    .filter((segment) => segment !== fallback);
+};
+
+/**
+ * Tag and hash from ONE body, as `themeBoot` does. `undefined` when the app turned it off or no
+ * page is a candidate — then no document carries a tag and the policy admits nothing new. Called
+ * after the app is loaded: the route table and the routed locales are what it reads.
+ */
+export function pageSpeculation(input: PageSpeculationInput): PageSpeculation | undefined {
+  if (input.config.prefetch === false) return undefined;
+  const entries = input.entries ?? routeEntries();
+  const described = new Map((input.described ?? describeRoutes()).map((one) => [one.file, one]));
+  const client = new Set<string>(input.client);
+  const segments = input.localeSegments ?? otherLocaleSegments();
+  const include = entries
+    .filter((entry) => {
+      const facts = described.get(entry.file);
+      return facts !== undefined && speculationCandidate(entry, facts, client);
+    })
+    .map((entry) => speculationPattern(entry.path, segments));
+  const body = speculationRulesBody({
+    eagerness: input.config.prefetch,
+    include,
+    exclude: input.config.exclude,
+  });
+  if (body === undefined) return undefined;
+  return {
+    head: renderHead([speculationRulesTag(body)]),
+    body,
+    cspSource: cspHashSource(body),
+  };
+}

package/src/permission-grants.ts

@@ -1,5 +1,5 @@
-// The `policy` step's second question: every permission an action, a query or a route REQUIRES is
-// one some role GRANTS. `x g resource customer` declared `customer:read`/`customer:write`, the
+// The `policy` step's second question: every permission an action, a query, a route or a MOUNTED
+// screen (the admin's) REQUIRES is one some role GRANTS. `x g resource customer` declared `customer:read`/`customer:write`, the
 // actions required them, no role held them, and `x verify` was green over an app whose every
 // generated endpoint answered 403 to the dev actor (plan 101 slice 11 a).
 
@@ -7,14 +7,14 @@ import { listActions } from '@ultimat3/action';
 import type { Policy } from '@ultimat3/policy';
 import { roleDefinitions, rolesGranting } from '@ultimat3/policy';
 import { listQueries } from '@ultimat3/query';
-import { routeEntries } from '@ultimat3/render';
+import { describeRoutes, routeEntries } from '@ultimat3/render';
 import type { Finding } from './output';
 import { quoteArg } from './shell-quote';
 
 /** One rule that cannot pass for any actor the role map mints. */
 export interface UngrantedRequirement {
   readonly permission: string;
-  /** `action createCustomer`, `query customerList`, or the route file. */
+  /** `action createCustomer`, `query customerList`, the route file, or a mounted route's URL. */
   readonly by: string;
 }
 
@@ -43,6 +43,28 @@ export function requirements(): readonly UngrantedRequirement[] {
     const permission = entry.config.policy?.permission;
     if (permission !== undefined) rules.push({ permission, by: entry.file });
   }
+  // A route a package MOUNTED — the admin's — is in no file and so in no `routeEntries()` row. Its
+  // screen decides on every permission of the mount, not only the coarse gate its route config
+  // carries, so each one is a requirement: a hand-written entity nobody granted `<table>:read`
+  // for was a green gate and a 403 on its first open. `describeRoutes()` is memoized by the
+  // registry, so this loop reads a list every other step already built.
+  // One requirement per permission per mount, naming the first route that asks it: `posts:write`
+  // gates the create form and the edit form, and one missing grant is one finding.
+  const asked = new Map<string, { permission: string; by: string; first: string; more: number }>();
+  for (const route of describeRoutes()) {
+    if (route.mount === undefined) continue;
+    for (const permission of route.mount.permissions) {
+      const key = `${route.mount.by} ${permission}`;
+      const held = asked.get(key);
+      if (held === undefined) {
+        asked.set(key, { permission, by: route.mount.by, first: route.path, more: 0 });
+      } else held.more += 1;
+    }
+  }
+  for (const { permission, by, first, more } of asked.values()) {
+    const rest = more === 0 ? '' : `, and ${String(more)} more of its routes`;
+    rules.push({ permission, by: `${first} (mounted by ${by}${rest})` });
+  }
   return rules;
 }
 
@@ -73,14 +95,24 @@ export function ungrantedRequirements(
     );
 }
 
-/** Where the scaffold keeps the role map — the file `x g policy` and `x g resource` edit. */
+/**
+ * Where the SCAFFOLD keeps the role map — the file `x g policy` and `x g resource` edit. Never what
+ * a finding names: an app may declare its roles anywhere (the reference app's are in
+ * `shared/policies.ts`), so `ungrantedFinding` takes the file the role map was declared in.
+ */
 export const ROLES_FILE = 'apps/web/shared/roles.ts';
 
-export function ungrantedFinding(rule: UngrantedRequirement): Finding {
-  return {
+/**
+ * `rolesAt` is the app-relative file `defineRoles` ran in (`app-permissions.ts`'s `roleMapFile`),
+ * or `undefined` when no site under the app root can be read — then the fix names the call, not a
+ * path this function would have to guess.
+ */
+export function ungrantedFinding(rule: UngrantedRequirement, rolesAt: string | undefined): Finding {
+  const where = rolesAt ?? 'the module that calls defineRoles({ ... })';
+  const finding: Finding = {
     code: 'X_PERMISSION_UNGRANTED',
     cause: `${rule.by} requires ${quoteArg(rule.permission)}, and no role in the app's role map grants it — no actor a role mints can ever pass`,
-    fix: `add '${rule.permission}' to the grants of a role in ${ROLES_FILE}, then x verify --only policy`,
-    at: ROLES_FILE,
+    fix: `add '${rule.permission}' to the grants of a role in ${where}, then x verify --only policy`,
   };
+  return rolesAt === undefined ? finding : { ...finding, at: rolesAt };
 }

package/src/prerender.ts

@@ -28,6 +28,7 @@ import { measureDatabase } from './measure-database';
 import { measurePaths } from './measure-paths';
 import { measureScope, withAppUrl } from './measure-scope';
 import { loadNavigation, pageNavigation } from './page-navigation';
+import { loadSpeculation, pageSpeculation } from './page-speculation';
 import { localizedArtifacts } from './prerender-locales';
 import { clearPrerenderOut } from './prerender-out';
 import { loadPwaArtifacts, writePwaIcons } from './pwa-artifacts';
@@ -237,11 +238,13 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // The client router, for the surfaces that opted in: written BEFORE any document names it, for
   // the register's reason below — `measureDocumentJs` weighs it off disk, and it is charged to
   // the route (the interactivity the app asked for), so it must be there to be weighed.
-  const navigation = await pageNavigation(
-    options.root,
-    await loadNavigation(options.root),
-    buildId,
-  );
+  const declared = await loadNavigation(options.root);
+  const navigation = await pageNavigation(options.root, declared, buildId);
+  // The same rules the served process writes, so the exported file and the served document agree.
+  const speculation = pageSpeculation({
+    config: await loadSpeculation(options.root),
+    client: declared.surfaces,
+  });
   if (navigation.script !== undefined) {
     await Bun.write(join(options.out, navigation.script.url.slice(1)), navigation.script.code);
   }
@@ -305,6 +308,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     routeDocument(entry, data, {
       resolveIsland: (file: string) => islands.resolverFor(file),
       themeHead: theme.head,
+      ...(speculation === undefined ? {} : { speculationHead: speculation.head }),
       origin,
       ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
       ...(pwa === undefined

package/src/publish-closure.ts

@@ -0,0 +1,101 @@
+// `package-shape`'s other half of "a fixture does not ship": what a published package's ENTRY
+// POINTS can load, held against the files its tarball leaves out. `files` negates
+// `src/**/*-fixture.ts`, so a module an entry reaches under that suffix is a published package
+// that fails on import — and the defect is the name, not the exclusion.
+
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { ClosureHost } from './import-closure';
+import { importClosure } from './import-closure';
+import type { Finding } from './output';
+
+/** The suffix `FIXTURE_EXCLUSION` removes from a tarball. */
+export const FIXTURE_SUFFIX = '-fixture.ts';
+
+/** A package directory, read by package-relative POSIX path. */
+export type PackageReader = Pick<ClosureHost, 'read'>;
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null;
+
+/** Every string under `exports` / `bin`, whatever the nesting: a condition map is still a file. */
+const targetsOf = (value: unknown): readonly string[] => {
+  if (typeof value === 'string') return [value];
+  return isRecord(value) ? Object.values(value).flatMap(targetsOf) : [];
+};
+
+/**
+ * The modules a consumer can import or run: `exports` and `bin`, package-relative. A subpath
+ * pattern (`./icons/*`) names no one file and a stylesheet is not a module, so neither is an
+ * entry to walk from.
+ */
+export function entryFilesOf(manifest: unknown): readonly string[] {
+  if (!isRecord(manifest)) return [];
+  const targets = [...targetsOf(manifest['exports']), ...targetsOf(manifest['bin'])];
+  const files = targets
+    .map((target) => target.replace(/^\.\//, ''))
+    .filter((target) => /\.tsx?$/.test(target) && !target.includes('*'));
+  return [...new Set(files)].sort();
+}
+
+/**
+ * Every `*-fixture.ts` whose body an entry can run. Bare specifiers end the walk: another package
+ * is that package's tarball, held by its own run of this rule.
+ */
+export function fixturesReachedFrom(
+  reader: PackageReader,
+  entries: readonly string[],
+): readonly string[] {
+  const host: ClosureHost = { read: reader.read, alias: () => undefined };
+  return importClosure(host, entries).filter((path) => path.endsWith(FIXTURE_SUFFIX));
+}
+
+/** `src/a/driver-fixture.ts` → `driver-fixture`; an `index.ts` is named by its directory. */
+const stemOf = (path: string): string => {
+  const parts = path.replace(/\.tsx?$/, '').split('/');
+  const last = parts.at(-1) ?? '';
+  return last === 'index' ? (parts.at(-2) ?? last) : last;
+};
+
+const escaped = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * The cheap question, asked before the walk: COULD an entry reach a fixture? Backwards from each
+ * fixture, by the last segment of a relative specifier, over text alone — so it over-answers (a
+ * type-only import, two files of one name) and never under-answers. `false` is final; `true`
+ * earns the real closure. Measured 2026-10: the closure alone was ~650 ms across the 12 packages
+ * that hold a fixture, and all but one of them are answered here.
+ */
+export function mayReachFixture(
+  sources: ReadonlyMap<string, string>,
+  entries: readonly string[],
+): boolean {
+  const entrySet = new Set(entries);
+  const seen = new Set<string>();
+  let frontier = [...sources.keys()].filter((path) => path.endsWith(FIXTURE_SUFFIX));
+  while (frontier.length > 0) {
+    const names = new RegExp(
+      `/(?:${frontier.map(stemOf).map(escaped).join('|')})(?:\\.[jt]sx?)?['"]`,
+    );
+    const next: string[] = [];
+    for (const [path, text] of sources) {
+      if (seen.has(path) || path.endsWith(FIXTURE_SUFFIX) || !names.test(text)) continue;
+      if (entrySet.has(path)) return true;
+      seen.add(path);
+      next.push(path);
+    }
+    frontier = next;
+  }
+  return false;
+}
+
+export const fixtureReachFinding = (
+  dir: string,
+  fixture: string,
+  entries: readonly string[],
+): Finding => ({
+  code: 'X_PACKAGE_SHAPE',
+  cause: `packages/${dir}/${fixture} is loaded from the package's entry points (${entries.join(', ')}), and "files" leaves every *${FIXTURE_SUFFIX} out of the tarball — the published package would fail on import`,
+  fix: `rename packages/${dir}/${fixture} so it does not end in ${FIXTURE_SUFFIX} — it is shipped source, not test code — and update the imports that name it`,
+  docs: ERROR_DOCS_URL,
+  at: `packages/${dir}/${fixture}`,
+});

package/src/role-load.ts

@@ -0,0 +1,143 @@
+// What a container role imports of the app. `web`, `sync` and `replicator` answer for registries a
+// request, a subscription or the WAL names — routes, queries, entities — so they import every
+// module. `worker` and `scheduler` run jobs and tasks: they import the API index and every module
+// that brings no document (a component, a stylesheet) with it, and nothing else.
+
+// why: Bun ships no path API; the API index is named app-root-relative and imported absolute.
+import { join, resolve } from 'node:path';
+import type { Role } from '@ultimat3/core';
+import { isJsonObject, logger, UltimateError } from '@ultimat3/core';
+import { registeredJobs, registeredTasks } from '@ultimat3/jobs';
+import type { AppScan } from './app-load';
+import { scanAppModules } from './app-load';
+import { API_INDEX } from './app-root';
+import { createDocumentGraph } from './document-graph';
+
+/** `everything`: the scan every tool runs. `background`: no document a job does not import. */
+export type RoleLoad = 'everything' | 'background';
+
+/**
+ * Typed over `Role`, so a seventh role does not compile until somebody decides what it imports.
+ * `migrate` never reaches a load — `runMigrations` reads SQL files — and says `everything` so a
+ * caller that boots it by hand is given the whole app rather than a guess.
+ */
+const DECLARED: Readonly<Record<Role, RoleLoad>> = {
+  web: 'everything',
+  // A subscription names a live query, and a page module may export one.
+  sync: 'everything',
+  // The slot decodes every table an entity declares, wherever the entity is declared.
+  replicator: 'everything',
+  worker: 'background',
+  scheduler: 'background',
+  migrate: 'everything',
+};
+
+/** A `Map`, so the read below is an own-key lookup — never a member of `Object.prototype`. */
+export const ROLE_LOADS: ReadonlyMap<Role, RoleLoad> = new Map(
+  Object.entries(DECLARED) as [Role, RoleLoad][],
+);
+
+/** What `role` imports. A value that is no role — an untyped caller's — is given everything. */
+export const roleLoadFor = (role: Role): RoleLoad => ROLE_LOADS.get(role) ?? 'everything';
+
+/** The file the gate holds fresh (`manifest` step) and every image carries beside the source. */
+const MANIFEST_FILE = 'x.manifest.json';
+
+/**
+ * A background load that left out a job or task the committed manifest names. Logged, never
+ * thrown: the boot answers it by importing the rest of the app, so the role runs everything it
+ * ran before — it only pays for the documents this load exists to leave out.
+ */
+export class RoleLoadIncompleteError extends UltimateError {
+  constructor(input: { role: Role; missing: readonly string[] }) {
+    super({
+      code: 'X_ROLE_LOAD_INCOMPLETE',
+      cause: `the ${input.role} role imported ${API_INDEX} and every module that reaches no component or stylesheet, and ${MANIFEST_FILE} names ${String(input.missing.length)} job(s) or task(s) that load did not register (${input.missing.join(', ')}), so the whole app was imported instead`,
+      fix: `add import * as <module> from the file that declares it and <module> to jobs: [...] or tasks: [...] in ${API_INDEX}, then x manifest`,
+      meta: { role: input.role, missing: input.missing },
+    });
+  }
+}
+
+/** `name` of every entry of one manifest list — `[]` for a list that is absent or malformed. */
+function namesIn(manifest: Record<string, unknown>, key: 'jobs' | 'tasks'): readonly string[] {
+  const list = manifest[key];
+  if (!Array.isArray(list)) return [];
+  return list.flatMap((entry: unknown) =>
+    isJsonObject(entry) && typeof entry['name'] === 'string' ? [entry['name']] : [],
+  );
+}
+
+/**
+ * Every job and task the committed manifest names that this process has not registered —
+ * `undefined` when there is no manifest to check against, which is not the same answer as "none".
+ */
+export async function unregisteredFromManifest(
+  root: string,
+): Promise<readonly string[] | undefined> {
+  const parsed: unknown = await Bun.file(join(root, MANIFEST_FILE))
+    .json()
+    .catch(() => undefined);
+  if (!isJsonObject(parsed)) return undefined;
+  const jobs = new Set(registeredJobs().map((job) => job.name));
+  const tasks = new Set(registeredTasks().map((task) => task.name));
+  return [
+    ...namesIn(parsed, 'jobs').filter((name) => !jobs.has(name)),
+    ...namesIn(parsed, 'tasks').filter((name) => !tasks.has(name)),
+  ].sort();
+}
+
+/**
+ * The background scan alone, with no proof and no fallback: the API index and every module that
+ * brings no document. What a worker imports when nothing is wrong — and what the gate imports in a
+ * child to compare against the whole app (`verify-role-load.ts`).
+ */
+export async function scanBackground(root: string): Promise<AppScan> {
+  const index = resolve(root, API_INDEX);
+  // why `require.cache`: Bun 1.4 lists every evaluated ES module there, by absolute path — the
+  // same table `app-reload-graph.ts` evicts from.
+  const loaded = (absolute: string): boolean => absolute in require.cache;
+  const graph = createDocumentGraph(loaded);
+  return scanAppModules(root, {
+    track: false,
+    // The index first (`appModulePaths` leads with it): what it imports is what the app runs.
+    // Then every module already here, and every one that brings no document with it — a service,
+    // a catalog, a storage declaration registers on import and no job names it.
+    include: async (absolute) =>
+      absolute === index || loaded(absolute) || !(await graph.reachesDocument(absolute)),
+  });
+}
+
+/**
+ * The background load, then the proof it was enough. A job runs by NAME — the queue row carries
+ * it — so the one thing this load must not do is leave a named job unregistered. The gate already
+ * requires every job and task to be named from a `defineApi()` call (`X_JOB_UNREGISTERED`); the
+ * manifest is the list that call produced, and a name it holds that this load did not register is
+ * answered by importing everything, loudly.
+ */
+async function loadBackground(root: string, role: Role): Promise<AppScan> {
+  const scan = await scanBackground(root);
+  const missing = await unregisteredFromManifest(root);
+  if (missing !== undefined && missing.length === 0) return scan;
+  if (missing === undefined) {
+    logger.warn('ultimate role load unverified', {
+      role,
+      cause: `${MANIFEST_FILE} is absent or unreadable, so nothing names the jobs this role must run and the whole app was imported`,
+      fix: 'x manifest',
+    });
+  } else {
+    const error = new RoleLoadIncompleteError({ role, missing });
+    logger.error(error.format(), { code: error.code, role, missing });
+  }
+  return scanAppModules(root, { track: false });
+}
+
+/**
+ * What `serve-boot.ts` calls instead of `loadApp`: the scan a role needs and none of what a tool
+ * reads from it afterwards — no reload graph, no error-code walk of the app's source.
+ */
+export async function loadAppForRole(root: string, role: Role): Promise<AppScan> {
+  return roleLoadFor(role) === 'background'
+    ? loadBackground(root, role)
+    : scanAppModules(root, { track: false });
+}

package/src/role-start.ts

@@ -29,12 +29,17 @@ import {
 import type { SyncWs } from '@ultimat3/realtime/server';
 import { errorPageHook } from './error-pages';
 import { BadFlagError, PortInvalidError, RuntimeDriverSplitError } from './errors';
-import { DEFAULT_METRICS_PORT, startMetricsEndpoint } from './metrics-endpoint';
+import {
+  DEFAULT_METRICS_PORT,
+  startMetricsEndpoint,
+  whenMetricsPortTaken,
+} from './metrics-endpoint';
 import { rolesUnderRealtime } from './role-realtime';
 import { startReplicator } from './role-replicator';
 import type { RunningRoles, StartRolesOptions } from './role-start-types';
 import { DEV_ROLES } from './role-start-types';
 import { prepareSync, type RunningSync } from './role-sync';
+import { startWorkerWake } from './role-wake';
 import type { Env } from './runtime-bindings';
 import { devHooks } from './runtime-hooks';
 import { workerOptionsFor } from './runtime-jobs';
@@ -304,6 +309,9 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
       startMetricsEndpoint({
         port: options.metricsPort ?? (options.port === 0 ? 0 : DEFAULT_METRICS_PORT),
         hostname: binding.hostname,
+        // `x dev` is one process running several roles: its `process_info` says which.
+        role: selected.join('+'),
+        whenTaken: whenMetricsPortTaken(binding.dev, options.env),
       });
     started.push(async () => metrics.stop());
 
@@ -350,6 +358,13 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
     // one hands the failure rollback the same window a dropped `await` gives the teardown below.
     if (relay !== null) started.push(() => relay.stop());
 
+    // The cross-process wake: one LISTEN session, so a job another pod committed starts now
+    // instead of at the next poll. On `worker` alone — it is the role whose two loops (the claim
+    // and the relay above) hear it; a web or scheduler pod holding a session would pin a
+    // connection per replica to wake nothing (`role-wake.ts`).
+    const wake = selected.includes('worker') ? startWorkerWake(options.runtime.db) : null;
+    if (wake !== null) started.push(() => wake.stop());
+
     // `state` and `leader`, not the defaults. `createMemorySchedulerState` forgets every watermark
     // on restart, so a rolling deploy re-fires or skips whatever was due across it, and
     // `soleLeader()` makes every replica the leader — three `scheduler` pods, three of every task.
@@ -413,6 +428,8 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
         // and AWAITED, because a pass is a `driver.enqueue` followed by a `markPublished`. Dropped,
         // this returns between the two and the lines below close the pool under the row it was
         // about to mark: re-published next boot at best, a rejection against a closed pool at worst.
+        // The session first: a notification arriving after this wakes a loop that is about to stop.
+        await wake?.stop();
         await relay?.stop();
         await worker?.stop('x dev stopped');
         await sync?.stop();

package/src/role-wake.ts

@@ -0,0 +1,45 @@
+// The worker role's cross-process wake, and the one series that says whether it is PROVEN. The
+// mechanism is `@ultimat3/jobs`' (`startQueueWake`); this decides who holds the LISTEN session —
+// the worker, and only over a client that can listen — and publishes `queue_wake_live`, because a
+// transaction-pooling proxy disables the wake in silence and the poll hides that it did.
+
+import { gauge } from '@ultimat3/core';
+import type { DbClient } from '@ultimat3/db';
+import { canListen } from '@ultimat3/db';
+import type { QueueWake } from '@ultimat3/jobs';
+import { startQueueWake } from '@ultimat3/jobs';
+import { pgExecutorFor } from './runtime-queue';
+
+// The wake the gauge reads. One observer for the life of the process: a gauge redeclared with a
+// different `observe` is refused, and `x dev` starts the roles again on every restart-in-place.
+let current: QueueWake | undefined;
+let declared = false;
+
+const wakeLive = (): number => (current?.live() === true ? 1 : 0);
+
+/**
+ * Starts the wake for a worker, or answers `null` when the client cannot hold a session (a
+ * hand-built runtime): the claim loop and the relay then keep the poll they always had.
+ */
+export function startWorkerWake(db: DbClient): QueueWake | null {
+  if (!canListen(db)) return null;
+  if (!declared) {
+    declared = true;
+    gauge('queue_wake_live', {
+      unit: '1',
+      description:
+        '1 while a notification has crossed the worker LISTEN session, 0 while jobs start on the poll alone',
+      observe: wakeLive,
+    });
+  }
+  const wake = startQueueWake({ listener: db, executor: pgExecutorFor(db) });
+  current = wake;
+  return {
+    live: () => wake.live(),
+    async stop(): Promise<void> {
+      // Only the wake still published: a stop of one that was already replaced silences nothing.
+      if (current === wake) current = undefined;
+      await wake.stop();
+    },
+  };
+}