@ultimat3/cli 23.0.0 → 24.0.0

package/src/island-bundle.ts

@@ -22,8 +22,7 @@
 // POSIX by construction), `join`/`basename` the filesystem side.
 import { basename, join, posix, relative, sep } from 'node:path';
 import { ISLAND_EXTENSION, IslandInvalidError, islandModuleId } from '@ultimat3/render';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 import { IslandBuildFailedError } from './errors';
 import { describeBuildError, sourcesContentOf, stableChunk, stripDebugId } from './island-identity';
 import type { BuiltOutput, LinkedFile } from './island-link';
@@ -357,20 +356,9 @@ export interface BuildIslandsOptions {
   readonly sharedChunks?: boolean;
 }
 
-/**
- * `islands.sharedChunks` as `defineConfig` validated it — `false` for an app with no config file or
- * none of it. Structural, never `instanceof`, for `loadNavigation`'s reason.
- */
+/** `islands.sharedChunks` off the one loader (`app-config-load.ts`) — `false` with no config file. */
 export async function loadSharedChunks(root: string): Promise<boolean> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(configPath).exists())) return false;
-  const config: unknown = ((await import(configPath)) as Record<string, unknown>)[
-    APP_CONFIG_EXPORT
-  ];
-  if (typeof config !== 'object' || config === null) return false;
-  const islands: unknown = (config as Record<string, unknown>)['islands'];
-  if (typeof islands !== 'object' || islands === null) return false;
-  return (islands as Record<string, unknown>)['sharedChunks'] === true;
+  return (await loadAppConfig(root))?.islands.sharedChunks ?? false;
 }
 
 /** Build every island in the app. An app with none returns an empty bundle and costs one glob. */

package/src/jobs-drain.ts

@@ -2,9 +2,9 @@
 // it is the only command here that WRITES to two drivers at once, and the ordering rule that makes
 // that safe — lease, copy steps, enqueue, then ack — has to be readable in one screen.
 
-import { uuid } from '@ultimat3/core';
+import { logger, uuid } from '@ultimat3/core';
 import type { ClaimedJob, JobDriver, JobRecord, JobState } from '@ultimat3/jobs';
-import { claimOf, inspectJobList } from '@ultimat3/jobs';
+import { claimOf, inspectJobList, jobCursor, MAX_JOB_PAGE } from '@ultimat3/jobs';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 
@@ -12,10 +12,10 @@ import { findingFrom } from './output';
 const PENDING_STATES: readonly JobState[] = ['ready', 'delayed', 'suspended'];
 
 /**
- * The lease has to outlive the WHOLE transfer loop, not one record: the batch is claimed up
- * front, and a lease expiring mid-drain would hand a half-transferred job back to a source
- * worker. The snapshot is bounded by the drivers' own 100-row-per-state list cap, so this is a
- * ceiling over a few hundred sequential enqueues rather than a guess about one.
+ * The lease has to outlive the transfer of the whole BATCH it covers: a batch is claimed up front,
+ * and a lease expiring mid-batch would hand a half-transferred job back to a source worker. A
+ * batch is at most `MAX_JOB_PAGE` rows, so this is a ceiling over a couple of hundred sequential
+ * enqueues rather than a guess about however many the queue holds.
  */
 const DRAIN_LEASE_MS = 300_000;
 
