@ultimat3/cli 22.15.0 → 24.0.0

package/src/api-registration.ts

@@ -1,16 +1,19 @@
-// `x g job` / `x g task` / `x g resource` hand what they wrote to `apps/web/api/index.ts`. The scan
-// registers actions and queries by export name on its own and registers NO job: a job module
-// nothing lists keeps the positional `anonymous-job-2` that `job()` minted, on the queue row, in
+// Every generator hands the primitives it wrote to `apps/web/api/index.ts`. The scan registers
+// actions and queries by export name on its own and registers NO job: a job module nothing lists
+// keeps the positional `anonymous-job-2` that `job()` minted, on the queue row, in
 // `x.manifest.json` and in every dead-letter trace — under a green gate (plan 101 slice 11 b).
+// Actions and queries are listed for the TYPE: `Api` is what the browser's client is shaped from.
 
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { API_INDEX } from './app-root';
 import { containedPath } from './generate-write';
+import type { Finding } from './output';
 import { camel } from './templates/naming';
 import { wrapList } from './templates/wrap';
 
 /** One module to import as a namespace and list under a `defineApi` key. */
 export interface ApiEntry {
-  readonly key: 'jobs' | 'tasks';
+  readonly key: 'actions' | 'queries' | 'jobs' | 'tasks';
   /** The namespace binding: the file's own name, camelCased — `reindexPost`. */
   readonly binding: string;
   /** From `apps/web/api/`: `../app/post/jobs/reindex-post`. */
@@ -18,17 +21,37 @@ export interface ApiEntry {
 }
 
 const PRIMITIVE_PATH =
-  /^apps\/web\/(?<rest>[^/]+\/[^/]+\/(?<dir>jobs|tasks)\/(?<file>[a-z0-9-]+))\.ts$/;
+  /^apps\/web\/(?<rest>[^/]+\/[^/]+\/(?<dir>actions|queries|live|jobs|tasks)\/(?<file>[a-z0-9-]+))\.ts$/;
 
-/** The job and task modules among the paths a generator wrote. Tests are not modules to list. */
+/** The order `x new` writes the lists in, which a list this adds keeps. */
+const LIST_ORDER: readonly ApiEntry['key'][] = ['actions', 'queries', 'jobs', 'tasks'];
+
+/**
+ * The `defineApi` list each generated directory belongs in. `actions/` holds mutators too, and a
+ * mutator IS an action — `defineApi` merges both lists into one registration — so one key serves.
+ */
+const KEY_OF: Readonly<Record<string, ApiEntry['key']>> = {
+  actions: 'actions',
+  queries: 'queries',
+  live: 'queries',
+  jobs: 'jobs',
+  tasks: 'tasks',
+};
+
+/**
+ * The primitive modules among the paths a generator wrote. Tests are not modules to list.
+ *
+ * Actions and queries too, though the scan registers those at boot without being told: `Api` —
+ * the type the browser's typed client is shaped from — is `typeof defineApi({ … })`, so one the
+ * index does not list is an endpoint the page has no typed call for.
+ */
 export function apiEntriesFor(written: readonly string[]): readonly ApiEntry[] {
   return written.flatMap((path) => {
     const groups = PRIMITIVE_PATH.exec(path)?.groups;
     if (groups === undefined) return [];
     const { rest = '', dir, file = '' } = groups;
-    return [
-      { key: dir === 'tasks' ? 'tasks' : 'jobs', binding: camel(file), specifier: `../${rest}` },
-    ];
+    const key = dir !== undefined && Object.hasOwn(KEY_OF, dir) ? KEY_OF[dir] : undefined;
+    return key === undefined ? [] : [{ key, binding: camel(file), specifier: `../${rest}` }];
   });
 }
 
@@ -87,8 +110,12 @@ export function insertApiEntries(
     const list = listOf(next, entry.key, call);
     if (list?.items.includes(entry.binding) === true) continue;
     if (list === undefined) {
-      // After `actions: [...],` — the order `x new` writes: actions, queries, jobs, tasks.
-      const after = next.indexOf('\n', actions.end);
+      // In the order `x new` writes — actions, queries, jobs, tasks: after the nearest list
+      // before it that the call already holds, which is `actions` at the least.
+      const earlier = LIST_ORDER.slice(0, LIST_ORDER.indexOf(entry.key))
+        .map((key) => listOf(next, key, call))
+        .findLast((found) => found !== undefined);
+      const after = next.indexOf('\n', (earlier ?? actions).end);
       const line = `  ${entry.key}: [${entry.binding}],`;
       next = `${next.slice(0, after + 1)}${line}\n${next.slice(after + 1)}`;
     } else {
@@ -118,6 +145,93 @@ function withImport(source: string, importLine: string): string {
   return lines.join('\n');
 }
 
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+/** Every binding an import clause declares: `* as x`, `x`, `{ a, b as c, type d }`. */
+const clauseBindings = (clause: string): readonly string[] =>
+  clause
+    .replace(/^type\s+/, '')
+    .replace(/[{}]/g, ',')
+    .split(',')
+    .map((part) =>
+      part
+        .trim()
+        .replace(/^type\s+/, '')
+        .replace(/^\*\s+as\s+/, ''),
+    )
+    .map(
+      (part) =>
+        part
+          .split(/\s+as\s+/)
+          .at(-1)
+          ?.trim() ?? '',
+    )
+    .filter((name) => IDENTIFIER.test(name));
+
+/**
+ * Every top-level name the index declares, and what holds it: a namespace import by its
+ * specifier, anything else (`defineApi`, `api`, `Api`, a named import) by its own name. A second
+ * binding of any of them is a module that does not load — `import * as api` beside
+ * `export const api` is a ReferenceError in every app-loading command.
+ */
+function declaredBindings(source: string): ReadonlyMap<string, string> {
+  const held = new Map<string, string>();
+  for (const found of source.matchAll(/^import\s+([^;]*?)\s+from\s+'([^']+)';/gm)) {
+    const [, clause = '', specifier = ''] = found;
+    const namespace = /^\*\s+as\s+([A-Za-z_$][\w$]*)$/.exec(clause.trim())?.[1];
+    if (namespace !== undefined) held.set(namespace, specifier);
+    else for (const name of clauseBindings(clause)) held.set(name, `an import from ${specifier}`);
+  }
+  const declaration =
+    /^(?:export\s+)?(?:declare\s+)?(?:const|let|var|function\*?|class|type|interface|enum)\s+([A-Za-z_$][\w$]*)/gm;
+  for (const found of source.matchAll(declaration)) {
+    const [, name = ''] = found;
+    if (!held.has(name)) held.set(name, `the index's own ${name}`);
+  }
+  return held;
+}
+
+/**
+ * A written primitive whose namespace binding the index already holds — for another module, or as
+ * one of its own names — is a finding, decided BEFORE anything is written. Skipped silently, the
+ * job stayed unregistered under a green run; inserted, the index stopped loading.
+ */
+export function apiBindingFindings(
+  source: string,
+  written: readonly string[],
+  fix: string,
+): readonly Finding[] {
+  const held = new Map(declaredBindings(source));
+  const findings: Finding[] = [];
+  for (const entry of apiEntriesFor(written)) {
+    const holder = held.get(entry.binding);
+    if (holder === entry.specifier) continue;
+    if (holder === undefined) {
+      held.set(entry.binding, entry.specifier);
+      continue;
+    }
+    findings.push({
+      code: 'X_GENERATE_CONFLICT',
+      cause: `${API_INDEX} binds every listed module under its file name, and "${entry.binding}" is already ${holder.startsWith('.') ? `the namespace of ${holder}` : holder} — ${entry.specifier} cannot be listed under it`,
+      fix,
+      docs: ERROR_DOCS_URL,
+      at: API_INDEX,
+    });
+  }
+  return findings;
+}
+
+/** `apiBindingFindings` against the app's own index; none when the app has no index. */
+export async function indexBindingFindings(
+  root: string,
+  written: readonly string[],
+  fix: string,
+): Promise<readonly Finding[]> {
+  const file = containedPath(root, API_INDEX);
+  if (!(await Bun.file(file).exists())) return [];
+  return apiBindingFindings(await Bun.file(file).text(), written, fix);
+}
+
 /** Performs `insertApiEntries` on the app's index. Answers the paths it rewrote. */
 export async function registerGeneratedPrimitives(
   root: string,

package/src/app-artifacts.ts

@@ -1,6 +1,6 @@
 // The two generated contracts an app commits — `x.manifest.json` and `openapi.json` — written by one
 // function, because two commands wrote them and only one wrote both: `x g` refreshed the manifest
-// and left `openapi.json` behind, so its own output failed the `contract-diff` step next.
+// and left `openapi.json` behind, so its own output failed the gate's `manifest` step next.
 
 import { join } from 'node:path'; // why: Bun ships no path-join primitive.
 import type { Manifest } from '@ultimat3/manifest';

package/src/app-auth.ts

@@ -1,32 +1,9 @@
 // The one fact `x dev` and `serve.ts` need out of `app.config.ts` before a listener binds: where
-// this app's sign-in page is. Sibling of `app-env.ts`'s `loadEnvSchema`, and imports the config
-// for the same reason — a regex over the app's source is the pattern `app-load.ts` refuses.
+// this app's sign-in page is, off the one loader (`app-config-load.ts`).
 
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 
-/** The export every app declares. Named, never default — the CLI and the runtime both import it. */
-export const APP_CONFIG_EXPORT = 'config';
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-/**
- * `auth.signInPath`, or `null` when the app declares none.
- *
- * Structural, not `instanceof`: `defineConfig` returns a plain object, and a config that resolved
- * through an older version of core simply has no `auth` section. `null` is the safe answer either
- * way — it is what turns the browser redirect off and leaves the problem document in place.
- */
+/** `auth.signInPath`, or `null` when the app declares none or the root has no config file. */
 export async function loadSignInPath(root: string): Promise<string | null> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!existsSync(configPath)) return null;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!isRecord(config)) return null;
-  const auth = config['auth'];
-  if (!isRecord(auth)) return null;
-  const path = auth['signInPath'];
-  return typeof path === 'string' && path.startsWith('/') ? path : null;
+  return (await loadAppConfig(root))?.auth.signInPath ?? null;
 }

