@ultimat3/cli 23.0.0 → 24.0.0

package/src/app-permissions-borrowed.ts

@@ -0,0 +1,129 @@
+// The `policy` step's provenance question: every permission the app's OWN actions, queries and
+// routes require is one the app ITSELF declares. `defineAdmin()` declares `<entity>:read|write|
+// delete` for every mounted entity, so an app rule naming one passed in the web process and threw
+// X_PERMISSION_UNKNOWN in any process that never mounted the admin — with nothing saying so.
+
+// why: Bun ships no path API, and `relative` renders a frame's absolute path against the app root.
+import { relative } from 'node:path';
+import { listActions } from '@ultimat3/action';
+import { type Policy, permissionDeclarationSites, policyPermissions } from '@ultimat3/policy';
+import { listQueries } from '@ultimat3/query';
+import { routeEntries } from '@ultimat3/render';
+import { frameFile, siteFile } from './app-permissions-site';
+import type { Finding } from './output';
+
+/** One permission one app declaration requires. */
+export interface AppRule {
+  readonly permission: string;
+  /** `action createPost`, `query postList`, or the route file. */
+  readonly by: string;
+}
+
+/** An app rule whose permission no app module declares, and the file that did declare it. */
+export interface BorrowedPermission extends AppRule {
+  /**
+   * Root-relative paths of EVERY declaring module (`node_modules/…` or `../…`), distinct and
+   * sorted: naming only the first told the reader one package declared it when two did.
+   */
+  readonly from: readonly string[];
+}
+
+/**
+ * EVERY permission in each tree, composites included — unlike the grant question, which judges
+ * only a bare `can()`: an `or()` branch is still a `can()` that asserted its name, so it needs the
+ * app's own declaration as much as a bare one does. A screen the admin MOUNTS is not here: those
+ * are the package's rules, and declaring their names is the package's job.
+ */
+export function appRules(): readonly AppRule[] {
+  const named = (by: string, policy: Policy<unknown, unknown>): readonly AppRule[] =>
+    policyPermissions(policy).map((permission) => ({ permission, by }));
+  return [
+    ...listActions().flatMap((target) => named(`action ${target.name}`, target.policy)),
+    ...listQueries().flatMap((target) => named(`query ${target.name}`, target.policy)),
+    ...routeEntries().flatMap((entry) => {
+      const permission = entry.config.policy?.permission;
+      return permission === undefined ? [] : [{ permission, by: entry.file }];
+    }),
+  ];
+}
+
+/** An app module's root-relative path, or `undefined` for a dependency's or an unreadable frame. */
+const appFile = (root: string, site: string): string | undefined => {
+  const file = siteFile(root, site);
+  return file === undefined || file.split('/').includes('node_modules') ? undefined : file;
+};
+
+/**
+ * Provenance by the declaring module's PATH, which is where the call ran — never by the name's
+ * shape: `posts:read` is the same string whether `defineAdmin()` or the app declared it. A name
+ * with any unreadable site is one whose origin nobody can state, so it is not judged — and that
+ * covers an UNKNOWN name too, which has no site at all: it is X_PERMISSION_UNKNOWN's, asked first,
+ * and a second finding would be a second instruction for one fault.
+ */
+export function borrowedPermissions(
+  root: string,
+  rules: readonly AppRule[] = appRules(),
+  declaredAt: Readonly<Record<string, readonly string[]>> = permissionDeclarationSites(),
+): readonly BorrowedPermission[] {
+  const found = new Map<string, BorrowedPermission>();
+  for (const rule of rules) {
+    const sites = Object.hasOwn(declaredAt, rule.permission) ? declaredAt[rule.permission] : [];
+    const files = (sites ?? []).map(frameFile);
+    if (files.length === 0 || files.some((file) => file === undefined)) continue;
+    if ((sites ?? []).some((site) => appFile(root, site) !== undefined)) continue;
+    const from = [
+      ...new Set(
+        files.flatMap((file) =>
+          file === undefined ? [] : [relative(root, file).replaceAll('\\', '/')],
+        ),
+      ),
+    ].sort();
+    found.set(`${rule.permission}\u0000${rule.by}`, { ...rule, from });
+  }
+  return [...found.values()].sort((a, b) =>
+    a.permission === b.permission
+      ? a.by.localeCompare(b.by)
+      : a.permission.localeCompare(b.permission),
+  );
+}
+
+/**
+ * The app file its permissions are declared in — where the missing name is added. Read off the
+ * recorded sites, never a scaffold path; none under the root is `undefined`, never a guess.
+ */
+export function permissionsFile(root: string): string | undefined {
+  for (const sites of Object.values(permissionDeclarationSites())) {
+    for (const site of sites) {
+      const file = appFile(root, site);
+      if (file !== undefined) return file;
+    }
+  }
+  return undefined;
+}
+
+/** A TS string literal for the name — quoted the house way unless the name itself needs escaping. */
+const literal = (name: string): string =>
+  /^[\w:.*-]+$/.test(name) ? `'${name}'` : JSON.stringify(name);
+
+export function borrowedFinding(
+  entry: BorrowedPermission,
+  declaredIn: string | undefined,
+): Finding {
+  const [only, ...more] = entry.from;
+  const declarers =
+    more.length === 0 ? `only ${only} declares it` : `only ${entry.from.join(', ')} declare it`;
+  const where =
+    declaredIn === undefined
+      ? 'paste this call into an app module'
+      : `paste this call into ${declaredIn} (definePermissions() merges, so a second call is fine)`;
+  const finding: Finding = {
+    code: 'X_PERMISSION_BORROWED',
+    cause:
+      `${entry.by} requires ${literal(entry.permission)}, and ${declarers} — no app module does, ` +
+      "so the rule holds only in a process that ran that package's declaration (defineAdmin()) " +
+      `first; ${where}, then x verify --only policy`,
+    // A call to paste, never prose: `add …` read as a command answered `add: command not found`.
+    fix: `definePermissions([${literal(entry.permission)}])`,
+  };
+  return declaredIn === undefined ? finding : { ...finding, at: declaredIn };
+}

