@ultimat3/cli 22.15.0 → 24.0.0

package/src/templates/slice-foundation.ts

@@ -4,6 +4,7 @@
 // none of them, so each emitted TS2307 in any slice a resource had not been run in first.
 
 import { stripComments } from '@ultimat3/core';
+import { adminCatalogFiles } from './admin-catalog';
 import type { FeatureTarget } from './entity';
 import { entityFiles } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
@@ -74,16 +75,24 @@ const ifAbsent = (files: readonly GeneratedFile[]): readonly GeneratedFile[] =>
 export function sliceFoundation(
   target: FeatureTarget,
   needs: readonly SliceModule[],
+  /** Every locale the planted entity's admin labels ship for. Defaults to `['en']`. */
+  locales?: readonly string[],
 ): readonly GeneratedFile[] {
   const feature = names(target.feature);
   const dir = `${target.surfaceDir}/${target.feature}`;
-  return ifAbsent([
-    ...(needs.includes('entity') ? entityFiles(target.feature, target) : []),
-    ...(needs.includes('policy') ? policyFiles(target.feature, target) : []),
-    ...(needs.includes('errors')
-      ? [{ path: `${dir}/errors.ts`, contents: errorsSource(feature) }]
-      : []),
-  ]);
+  return [
+    ...ifAbsent([
+      ...(needs.includes('entity') ? entityFiles(target.feature, target) : []),
+      ...(needs.includes('policy') ? policyFiles(target.feature, target) : []),
+      ...(needs.includes('errors')
+        ? [{ path: `${dir}/errors.ts`, contents: errorsSource(feature) }]
+        : []),
+    ]),
+    // A planted entity joins the typed handle, and an entity in the handle IS an admin screen —
+    // so it gets the labels `x g entity` writes for one, or its nav entry renders a missing-key
+    // marker. A catalog MERGE, never `if-absent`: a key already there keeps the value it has.
+    ...(needs.includes('entity') ? adminCatalogFiles(target.feature, target, locales) : []),
+  ];
 }
 
 /** The exported names an `export { a, b as c }` list declares — `c`, never `b`. */
@@ -117,10 +126,39 @@ export function sliceExports(source: string, name: string): boolean {
   const code = stripComments(source);
   // `(?:async\s+)?` before `function`: an `export async function byId` — every repo function
   // `x g entity` scaffolds — matched neither this nor `listedExports`, so a caller checking for
-  // `byId`/`listByOrg` on a real repo.ts always read `false`. `async` has no meaning before
+  // `byId`/`list` on a real repo.ts always read `false`. `async` has no meaning before
   // `class`/`const`/`let`/`var`/`enum`, so it is scoped to `function` only.
   const declared = new RegExp(
     `\\bexport\\s+(?:abstract\\s+)?(?:class|const|let|var|(?:async\\s+)?function|enum)\\s+${name}\\b`,
   );
   return declared.test(code) || listedExports(code).includes(name);
 }