@@ -54,19 +54,56 @@ export interface DrainOutcome {
  * left alone. `queues` is always explicit because the pg driver reads an empty list as
  * `['default']` rather than as "every queue".
  */
-function leaseCandidates(
+function leaseBatch(
   source: JobDriver,
   candidates: readonly JobRecord[],
+  limit: number,
 ): Promise<readonly ClaimedJob[]> {
-  if (candidates.length === 0) return Promise.resolve([]);
+  if (candidates.length === 0 || limit <= 0) return Promise.resolve([]);
   return source.claim({
     queues: [...new Set(candidates.map((record) => record.queue))],
-    limit: candidates.length,
+    limit,
     visibilityTimeoutMs: DRAIN_LEASE_MS,
     workerId: `x-jobs-drain:${uuid()}`,
+    // A claim BURIES a row whose lease lapsed on its final attempt, whoever makes it — this one
+    // too. The drain is an operator's tool with no worker context, so it runs no `onSettled`
+    // (at most once across a crash, as documented) and names no `dropExhausted`: said out loud
+    // here, because an unlistened burial is a row that went `dead` with nothing anywhere saying so.
+    onExhausted: (dead) => {
+      for (const row of dead) {
+        logger.error('jobs.claim.exhausted', {
+          workerId: 'x-jobs-drain',
+          job: row.name,
+          jobId: row.id,
+          attempt: row.attempt,
+          maxAttempts: row.maxAttempts,
+          error: row.lastError ?? '',
+        });
+      }
+    },
   });
 }
 
+/**
+ * Every row in `state`, page by page on the keyset cursor until a short page: one page was the
+ * drivers' default 100, so a drain of 350 ready jobs moved 100 and left 250 on the source.
+ */
+async function everyRow(source: JobDriver, state: JobState): Promise<readonly JobRecord[]> {
+  const rows: JobRecord[] = [];
+  let after: string | undefined;
+  for (;;) {
+    const page = await inspectJobList(source, {
+      state,
+      limit: MAX_JOB_PAGE,
+      ...(after === undefined ? {} : { after }),
+    });
+    rows.push(...page);
+    const last = page.at(-1);
+    if (page.length < MAX_JOB_PAGE || last === undefined) return rows;
+    after = jobCursor(last);
+  }
+}
+
 /** Steps carry their own `runId`, so a copy lands under the same key the target job resumes on. */
 async function copySteps(source: JobDriver, target: JobDriver, runId: string): Promise<void> {
   for (const record of await source.steps.list(runId)) await target.steps.put(record);
@@ -114,18 +151,49 @@ export async function drainJobs(
   target: JobDriver,
   dryRun: boolean,
 ): Promise<DrainOutcome> {
-  const lists = await Promise.all(PENDING_STATES.map((state) => inspectJobList(source, { state })));
+  const lists = await Promise.all(PENDING_STATES.map((state) => everyRow(source, state)));
   const candidates = lists.flat();
   const base = { from: source.name, to: target.name, candidates };
   if (dryRun) return { ...base, dryRun: true, moved: [], skipped: [], failures: [] };
 
-  const leased = await leaseCandidates(source, candidates);
-  const held = new Set(leased.map((record) => record.id));
   const found = new Map(candidates.map((record) => [record.id, record]));
-  const skipped = candidates.filter((record) => !held.has(record.id)).map(toSkip);
-
+  const held = new Set<string>();
   const moved: JobRecord[] = [];
   const failures: DrainFailure[] = [];
+  // Batch by batch, each under its own lease, until the claims stop or the snapshot's count is
+  // spent — a claim may lease a row enqueued after the snapshot, and that row spends the budget
+  // too, so a queue that keeps filling cannot keep the drain running.
+  let budget = candidates.length;
+  while (budget > 0) {
+    const leased = await leaseBatch(source, candidates, Math.min(budget, MAX_JOB_PAGE));
+    if (leased.length === 0) break;
+    // A row the target already refused is tried once per drain: handed straight back, spending
+    // no budget and adding no second failure for the same id.
+    const refused = new Set(failures.map((failure) => failure.id));
+    const fresh = leased.filter((record) => !refused.has(record.id));
+    for (const record of leased) if (refused.has(record.id)) await releaseLease(source, record);
+    if (fresh.length === 0) break;
+    budget -= fresh.length;
+    for (const record of fresh) held.add(record.id);
+    const before = moved.length;
+    await transfer(source, target, fresh, found, moved, failures);
+    // A batch that moved nothing handed its leases back, and the next claim would take the same
+    // rows to the same refusing target: stop, and let the failures already counted say why.
+    if (moved.length === before) break;
+  }
+  const skipped = candidates.filter((record) => !held.has(record.id)).map(toSkip);
+  return { ...base, dryRun: false, moved, skipped, failures };
+}
+
+/** One leased batch onto the target: steps, then the job, then the ack — per record. */
+async function transfer(
+  source: JobDriver,
+  target: JobDriver,
+  leased: readonly ClaimedJob[],
+  found: ReadonlyMap<string, JobRecord>,
+  moved: JobRecord[],
+  failures: DrainFailure[],
+): Promise<void> {
   for (const record of leased) {
     let enqueued = false;
     try {
@@ -159,5 +227,4 @@ export async function drainJobs(
       failures.push({ id: record.id, name: record.name, finding: findingFrom(error) });
     }
   }
-  return { ...base, dryRun: false, moved, skipped, failures };
 }

package/src/jobs-report.ts

@@ -127,10 +127,10 @@ export async function showJob(driver: JobDriver, id: string): Promise<JobTrace>
 // ── retry ─────────────────────────────────────────────────────────────────
 
 /**
- * Existence is checked up front so an unknown id always surfaces as `X_JOB_UNKNOWN`: the
- * concrete drivers (pg, memory) throw their own error from inside `requeue()` for a missing
- * row, and that error is not this command's contract — `retryFromStep`'s documented `undefined`
- * return is, and the driver never reaches it once the row is already known absent.
+ * Existence is checked up front so an unknown id always surfaces as `X_JOB_UNKNOWN`: both
+ * drivers answer `X_JOB_NOT_FOUND` from inside `requeue()` for a missing row, and that code is
+ * the driver's contract, not this command's — `retryFromStep`'s documented `undefined` return
+ * is, and the driver never reaches it once the row is already known absent.
  */
 export async function retryJob(
   driver: JobDriver,

package/src/loopback-host.ts

@@ -0,0 +1,13 @@
+// Whether a hostname is this machine: `localhost`, a `*.localhost` name (RFC 6761 reserves both
+// to loopback) or a loopback address literal. One answer for `x dev`'s Host check and `x doctor`'s
+// APP_URL rule, which ask the same question about two different headers.
+
+import { classifyAddress } from '@ultimat3/core';
+
+/** `hostname` as `URL` spells it — `[::1]` bracketed, no port. */
+export const isLoopbackHostname = (hostname: string): boolean => {
+  const name = hostname.toLowerCase();
+  return (
+    name === 'localhost' || name.endsWith('.localhost') || classifyAddress(name) === 'loopback'
+  );
+};

package/src/manifest-staleness.ts

@@ -0,0 +1,62 @@
+// Do the committed generated files still describe the code? ONE check, asked by `x manifest
+// --check` and by the gate's `manifest` step through this function — two commands answering
+// differently about one file is itself the drift these files exist to prevent.
+
+// why: Bun has no synchronous existence probe, and `hasCommittedContract` guards an app load.
+import { existsSync } from 'node:fs';
+// why: Bun exposes no path-join primitive; Bun.file takes a path already joined.
+import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { Manifest } from '@ultimat3/manifest';
+import { assertNoDrift, MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { OPENAPI_FILE, openApiStaleness } from './app-openapi';
+import { APP_CONFIG_FILE } from './app-root';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+/** Whether there is any committed contract here to judge — the cheap question, asked first. */
+export const hasCommittedContract = (root: string): boolean =>
+  existsSync(join(root, MANIFEST_FILENAME)) || existsSync(join(root, OPENAPI_FILE));
+
+/**
+ * `x.manifest.json` was never written. An app root only: the framework monorepo emits
+ * `framework.manifest.json` and has no `x.manifest.json` to be missing. `AGENTS.md` tells an agent
+ * that facts live in this file, and after `x new` and every generator nothing had run the one
+ * command that writes it while the gate reported green (#F7).
+ */
+export function manifestMissingFindings(root: string): readonly Finding[] {
+  if (!existsSync(join(root, APP_CONFIG_FILE))) return [];
+  if (existsSync(join(root, MANIFEST_FILENAME))) return [];
+  return [
+    {
+      code: 'X_MANIFEST_MISSING',
+      cause: `${MANIFEST_FILENAME} does not exist, so every fact an agent reads about this app — route table, action schemas, policies, error codes — is unavailable`,
+      fix: 'x manifest',
+      docs: ERROR_DOCS_URL,
+      at: MANIFEST_FILENAME,
+    },
+  ];
+}
+
+/**
+ * Every way the committed files disagree with `manifest`, the app as the code declares it now:
+ * `x.manifest.json` missing (`X_MANIFEST_MISSING`) or drifted (`X_MANIFEST_DRIFT` — a body that no
+ * longer hashes to its own `buildId` included), and `openapi.json` or a bearer mount's document
+ * stale (`X_MANIFEST_STALE`). The spec is judged whether or not the manifest is there: it is a
+ * published contract on its own, and the typed client is generated from it.
+ */
+export async function manifestStaleness(
+  root: string,
+  manifest: Manifest,
+): Promise<readonly Finding[]> {
+  const path = join(root, MANIFEST_FILENAME);
+  const findings: Finding[] = [...manifestMissingFindings(root)];
+  if (existsSync(path)) {
+    try {
+      await assertNoDrift({ manifest, path });
+    } catch (error) {
+      findings.push({ ...findingFrom(error), at: MANIFEST_FILENAME });
+    }
+  }
+  return [...findings, ...(await openApiStaleness(root, manifest))];
+}

package/src/mcp-errors.ts

@@ -51,7 +51,9 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x verify --only unit --json   # the finding carries the measured numbers and the "coverage" line to add to x.verify.json',
   X_COVERAGE_FLOOR_STALE:
     'x verify --only unit --json   # the finding carries the measured numbers; raise "coverage" in x.verify.json to them',
-  X_TEST_SHARD_FAILED: 'x test --workers 1 --json',
+  // Unthrown since `--worker` was deleted, and kept only because this record is typed over every
+  // registered code: `--shard i/n` is the one way to rerun a slice.
+  X_TEST_SHARD_FAILED: 'x verify --only unit --shard 1/2 --json',
   X_SCAFFOLD_PATH_ESCAPE: 'x g route posts --json   # a path with no ".." segment',
   X_GENERATE_JSON_INVALID:
     'bun test packages/cli/src/cmd-generate.test.ts   # the error names the template to fix',
@@ -118,8 +120,7 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x errors list --json   # register the code in its package src/errors.ts, or move its row under "Reserved codes"',
   X_ERROR_CODE_UNRESOLVED:
     'x verify --json   # the finding names the file, the line and the name it could not resolve',
-  X_ERROR_CODE_UNTHROWN:
-    'x errors explain X_ERROR_CODE_UNTHROWN --json   # then mark the row "registered, thrown by nothing since <version>"',
+  X_ERROR_CODE_UNTHROWN: 'x errors explain X_ERROR_CODE_UNTHROWN --json',
   X_CLI_UNEXPECTED: 'x doctor --json',
   // `-p .`: an app root has no `references`, so the gate's own step runs this form (#450).
   X_TYPECHECK_FAILED: 'bunx tsc -p . --pretty false',
@@ -284,6 +285,14 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'edit docker/Dockerfile: add RUN bun node_modules/@ultimat3/cli/src/bin.ts build --target prebuilt after COPY . . in the runtime stage, then rebuild the image',
   X_ADMIN_UNSCANNED:
     'git mv apps/admin/src/index.ts apps/admin/app/admin/admin.ts   # then repoint its relative imports and x verify --only manifest --json',
+  X_FRAMEWORK_TABLE_ORPHANED: 'x doctor --json',
+  X_BUILD_OUT_UNSAFE: 'x build --target static --out .x/static --json',
+  X_FRAMEWORK_SCHEMA_UNAPPLIED: 'x db migrate --json',
+  X_APP_URL_PORT_MISMATCH: 'export APP_URL=http://localhost:3000',
+  X_DEV_HOST_REFUSED: "curl -sS -H 'accept: application/json' http://localhost:3000/_x",
+  X_TRUSTED_PROXY_HOPS_INVALID: 'TRUSTED_PROXY_HOPS=1 ROLE=web bun apps/web/server.ts',
+  X_PERMISSION_BORROWED: 'x verify --only policy --json',
+  X_ERROR_CODE_UNTHROWN_STALE: 'x errors explain X_ERROR_CODE_UNTHROWN_STALE --json',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/mcp-host.ts

@@ -7,7 +7,13 @@
 // or prints inside a `fix:` an operator runs — the dev log, a per-role log, the committed
 // manifest — and string concatenation would answer a different path on a Windows checkout.
 import { join } from 'node:path';
-import { agentActor, isUltimateError, renderThrowable, UltimateError } from '@ultimat3/core';
+import {
+  agentActor,
+  isUltimateError,
+  NotImplementedError,
+  renderThrowable,
+  UltimateError,
+} from '@ultimat3/core';
 import type { DbClient } from '@ultimat3/db';
 import {
   ensureReadOnlyRole,
@@ -35,12 +41,11 @@ import { appManifest, policyFacts } from './app-manifest';
 import { runVerify, VERIFY_STEPS } from './cmd-verify';
 import { declareDevEnvironment } from './dev-environment';
 import { loadCodeFixes } from './error-fixes';
-import { BadFlagError, CliNotImplementedError } from './errors';
+import { BadFlagError } from './errors';
 import type { Runner } from './exec';
-import { execOutput } from './exec';
 import { databaseTarget } from './mcp-db-target';
 import { explainErrorCode } from './mcp-errors';
-import { parseBunTest } from './mcp-test-output';
+import { testRunOf } from './mcp-test-run';
 import { type UiCapabilities, uiCapabilities } from './mcp-ui';
 import { readMigrations } from './migrations';
 import { retryMemo } from './retry-memo';
@@ -107,8 +112,9 @@ export function lazyServices(input: DevHostInput): LazyServices {
       // A boot started after close() would hold the PGlite data directory for the life of the
       // process with nobody left to stop it — the host is closed, so the call is the bug.
       if (closed) {
-        throw new CliNotImplementedError({
-          feature: 'an MCP tool that needs the database after the host closed',
+        throw new NotImplementedError({
+          cause:
+            'an MCP tool that needs the database after the host closed is not implemented in this build',
           fix: 'x mcp serve --transport stdio   # keep the host open for the whole session',
         });
       }
@@ -271,7 +277,8 @@ function capabilities(
         cwd: root,
         ...(Object.keys(envOverrides).length === 0 ? {} : { env: envOverrides }),
       });
-      return parseBunTest(execOutput(result), result.durationMs);
+      // The whole result, exit code included: `0 fail` beside `1 error` is a red run.
+      return testRunOf(result);
     },
 
     async tailLogs(lines: number, role: string | undefined) {
@@ -281,8 +288,8 @@ function capabilities(
       if (!(await file.exists())) {
         // `@ultimat3/core`'s `logger` is a module const with no sink seam, so there is nothing to
         // intercept in-process — a log on disk is the only honest source, and the fix creates one.
-        throw new CliNotImplementedError({
-          feature: `logs.tail without ${path}`,
+        throw new NotImplementedError({
+          cause: `logs.tail without ${path} is not implemented in this build`,
           fix:
             role === undefined
               ? `x dev > ${path} 2>&1`

package/src/mcp-test-run.ts

@@ -0,0 +1,38 @@
+// `test.run`'s answer from the whole `bun test` result, not from its pass/fail lines alone: bun
+// counts an error raised OUTSIDE any test on a line of its own (`1 error`) beside `0 fail`, and
+// says the run failed only through its exit code.
+
+import type { TestRun } from '@ultimat3/mcp';
+import type { ExecResult } from './exec';
+import { execOutput } from './exec';
+import { parseBunTest } from './mcp-test-output';
+
+/** Bun's own `N error` / `N errors` summary line: the last one, as `parseBunTest` reads the rest. */
+export const errorsIn = (output: string): number => {
+  const last = [...output.matchAll(/^\s*(\d+)\s+errors?\s*$/gm)].at(-1);
+  return last === undefined ? 0 : Number.parseInt(last[1] ?? '0', 10);
+};
+
+/**
+ * Every error outside a test is one failure, carried with the run's own message; a non-zero exit
+ * with nothing else counted is one more, so a red process can never answer `failed: 0`.
+ */
+export function testRunOf(result: ExecResult): TestRun {
+  const output = execOutput(result);
+  const run = parseBunTest(output, result.durationMs);
+  const errors = errorsIn(output);
+  const outside = Array.from({ length: errors }, () => ({
+    test: 'bun test',
+    message: 'an error outside any test — a file that threw while loading, or a failed hook',
+  }));
+  const counted = run.failed + errors;
+  const exitOnly =
+    result.code !== 0 && counted === 0
+      ? [{ test: 'bun test', message: `bun test exited ${String(result.code)} with no failure` }]
+      : [];
+  return {
+    ...run,
+    failed: counted + exitOnly.length,
+    failures: [...run.failures, ...outside, ...exitOnly],
+  };
+}

package/src/messages.ts

@@ -197,6 +197,8 @@ const CATALOG = {
   'cli.registry.described': '{kind} {name}',
   'cli.routes.count': '{count} routes',
   'cli.routes.empty': 'no routes in the manifest — run `x manifest` first',
+  'cli.auth.sealed':
+    'sealed {sealed} second-factor secret(s); {already} already sealed, {skipped} changed mid-run and left alone',
   'cli.tasks.count': '{count} task(s)',
   'cli.tasks.shown': '{name} — {cron} ({tz}), next {next}',
   'cli.affected.count':

package/src/metrics-endpoint.ts

@@ -5,11 +5,14 @@
 
 import {
   finiteCount,
+  type HealthPayload,
+  healthzPayload,
   logger,
   METRICS_CONTENT_TYPE,
   METRICS_PATH,
   markListening,
   metricsText,
+  readyzPayload,
   startProcessMetrics,
   stringField,
   UltimateError,
@@ -123,6 +126,18 @@ export interface MetricsEndpoint {
   stop(): void;
 }
 
+/**
+ * `/healthz` and `/readyz` for the roles whose only socket this is — `worker`, `scheduler`,
+ * `replicator` — so the replicator's readiness check (`role-replicator.ts`) is read by a probe.
+ * The verdict only, never the report: this port is unauthenticated, and check names are topology.
+ */
+function healthResponse(payload: HealthPayload, role: string): Response {
+  return Response.json(
+    { state: payload.body.state, ready: payload.body.ready, role },
+    { status: payload.status, headers: { 'cache-control': 'no-store' } },
+  );
+}
+
 /**
  * Answers outside the request pipeline, exactly as `/healthz` and `/readyz` do in
  * `@ultimat3/http`'s `server.ts`: no auth, no rate limit, no locale negotiation. A saturated or
@@ -142,7 +157,16 @@ export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): Metr
       port: candidate,
       hostname: options.hostname ?? 'localhost',
       fetch(request: Request): Response {
-        if (new URL(request.url).pathname !== METRICS_PATH) {
+        const url = new URL(request.url);
+        const role = options.role ?? 'unknown';
+        if (url.pathname === '/healthz') return healthResponse(healthzPayload(), role);
+        if (url.pathname === '/readyz') {
+          return healthResponse(
+            readyzPayload({ deep: url.searchParams.get('deep') === '1' }),
+            role,
+          );
+        }
+        if (url.pathname !== METRICS_PATH) {
           return new Response('not found', { status: 404 });
         }
         // `collectMetrics()` is cumulative and never reset by a read, so two scrapers cannot

package/src/output.ts

@@ -29,6 +29,12 @@ export interface Finding {
    * and must never be run as this CLI's own instruction.
    */
   readonly source?: 'ci-log';
+  /**
+   * Structured facts behind `cause`, for a `--json` reader that would otherwise parse the sentence:
+   * `X_VERIFY_STEP_TIMEOUT` carries the processes it killed and the files still in flight. Never
+   * the only home of a fact — the human render prints `cause` and `fix`, and both already say it.
+   */
+  readonly meta?: { readonly [key: string]: JsonValue };
 }
 
 export interface StepResult {

package/src/page-navigation.ts

@@ -6,12 +6,9 @@
 // check a soft visit gets before `load`. No surface opted in: nothing is built, served or named — a
 // `site/` page that did not ask stays 0kb (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 { clientScopeOf } from '@ultimat3/auth';
 import type { Ctx, NavigationSurface } from '@ultimat3/core';
-import { CLIENT_NAVIGATION_SCOPE_HEADER, NAVIGATION_SURFACES } from '@ultimat3/core';
+import { CLIENT_NAVIGATION_SCOPE_HEADER } from '@ultimat3/core';
 import type { Route, RouteNavigation, UltimateRequest } from '@ultimat3/http';
 import { locationFor, navigationPurpose, relocate } from '@ultimat3/http';
 import type { ClientNavigationHead, HeadTag, RouteEntry } from '@ultimat3/render';
@@ -22,8 +19,7 @@ import {
   routeEntries,
 } from '@ultimat3/render';
 import { ssrHeaders } from '@ultimat3/render/server';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 import { FrameworkScriptBuildFailedError } from './errors';
 import {
   buildNavigationScript,
@@ -56,26 +52,14 @@ export interface NavigationDeclaration {
   readonly surfaces: readonly NavigationSurface[];
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-const isSurface = (value: unknown): value is NavigationSurface =>
-  NAVIGATION_SURFACES.some((surface) => surface === value);
-
 /**
- * `navigation.client` and `name`, as `defineConfig` validated them — no surfaces when the app says
- * nothing or has no config file. Structural, never `instanceof`, for `loadThemeMode`'s reason.
+ * `navigation.client` and `name`, off the one loader (`app-config-load.ts`) — no surfaces, and the
+ * app called `app`, for a root with no config file.
  */
 export async function loadNavigation(root: string): Promise<NavigationDeclaration> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(configPath).exists())) return { app: 'app', surfaces: [] };
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!isRecord(config)) return { app: 'app', surfaces: [] };
-  const app = typeof config['name'] === 'string' ? config['name'] : 'app';
-  const navigation = config['navigation'];
-  const client = isRecord(navigation) ? navigation['client'] : undefined;
-  return { app, surfaces: Array.isArray(client) ? client.filter(isSurface) : [] };
+  const config = await loadAppConfig(root);
+  if (config === undefined) return { app: 'app', surfaces: [] };
+  return { app: config.name, surfaces: config.navigation.client };
 }
 
 /**

package/src/page-speculation.ts

@@ -5,11 +5,8 @@
 // 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 { DEFAULT_SPECULATION, localeSegment } from '@ultimat3/core';
 import { cspHashSource } from '@ultimat3/http';
 import { localeConfig, routedLocales } from '@ultimat3/i18n';
 import type { RouteDescriptor, RouteEntry } from '@ultimat3/render';
@@ -21,26 +18,14 @@ import {
   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;
+import { loadAppConfig } from './app-config-load';
 
 /**
- * `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.
+ * `navigation.speculation` off the one loader (`app-config-load.ts`), which holds it to core's
+ * `resolveSpeculation` — the default (on, `'moderate'`) for a root with no config file.
  */
 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);
+  return (await loadAppConfig(root))?.navigation.speculation ?? DEFAULT_SPECULATION;
 }
 
 /**

package/src/prerender-out.ts

@@ -1,25 +1,52 @@
 // The export directory is the build's own, and emptied before every build: `prerenderSite` only
 // ever ADDED files, so a route deleted from the app kept shipping its last HTML from `.x/static`.
-// Refused when `out` is the app root or above it — an `rm -rf` there deletes the app.
+// Emptied only when it is provably the build's: absent, empty, or marked by an earlier build —
+// `--out apps` deleted the app's pages and `--out .x` its embedded dev database.
 
-import { rm } from 'node:fs/promises'; // why: Bun has no recursive directory delete.
-import { isAbsolute, relative, resolve, sep } from 'node:path'; // why: Bun ships no path resolve/relative.
+import { lstat, readdir, rm } from 'node:fs/promises'; // why: Bun has no recursive delete or readdir.
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'; // why: Bun ships no path resolve/relative.
 import { UltimateError } from '@ultimat3/core';
 
+/** Written into every export directory a build empties: the proof the next build may empty it. */
+export const EXPORT_MARKER = '.x-export';
+
+/**
+ * The export directory `x build --target static` chooses itself. Exempt from the marker: a build
+ * from before the marker existed left it full and unmarked, and the build owns this path by name.
+ */
+const DEFAULT_EXPORT = join('.x', 'static');
+
+const MARKER_TEXT =
+  'Written by x build --target static. This directory is emptied before every static build.\n';
+
 /** True when `dir` is `root` itself or one of its ancestors. */
 const containsRoot = (dir: string, root: string): boolean => {
   const up = relative(resolve(dir), resolve(root));
   return up === '' || (up !== '..' && !up.startsWith(`..${sep}`) && !isAbsolute(up));
 };
 
-/** Empties `out` for a fresh export, or refuses a directory that holds the app. */
+/** Why `out` is not the build's to empty, or `undefined` when it is. */
+async function unsafeReason(out: string, root: string): Promise<string | undefined> {
+  if (containsRoot(out, root)) return 'is the app root or holds it';
+  const stat = await lstat(out).catch(() => undefined);
+  if (stat === undefined) return undefined;
+  if (!stat.isDirectory()) return 'is not a directory';
+  const entries = await readdir(out);
+  if (entries.length === 0 || entries.includes(EXPORT_MARKER)) return undefined;
+  if (resolve(out) === resolve(root, DEFAULT_EXPORT)) return undefined;
+  return `already holds ${entries.length} entr${entries.length === 1 ? 'y' : 'ies'} and no ${EXPORT_MARKER} a previous build wrote`;
+}
+
+/** Empties `out` for a fresh export and marks it, or refuses a directory the build did not write. */
 export async function clearPrerenderOut(out: string, root: string): Promise<void> {
-  if (containsRoot(out, root)) {
+  const reason = await unsafeReason(out, root);
+  if (reason !== undefined) {
     throw new UltimateError({
-      code: 'X_CLI_BAD_FLAG',
-      cause: `the static export directory ${resolve(out)} is the app root or holds it, and every build empties its export directory first`,
+      code: 'X_BUILD_OUT_UNSAFE',
+      cause: `the static export directory ${resolve(out)} ${reason}, and every build empties its export directory first`,
       fix: 'x build --target static --out .x/static --json',
     });
   }
   await rm(out, { recursive: true, force: true });
+  await Bun.write(join(out, EXPORT_MARKER), MARKER_TEXT);
 }