package/src/app-boundaries.ts

@@ -9,6 +9,10 @@
 // Runtime imports only: `Bun.Transpiler.scanImports` sees what survives type erasure, which is
 // exactly the distinction the `app/ -> api/` rule needs (`import type` is allowed, a value
 // import is not).
+//
+// The browser-transport rule rides the same read: `boundary-findings.ts`'s `appBoundaryFindings`
+// hands the files read here to `app-transport.ts`, so a raw `fetch(` in an island is a finding of
+// this step with no second walk of the app.
 
 // Bun ships no `Bun.*` path API: `joinPath` reaches a file on disk with the host's separator.
 import { join as joinPath } from 'node:path';
@@ -17,6 +21,7 @@ import { dirname, join, normalize, relative } from 'node:path/posix';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { BoundaryRule, ImportGraph } from '@ultimat3/render';
 import { checkSurfaceBoundary, importGraph, SURFACES } from '@ultimat3/render';
+import { commentSafe } from './comment-safe';
 import { scanRuntimeImports, stripShebang } from './import-scan';
 import type { Finding } from './output';
 import { hasPathSegment } from './path-segments';
@@ -156,20 +161,6 @@ function subjectOf(path: string): string | undefined {
   return parent === undefined || SURFACE_NAMES.has(parent) ? undefined : parent;
 }
 