+
+/** `    title: text({ max: 200 }),` — one column of an entity, as its name and its builder. */
+const COLUMN_LINE = /^ {4}([A-Za-z_$][\w$]*): ([A-Za-z_$][\w$]*)\(/gm;
+
+const columnsOf = (entitySource: string): string =>
+  [...stripComments(entitySource).matchAll(COLUMN_LINE)]
+    .map((match) => `${match[1] ?? ''}: ${match[2] ?? ''}`)
+    .join(', ');
+
+/**
+ * Whether a generated TEST may store a row in this slice: its entity declares exactly the columns
+ * `x g entity` scaffolds for this feature — read off the entity this generator would write, never
+ * a second list — and its `repo.ts`, when one is on disk, still exports `insert`. A slice an author
+ * reshaped has a row this generator cannot spell (one more required column is enough), so its
+ * tests assert the branches that need none and leave the stored-row case to the author.
+ */
+export function sliceTakesScaffoldRow(
+  target: FeatureTarget,
+  sliceEntity: string | undefined,
+  sliceRepo: string | undefined,
+): boolean {
+  if (sliceEntity === undefined) return false;
+  const scaffold = entityFiles(target.feature, target).find((file) =>
+    file.path.endsWith('/entity.ts'),
+  );
+  const wanted = columnsOf(String(scaffold?.contents ?? ''));
+  if (wanted === '' || columnsOf(sliceEntity) !== wanted) return false;
+  return sliceRepo === undefined || sliceExports(sliceRepo, 'insert');
+}

package/src/test-counts.ts

@@ -5,12 +5,21 @@
 import type { ExecResult } from './exec';
 import { execOutput } from './exec';
 import { parseBunTest } from './mcp-test-output';
+// One reader of bun's `N errors` line, shared with MCP `tests.run` — never a second regex.
+import { errorsIn } from './mcp-test-run';
 
 export interface TestCounts {
   /** Tests that executed — passed plus failed. A failed test is a test that ran. */
   readonly ran: number;
   /** Tests bun reported as skipped or todo, which is the same thing here: they did not run. */
   readonly skipped: number;
+  /**
+   * Errors raised OUTSIDE any test — a `describe` body or a module that threw on load, a failed
+   * hook — which bun counts on a line of their own (`1 error`) beside `0 fail`. Present only when
+   * there were some: the exit code already makes the step red, and without this number the step
+   * line read "12 ran, 0 skipped" over a run whose file never got as far as declaring a test.
+   */
+  readonly errors?: number;
 }
 
 /**
@@ -26,10 +35,13 @@ export interface TestCounts {
 export const countsOf = (results: readonly ExecResult[]): TestCounts => {
   let ran = 0;
   let skipped = 0;
+  let errors = 0;
   for (const result of results) {
-    const run = parseBunTest(execOutput(result), result.durationMs);
+    const output = execOutput(result);
+    const run = parseBunTest(output, result.durationMs);
     ran += run.passed + run.failed;
     skipped += run.skipped;
+    errors += errorsIn(output);
   }
-  return { ran, skipped };
+  return { ran, skipped, ...(errors === 0 ? {} : { errors }) };
 };

package/src/test-ignores.ts

@@ -0,0 +1,25 @@
+// The ONE policy for which paths are never a test the gate runs here, projected twice: the path
+// predicate `discoverTests` filters by and the `--path-ignore-patterns` the serial steps pass to
+// `bun test`. A leaf, so `test-select.ts` and `verify-tests.ts` (which import each other) share it.
+
+/** Build output and installed packages: never a test, at ANY depth — a workspace's `dist/` too. */
+const IGNORED_ANYWHERE = ['dist', 'node_modules'] as const;
+
+/**
+ * Nested projects with their own gate (`examples/`, `dummy/`, run by
+ * `scripts/reference-app-gate.ts`) and the root `build/` — skipped AT THE ROOT only. Matched at any
+ * depth they swallowed an app's own slice: `x g resource build` lost 14 of its 16 test files and
+ * `x g resource example` its `examples/` page tests, from `x test` and the gate alike.
+ */
+const IGNORED_AT_ROOT = ['build', 'examples', 'dummy'] as const;
+
+/** Whether a root-relative POSIX path is excluded from every test selection. */
+export const isIgnoredTestPath = (path: string): boolean =>
+  IGNORED_ANYWHERE.some((dir) => `/${path}`.includes(`/${dir}/`)) ||
+  IGNORED_AT_ROOT.some((dir) => path.startsWith(`${dir}/`));
+
+/** The same policy as `bun test --path-ignore-patterns` globs, relative to the run's root. */
+export const IGNORED_TEST_PATTERNS: readonly string[] = [
+  ...IGNORED_ANYWHERE.map((dir) => `**/${dir}/**`),
+  ...IGNORED_AT_ROOT.map((dir) => `${dir}/**`),
+];

package/src/test-passes.ts

@@ -24,8 +24,6 @@ export interface PassInput {
   readonly workers: number;
   /** The positional, when there was one. A pass over one type keeps it; the split never adds one. */
   readonly type?: TestType;
-  /** Set for a `--worker I` rerun, which is one process by construction. */
-  readonly shard?: number;
 }
 
 const widthFor = (files: readonly TestFile[], workers: number): number =>
@@ -45,22 +43,9 @@ const widthFor = (files: readonly TestFile[], workers: number): number =>
  *
  * Each serial type is its own pass rather than one pass over both, because the pass's `type` is
  * what its failure reproduces with: `x test live --workers 1` selects exactly the files that ran.
- *
- * A `--worker I` rerun is left whole: it is a single `bun test --isolate --shard=i/N` process, so
- * nothing inside it runs beside anything else, and splitting it would make shard i of the rerun a
- * different set of files from shard i of the run it reproduces.
  */
 export function testPasses(input: PassInput): readonly TestPass[] {
   const serialTypes = new Set<TestType>(SERIAL_TYPES);
-  if (input.shard !== undefined) {
-    return [
-      {
-        files: input.files,
-        workers: widthFor(input.files, input.workers),
-        ...(input.type === undefined ? {} : { type: input.type }),
-      },
-    ];
-  }
   const shared = input.files.filter((file) => !serialTypes.has(ownerOf(file.path)));
   const passes: TestPass[] = [];
   // Cheapest first, and the widest first: the pool run is most of the corpus and most of the

package/src/test-select.ts

@@ -9,6 +9,7 @@ import { nearestName, renderFixShellArg } from '@ultimat3/core';
 import { BadFlagError } from './errors';
 import type { ParsedArgs } from './parse';
 import { flagString } from './parse';
+import { isIgnoredTestPath } from './test-ignores';
 import type { TestType } from './verify-tests';
 import { ownerOf, TEST_TYPES } from './verify-tests';
 
@@ -27,20 +28,10 @@ const TEST_GLOB = '**/*.test.{ts,tsx}';
 
 /**
  * The root `test` script's ignore list, kept identical so `x test` and `bun run test` see one
- * suite. `e2e/` is NOT on it: an opt-in suite that the gate runs but `x test` silently drops is
- * a suite nobody runs until CI says so. `examples/` is, because the reference app is a separate
- * project with its own gate — `x verify` there, not `x test` here.
- *
- * `dummy/` and `build/` complete the list `verify-tests.ts` already excluded (`NEVER_A_TEST`). The
- * comment above claimed the two agreed and they did not: `x test unit` discovered 464 files where
- * the gate's `unit` step ran 441, so the gate's own test steps — which now select through this
- * function — would have started running a nested demo app's suite on the framework's gate.
- *
- * Both directories are gated where they belong, by `scripts/reference-app-gate.ts` running
- * `x verify` inside each app — see `NEVER_A_TEST` for why that is the only place they run.
+ * suite — `test-ignores.ts` holds it, and the serial steps' argv projects the same policy. `e2e/`
+ * is NOT on it: an opt-in suite that the gate runs but `x test` silently drops is a suite nobody
+ * runs until CI says so.
  */
-const IGNORED = ['/dist/', '/build/', '/node_modules/', '/examples/', '/dummy/'];
-
 /**
  * File size stands in for duration: cheap to read, and it correlates far better than file count.
  * `type`, when given, narrows to exactly the files verify-tests.ts would run for that suite — one
@@ -58,7 +49,7 @@ export async function discoverTests(
   const files: TestFile[] = [];
   for await (const found of new Bun.Glob(TEST_GLOB).scan({ cwd: root, absolute: false })) {
     const path = found.split('\\').join('/');
-    if (IGNORED.some((part) => `/${path}`.includes(part))) continue;
+    if (isIgnoredTestPath(path)) continue;
     if (filters !== undefined && !filters.some((part) => path.includes(part))) continue;
     if (type !== undefined && !belongsToType(path, type)) continue;
     files.push({ path, bytes: Bun.file(join(root, path)).size });

package/src/test-shards.ts

@@ -39,12 +39,12 @@
 // `@ultimat3/testing`'s preload clears the plugins after each file (`isolated-plugins.ts`). And the
 // per-WORKER database survives untouched: `@ultimat3/testing`'s `workerId` already read
 // `BUN_TEST_WORKER_ID` as its second key, which is exactly what Bun sets, 1..N, one per real
-// process (probed on 1.4.0). `ULTIMATE_TEST_WORKER` stays the first key and is what `--worker`
-// still sets, so a single-shard rerun keeps naming its own database.
+// process (probed on 1.4.0).
 
 // why: Bun ships no path-join primitive; the timings cache lives under the run's root.
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { ISOLATED_ENV } from '@ultimat3/testing';
 import type { AffectedSelection } from './affected';
 import type { Runner } from './exec';
 import { msg } from './messages';
@@ -52,8 +52,8 @@ import type { CommandResult, Finding, JsonValue, StepResult } from './output';
 import { quoteArg } from './shell-quote';
 import { testEnvOverrides } from './test-dotenv';
 
-/** `@ultimat3/testing`'s `ISOLATED_ENV`, restated: `cli → testing` is a runtime edge, kept to fixtures. */
-export const ISOLATED_TEST_ENV = 'ULTIMATE_TEST_ISOLATED';
+/** `@ultimat3/testing`'s `ISOLATED_ENV` — the one spelling, which that package's preload reads. */
+export const ISOLATED_TEST_ENV = ISOLATED_ENV;
 
 /** Bun's per-file durations, cached under the run's root and refreshed by every parallel run. */
 export const TEST_TIMINGS_FILE = '.x/test-timings.json';
@@ -68,24 +68,13 @@ import type { TestType } from './verify-tests';
  * The argv for one run. An explicit file list, never a re-glob: discovery already decided which
  * files belong to this type, and a child that globs again can pick up a file the selection removed.
  *
- * `--parallel=N` for the whole selection, `--shard=i+1/N` for one slice of it. The shard form is
- * `--worker`'s, and it carries `--isolate` in its own right — only `--parallel` implies it, and a
- * partition without a fresh module registry per file is the failure mode this whole design exists
- * to remove: measured on this repo, an 8-way split turned 0 failures into 36, every one
- * `X_PERMISSION_UNKNOWN` in `@ultimat3/query` because the `packages/cli` file that had been
- * declaring `feed:read` for it landed elsewhere. Half a dozen registries here are process-global by
- * design — the permission set, the roles, the entity/action/query tables, the error-code titles,
- * the fixture bag — and a serial `bun test` only passes because glob order happens to put every
- * declaring file before every file that reads what it left behind.
- *
- * Bun's shard partition is round-robin over the list it is given, so the sorted list this hands it
- * makes `--shard=2/8` the same 1/8 on CI and on a laptop (probed on 1.4.0).
+ * `--parallel=N` over the selection, sorted, so two runs over one corpus hand Bun the same list.
+ * One CI job's share of the corpus is `x verify --only unit --shard i/n` (`verify-shard.ts`), never
+ * a flag here: `x test --worker I` was a second, 0-based, unhashed split of the same suite.
  */
 export function testArgs(input: {
   readonly files: readonly string[];
   readonly workers: number;
-  /** 0-based, matching `--worker`. Absent runs the whole selection across `workers` processes. */
-  readonly shard?: number;
   /**
    * Everything after a bare `--`, handed to `bun test` verbatim and BEFORE the file list, which is
    * where bun reads its flags. `ParsedArgs.passthrough` had no reader anywhere until 2026-09, so
@@ -114,32 +103,23 @@ export function testArgs(input: {
   const isolate =
     extra.includes('--isolate') || (input.isolate === true && !extra.includes('--no-isolate'));
   const bare = extra.filter((arg) => arg !== '--isolate' && arg !== '--no-isolate');
-  return input.shard === undefined
-    ? [
-        'bun',
-        'test',
-        `--parallel=${String(input.workers)}`,
-        ...(isolate ? [] : ['--no-isolate']),
-        ...(input.timings === undefined || bare.some((arg) => arg.startsWith('--timings'))
-          ? []
-          : [`--timings=${input.timings}`, '--update-timings']),
-        ...bare,
-        ...files,
-      ]
-    : [
-        'bun',
-        'test',
-        ...(isolate ? ['--isolate'] : []),
-        `--shard=${String(input.shard + 1)}/${String(input.workers)}`,
-        ...bare,
-        ...files,
-      ];
+  return [
+    'bun',
+    'test',
+    `--parallel=${String(input.workers)}`,
+    ...(isolate ? [] : ['--no-isolate']),
+    ...(input.timings === undefined || bare.some((arg) => arg.startsWith('--timings'))
+      ? []
+      : [`--timings=${input.timings}`, '--update-timings']),
+    ...bare,
+    ...files,
+  ];
 }
 
 /**
  * The files an argv selects, flags stripped. `bun test` takes its file list positionally, so this
  * is the inverse of `testArgs` and the one thing a test asserting "what did the child get?" needs
- * — the flag COUNT is not fixed (`--parallel=N` is one token, a shard run carries two more), and a
+ * — the flag COUNT is not fixed (`--no-isolate` and the timings pair come and go), and a
  * test slicing a hardcoded prefix length reads a flag as a filename the day that changes.
  */
 export const filesIn = (command: readonly string[]): readonly string[] =>
@@ -154,12 +134,9 @@ export interface ReproduceOptions {
   readonly sample?: number;
   /**
    * The `--affected` narrowing, when there was one. The input most easily forgotten: `--affected`
-   * decides which files exist to run at all, so a rerun without it selects the WHOLE corpus and
-   * its shard 2 is a different shard 2.
+   * decides which files exist to run at all, so a rerun without it selects the WHOLE corpus.
    */
   readonly affected?: AffectedSelection;
-  /** 0-based, when reproducing ONE shard. Absent reproduces the whole selection. */
-  readonly shard?: number;
   /** What the caller put after `--`. It reaches `bun test`, so a rerun without it runs differently. */
   readonly passthrough?: readonly string[];
   /** The run was isolated per file; the rerun must be too. */
@@ -185,7 +162,6 @@ export function reproduceFor(options: ReproduceOptions): string {
     ...(options.affected?.dirty === true ? ['--dirty'] : []),
     '--workers',
     String(options.workers),
-    ...(options.shard === undefined ? [] : ['--worker', String(options.shard)]),
     ...(options.isolate === true ? ['--isolate'] : []),
     // Last, and after a `--` of its own, because that is where the caller typed it and where the
     // parser will find it again. Quoted for `shell-quote.ts`'s reason: a reproduce line is pasted.
@@ -200,14 +176,11 @@ export interface RunShardsOptions {
   readonly runner: Runner;
   readonly files: readonly TestFile[];
   readonly workers: number;
-  /** Run exactly one shard of the same N-way split, not a one-worker run of everything. */
-  readonly only?: number;
   readonly filter?: string;
   readonly type?: TestType;
   /**
    * Set when `--sample` narrowed `files`: `kept` is what survived, `total` what discovery found.
-   * `kept` is carried rather than counted from what ran, because `--worker N` runs one shard of the
-   * sample and would otherwise report that shard's size as the corpus.
+   * Carried rather than counted from what ran: a pass runs part of the sample, never the corpus.
    */
   readonly sample?: { readonly kept: number; readonly total: number };
   /** Passed straight to `reproduceFor`: see `ReproduceOptions.affected`. */
@@ -248,7 +221,6 @@ const planOf = (
   ...(pass.type === undefined ? {} : { type: pass.type }),
   ...(options.sample === undefined ? {} : { sample: options.sample.kept }),
   ...(options.affected === undefined ? {} : { affected: options.affected }),
-  ...(options.only === undefined ? {} : { shard: options.only }),
   ...(options.isolate === true ? { isolate: true } : {}),
   ...(options.passthrough === undefined || options.passthrough.length === 0
     ? {}
@@ -256,17 +228,12 @@ const planOf = (
 });
 
 /**
- * `X_TEST_SHARD_FAILED` for a `--worker` run and `X_TEST_FAILED` for a whole one, because the two
- * name different reruns: a shard is reproduced by naming it, and a full run by rerunning it. Both
- * codes already exist and both are already documented — a third would be a new name for a failed
- * `bun test`.
+ * `X_TEST_FAILED`, whose `fix:` reruns exactly what failed. `X_TEST_SHARD_FAILED` was the
+ * `--worker` rerun's and went with it: the code stays registered (codes are forever) and unthrown.
  */
 export const failureOf = (code: number, files: number, plan: ReproduceOptions): Finding => ({
-  code: plan.shard === undefined ? 'X_TEST_FAILED' : 'X_TEST_SHARD_FAILED',
-  cause:
-    plan.shard === undefined
-      ? `${plan.type ?? 'test'} run exited ${code} across ${plan.workers} worker(s) (${files} file(s))`
-      : `shard ${plan.shard} of ${plan.workers} exited ${code} (${files} file(s))`,
+  code: 'X_TEST_FAILED',
+  cause: `${plan.type ?? 'test'} run exited ${code} across ${plan.workers} worker(s) (${files} file(s))`,
   fix: reproduceFor(plan),
   docs: ERROR_DOCS_URL,
 });
@@ -281,12 +248,10 @@ export const failureOf = (code: number, files: number, plan: ReproduceOptions):
  * it. And every pass runs even after one fails — the caller asked for a suite, and a report that
  * stops at the first red step hides the rest of the answer.
  *
- * `ULTIMATE_TEST_WORKER` is still set for a `--worker` rerun and only then: that run is one
- * process, so naming its database is this file's to do. A `--parallel` run has N of them and Bun
- * numbers each with `BUN_TEST_WORKER_ID`, which `@ultimat3/testing`'s `workerId` already reads.
+ * No `ULTIMATE_TEST_WORKER` here: a `--parallel` run has N processes and Bun numbers each with
+ * `BUN_TEST_WORKER_ID`, which `@ultimat3/testing`'s `workerId` already reads.
  */
 export async function runShards(options: RunShardsOptions): Promise<CommandResult> {
-  const only = options.only;
   // Computed ONCE per invocation, never per pass: every pass spawns from the same `root` and the
   // same parent env, so the leaked-key set cannot differ pass to pass.
   const envOverrides: Record<string, string | undefined> = {
@@ -302,7 +267,6 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
     files: options.files,
     workers: options.workers,
     ...(options.type === undefined ? {} : { type: options.type }),
-    ...(only === undefined ? {} : { shard: only }),
   });
   const started = performance.now();
   const steps: StepResult[] = [];
@@ -312,53 +276,38 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
   let exitCode = 0;
   for (const pass of passes) {
     const files = pass.files.map((file) => file.path);
-    // A `--worker` rerun is one process over one shard and is never split: shard i of the rerun
-    // must be the same files as shard i of the run it reproduces. Nor is `-- --watch`, which never
-    // exits, so a second batch would never start. Every other pass is spent in `test-batches.ts`'
-    // batches, one `bun test` after another.
-    const batches =
-      only === undefined && !watching
-        ? testBatches(
-            files,
-            pass.workers,
-            isolatedRun(options) ? BATCH_FILES_PER_WORKER : SHARED_BATCH_FILES_PER_WORKER,
-          )
-        : [files];
+    // `-- --watch` is never split: it never exits, so a second batch would never start. Every
+    // other pass is spent in `test-batches.ts`' batches, one `bun test` after another.
+    const batches = !watching
+      ? testBatches(
+          files,
+          pass.workers,
+          isolatedRun(options) ? BATCH_FILES_PER_WORKER : SHARED_BATCH_FILES_PER_WORKER,
+        )
+      : [files];
     const result = await runBatches({
       runner: options.runner,
       batches,
       stopOnFailure: bailing,
       workers: pass.workers,
-      // A `--worker` rerun is one process whatever its N says, and a serial pass is one worker:
-      // only a default-width parallel pass leases from the machine pool.
-      ...(only === undefined && pass.workers > 1 && options.lease !== undefined
-        ? { lease: options.lease }
-        : {}),
+      // A serial pass is one worker: only a default-width parallel pass leases from the pool.
+      ...(pass.workers > 1 && options.lease !== undefined ? { lease: options.lease } : {}),
       argsFor: (batch, width) =>
         testArgs({
           files: batch,
-          workers: only === undefined ? width : pass.workers,
-          ...(only === undefined ? {} : { shard: only }),
+          workers: width,
           ...(options.passthrough === undefined ? {} : { passthrough: options.passthrough }),
           ...(options.isolate === undefined ? {} : { isolate: options.isolate }),
           timings: join(options.root, TEST_TIMINGS_FILE),
         }),
       options: {
         cwd: options.root,
-        ...(Object.keys(envOverrides).length === 0 && only === undefined
-          ? {}
-          : {
-              env: {
-                ...envOverrides,
-                ...(only === undefined ? {} : { ULTIMATE_TEST_WORKER: String(only) }),
-              },
-            }),
+        ...(Object.keys(envOverrides).length === 0 ? {} : { env: envOverrides }),
       },
     });
     batchCount += batches.length;
     const plan = planOf(options, pass);
-    const label =
-      only === undefined ? `${pass.workers} worker(s)` : `shard ${only} of ${pass.workers}`;
+    const label = `${pass.workers} worker(s)`;
     steps.push({
       name: `${pass.type === undefined ? label : `${pass.type} · ${label}`} · ${files.length} files${
         batches.length > 1 ? msg('cli.test.batches', { batches: batches.length }) : ''
@@ -403,7 +352,6 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
     durationMs,
     ...(options.filter === undefined ? {} : { filter: options.filter }),
     ...(sample === undefined ? {} : { sample: { kept: sample.kept, total: sample.total } }),
-    ...(only === undefined ? {} : { shard: only }),
     // Only when the split made more than one, so a single-pass run's JSON is byte-identical to
     // what it has always been — and a mixed one can never be read as if it were a single run.
     ...(spent.length > 1 ? { passes: spent } : {}),

package/src/test-workers.ts

@@ -1,14 +1,36 @@
 // How wide a parallel test run goes, decided in one place. `x test --workers`, `x verify
 // --workers` and every parallel step of the gate read this — a second default would split the same
-// suite two different ways, and the `--worker N` reproduction a shard failure prints would then
-// name a shard the gate never ran.
+// suite two different ways, and the `--workers N` a failure's reproduction prints would then name
+// a width the gate never ran.
 
 // Bun ships no CPU-count or memory primitive: `cpus()` is the fallback when navigator cannot
 // answer, and `totalmem()` is the only reader of the machine's RAM.
 // why: Bun ships no CPU-count or total-memory primitive.
 import { cpus, totalmem } from 'node:os';
+import { UltimateError } from '@ultimat3/core';
 import type { TestType } from '@ultimat3/testing';
-import { TestBudgetInvalidError } from './verify-errors';
+
+/**
+ * `ULTIMATE_TEST_MEMORY_BUDGET` or `ULTIMATE_TEST_MAX_WORKERS` set to something that does not
+ * parse. Refused rather than ignored: a typo read as "the default" is a run sized for a machine
+ * the caller said this is not.
+ */
+export class TestBudgetInvalidError extends UltimateError {
+  constructor(name: string, value: string) {
+    super({
+      code: 'X_TEST_BUDGET_INVALID',
+      cause: `${name}=${JSON.stringify(value)} does not parse — ${
+        name === 'ULTIMATE_TEST_MAX_WORKERS'
+          ? 'expected a positive integer'
+          : 'expected a size such as 3g, 512m or 4GiB'
+      }`,
+      fix:
+        name === 'ULTIMATE_TEST_MAX_WORKERS'
+          ? 'ULTIMATE_TEST_MAX_WORKERS=4 x verify'
+          : 'ULTIMATE_TEST_MEMORY_BUDGET=3g x verify',
+    });
+  }
+}
 
 /** navigator first: it is the runtime's own answer, and it respects a container's CPU limit. */
 export function availableCpus(): number {
@@ -219,7 +241,7 @@ export const sharedWorkers = (
  * Which types run across worker processes, and why the other two cannot.
  *
  * Parallel is safe when the only thing a test file shares with another file is the database, and
- * the database is per worker by construction (`ULTIMATE_TEST_WORKER` → one clone of the migrated
+ * the database is per worker by construction (`BUN_TEST_WORKER_ID` → one clone of the migrated
  * template, `@ultimat3/testing`'s `acquireWorkerDatabase`). Every other process-global in this
  * framework — the permission set, the roles, the entity/action/query registries, the error-code
  * titles, the fixture bag — is handled by `--isolate` giving each FILE its own module registry.

package/src/theme-boot.ts

@@ -1,40 +1,15 @@
-// The no-flash theme script, inlined into every document a served or exported process writes,
-// with `theme.defaultMode` from `app.config.ts` as its fallback. Before this the key had no reader
-// at all (pinned as a dead key in `scripts/lib/config-reader-pins.ts`) and neither of the two
-// scripts the framework exported was wired into a document: an app that wanted to open dark had to
-// write its own boot script AND admit it to the CSP by hand — which every app forgot in one of the
-// two places. Sibling of `app-auth.ts`'s `loadSignInPath` and imports the config for the same
-// reason: a regex over the app's source is the pattern `app-load.ts` refuses.
+// The no-flash theme script, inlined into every document a served or exported process writes, with
+// `theme.defaultMode` (off the one loader, `app-config-load.ts`) as its fallback — and the CSP source
+// that admits it, so no app writes its own boot script and forgets to admit it.
 
-// why: Bun exposes no path-join primitive, and the config path is app-root-relative — the same
-// necessity `app-auth.ts` records.
-import { join } from 'node:path';
 import type { ThemeMode } from '@ultimat3/core';
 import { cspHashSource } from '@ultimat3/http';
 import { renderHead, themeScript, themeScriptBody } from '@ultimat3/render';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-const isThemeMode = (value: unknown): value is ThemeMode =>
-  value === 'light' || value === 'dark' || value === 'system';
-
-/**
- * `theme.defaultMode`, or `'system'` — the value `defineConfig` fills in — when the app declares
- * none or the file is absent. Structural, never `instanceof`, for `loadSignInPath`'s reason.
- */
+/** `theme.defaultMode`, or `'system'` — core's own default — for a root with no config file. */
 export async function loadThemeMode(root: string): Promise<ThemeMode> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(configPath).exists())) return 'system';
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!isRecord(config)) return 'system';
-  const theme = config['theme'];
-  if (!isRecord(theme)) return 'system';
-  const mode = theme['defaultMode'];
-  return isThemeMode(mode) ? mode : 'system';
+  return (await loadAppConfig(root))?.theme.defaultMode ?? 'system';
 }
 
 export interface ThemeBoot {