package/src/app-permissions-site.ts

@@ -0,0 +1,24 @@
+// Single responsibility: a declaration site — a stack FRAME `@ultimat3/policy` recorded for a
+// `defineRoles()` or `definePermissions()` call — reduced to the file it names, absolute or
+// app-root-relative. Both `policy` step questions key their findings by it.
+
+// why: Bun ships no path API, and `relative` is what turns a stack frame's absolute path into
+// the app-root-relative one every finding is keyed by.
+import { relative } from 'node:path';
+
+/** The absolute source path a frame (`at foo (/abs/path.ts:3:1)`) names, or `undefined`. */
+export function frameFile(site: string): string | undefined {
+  return /\(?(\/[^():]+\.[cm]?tsx?)(?::\d+)?(?::\d+)?\)?/.exec(site)?.[1];
+}
+
+/**
+ * The frame's file relative to the app root, or `undefined` outside it: a locator nobody can act on
+ * is worse than none. The frame is the only place the declaring module's name exists by the time
+ * the declaration runs.
+ */
+export function siteFile(root: string, site: string): string | undefined {
+  const absolute = frameFile(site);
+  if (absolute === undefined) return undefined;
+  const rel = relative(root, absolute).replaceAll('\\', '/');
+  return rel.startsWith('..') || rel.length === 0 ? undefined : rel;
+}

package/src/app-permissions.ts

@@ -7,9 +7,6 @@
 // required it on `/dashboard`, declared it nowhere, and served HTTP 500 on two of its three routes
 // with `x verify` green (#F1). This is the question nothing asked.
 
