@ultimat3/cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# @ultimat3/cli
+
+The `x` binary. One char during dev, one command per job, `--json` on every one of them.
+
+## What it owns
+
+Commands and the `x verify` step count, `As of 2026-08`:
+
+| Command | Does | Notes |
+|---|---|---|
+| `x new <name>` | scaffolds the monorepo | interactive-free; auth, seeded DB, example route |
+| `x dev` | every role in one process | embedded Postgres/events/storage, `/_x` mounted |
+| `x build --target docker\|binary\|static` | one artifact | `ROLE` selects behaviour at start |
+| `x verify` | **the gate** | 16 named steps, each with pass/fail + duration |
+| `x g <primitive> <name>` | scaffolds a primitive **with a passing test** | never a TODO stub |
+| `x db gen\|migrate\|reset\|studio\|branch` | everything DB | `branch` = copy-on-write clone + preview URL |
+| `x mcp serve` | `@ultimat3/mcp`'s 13 dev tools, over stdio or HTTP | one catalog, one scope set, both transports |
+| `x doctor` | environment, ports, drift, PWA prerequisites | every finding carries a fix command |
+| `x deploy` | container deploy plan | compose or helm; zero platform primitives |
+| `x manifest` / `x routes` | generated facts | `x.manifest.json`, `openapi.json`, route table |
+| `x actions` / `x queries` / `x entities` | the declaration registries | `list` and `describe <name>`, straight off the registries |
+| `x jobs ls\|show\|retry\|drain` | the queue | depth, dead letters, step traces, `retry --from-step`, `drain --to` |
+| `x test [type]` | one of the six test types, or all | same type rule as the gate; `--filter`, `--sample N` |
+| `x errors explain <CODE>` | the error table, programmatically | refuses an unregistered code instead of inventing one |
+| `x fix boundary <file>` | the minimal cut for a crossed surface boundary | prints the plan and the `git mv`; never rewrites a file |
+
+Everything in [CLI reference](../../wiki/CLI-Reference.md)'s planned table is also in the registry
+and exits `X_NOT_IMPLEMENTED` with a `fix:` naming the closest shipped command — "not built yet"
+and "not a command" are different facts.
+
+## The output contract
+
+Every command returns one `CommandResult`; the human renderer and the JSON renderer are
+projections of it, so `--json` can never drift from the terminal.
+
+```
+X_DB_DRIFT: schema differs from migrations
+  cause: table "posts" has column "publish_at" not present in any migration
+  fix:   x db gen "add publish_at"
+```
+
+```sh
+x verify --json
+# {"ok":false,"command":"verify","summary":"1 of 16 steps failed","steps":[...]}
+```
+
+## `x verify` steps
+
+`typecheck lint boundaries filesize package-shape errors unit contract live job e2e eval drift
+contract-diff budgets manifest`
+
+One list, in cost order, defined once in `cmd-verify.ts` — the framework repo's own gate
+(`bun run verify`) runs exactly it. A step with nothing to check here reports as skipped, never as
+passed. Never bails early: an agent fixing three things needs all three findings from one run.
+There is no `--only` and no `--skip`; the exit code is non-zero if any step fails.
+
+## Layout
+
+| File | Responsibility |
+|---|---|
+| `bin.ts` | argv, stdout, exit code — nothing else |
+| `dispatch.ts` | parse → run → render → exit; the only I/O boundary |
+| `parse.ts` | flags, subcommands, `--json`, `--help`, suggestions |
+| `output.ts` | one data shape, two renderers, the 3-line error format |
+| `registry.ts` | the one command list |
+| `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-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 |
+| `app-agents-md.ts` | `AGENTS.md` exists and stays short, over `@ultimat3/manifest`'s check |
+| `dev-*.ts` | what `x dev` boots: services, runtime, routes, hooks, roles, the `/_x` mount |
+| `mcp-host.ts` | the shell-side half of `@ultimat3/mcp`'s dev server — db, tests, logs, verify |
+| `verify-step.ts` | the step shape, the step names, the host-check hook |
+| `verify-tests.ts` | one `bun test` invocation per test type |
+| `workspace-checks.ts` | file-size ceiling and package contract files |
+| `drift.ts` `budgets.ts` | the checks `x verify` composes |
+
+The CLI describes an app by **loading** it, never by parsing it: `action()`, `entity()`,
+`job()` and `defineRoute()` register themselves, and `x manifest`, `x routes` and `x verify`
+read the same tables the running server reads. There is no second definition of a primitive,
+no second OpenAPI builder and no second surface-boundary walk anywhere in this package.
+
+## Generated file layout
+
+`x g` writes into the feature slice:
+
+```
+apps/web/app/<feature>/{entity,repo,service,policy,errors,ui}.ts
+apps/web/app/<feature>/{actions,queries,live,jobs,tasks}/<name>.ts
+apps/web/{site,app}/<path>/page.tsx
+```
+
+Every emitted source has a `<file>.test.ts` beside it that passes on the first run.
+
+## Errors
+
+`X_CLI_UNKNOWN_COMMAND` `X_CLI_BAD_FLAG` `X_VERIFY_FAILED` `X_NOT_IN_APP` `X_BUN_VERSION`
+`X_NOT_IMPLEMENTED`

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@ultimat3/cli",
+  "version": "1.0.0",
+  "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "x": "./src/bin.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test",
+    "dev": "bun run src/bin.ts dev"
+  },
+  "dependencies": {
+    "@ultimat3/action": "1.0.0",
+    "@ultimat3/admin": "1.0.0",
+    "@ultimat3/ai": "1.0.0",
+    "@ultimat3/cache": "1.0.0",
+    "@ultimat3/core": "1.0.0",
+    "@ultimat3/db": "1.0.0",
+    "@ultimat3/entity": "1.0.0",
+    "@ultimat3/http": "1.0.0",
+    "@ultimat3/i18n": "1.0.0",
+    "@ultimat3/jobs": "1.0.0",
+    "@ultimat3/mail": "1.0.0",
+    "@ultimat3/manifest": "1.0.0",
+    "@ultimat3/mcp": "1.0.0",
+    "@ultimat3/policy": "1.0.0",
+    "@ultimat3/pwa": "1.0.0",
+    "@ultimat3/query": "1.0.0",
+    "@ultimat3/realtime": "1.0.0",
+    "@ultimat3/render": "1.0.0",
+    "@ultimat3/seo": "1.0.0",
+    "@ultimat3/storage": "1.0.0",
+    "@ultimat3/testing": "1.0.0",
+    "@ultimat3/time": "1.0.0"
+  }
+}

package/src/app-agents-md.ts

@@ -0,0 +1,27 @@
+// The hand-written half of what an agent reads. `@ultimat3/manifest` owns both context files —
+// `x.manifest.json` carries the facts derived from code, `AGENTS.md` the conventions code cannot
+// express — so the gate runs that package's own check rather than forming a second opinion about
+// what a context file has to be. Warnings never fail: they are judgement calls a human makes.
+
+// Bun ships no `Bun.*` path API: `join` builds the host-separator path the check reads.
+import { join } from 'node:path';
+import { AGENTS_MD_FILENAME, assertAgentsMd } from '@ultimat3/manifest';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+export interface AgentsMdOutcome {
+  readonly findings: readonly Finding[];
+  /** Non-fatal observations, carried into `--json` so a human can judge them. */
+  readonly warnings: readonly string[];
+}
+
+/** `assertAgentsMd` throws `X_AGENTS_MD_*`; a gate step reports, so the error becomes a finding. */
+export async function checkAgentsMd(root: string): Promise<AgentsMdOutcome> {
+  const path = join(root, AGENTS_MD_FILENAME);
+  try {
+    const { warnings } = await assertAgentsMd({ path });
+    return { findings: [], warnings };
+  } catch (error) {
+    return { findings: [{ ...findingFrom(error), at: AGENTS_MD_FILENAME }], warnings: [] };
+  }
+}

package/src/app-boundaries.ts

@@ -0,0 +1,206 @@
+// App-level import boundaries: the rules that keep the static path from paying for the app path
+// (axiom 6) and keep layers from collapsing into each other.
+//
+// The three surface rules are `@ultimat3/render`'s `checkSurfaceBoundary` — the same check the
+// build runs, transitive, naming the whole chain. The two layer rules below stay here because no
+// package owns them: `service.ts` is not a primitive, and a route's ban on the database is about
+// app layout, not about rendering.
+//
+// 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).
+
+// Bun ships no `Bun.*` path API: `joinPath` reaches a file on disk with the host's separator.
+import { join as joinPath } from 'node:path';
+// The POSIX variants resolve specifiers against import-graph keys, which are POSIX on every host.
+import { dirname, join, normalize, relative } from 'node:path/posix';
+import type { BoundaryRule, ImportGraph } from '@ultimat3/render';
+import { checkSurfaceBoundary, importGraph } from '@ultimat3/render';
+import type { Finding } from './output';
+
+export const BOUNDARY_CODES = [
+  'X_BOUNDARY_SITE_TO_APP',
+  'X_BOUNDARY_SHARED_LEAF',
+  'X_BOUNDARY_APP_TO_API',
+  'X_BOUNDARY_ROUTE_TO_DB',
+  'X_BOUNDARY_SERVICE_TO_HTTP',
+] as const;
+
+export type BoundaryCode = (typeof BOUNDARY_CODES)[number];
+
+export interface SourceFile {
+  /** POSIX path relative to the app root, e.g. `apps/web/site/pricing/page.tsx`. */
+  readonly path: string;
+  readonly source: string;
+}
+
+const CODE_OF: Readonly<Record<BoundaryRule, BoundaryCode>> = {
+  'site-imports-app': 'X_BOUNDARY_SITE_TO_APP',
+  'shared-is-a-leaf': 'X_BOUNDARY_SHARED_LEAF',
+  'app-imports-api-at-runtime': 'X_BOUNDARY_APP_TO_API',
+};
+
+/**
+ * The one rule → diagnostic-code mapping. `x verify` reports a surface violation as a finding and
+ * `x fix boundary` re-reports the same violation as a cut; a second copy of this table is the two
+ * commands drifting onto different codes for one edge.
+ */
+export const boundaryCodeOf = (rule: BoundaryRule): BoundaryCode => CODE_OF[rule];
+
+const docs = (code: BoundaryCode): string => `https://ultimate.dev/errors/${code}`;
+
+const isRoute = (path: string): boolean => /\/(page|layout|route)\.[cm]?tsx?$/.test(path);
+const isService = (path: string): boolean => /\/service\.[cm]?ts$/.test(path);
+const isDbSpecifier = (specifier: string): boolean =>
+  /(^|\/)packages\/db($|\/)/.test(specifier) ||
+  specifier.endsWith('/db') ||
+  /^@[^/]+\/db$/.test(specifier) ||
+  specifier === 'drizzle-orm';
+const isHttpSpecifier = (specifier: string): boolean =>
+  specifier === '@ultimat3/http' || /(^|\/)http($|\/)/.test(specifier);
+
+/** The transpiler rejects a shebang, and an app's `bin/` entry points legitimately have one. */
+export const stripShebang = (source: string): string =>
+  source.startsWith('#!') ? source.slice(source.indexOf('\n') + 1) : source;
+
+/** Bun's transpiler is the parser; a regex fallback would miss re-exports and dynamic imports. */
+export function scanRuntimeImports(file: SourceFile): readonly string[] {
+  const loader = file.path.endsWith('x') ? 'tsx' : 'ts';
+  const transpiler = new Bun.Transpiler({ loader });
+  return transpiler.scanImports(stripShebang(file.source)).map((entry) => entry.path);
+}
+
+const CANDIDATE_SUFFIXES = ['', '.ts', '.tsx', '/index.ts', '/index.tsx'] as const;
+
+/**
+ * Resolve a relative specifier onto a real graph key. Extensions matter here and only here: an
+ * edge that does not land on a key is a dead end, and the transitive walk stops one hop short.
+ */
+export function resolveSpecifier(
+  fromFile: string,
+  specifier: string,
+  keys: ReadonlySet<string>,
+): string {
+  if (!specifier.startsWith('.')) return specifier;
+  const base = normalize(join(dirname(fromFile), specifier));
+  for (const suffix of CANDIDATE_SUFFIXES) {
+    if (keys.has(`${base}${suffix}`)) return `${base}${suffix}`;
+  }
+  return base;
+}
+
+/**
+ * The specifier `fromFile` must write to reach `target` — `resolveSpecifier` run backwards, and
+ * what every import of a file has to become once that file moves. Extensionless, because that is
+ * the form `CANDIDATE_SUFFIXES` resolves and the form every app source already writes.
+ */
+export function relativeSpecifier(fromFile: string, target: string): string {
+  const path = relative(dirname(fromFile), target).replace(/\.[cm]?tsx?$/, '');
+  return path.startsWith('.') ? path : `./${path}`;
+}
+
+interface ScannedFile {
+  readonly path: string;
+  readonly imports: readonly string[];
+}
+
+function scan(files: readonly SourceFile[]): readonly ScannedFile[] {
+  const keys = new Set(files.map((file) => file.path));
+  return files.map((file) => ({
+    path: file.path,
+    imports: scanRuntimeImports(file).map((specifier) =>
+      resolveSpecifier(file.path, specifier, keys),
+    ),
+  }));
+}
+
+function graphOf(scanned: readonly ScannedFile[]): ImportGraph {
+  const record: Record<string, readonly string[]> = {};
+  for (const file of scanned) record[file.path] = file.imports;
+  return importGraph(record);
+}
+
+const surfaceFindings = (graph: ImportGraph): readonly Finding[] =>
+  checkSurfaceBoundary(graph).map((violation) => {
+    const code = boundaryCodeOf(violation.rule);
+    return {
+      code,
+      cause: violation.cause,
+      fix: violation.fix,
+      docs: docs(code),
+      at: violation.importer,
+    };
+  });
+
+/** `apps/web/app/posts/service.ts` → `posts`: the primitive a generator would be told to make. */
+const subjectOf = (path: string, fallback: string): string => path.split('/').at(-2) ?? fallback;
+
+/**
+ * Both fixes are one runnable line, with the rest of the instruction behind a `#` — a fix a
+ * caller has to edit before it runs is prose, and prose is what "errors are instructions" bans.
+ */
+function layerFindings(scanned: readonly ScannedFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of scanned) {
+    for (const specifier of file.imports) {
+      if (isRoute(file.path) && isDbSpecifier(specifier)) {
+        findings.push({
+          code: 'X_BOUNDARY_ROUTE_TO_DB',
+          cause: `route imports the database ("${specifier}") — routes call actions and queries`,
+          fix: `x g query ${subjectOf(file.path, 'rows')}   # then call it from the route`,
+          docs: docs('X_BOUNDARY_ROUTE_TO_DB'),
+          at: file.path,
+        });
+      }
+      if (isService(file.path) && isHttpSpecifier(specifier)) {
+        findings.push({
+          code: 'X_BOUNDARY_SERVICE_TO_HTTP',
+          cause: `service imports HTTP ("${specifier}") — a service that knows about requests cannot be reused by a job`,
+          fix: `x g action ${subjectOf(file.path, 'service')}   # read the request there, pass the service plain values`,
+          docs: docs('X_BOUNDARY_SERVICE_TO_HTTP'),
+          at: file.path,
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * Check every app source file against both rule sets. Pure — callers do the I/O — so the dev
+ * server can run this on every save and `x verify` can run it over a full file list.
+ */
+export function checkImportRules(files: readonly SourceFile[]): readonly Finding[] {
+  const scanned = scan(files);
+  return [...surfaceFindings(graphOf(scanned)), ...layerFindings(scanned)];
+}
+
+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.
+ */
+export async function readAppSources(root: string): Promise<readonly SourceFile[]> {
+  const files: SourceFile[] = [];
+  for (const pattern of APP_GLOBS) {
+    const glob = new Bun.Glob(pattern);
+    for await (const path of glob.scan({ cwd: root, absolute: false })) {
+      if (path.includes('node_modules') || path.includes('.test.')) continue;
+      const posix = path.split('\\').join('/');
+      files.push({ path: posix, source: await Bun.file(joinPath(root, posix)).text() });
+    }
+  }
+  return files;
+}
+
+/** The resolved import graph over a file set — what `checkSurfaceBoundary` walks. */
+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-evals.ts

@@ -0,0 +1,74 @@
+// The eval facts `x verify` reads: recording is off, every prompt has an eval, and every eval has
+// a baseline it can actually gate against.
+//
+// All three come from the app's own registries and from `@ultimat3/ai`'s own reader — never from a
+// filename, so renaming a file cannot silently un-gate a prompt, and never from a second baseline
+// parser, so the gate and the suite can never disagree about what a recorded score is.
+
+import {
+  baselinePath,
+  describeEvals,
+  EvalBaselineMissingError,
+  EvalMissingError,
+  EvalRecordingError,
+  promptsWithoutEvals,
+  RECORD_ENV,
+  readBaseline,
+  recordingBaselines,
+} from '@ultimat3/ai';
+import { loadApp } from './app-load';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+/**
+ * Recording makes every eval write the numbers it just measured and pass, so a gate run that
+ * inherited the flag is green over scores nothing compared — and rewrites the committed baselines
+ * on its way through. The step refuses before the suite runs, because a red step alone would not
+ * undo the rewrite.
+ */
+export function checkEvalRecording(): readonly Finding[] {
+  if (!recordingBaselines()) return [];
+  return [{ ...findingFrom(new EvalRecordingError({ env: RECORD_ENV })), at: RECORD_ENV }];
+}
+
+/** Every prompt an app registers must be named by an eval. */
+export async function checkEvalCoverage(root: string): Promise<readonly Finding[]> {
+  // Loading is idempotent per process: `x verify` loads the app once and every later step,
+  // including the manifest, reads the same registries.
+  await loadApp(root);
+  return promptsWithoutEvals().map((prompt) => ({
+    ...findingFrom(new EvalMissingError({ prompt: prompt.ref, id: prompt.id })),
+    at: prompt.ref,
+  }));
+}
+
+/**
+ * Every eval must have a baseline on disk that reads back. Without this the gate asks only whether
+ * a `defineEval` exists, and an eval whose numbers were never recorded — one no test asserts, one
+ * whose `baseline:` is a cwd-relative string — passes it while gating on nothing.
+ */
+export async function checkEvalBaselines(root: string): Promise<readonly Finding[]> {
+  await loadApp(root);
+  const findings: Finding[] = [];
+  for (const fact of describeEvals()) {
+    // `baselinePath` refuses a spec that is not `import.meta.resolve('./…')`, and `readBaseline`
+    // refuses a file that is not a baseline; both say so as the eval's own X_* code.
+    try {
+      const path = baselinePath(fact.baseline, fact.name);
+      if ((await readBaseline(path)) !== undefined) continue;
+      findings.push({
+        ...findingFrom(
+          new EvalBaselineMissingError({
+            eval: fact.name,
+            path,
+            reason: 'has never been recorded',
+          }),
+        ),
+        at: fact.name,
+      });
+    } catch (error) {
+      findings.push({ ...findingFrom(error), at: fact.name });
+    }
+  }
+  return findings;
+}

package/src/app-load.ts

@@ -0,0 +1,136 @@
+// Loading an app into the framework's own registries. The CLI owns no second definition of what
+// a primitive is: `entity()`, `job()` and `task()` register on import, and `registerActions` /
+// `registerQueries` / `registerRoute` name the rest — so `x manifest`, `x routes` and `x verify`
+// read exactly the tables the running server reads.
+
+// Bun ships no `Bun.*` path API: `relative`/`sep` turn an absolute scan hit into the app-root-
+// relative POSIX path every finding and every manifest fact is keyed by.
+import { relative, sep } from 'node:path';
+import { registerActions } from '@ultimat3/action';
+import { localeConfig } from '@ultimat3/i18n';
+import type { ErrorCodeFact } from '@ultimat3/manifest';
+import { registerQueries } from '@ultimat3/query';
+import { isRouteConfig, registerRoute } from '@ultimat3/render';
+import { collectDeclaredCodes } from './error-contract';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+/** Every place an app keeps code the framework has to see. */
+const APP_GLOBS = [
+  'apps/*/{site,app,api,shared}/**/*.{ts,tsx}',
+  'apps/*/*.{ts,tsx}',
+  'packages/*/src/**/*.ts',
+] as const;
+
+export interface LoadedApp {
+  readonly root: string;
+  /** App-root-relative POSIX paths of every module that imported, sorted. */
+  readonly files: readonly string[];
+  /** Every `X_*` code the app's source declares, by code — the one fact no registry holds. */
+  readonly errorCodes: readonly ErrorCodeFact[];
+  /**
+   * The locale the app falls back to. `packages/i18n/src/index.ts` is inside the import loop, and
+   * `defineCatalogs()` configures `@ultimat3/i18n` on its way through — so this is the framework's
+   * own answer, read back from `localeConfig()`, and never a regex over the app's source, which
+   * only ever matched the one `defineCatalogs({ default: '…' })` spelling it anticipated. An app
+   * whose i18n module would not import leaves the framework default (`en`) and a finding saying so.
+   */
+  readonly defaultLocale: string;
+  /** Modules that would not import, and primitives that would not register. */
+  readonly findings: readonly Finding[];
+}
+
+// A module is imported and registered exactly once per PROCESS: `import()` caches, and a registry
+// rejects a second registration of a name. So a rescan refreshes only the facts DERIVED from the
+// registries — the manifest and its build id — and never the primitives themselves: an edited route
+// config, action or query needs a restart. Clearing the registries would not change that. Bun
+// exposes no way to invalidate a cached module, so the re-import hands back the same stale exports,
+// and a cache-busting query string leaks a fresh module instance on every save.
+const registered = new Set<string>();
+// A registration failure is sticky: the file is never retried, so the finding is replayed.
+const failures = new Map<string, Finding>();
+
+/** Test seam, and what `x dev` would call if it ever restarted the registries in-process. */
+export function resetAppLoad(): void {
+  registered.clear();
+  failures.clear();
+}
+
+export async function loadApp(root: string): Promise<LoadedApp> {
+  const files: string[] = [];
+  const findings: Finding[] = [];
+
+  for (const pattern of APP_GLOBS) {
+    for await (const absolute of new Bun.Glob(pattern).scan({ cwd: root, absolute: true })) {
+      if (absolute.includes('node_modules') || absolute.includes('.test.')) continue;
+      const file = relative(root, absolute).split(sep).join('/');
+      let module: Record<string, unknown>;
+      try {
+        module = (await import(absolute)) as Record<string, unknown>;
+      } catch (error) {
+        findings.push({ ...findingFrom(error), at: file });
+        continue;
+      }
+      files.push(file);
+      const finding = await register(absolute, file, module);
+      if (finding !== undefined) findings.push(finding);
+    }
+  }
+
+  files.sort();
+  // Read after the loop, never before it: `configureLocales` runs on the app's own import.
+  return {
+    root,
+    files,
+    errorCodes: await appErrorCodes(root),
+    defaultLocale: localeConfig().fallback,
+    findings,
+  };
+}
+
+/** Registers a module once; every later call replays whatever the first one reported. */
+async function register(
+  absolute: string,
+  file: string,
+  module: Record<string, unknown>,
+): Promise<Finding | undefined> {
+  const previous = failures.get(absolute);
+  if (previous !== undefined) return previous;
+  if (registered.has(absolute)) return undefined;
+  registered.add(absolute);
+  try {
+    const config = module['config'];
+    if (isRouteConfig(config)) {
+      // The build counts boundaries from the compiled JSX; before a build there is only the
+      // source, and `render: 'stream'` is rejected without one — so count them in the text.
+      const source = await Bun.file(absolute).text();
+      registerRoute({ file, config, suspenseBoundaries: countSuspense(source) });
+    }
+    registerActions(module);
+    registerQueries(module);
+    return undefined;
+  } catch (error) {
+    const finding: Finding = { ...findingFrom(error), at: file };
+    failures.set(absolute, finding);
+    return finding;
+  }
+}
+
+const countSuspense = (source: string): number => source.match(/<Suspense[\s/>]/g)?.length ?? 0;
+
+/** `packages/db/src/errors.ts` → `packages/db`; `apps/web/app/posts/errors.ts` → `apps/web`. */
+const workspaceOf = (file: string): string => file.split('/').slice(0, 2).join('/');
+
+/**
+ * The app's `X_*` codes, from the same walk and the same scanner the `errors` gate step uses.
+ * Deliberately not a second scan of the loaded modules' `*_ERROR_CODES` exports: that array is a
+ * convention some apps follow and most do not, so an app that declares every code at its throw
+ * site — the reference app included — published `"errorCodes": []`, a manifest claiming a
+ * completeness it never had. `collectDeclaredCodes` is the only answer to "which codes exist?",
+ * already sorted by code and one entry per code, so the projection is just the owning workspace.
+ */
+const appErrorCodes = async (root: string): Promise<readonly ErrorCodeFact[]> =>
+  (await collectDeclaredCodes(root)).map((site) => ({
+    code: site.code,
+    package: workspaceOf(site.at),
+  }));