-/**
- * Control characters, `\u00xx`-escaped. The path is a value read off the repository being scanned,
- * and it rides in a `#` comment: a directory holding a NEWLINE ends that comment, so everything
- * after it is a second command in a line whose whole purpose is to be pasted into a shell.
- * Escaped rather than deleted, because the comment still has to name the file the reader owns.
- */
-const commentSafe = (path: string): string =>
-  [...path]
-    .map((char) => {
-      const code = char.codePointAt(0) ?? 0;
-      return code < 0x20 || code === 0x7f ? `\\u${code.toString(16).padStart(4, '0')}` : char;
-    })
-    .join('');
-
 /**
  * `x g query posts` where the path names a resource, `x g query <name>` where it names a surface.
  * The placeholder form is the shape `MissingPositionalError` already hands out (`x g route
@@ -233,7 +224,7 @@ const APP_GLOBS = ['apps/*/{site,app,api,shared}/**/*.{ts,tsx}'];
 /**
  * Read every source file under an app's site, app, api and shared surfaces (`APP_GLOBS`). The
  * only I/O in this module, and the one definition of "which files are the app's sources" —
- * `checkAppBoundaries` reads through this, and so does `x fix boundary`, never a second glob.
+ * `appBoundaryFindings` reads through this, and so does `x fix boundary`, never a second glob.
  */
 export async function readAppSources(root: string): Promise<readonly SourceFile[]> {
   const files: SourceFile[] = [];
@@ -252,8 +243,3 @@ export async function readAppSources(root: string): Promise<readonly SourceFile[
 export function appImportGraph(files: readonly SourceFile[]): ImportGraph {
   return graphOf(scan(files));
 }
-
-/** Read an app's sources and check them. */
-export async function checkAppBoundaries(root: string): Promise<readonly Finding[]> {
-  return checkImportRules(await readAppSources(root));
-}

package/src/app-config-load.ts

@@ -0,0 +1,51 @@
+// The one reader of an app's `app.config.ts`: imported here and nowhere else in the tree
+// (`bun run boundaries`, `X_CONFIG_IMPORT_OUTSIDE_LOADER`), its `config` export handed back through
+// core's own `defineConfig` — so every boot fact the CLI reads is the validated, default-merged
+// `AppConfig`, never a structural walk with a fallback of its own.
+
+// why: Bun exposes no path-join primitive, and the config path is app-root-relative.
+import { join } from 'node:path';
+import type { AppConfig, AppConfigInput } from '@ultimat3/core';
+import { ConfigInvalidError, defineConfig, describeValue } from '@ultimat3/core';
+import { APP_CONFIG_FILE } from './app-root';
+
+/** The export every app declares. Named, never default — the CLI and the runtime both import it. */
+export const APP_CONFIG_EXPORT = 'config';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * One named export of `root`'s `app.config.ts`, or `undefined` when the root has no such file or
+ * the module does not export `name`. A module that will not import throws as it did — the callers
+ * that report rather than crash (`x doctor`'s env check) turn that into a finding.
+ */
+export async function appConfigExport(root: string, name: string): Promise<unknown> {
+  const path = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(path).exists())) return undefined;
+  const module = (await import(path)) as Record<string, unknown>;
+  return Object.hasOwn(module, name) ? module[name] : undefined;
+}
+
+/**
+ * `root`'s `AppConfig`, or `undefined` when the root has no `app.config.ts` — not an app, and each
+ * caller's "nothing declared" answer is its own. A file that IS there is held to `defineConfig`'s
+ * one validator: a hand-built `config` object, or one resolved through an older core, reaches the
+ * boot validated and defaulted exactly as one built by `defineConfig` does, which re-merges to
+ * itself. A file with no `config` object is refused rather than read as "every default".
+ */
+export async function loadAppConfig(root: string): Promise<AppConfig | undefined> {
+  const path = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(path).exists())) return undefined;
+  const exported = await appConfigExport(root, APP_CONFIG_EXPORT);
+  if (!isRecord(exported)) {
+    throw new ConfigInvalidError({
+      cause: `${path} exports no ${APP_CONFIG_EXPORT} object (${describeValue(exported)})`,
+      fix: "export const config = defineConfig({ name: 'my-app' });",
+      meta: { key: APP_CONFIG_EXPORT },
+    });
+  }
+  // A cast over a record whose structure `defineConfig` screens first (`shapeIssues`, per layer):
+  // the validator IS the parse, and a second hand-written schema here would be a second answer.
+  return defineConfig(exported as unknown as AppConfigInput);
+}