-// why: Bun ships no path API, and `relative` is what turns a stack frame's absolute path into
-// the app-root-relative one every finding is keyed by.
-import { relative } from 'node:path';
 import {
   grantMatches,
   isKnownPermission,
@@ -21,6 +18,8 @@ import {
 import { routeEntries } from '@ultimat3/render';
 import { definedStorage } from '@ultimat3/storage';
 import { loadApp } from './app-load';
+import { borrowedFinding, borrowedPermissions, permissionsFile } from './app-permissions-borrowed';
+import { siteFile } from './app-permissions-site';
 import type { DuplicateProbe } from './duplicate-packages';
 import { duplicateFinding, findDuplicateInstalls } from './duplicate-packages';
 import type { Finding } from './output';
@@ -45,19 +44,6 @@ export interface PermissionReference {
 /** What this check needs of a boot — the seam `i18n-registration.ts` already established. */
 export type AppLoader = (root: string) => Promise<{ readonly findings: readonly Finding[] }>;
 
-/**
- * A role's declaration site is a stack FRAME (`at foo (/abs/path.ts:3:1)`), which is the only
- * place the declaring module's name exists by the time `defineRoles` runs. Reduced to the
- * app-relative path an agent opens, or dropped: a locator nobody can act on is worse than none.
- */
-export function siteFile(root: string, site: string): string | undefined {
-  const match = /\(?(\/[^():]+\.[cm]?tsx?)(?::\d+)?(?::\d+)?\)?/.exec(site);
-  const absolute = match?.[1];
-  if (absolute === undefined) return undefined;
-  const rel = relative(root, absolute).replaceAll('\\', '/');
-  return rel.startsWith('..') || rel.length === 0 ? undefined : rel;
-}
-
 /** Every permission a registered role grants, with where that role was declared. */
 export function grantedReferences(root: string): readonly PermissionReference[] {
   const sites = roleDeclarationSites();
@@ -198,7 +184,11 @@ export async function policyFindings(
     unknown.length === 0
       ? ungrantedRequirements().map((rule) => ungrantedFinding(rule, rolesAt))
       : [];
-  const findings = [...duplicated, ...unknown, ...ungranted];
+  // Asked of KNOWN names only (`borrowedPermissions` skips the rest), so it rides beside the
+  // unknown half rather than behind it: one fault, one finding.
+  const declaredIn = permissionsFile(root);
+  const borrowed = borrowedPermissions(root).map((entry) => borrowedFinding(entry, declaredIn));
+  const findings = [...duplicated, ...unknown, ...borrowed, ...ungranted];
   return findings.length === 0 ? [] : [...findings, ...app.findings];
 }
 

package/src/budgets.ts

@@ -39,15 +39,6 @@ export interface RouteStats {
    * older build simply did not count it, and `checkBudgets` reads `jsBytes` either way.
    */
   readonly frameworkJsBytes?: number;
-  /**
-   * **Written by nothing, `As of 2026-08`.** `apps/web/prerender.ts` is the only producer of this
-   * file and it emits static HTML — there is no browser in the build to observe a paint. So the
-   * comparison in `checkBudgets` below is reachable only for an app that writes its own stats, and
-   * `x new` no longer scaffolds an `lcp` budget for exactly that reason: a budget the build cannot
-   * weigh passes silently the moment a stats row exists, which is the false green this file's
-   * header is about. `RouteBudget.lcp` still accepts one — that key is `@ultimat3/render`'s.
-   */
-  readonly lcpMs?: number;
   /** Import chain that pulled the heaviest module into this route. */
   readonly heaviestChain?: readonly string[];
 }
@@ -67,8 +58,9 @@ export interface BuildStats {
  * `examples/dummy` was charged 250 B for `/x-sw-register.js` by a file written before
  * `FRAMEWORK_SCRIPTS` exempted it. `2`: that exemption and the page-boot decision (ledger #28).
  * `3`: an island entry's imported chunks are charged, each once per document (shared chunks).
+ * `4`: the exempt theme script's bytes moved — it also stamps `data-theme-default` (plan 101, 09).
  */
-export const BUILD_STATS_RULES = 3;
+export const BUILD_STATS_RULES = 4;
 
 const chainOf = (stats: RouteStats): string =>
   stats.heaviestChain === undefined ? 'unknown import chain' : stats.heaviestChain.join(' -> ');
@@ -94,14 +86,6 @@ function exceededJsFix(url: string, file: string | undefined, bytes: number): st
   return `edit ${where} — set budget: { js: '${String(kb)}kb' } with // measured: ${String(bytes)} B (x build --target static) — why: <the function it buys> directly above it; or x routes --json for the chain and move the heavy import behind hydrate: 'interaction'`;
 }
 
-/** Which budgets the route declared, for a cause line that names what went unmeasured. */
-function declaredBudgets(js: number | null, lcp: number | undefined): string {
-  const labels: string[] = [];
-  if (js !== null) labels.push('JS');
-  if (lcp !== undefined) labels.push('LCP');
-  return labels.join(' and ');
-}
-
 /**
  * Compare declared budgets against measured stats. A declared budget with no measurement is a
  * finding, never a pass: a route that clears the gate without ever being weighed is exactly the
@@ -210,17 +194,11 @@ export function checkBudgets(
     if (unweighable.has(route.url)) continue;
     const measured = byPath.get(route.url);
     const js = jsBudgetOf(route);
-    const lcp = route.budget?.lcp;
     if (measured === undefined) {
-      if (js !== null || lcp !== undefined) {
+      if (js !== null) {
         findings.push(
           ownCodeFinding(route.url, unmeasured) ??
-            unmeasuredFinding(
-              route.url,
-              declaredBudgets(js, lcp),
-              stats !== undefined,
-              stats?.stale === true,
-            ),
+            unmeasuredFinding(route.url, 'JS', stats !== undefined, stats?.stale === true),
         );
       }
       continue;
@@ -234,15 +212,6 @@ export function checkBudgets(
         at: route.url,
       });
     }
-    if (lcp !== undefined && measured.lcpMs !== undefined && measured.lcpMs > lcp) {
-      findings.push({
-        code: 'X_BUDGET_EXCEEDED',
-        cause: `${route.url} LCP ${measured.lcpMs}ms over the ${lcp}ms budget`,
-        fix: `raise the budget in defineRoute, or switch render to 'isr' to serve it prebuilt`,
-        docs: ERROR_DOCS_URL,
-        at: route.url,
-      });
-    }
   }
   return findings;
 }

package/src/cdp-shot-driver.ts

@@ -91,7 +91,9 @@ export function cdpShotDriver(options: CdpShotDriverOptions): ShotDriver {
       throw new CdpBrowserMissingError({ tried: CHROME_CANDIDATES });
     }
     const launched = await launch(options.executablePath, timeoutMs);
-    return { connection: launched.connection, end: async () => launched.close() };
+    // Awaited by `close` below: `x shot` exits right after its last picture, and a reap still
+    // running then is a Chrome child left behind and a profile directory it re-creates.
+    return { connection: launched.connection, end: () => launched.close() };
   };
 
   return {

package/src/cmd-auth-spec.ts

@@ -0,0 +1,16 @@
+// `x auth`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-auth.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const AUTH_SUBCOMMANDS = ['seal-mfa'] as const;
+
+export const authSpec: CommandSpec = {
+  name: 'auth',
+  summary: 'one-shot maintenance of the auth tables: seal every plaintext second-factor secret',
+  usage: 'x auth seal-mfa [--json]',
+  requiresApp: true,
+  // No default: the one subcommand WRITES, and a bare `x auth` must not.
+  subcommands: [...AUTH_SUBCOMMANDS],
+  flags: [],
+};

package/src/cmd-auth.ts

@@ -0,0 +1,65 @@
+// `x auth seal-mfa` — seal every `x_users.mfa_secret` still stored in the clear, in place, under
+// the app's master key. The one-shot an upgrade onto sealed second-factor secrets owes: readers
+// refuse a plaintext value (`X_MFA_SECRET_UNSEALED`), and this is the command that refusal names.
+// Idempotent — a sealed value is counted and left alone — so an interrupted run is finished by
+// running it again.
+
+import type { MfaSecretStore } from '@ultimat3/auth';
+import { BuiltinAdapter, sealMfaSecrets } from '@ultimat3/auth';
+import { requireAppRoot } from './app-root';
+import { authSpec } from './cmd-auth-spec';
+import type { CliCommand, CommandContext } from './command';
+import { ok } from './command';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { resolveServices } from './runtime-bindings';
+import { startQueue } from './runtime-queue';
+
+export interface OpenAuthStore extends MfaSecretStore {
+  close(): Promise<void>;
+}
+
+/**
+ * The app's own database, opened the way every other command opens it (`startQueue`: the
+ * framework's tables are applied first, so `x_users` exists) and ALWAYS released — a CLI that
+ * exits holding the PGlite lock breaks the next command run against this app.
+ */
+async function openAppAuthStore(root: string, ctx: CommandContext): Promise<OpenAuthStore> {
+  const queue = await startQueue(resolveServices(root, ctx.env), undefined, ctx.env);
+  return { adapter: new BuiltinAdapter(queue.db), close: () => queue.stop() };
+}
+
+/** `open` is the seam a test supplies a store through; the shipped command opens the app's. */
+export const authCommandOver = (
+  open: (root: string, ctx: CommandContext) => Promise<OpenAuthStore>,
+): CliCommand => ({
+  spec: authSpec,
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('auth', ctx.cwd).dir;
+    const store = await open(root, ctx);
+    try {
+      // The key is read from the command's own environment and the app's `.secrets.key`: with
+      // neither, the first seal refuses (`X_SEAL_KEY_MISSING`) before any row is written.
+      const report = await sealMfaSecrets(store, { root, env: ctx.env });
+      return ok(
+        'auth',
+        msg('cli.auth.sealed', {
+          sealed: report.sealed,
+          already: report.alreadySealed,
+          skipped: report.skipped,
+        }),
+        {
+          data: {
+            sealed: report.sealed,
+            alreadySealed: report.alreadySealed,
+            skipped: report.skipped,
+          },
+        },
+      );
+    } finally {
+      await store.close();
+    }
+  },
+});
+
+export const authCommand: CliCommand = authCommandOver(openAppAuthStore);

package/src/cmd-build.ts

@@ -4,19 +4,21 @@
 
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { ERROR_DOCS_URL, frameworkVersion, VERSION_DEFINE } from '@ultimat3/core';
+import { ERROR_DOCS_URL, frameworkVersion, UltimateError, VERSION_DEFINE } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
 import { buildSpec } from './cmd-build-spec';
 import { runVerify } from './cmd-verify';
 import type { CliCommand, CommandContext } from './command';
 import { externalArgs } from './compile-externals';
-import { BadFlagError, BuildEntryMissingError, UnknownCommandError } from './errors';
+import { BadFlagError, UnknownCommandError } from './errors';
 import type { ExecResult } from './exec';
 import { execOutput } from './exec';
 import { msg } from './messages';
 import type { CommandResult } from './output';
+import type { ParsedArgs } from './parse';
 import { flagString } from './parse';
 import { PREBUILT_DIR } from './serve-prebuilt-paths';
+import { quoteArg } from './shell-quote';
 import type { StaticReport } from './static-report';
 import {
   readStaticReport,
@@ -24,6 +26,22 @@ import {
   renderStaticReport,
   staticReportData,
 } from './static-report';
+import type { VerifyStepName } from './verify-step';
+
+/**
+ * A build target names an entry file the app does not have. `x build` refuses before it spawns the
+ * builder: `bun build`'s own "module not found" says nothing about which file an Ultimate app is
+ * supposed to own, and `docker build`'s says nothing about which target wanted it.
+ */
+export class BuildEntryMissingError extends UltimateError {
+  constructor(input: { target: string; entry: string }) {
+    super({
+      code: 'X_BUILD_ENTRY_MISSING',
+      cause: `x build --target ${input.target} builds from ${input.entry}, and the app does not have it`,
+      fix: `x new scratch-app --dry-run --json   # its file list carries ${input.entry}; copy that file into this app`,
+    });
+  }
+}
 
 export const BUILD_TARGETS = ['docker', 'binary', 'static', 'prebuilt'] as const;
 
@@ -190,6 +208,46 @@ export function buildResult(input: {
   };
 }
 
+/** The flags only some targets read. */
+const TARGET_SCOPED_FLAGS = ['tag', 'out', 'preflight'] as const;
+
+type TargetScopedFlag = (typeof TARGET_SCOPED_FLAGS)[number];
+
+/** The optional flags each target READS. One table, so a flag cannot be read by one and ignored. */
+const TARGET_FLAGS: ReadonlyMap<BuildTarget, readonly TargetScopedFlag[]> = new Map([
+  ['docker', ['tag', 'preflight']],
+  ['binary', ['out', 'preflight']],
+  ['static', ['out', 'preflight']],
+  // The boot reads ONE place, and the image holds no devDependencies to run a gate with.
+  ['prebuilt', []],
+]);
+
+/** Why a target takes no `--<flag>`, in the words its refusal prints. */
+const UNREAD_BECAUSE: Readonly<Record<TargetScopedFlag, string>> = {
+  tag: 'only the docker target tags an image',
+  out: 'the docker target writes an image, not a path',
+  preflight: 'the prebuilt target runs no gate: `x verify` ran before `docker build` was called',
+};
+
+/**
+ * A flag the chosen target never reads is refused before the gate runs. Accepted and dropped, it
+ * printed a green build: `--out dist` on `docker` and `--tag` on `binary` read as if they landed.
+ */
+function refuseUnreadFlags(args: ParsedArgs, target: BuildTarget): void {
+  for (const flag of TARGET_SCOPED_FLAGS) {
+    if (!args.flags.has(flag) || TARGET_FLAGS.get(target)?.includes(flag) === true) continue;
+    throw new BadFlagError({
+      flag,
+      command: 'build',
+      reason:
+        target === 'prebuilt' && flag !== 'preflight'
+          ? `the prebuilt target writes ${PREBUILT_DIR}, the one place a container boots from, and takes no --${flag}`
+          : `--target ${target} never reads it: ${UNREAD_BECAUSE[flag]}`,
+      fix: `x build --target ${quoteArg(target)}`,
+    });
+  }
+}
+
 /**
  * `x build --target prebuilt`: the island chunks and compiled stylesheets, written by the process
  * `docker build` runs after the source is copied in. No gate and no subprocess — the image holds
@@ -198,17 +256,7 @@ export function buildResult(input: {
  * A module that would not import fails the image build rather than warning into a build log
  * nobody reads: its stylesheets are missing from the store, and every pod would compile them.
  */
-async function buildPrebuilt(ctx: CommandContext, root: string): Promise<CommandResult> {
-  // The boot reads ONE place; a flag that seemed to move it would write a store no pod opens.
-  for (const flag of ['tag', 'out']) {
-    if (flagString(ctx.args, flag) === undefined) continue;
-    throw new BadFlagError({
-      flag,
-      command: 'build',
-      reason: `the prebuilt target writes ${PREBUILT_DIR}, the one place a container boots from, and takes no --${flag}`,
-      fix: 'x build --target prebuilt',
-    });
-  }
+async function buildPrebuilt(root: string): Promise<CommandResult> {
   const started = Bun.nanoseconds();
   const { prebuildImage } = await import('./image-prepare');
   const built = await prebuildImage(root);
@@ -230,7 +278,7 @@ async function buildPrebuilt(ctx: CommandContext, root: string): Promise<Command
 }
 
 /** The static steps `x build` runs before it builds, and `--no-preflight` leaves to the gate. */
-export const PREFLIGHT_STEPS: readonly string[] = [
+export const PREFLIGHT_STEPS: readonly VerifyStepName[] = [
   'typecheck',
   'lint',
   'boundaries',
@@ -248,7 +296,8 @@ export const buildCommand: CliCommand = {
     // typecheck, and eight seconds of `tsc` ahead of "that file does not exist" is eight seconds
     // an agent spends on the wrong question.
     requireEntry(root, target);
-    if (target === 'prebuilt') return buildPrebuilt(ctx, root);
+    refuseUnreadFlags(ctx.args, target);
+    if (target === 'prebuilt') return buildPrebuilt(root);
 
     // Run static verify steps before building — unless the caller is a gate that runs the same
     // six steps itself right after (`bin/check`: `x build --no-preflight && x verify`), where the

package/src/cmd-db-backfill.ts

@@ -23,7 +23,7 @@ import { BadFlagError } from './errors';
 import { withJobDriver } from './jobs-driver';
 import { backfillToJson } from './jobs-json';
 import { msg } from './messages';
-import type { CommandResult } from './output';
+import type { CommandResult, Finding } from './output';
 import { findingFrom } from './output';
 import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
@@ -171,15 +171,22 @@ async function runBackfillList(ctx: CommandContext, root: string): Promise<Comma
  * The alarm the framework did not have. Non-zero when anything is unswept, so a cron or a deploy
  * check can read the exit code — a `--json` nobody has to parse to know something is wrong.
  * `loadApp` first: importing the app's modules IS the declaration, and a diff run without it
- * would report a clean database against an empty declaration list.
+ * would report a clean database against an empty declaration list. Its findings fail the run for
+ * the same reason: a module that would not import may be the one declaring the unswept backfill.
  */
 async function runBackfillPending(ctx: CommandContext, root: string): Promise<CommandResult> {
-  await loadApp(root);
+  const { findings: loadFindings } = await loadApp(root);
   const environment = resolveEnvironment({ env: ctx.env });
   return withJobDriver(root, ctx, async (driver) => {
     const report = await pendingReport(driver, environment);
+    const findings = [
+      ...report.pending.map((row) =>
+        findingFrom(new BackfillPendingError({ backfill: row.name, environment })),
+      ),
+      ...loadFindings,
+    ];
     return {
-      ok: report.pending.length === 0,
+      ok: findings.length === 0,
       command: 'db',
       summary:
         report.pending.length === 0
@@ -188,9 +195,7 @@ async function runBackfillPending(ctx: CommandContext, root: string): Promise<Co
               count: report.pending.length,
               declared: report.rows.length,
             }),
-      findings: report.pending.map((row) =>
-        findingFrom(new BackfillPendingError({ backfill: row.name, environment })),
-      ),
+      findings,
       lines: report.rows.length === 0 ? [] : renderPendingTable(report).map((line) => `  ${line}`),
       data: pendingToJson(report),
     };
@@ -208,7 +213,7 @@ async function runBackfillPass(
   root: string,
   names: readonly string[] | 'all',
 ): Promise<CommandResult> {
-  await loadApp(root);
+  const { findings: loadFindings } = await loadApp(root);
   const environment = resolveEnvironment({ env: ctx.env });
   const write = flagBool(ctx.args, 'write');
   return withJobDriver(root, ctx, async (driver) => {
@@ -220,16 +225,24 @@ async function runBackfillPass(
       environment,
       appliedMigrations: await readAppliedMigrations(),
     });
-    return backfillPassResult(rows, write);
+    return backfillPassResult(rows, write, loadFindings);
   });
 }
 
 /**
  * A blocked or deduped name is a finding and a non-zero exit, and every OTHER name still ran —
- * that isolation is what stops one wedged cleanup blocking every later one forever.
+ * that isolation is what stops one wedged cleanup blocking every later one forever. A module that
+ * would not import fails the pass too: `--all` over it plans every backfill but the unloaded ones.
  */
-function backfillPassResult(rows: readonly BackfillPlanRow[], write: boolean): CommandResult {
-  const findings = rows.flatMap((row) => (row.finding === null ? [] : [row.finding]));
+function backfillPassResult(
+  rows: readonly BackfillPlanRow[],
+  write: boolean,
+  loadFindings: readonly Finding[],
+): CommandResult {
+  const findings = [
+    ...rows.flatMap((row) => (row.finding === null ? [] : [row.finding])),
+    ...loadFindings,
+  ];
   // Counted per action, never derived from the total: a deduped pass is neither enqueued nor
   // blocked, and `rows.length - enqueued` reported it as blocked while `--json` reported it as
   // deduped. `planToJson` is the same list, so the two renders now add up to the same run.

package/src/cmd-db.ts

@@ -11,7 +11,7 @@
 // directory tree. `node:path` for `join` — Bun exposes no path joiner.
 import { rm } from 'node:fs/promises';
 import { join } from 'node:path';
-import { resolveEnvironment } from '@ultimat3/core';
+import { NotImplementedError, resolveEnvironment } from '@ultimat3/core';
 import { type DriftReport, driftError, withTransaction } from '@ultimat3/db';
 import { postgresDriver } from '@ultimat3/entity';
 import { requireAppRoot } from './app-root';
@@ -40,7 +40,7 @@ import {
   selectSeeds,
 } from './db-seed';
 import { DevAlreadyRunningError, liveDevLock } from './dev-lock';
-import { CliNotImplementedError, MissingSubcommandError, UnknownCommandError } from './errors';
+import { MissingSubcommandError, UnknownCommandError } from './errors';
 import { withJobDriver } from './jobs-driver';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
@@ -254,8 +254,8 @@ async function runMigrate(
 async function runReset(ctx: CommandContext, root: string): Promise<CommandResult> {
   const services = resolveServices(root, ctx.env);
   if (services.db.mode === 'external') {
-    throw new CliNotImplementedError({
-      feature: 'x db reset against an external Postgres',
+    throw new NotImplementedError({
+      cause: 'x db reset against an external Postgres is not implemented in this build',
       fix: 'drop and recreate the database yourself, then run: x db migrate',
     });
   }
@@ -301,7 +301,8 @@ async function runSeed(ctx: CommandContext, root: string): Promise<CommandResult
   });
   if (chosen.length === 0) {
     return {
-      ok: true,
+      // A seed module that would not import may hold the seed that was asked for.
+      ok: discovery.findings.length === 0,
       command: 'db',
       summary: msg('cli.db.seed.none'),
       findings: discovery.findings,

package/src/cmd-deploy-helm.ts

@@ -8,8 +8,7 @@
 // why: Bun exposes no path-join primitive; the chart path is handed to helm as one joined string.
 import { join } from 'node:path';
 import { UltimateError } from '@ultimat3/core';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 import { BadFlagError } from './errors';
 
 /** Long enough for a migration a pre-upgrade hook must finish; helm's own 5m default is not. */
@@ -67,16 +66,18 @@ export function readLabel(flag: 'namespace' | 'release', raw: string): string {
  */
 export async function readReleaseName(root: string, flag: string | undefined): Promise<string> {
   if (flag !== undefined) return readLabel('release', flag);
-  const module = (await import(join(root, APP_CONFIG_FILE))) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  const name = isRecord(config) ? config['name'] : undefined;
+  const config = await loadAppConfig(root);
+  // `unknown`, not the declared `string`: core reads an absent name as `"undefined"` and lets it by.
+  const name: unknown = config?.name;
   if (typeof name === 'string' && name.length <= RELEASE_MAX && LABEL.test(name)) return name;
   throw new UltimateError({
     code: 'X_CONFIG_INVALID',
     cause:
       typeof name === 'string'
         ? `app.config.ts names the app "${name.slice(0, 80)}", which is not a helm release name (a DNS-1123 label of at most ${RELEASE_MAX} characters)`
-        : 'app.config.ts exports no config.name, and x deploy --method helm names the release after it',
+        : config === undefined
+          ? `${root} has no app.config.ts, and x deploy --method helm names the release after its config.name`
+          : 'app.config.ts exports no config.name, and x deploy --method helm names the release after it',
     fix: 'name the release explicitly: x deploy --method helm --release my-app --json',
   });
 }