package/src/app-env.ts

@@ -2,8 +2,6 @@
 // `app.config.ts`, the `.env.example` projected from it, and the drift between the two. One
 // declaration, both files (axiom 2) — nothing here holds a second list of variable names.
 
-// why: Bun ships no synchronous exists; `existsSync` answers whether this root is an app.
-import { existsSync } from 'node:fs';
 // why: Bun exposes no path API — the two files this module reads are joined to the app root.
 import { join } from 'node:path';
 import type { EnvSchema, EnvVarDecl } from '@ultimat3/core';
@@ -13,6 +11,7 @@ import {
   ERROR_DOCS_URL,
   renderEnvExample,
 } from '@ultimat3/core';
+import { appConfigExport } from './app-config-load';
 import { APP_CONFIG_FILE } from './app-root';
 import type { Finding } from './output';
 import { findingFrom } from './output';
@@ -45,17 +44,12 @@ export const isEnvSchema = (value: unknown): value is EnvSchema =>
   isRecord(value) && Object.values(value).every(isDecl);
 
 /**
- * Import `app.config.ts` and hand back the declaration it exports. Importing is the only honest
- * way to read it — the alternative is a regex over the app's source, which is the pattern
- * `app-load.ts` exists to refuse. `undefined` means "this root declares no environment"; a config
- * that will not import throws, and the caller turns that into the finding.
+ * The declaration `app.config.ts` exports, through the one loader (`app-config-load.ts`).
+ * `undefined` means "this root declares no environment"; a config that will not import throws, and
+ * the caller turns that into the finding.
  */
 export async function loadEnvSchema(root: string): Promise<EnvSchema | undefined> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!existsSync(configPath)) return undefined;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const declared = module[ENV_SCHEMA_EXPORT];
-  if (declared === undefined) return undefined;
+  const declared = await appConfigExport(root, ENV_SCHEMA_EXPORT);
   return isEnvSchema(declared) ? declared : undefined;
 }
 

package/src/app-load.ts

@@ -151,7 +151,31 @@ export async function appModulePaths(root: string): Promise<readonly string[]> {
   return found.includes(index) ? [index, ...found.filter((path) => path !== index)] : found;
 }
 
-export async function loadApp(root: string): Promise<LoadedApp> {
+/** What one scan of the app's modules imported, and what would not. */
+export interface AppScan {
+  /** App-root-relative POSIX paths of every module that imported, sorted. */
+  readonly files: readonly string[];
+  /** Modules that would not import, and primitives that would not register. */
+  readonly findings: readonly Finding[];
+}
+
+export interface ScanOptions {
+  /**
+   * Records each module's bytes and pins so a LATER scan can evict what changed: a tool's and
+   * `x dev`'s. A container scans once per process, so its boot passes `false` and neither reads a
+   * module before importing it nor hashes one (`role-load.ts`).
+   */
+  readonly track: boolean;
+  /** `false` leaves a module out: neither read nor imported. Absent: every module is imported. */
+  readonly include?: (absolute: string) => boolean | Promise<boolean>;
+}
+
+/**
+ * The scan itself: every app module `options.include` admits, imported in `appModulePaths` order
+ * and registered. `loadApp` is this plus the facts a tool reads; a container role calls it through
+ * `loadAppForRole`, which decides what the role imports.
+ */
+export async function scanAppModules(root: string, options: ScanOptions): Promise<AppScan> {
   // Before any import: a stylesheet's surface is read below the app root, never off its absolute
   // path — under the container's `WORKDIR /app` that path's first segment is `app/`, and every
   // sheet, the site's included, classified as app CSS.
@@ -164,7 +188,7 @@ export async function loadApp(root: string): Promise<LoadedApp> {
   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);
+  if (options.track && registered.size > 0) await evictChanged(root);
 
   for (const absolute of await appModulePaths(root)) {
     // A SEGMENT, never a substring: an app checked out under
@@ -177,15 +201,19 @@ export async function loadApp(root: string): Promise<LoadedApp> {
     if (ENTRY_POINT.test(file) || CLIENT_ENTRY_POINT.test(file) || STATES_FILE.test(file)) {
       continue;
     }
+    if (options.include !== undefined && !(await options.include(absolute))) continue;
     // 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.
+    // re-import the next tick, of a file that did change. An untracked scan reads nothing here:
+    // no save lands in an image, so a route module's text is read after its import, once.
     const first = !registered.has(absolute) && !failures.has(absolute);
     const snapshot =
-      first || routeModules.has(absolute) ? await Bun.file(absolute).text() : undefined;
+      options.track && (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 {
@@ -195,16 +223,26 @@ export async function loadApp(root: string): Promise<LoadedApp> {
       continue;
     }
     files.push(file);
-    const finding = await register(absolute, file, module, snapshot);
+    const finding = await register(absolute, file, module, snapshot, options.track);
     if (finding !== undefined) findings.push(finding);
   }
 
   files.sort();
+  return { files, findings };
+}
+
+export async function loadApp(root: string): Promise<LoadedApp> {
+  const scan = await scanAppModules(root, { track: true });
+  // After the scan, because the scan is what mounts an admin: a declaration the globs above cannot
+  // reach is a finding here, owned by `manifest` like every other load finding. Imported here, not
+  // at the top: a container boots through `scanAppModules` and never asks (`serve-graph.test.ts`).
+  const { unscannedAdminFindings } = await import('./unscanned-admin');
+  const findings = [...scan.findings, ...(await unscannedAdminFindings(root))];
   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 (
-    files.length === 0 &&
+    scan.files.length === 0 &&
     findings.length === 0 &&
     registersNothing() &&
     (await Bun.file(join(root, APP_CONFIG_FILE)).exists())
@@ -214,7 +252,7 @@ export async function loadApp(root: string): Promise<LoadedApp> {
   // Read after the loop, never before it: `configureLocales` runs on the app's own import.
   return {
     root,
-    files,
+    files: scan.files,
     errorCodes: await appErrorCodes(root),
     defaultLocale: localeConfig().fallback,
     findings,
@@ -240,13 +278,15 @@ 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 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.
+ * `snapshot` is the source read before this import: always for a first pass and a route module of
+ * a TRACKED scan. An untracked one hands none, and a route module's text is read here instead.
  */
 async function register(
   absolute: string,
   file: string,
   module: Record<string, unknown>,
   snapshot: string | undefined,
+  track: boolean,
 ): Promise<Finding | undefined> {
   const previous = failures.get(absolute);
   if (previous !== undefined) return previous;
@@ -255,11 +295,15 @@ async function register(
   try {
     const config = module['config'];
     const route = isRouteConfig(config) ? config : undefined;
-    if (route !== undefined && snapshot !== undefined) {
-      registerRouteModule(file, module, route, snapshot);
+    if (route !== undefined) {
+      registerRouteModule(file, module, route, snapshot ?? (await Bun.file(absolute).text()));
       routeModules.set(absolute, module);
     }
-    if (definesPrimitive(module, route !== undefined) || file === API_INDEX) pinModule(absolute);
+    // A pin is the reload graph's: it stops an eviction a process that never rescans never runs,
+    // and deciding it walks every export of every module against the entity registry.
+    if (track && (definesPrimitive(module, route !== undefined) || file === API_INDEX)) {
+      pinModule(absolute);
+    }
     registerActions(module);
     registerQueries(module);
     return undefined;

package/src/app-manifest.ts

@@ -6,8 +6,10 @@
 // Bun ships no `Bun.*` path API: `join` builds the host-separator path to `x.manifest.json`.
 import { join } from 'node:path';
 import { describeActions } from '@ultimat3/action';
+import { primitiveRegistrar } from '@ultimat3/core';
 import { registeredLocales } from '@ultimat3/i18n';
 import { registeredTasks } from '@ultimat3/jobs';
+import { sendMailJob } from '@ultimat3/mail';
 import type { Manifest, PolicyFact, RouteFact, TaskFact } from '@ultimat3/manifest';
 import {
   buildManifest,
@@ -30,9 +32,21 @@ export interface AppManifest {
   readonly findings: readonly Finding[];
 }
 
+/**
+ * The jobs every role process registers whatever the app imports: `runtime-services.ts` imports
+ * `@ultimat3/mail` in every role, and that import declares `mail.send` — so every app's worker
+ * runs it, and the manifest records it. Seated here rather than left to an import's side effect:
+ * `x manifest`'s module graph never reached the mail barrel and `x verify`'s did, so the same app
+ * got two job lists and the `fix:` of `X_MANIFEST_DRIFT` could never clear it.
+ */
+const RUNTIME_JOBS: Readonly<Record<string, unknown>> = { sendMailJob };
+
 /** Load the app, then describe it. Every command that needs facts goes through here. */
 export async function appManifest(root: string): Promise<AppManifest> {
   const loaded = await loadApp(root);
+  // Through the registrar `defineApi` uses (`define-api.ts`): the declared name wins, and the
+  // same handle seated twice is one registration, so a second build of one tree is unchanged.
+  primitiveRegistrar('job')(RUNTIME_JOBS);
   const manifest = buildManifest(
     frameworkSources({
       app: await appIdentity(root),
@@ -103,14 +117,8 @@ const routeFacts = (): readonly RouteFact[] =>
       ...budgetOf(route),
     }));
 
-function budgetOf(route: RouteDescriptor): { budget?: { js?: string; lcp?: number } } {
-  if (route.budgetJs === null && route.budgetLcp === null) return {};
-  return {
-    budget: {
-      ...(route.budgetJs === null ? {} : { js: route.budgetJs }),
-      ...(route.budgetLcp === null ? {} : { lcp: route.budgetLcp }),
-    },
-  };
+function budgetOf(route: RouteDescriptor): { budget?: { js: string } } {
+  return route.budgetJs === null ? {} : { budget: { js: route.budgetJs } };
 }
 
 /**

package/src/app-mcp.ts

@@ -9,7 +9,7 @@
 
 // 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.
+// why: Bun exposes no path-join primitive; each candidate is joined to root.
 import { join } from 'node:path';
 import { logger } from '@ultimat3/core';
 import type { Route } from '@ultimat3/http';
@@ -20,8 +20,7 @@ import {
   McpPathDuplicateError,
   PROTECTED_RESOURCE_WELL_KNOWN,
 } from '@ultimat3/mcp';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 
 /** The one file an app writes, per app directory. */
 export const APP_MCP_GLOB = 'apps/*/mcp.ts';
@@ -57,26 +56,9 @@ interface ExposeDeclaration {
 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.
- */
+/** `config.ai.mcp` off the one loader (`app-config-load.ts`); nothing exposed with no config file. */
 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',
-  };
+  return (await loadAppConfig(root))?.ai.mcp;
 }
 
 const isAppMcp = (value: unknown): value is AppMcp =>
@@ -213,8 +195,13 @@ function endpointRoutes(route: Descriptor, path: string, index: number): readonl
       // The PUBLIC origin, as the pipeline resolved it (`ctx.https` honours a trusted proxy's
       // `x-forwarded-proto`): behind a TLS-terminating ingress the raw request URL is `http://`
       // on an internal host, and a `resource_metadata` naming that is a URL no client can reach.
+      // The client ADDRESS likewise: failed tokens are metered per address, and the descriptor
+      // has no other way to learn it.
       handler: (request, ctx) =>
-        route.handle(request.raw, { origin: selfOrigin(ctx.url, ctx.https) }),
+        route.handle(request.raw, {
+          origin: selfOrigin(ctx.url, ctx.https),
+          address: ctx.ip ?? undefined,
+        }),
       meta: { name, auth: 'public', enforcedBy: 'handler' },
     },
     ...metadata,