@ultimat3/cli 29.0.0 → 29.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "29.0.0",
+  "version": "29.2.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -39,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.7",
-    "@ultimat3/action": "29.0.0",
-    "@ultimat3/admin": "29.0.0",
-    "@ultimat3/ai": "29.0.0",
-    "@ultimat3/auth": "29.0.0",
-    "@ultimat3/cache": "29.0.0",
-    "@ultimat3/core": "29.0.0",
-    "@ultimat3/db": "29.0.0",
-    "@ultimat3/entity": "29.0.0",
-    "@ultimat3/flags": "29.0.0",
-    "@ultimat3/http": "29.0.0",
-    "@ultimat3/i18n": "29.0.0",
-    "@ultimat3/jobs": "29.0.0",
-    "@ultimat3/mail": "29.0.0",
-    "@ultimat3/manifest": "29.0.0",
-    "@ultimat3/mcp": "29.0.0",
-    "@ultimat3/money": "29.0.0",
-    "@ultimat3/notify": "29.0.0",
-    "@ultimat3/policy": "29.0.0",
-    "@ultimat3/pwa": "29.0.0",
-    "@ultimat3/query": "29.0.0",
-    "@ultimat3/realtime": "29.0.0",
-    "@ultimat3/render": "29.0.0",
-    "@ultimat3/schema": "29.0.0",
-    "@ultimat3/seo": "29.0.0",
-    "@ultimat3/storage": "29.0.0",
-    "@ultimat3/testing": "29.0.0",
-    "@ultimat3/time": "29.0.0",
+    "@ultimat3/action": "29.2.0",
+    "@ultimat3/admin": "29.2.0",
+    "@ultimat3/ai": "29.2.0",
+    "@ultimat3/auth": "29.2.0",
+    "@ultimat3/cache": "29.2.0",
+    "@ultimat3/core": "29.2.0",
+    "@ultimat3/db": "29.2.0",
+    "@ultimat3/entity": "29.2.0",
+    "@ultimat3/flags": "29.2.0",
+    "@ultimat3/http": "29.2.0",
+    "@ultimat3/i18n": "29.2.0",
+    "@ultimat3/jobs": "29.2.0",
+    "@ultimat3/mail": "29.2.0",
+    "@ultimat3/manifest": "29.2.0",
+    "@ultimat3/mcp": "29.2.0",
+    "@ultimat3/money": "29.2.0",
+    "@ultimat3/notify": "29.2.0",
+    "@ultimat3/policy": "29.2.0",
+    "@ultimat3/pwa": "29.2.0",
+    "@ultimat3/query": "29.2.0",
+    "@ultimat3/realtime": "29.2.0",
+    "@ultimat3/render": "29.2.0",
+    "@ultimat3/schema": "29.2.0",
+    "@ultimat3/seo": "29.2.0",
+    "@ultimat3/storage": "29.2.0",
+    "@ultimat3/testing": "29.2.0",
+    "@ultimat3/time": "29.2.0",
     "babel-preset-solid": "^1.9.16"
   }
 }

package/src/cmd-db.ts

@@ -23,6 +23,7 @@ import type { CliCommand, CommandContext } from './command';
 import { stepFinding } from './db-finding';
 import { generateAppMigration, unrenderedJson, unrenderedLines } from './db-generate';
 import { liveObjectDrift } from './db-object-drift';
+import { layTemplate } from './db-reset-template';
 import {
   afterWrittenMigration,
   refreshSchemaDump,
@@ -249,7 +250,8 @@ async function runMigrate(
 /**
  * Embedded only: `rm -rf` against a database this process does not own is not a reset, it is an
  * outage. The data directory goes before the migrator starts, so the run that follows is a fresh
- * database with an empty ledger rather than a re-apply over a live one.
+ * database rather than a re-apply over a live one — laid down from the migrated template when one
+ * can be had, its ledger already full, else an empty one the migrator fills.
  */
 async function runReset(ctx: CommandContext, root: string): Promise<CommandResult> {
   const services = resolveServices(root, ctx.env);
@@ -272,7 +274,11 @@ async function runReset(ctx: CommandContext, root: string): Promise<CommandResul
       embeddedDb: true,
     });
   }
-  await rm(join(services.stateDir, 'pgdata'), { recursive: true, force: true });
+  const dataDir = join(services.stateDir, 'pgdata');
+  await rm(dataDir, { recursive: true, force: true });
+  // From the migrated template when it can be had (`db-reset-template.ts`); the migrate below runs
+  // either way, so a template that could not be laid down costs time, never a different database.
+  await layTemplate(root, dataDir);
   return runMigrate(ctx, root, msg('cli.db.reset.done'));
 }
 

package/src/db-reset-template.ts

@@ -0,0 +1,47 @@
+// `x db reset`'s embedded fast path: the emptied data directory is laid down from the migrated
+// TEMPLATE (`test-database.ts`, cached under `.x/test-db`) instead of an `initdb` and every
+// migration replayed one by one.
+
+// The migrate that follows still runs and finds every migration in the ledger — so a template
+// that is missing something is completed by it, never trusted over it. Measured on
+// bank-integrations (33 migrations, a loaded 12-core box, 3 runs each): `x db reset` 8.7 s → 7.5 s.
+// What is left is the CLI's boot, the migrator's no-op pass and the schema dump's own replay (~3 s,
+// `db-schema-refresh.ts`). The e2e step's app boots through exactly this reset, once per gate.
+
+// why: Bun has no recursive remove; a failed lay-down must leave the directory as `rm` left it.
+import { rm } from 'node:fs/promises';
+import { raw } from '@ultimat3/db';
+import { appExtensions } from './migration-extensions';
+import { migratedDatabase } from './test-database';
+
+export interface TemplateLayDeps {
+  /** Boots a database from the template at `dataDir`; `test-database.ts`'s by default. */
+  readonly open?: typeof migratedDatabase;
+  readonly extensions?: (root: string) => Promise<readonly string[]>;
+}
+
+/**
+ * `true` when `dataDir` now holds the migrated template. Best effort and never a throw: anything
+ * that fails removes what it wrote, and the caller's migrate builds the database the slow way.
+ */
+export async function layTemplate(
+  root: string,
+  dataDir: string,
+  deps: TemplateLayDeps = {},
+): Promise<boolean> {
+  const open = deps.open ?? migratedDatabase;
+  try {
+    const extensions = await (deps.extensions ?? appExtensions)(root);
+    const client = await open({ root, dataDir, extensions });
+    try {
+      // The boot is lazy: one statement is what makes PGlite restore the template onto the disk.
+      await client.execute(raw('select 1'));
+    } finally {
+      await client.close();
+    }
+    return true;
+  } catch {
+    await rm(dataDir, { recursive: true, force: true }).catch(() => undefined);
+    return false;
+  }
+}

package/src/messages.ts

@@ -332,6 +332,7 @@ const CATALOG = {
   // counts — so the line says how many and `x test <type>` prints the names.
   'cli.verify.allSkipped': 'found {skipped} test(s) and every one skipped itself',
   'cli.verify.warnings': '{count} warning(s) — --verbose or --json lists them',
+  'cli.verify.slowest': 'slowest: {files}',
   'cli.verify.isrQueryUndeclared':
     "{file}: render 'isr' with no revalidate.query — its stored pages are keyed on the whole query string, so any visitor can mint one per request. Declare revalidate: { query: [] } (or the parameters the page varies on)",
   'cli.verify.isrQueryOmitted':

package/src/output.ts

@@ -42,6 +42,15 @@ export interface Finding {
   readonly meta?: { readonly [key: string]: JsonValue };
 }
 
+/** One test file of a run and how long Bun took over it (`test-timings.ts` measures it). */
+export interface SlowFile {
+  readonly file: string;
+  readonly ms: number;
+}
+
+/** How many of a step's slowest files the human line names; `--json` carries all it has. */
+export const SLOWEST_SHOWN = 3;
+
 export interface StepResult {
   readonly name: string;
   readonly ok: boolean;
@@ -65,6 +74,11 @@ export interface StepResult {
   readonly workers?: number;
   /** Why the width is what it is — `4 workers (budget 4.0 GB)`. */
   readonly widthReason?: string;
+  /**
+   * A test step's slowest files, slowest first — where its time went, on a pass too: a suite that
+   * grew a 20 s file is a slower gate for everyone, and nothing else said which file it was.
+   */
+  readonly slowest?: readonly SlowFile[];
   /** Under `x verify --shard`: this step's slice of its corpus. */
   readonly shard?: ShardFacts;
   /**
@@ -210,6 +224,10 @@ export function renderUltimateError(error: UltimateErrorShape, indent = ''): str
   return renderFinding(finding, indent);
 }
 
+/** `16.8s`, or `840ms` under a second: a slow file's duration as a reader scans it. */
+const seconds = (ms: number): string =>
+  ms < 1000 ? `${String(Math.round(ms))}ms` : `${(ms / 1000).toFixed(1)}s`;
+
 const mark = (step: StepResult): string => {
   if (step.skipped === true) return '-';
   return step.ok ? '✓' : '✗';
@@ -255,6 +273,13 @@ export function renderHuman(result: CommandResult, verbose = false): string {
     // Escaped like every other line text reaches fd 1 through: a warning names a file path. A
     // green terminal run shows the count, not the list: `filesize`'s band alone is ~150 lines,
     // and a wall of advice on every run is read by nobody. `--json` always carries the list.
+    const slowest = (step.slowest ?? []).slice(0, SLOWEST_SHOWN);
+    if (slowest.length > 0) {
+      const files = slowest
+        .map((slow) => `${singleLine(slow.file)} ${seconds(slow.ms)}`)
+        .join(' · ');
+      out.push(`      ${msg('cli.verify.slowest', { files })}`);
+    }
     const warnings = step.warnings ?? [];
     if (verbose) for (const warning of warnings) out.push(`      ! ${singleLine(warning)}`);
     else if (warnings.length > 0) {
@@ -292,6 +317,9 @@ export function renderJson(result: CommandResult, verbose = false): string {
       : { warnings: [...step.warnings] }),
     ...(step.workers === undefined ? {} : { workers: step.workers }),
     ...(step.widthReason === undefined ? {} : { widthReason: step.widthReason }),
+    ...(step.slowest === undefined || step.slowest.length === 0
+      ? {}
+      : { slowest: step.slowest.map((slow) => ({ file: slow.file, ms: slow.ms })) }),
     ...(step.shard === undefined
       ? {}
       : {

package/src/page-navigation.ts

@@ -11,10 +11,14 @@ import type { Ctx, NavigationSurface } 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 { Translator } from '@ultimat3/i18n';
 import type { ClientNavigationHead, HeadTag, RouteEntry } from '@ultimat3/render';
 import {
   clientNavigationTags,
   documentCarriesScope,
+  modalRouteList,
+  navigationModeOf,
+  navigationPrefetches,
   RouteNavigationInvalidError,
   routeEntries,
 } from '@ultimat3/render';
@@ -36,6 +40,11 @@ export interface NavigationDocumentHead {
   readonly buildId: string;
   /** `app.config.ts`'s `name`: two apps on one origin (web and admin) are two routers. */
   readonly app: string;
+  /**
+   * Per opted-in surface, its modal routes as `modalRouteList` orders them — what lets a click
+   * open the dialog before the answer. Absent or empty: the documents name none.
+   */
+  readonly modalRoutes?: ReadonlyMap<string, readonly string[]>;
 }
 
 export interface PageNavigation {
@@ -71,7 +80,7 @@ export function assertRouteNavigation(
   entries: readonly RouteEntry[] = routeEntries(),
 ): void {
   for (const entry of entries) {
-    const mode = entry.config.navigation;
+    const mode = navigationModeOf(entry.config.navigation);
     if (mode === undefined || surfaces.some((surface) => surface === entry.surface)) continue;
     throw new RouteNavigationInvalidError(
       `${entry.file} declares navigation: '${mode}', and its surface (${entry.surface}) is not in app.config.ts navigation.client`,
@@ -79,6 +88,28 @@ export function assertRouteNavigation(
   }
 }
 
+/**
+ * Each opted-in surface's modal routes, from the whole table: a page of ANY surface may outrank a
+ * modal pattern on the shared URL space, and the router must not open a frame the server will
+ * answer with that page.
+ */
+export function modalRoutesOf(
+  surfaces: readonly NavigationSurface[],
+  entries: readonly RouteEntry[] = routeEntries(),
+): ReadonlyMap<string, readonly string[]> {
+  return new Map(
+    surfaces.map((surface) => [
+      surface,
+      modalRouteList(
+        entries.map((entry) => ({
+          path: entry.path,
+          modal: entry.surface === surface && navigationModeOf(entry.config.navigation) === 'modal',
+        })),
+      ),
+    ]),
+  );
+}
+
 /**
  * Built at boot, never on the watcher tick — the router is framework code, and a tab that loaded
  * it keeps it across every soft navigation, so a URL that changed per save would be one no tab
@@ -109,6 +140,7 @@ export async function pageNavigation(
       scriptUrl: script.url,
       buildId,
       app: declared.app,
+      modalRoutes: modalRoutesOf(declared.surfaces),
     },
   };
 }
@@ -117,13 +149,25 @@ export async function pageNavigation(
 export const surfaceKey = (head: NavigationDocumentHead, surface: string): string =>
   `${head.app}:${surface}`;
 
-/** The head for one document, or `undefined` when its surface did not opt in. */
+/**
+ * The head for one document, or `undefined` when its surface did not opt in. With `t`, and modal
+ * routes on the surface, it names them and the frame's two words in the document's own locale
+ * (the framework catalog's `ui.close` and `ui.loading`, which an app may override).
+ */
 export function navigationHeadFor(
   head: NavigationDocumentHead | undefined,
   surface: string,
+  t?: Translator,
 ): ClientNavigationHead | undefined {
   if (head === undefined || !head.surfaces.has(surface)) return undefined;
-  return { surface: surfaceKey(head, surface), buildId: head.buildId, scriptUrl: head.scriptUrl };
+  const base = {
+    surface: surfaceKey(head, surface),
+    buildId: head.buildId,
+    scriptUrl: head.scriptUrl,
+  };
+  const routes = head.modalRoutes?.get(surface) ?? [];
+  if (t === undefined || routes.length === 0) return base;
+  return { ...base, modals: { routes, close: t('ui.close'), loading: t('ui.loading') } };
 }
 
 /**
@@ -137,15 +181,15 @@ export function navigationHeadFor(
 export function navigationTagsOf(
   head: NavigationDocumentHead | undefined,
   entry: Pick<RouteEntry, 'surface' | 'config'>,
+  t?: Translator,
 ): readonly HeadTag[] {
-  if (entry.config.navigation === 'document') return [];
-  const tags = navigationHeadFor(head, entry.surface);
+  const mode = navigationModeOf(entry.config.navigation);
+  if (mode === 'document') return [];
+  const tags = navigationHeadFor(head, entry.surface, t);
   if (tags === undefined) return [];
   // A modal says so in its own document: the router shows it over the page beneath, never decided
   // from a link — a redirect's target and a pasted `#/…` address are answered alike.
-  return clientNavigationTags(
-    entry.config.navigation === 'modal' ? { ...tags, modal: true } : tags,
-  );
+  return clientNavigationTags(mode === 'modal' ? { ...tags, modal: true } : tags);
 }
 
 /** `{ navigation }` for `metaOf`'s spread, or nothing. */
@@ -167,10 +211,10 @@ export function routeNavigationOf(
   head: NavigationDocumentHead | undefined,
 ): RouteNavigation | undefined {
   if (head === undefined || !head.surfaces.has(entry.surface)) return undefined;
-  if (entry.config.navigation === 'document') return undefined;
+  if (navigationModeOf(entry.config.navigation) === 'document') return undefined;
   return {
     surface: surfaceKey(head, entry.surface),
-    prefetch: entry.config.navigation === 'prefetch',
+    prefetch: navigationPrefetches(entry.config.navigation),
   };
 }
 

package/src/page-speculation.ts

@@ -12,6 +12,8 @@ import type { AppLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import type { RouteDescriptor, RouteEntry } from '@ultimat3/render';
 import {
   describePages,
+  navigationModeOf,
+  navigationPrefetches,
   renderHead,
   routeEntries,
   speculationPattern,
@@ -37,8 +39,9 @@ export async function loadSpeculation(root: string): Promise<SpeculationConfig>
  *   no policy, no `no-store`. Such a page ran its `load` at build time, for nobody. An `ssr` page
  *   there has no way to declare that its GET records something (`navigation` is refused on a
  *   surface that did not opt in), so it is never a candidate.
- * - On a client-routed surface: only a page that declared `navigation: 'prefetch'` — the app's own
- *   statement that its GET is a pure read, the same one the router's prefetch obeys.
+ * - On a client-routed surface: only a page that declared `navigation: 'prefetch'` (or a modal
+ *   that declared `prefetch: 'intent'`) — the app's own statement that its GET is a pure read,
+ *   the same one the router's prefetch obeys.
  * - Never an `api/` route, a `navigation: 'document'` page, or an `offline: 'network-only'` one.
  */
 export function speculationCandidate(
@@ -47,8 +50,9 @@ export function speculationCandidate(
   client: ReadonlySet<string>,
 ): boolean {
   if (entry.surface !== 'site' && entry.surface !== 'app') return false;
-  if (entry.config.navigation === 'document' || described.offline === 'network-only') return false;
-  if (client.has(entry.surface)) return entry.config.navigation === 'prefetch';
+  const mode = navigationModeOf(entry.config.navigation);
+  if (mode === 'document' || described.offline === 'network-only') return false;
+  if (client.has(entry.surface)) return navigationPrefetches(entry.config.navigation);
   return (described.mode === 'static' || described.mode === 'isr') && !described.personal;
 }
 

package/src/runtime-render.ts

@@ -120,7 +120,7 @@ const headFor = async (
 ): Promise<string> => {
   const meta = metaContextFor(ctx, data);
   const url = new URL(ctx.url);
-  const router = navigationTagsOf(options.navigation, entry);
+  const router = navigationTagsOf(options.navigation, entry, meta.t);
   return (
     renderHead(
       headFromMeta(

package/src/test-shards.ts

@@ -59,6 +59,7 @@ import { runBatches, testBatches } from './test-batches';
 import { tidyBeforeTestRun } from './test-housekeeping';
 import { testPasses } from './test-passes';
 import type { TestFile } from './test-select';
+import { loadTimings, SLOWEST_KEPT, slowestOf } from './test-timings';
 import { BATCH_FILES_PER_WORKER, SHARED_BATCH_FILES_PER_WORKER } from './test-workers';
 import type { TestType } from './verify-tests';
 
@@ -334,6 +335,19 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
   }
   const durationMs = Math.round(performance.now() - started);
   const fileCount = options.files.length;
+  // Where the time went, from the cache every pass's `--update-timings` just rewrote: a file this
+  // selection ran and nothing timed (a `--watch` run, a cache that could not be written) is left out.
+  const timings = await loadTimings(join(options.root, TEST_TIMINGS_FILE));
+  const slowest = slowestOf(
+    timings,
+    options.files.map((file) => file.path),
+    SLOWEST_KEPT,
+  );
+  // Each pass's line names its own slowest, so a mixed run's serial half is not hidden by the rest.
+  const timedSteps = steps.map((step, index) => {
+    const own = slowestOf(timings, passes[index]?.files.map((file) => file.path) ?? []);
+    return own.length === 0 ? step : { ...step, slowest: own };
+  });
   // The width the RUN reached, which is the widest pass: a mixed selection whose serial half ran
   // one at a time did not become a one-worker run, and reporting it as one would misname the
   // reproduce a reader is handed.
@@ -357,6 +371,8 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
     ...(spent.length > 1 ? { passes: spent } : {}),
     // Only when some pass was split, for the same reason: an unbatched run's JSON is unchanged.
     ...(batchCount > spent.length ? { batches: batchCount } : {}),
+    // Absent when nothing was timed, so an untimed run's JSON is byte-identical to before.
+    ...(slowest.length === 0 ? {} : { slowest: slowest.map((slow) => ({ ...slow })) }),
     ok,
     exitCode,
     reproduce: reproduceFor(plan),
@@ -376,7 +392,7 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
           failed: steps.filter((step) => !step.ok).length,
           workers,
         }),
-    steps,
+    steps: timedSteps,
     ...(sample === undefined
       ? {}
       : { lines: [msg('cli.test.sampled', { ...sample, type: type ?? 'all' })] }),

package/src/test-timings.ts

@@ -0,0 +1,127 @@
+// The per-file test durations a run learns and the next one spends: the local cache read leniently,
+// merged and written back atomically, a step's slowest files named, and work ordered longest-first.
+
+// A cache only ever orders work and names what was slow — never which files run or what a step
+// answers — so a missing, stale or broken one costs seconds, never a verdict.
+
+// why: Bun has no mkdir or rename; the cache is written to a temp name and renamed into place.
+import { mkdir, rename, rm } from 'node:fs/promises';
+// why: Bun ships no path-join primitive.
+import { dirname } from 'node:path';
+import type { SlowFile } from './output';
+import type { Timings } from './verify-shard';
+
+/** How many of a run's slowest files a step carries (`--json`); the human line shows fewer. */
+export const SLOWEST_KEPT = 10;
+
+const finiteMs = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && value >= 0;
+
+/** The cache as `{ path: ms }`; absent, unreadable or of another shape is `{}` — never a throw. */
+export async function loadTimings(path: string): Promise<Timings> {
+  try {
+    const parsed: unknown = JSON.parse(await Bun.file(path).text());
+    const files =
+      typeof parsed === 'object' && parsed !== null && 'files' in parsed
+        ? (parsed as { files: unknown }).files
+        : parsed;
+    if (typeof files !== 'object' || files === null || Array.isArray(files)) return {};
+    return Object.fromEntries(Object.entries(files).filter(([, ms]) => finiteMs(ms)));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * `fresh` merged over the cache and written back in Bun's own shape (`{ version: 1, files }`), so
+ * `bun test --timings` reads what this wrote and the other way round. Best effort: a cache that
+ * cannot be written costs the next run its ordering, which is all it ever bought.
+ */
+export async function recordTimings(path: string, fresh: Timings): Promise<void> {
+  if (Object.keys(fresh).length === 0) return;
+  const files = { ...(await loadTimings(path)), ...fresh };
+  const partial = `${path}.${String(process.pid)}.${crypto.randomUUID()}.partial`;
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await Bun.write(partial, `${JSON.stringify({ version: 1, files }, null, 2)}\n`);
+    await rename(partial, path);
+  } catch {
+    await rm(partial, { force: true }).catch(() => undefined);
+  }
+}
+
+const attribute = (tag: string, name: string): string | undefined => {
+  const match = new RegExp(`\\s${name}="([^"]*)"`).exec(tag);
+  return match === null ? undefined : match[1];
+};
+
+/** XML's five entities, the only ones Bun's junit writer emits in an attribute. */
+const unescapeXml = (text: string): string =>
+  text
+    .replaceAll('&quot;', '"')
+    .replaceAll('&apos;', "'")
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&amp;', '&');
+
+/**
+ * Per-file durations from a `bun test --reporter=junit` report: each file is one `<testsuite>`
+ * whose `file` (else `name`) is the path as the run was given it and whose `time` is seconds.
+ * Nested suites (a `describe`) carry no `file` and are skipped. A broken report yields `{}`.
+ */
+export function junitDurations(xml: string): Timings {
+  // A Map, not a `Record`: a test file named `constructor` must not read `Object.prototype`.
+  const out = new Map<string, number>();
+  for (const match of xml.matchAll(/<testsuite\s[^>]*>/g)) {
+    const tag = match[0];
+    const file = attribute(tag, 'file');
+    const seconds = Number(attribute(tag, 'time'));
+    if (file === undefined || file === '' || !finiteMs(seconds)) continue;
+    const path = unescapeXml(file);
+    out.set(path, Math.round(seconds * 1000) + (out.get(path) ?? 0));
+  }
+  return Object.fromEntries(out);
+}
+
+/** The `n` slowest of `files` by `timings`, slowest first (ties by path); unknown files left out. */
+export function slowestOf(
+  timings: Timings,
+  files: readonly string[],
+  n: number = SLOWEST_KEPT,
+): readonly SlowFile[] {
+  return [...new Set(files)]
+    .flatMap((file) => {
+      const ms = Object.hasOwn(timings, file) ? timings[file] : undefined;
+      return finiteMs(ms) ? [{ file, ms }] : [];
+    })
+    .sort((a, b) => b.ms - a.ms || (a.file < b.file ? -1 : a.file > b.file ? 1 : 0))
+    .slice(0, Math.max(0, n));
+}
+
+/**
+ * Indices of `costs` longest first (LPT): a pool that starts its longest piece of work last finishes
+ * that long after everything else. An unknown cost (`undefined`) is the median of the known ones,
+ * so new work neither jumps the queue nor waits behind all of it; ties keep their order.
+ */
+export function longestFirst(costs: readonly (number | undefined)[]): readonly number[] {
+  const known = costs.filter((cost): cost is number => finiteMs(cost)).sort((a, b) => a - b);
+  const median = known.length === 0 ? 0 : (known[Math.floor(known.length / 2)] as number);
+  const costOf = (index: number): number => {
+    const cost = costs[index];
+    return finiteMs(cost) ? cost : median;
+  };
+  return costs.map((_, index) => index).sort((a, b) => costOf(b) - costOf(a) || a - b);
+}
+
+/** A group of files' recorded cost: the sum of what is known, `undefined` when nothing is. */
+export function costOf(timings: Timings, files: readonly string[]): number | undefined {
+  let total = 0;
+  let known = false;
+  for (const file of files) {
+    const ms = Object.hasOwn(timings, file) ? timings[file] : undefined;
+    if (!finiteMs(ms)) continue;
+    total += ms;
+    known = true;
+  }
+  return known ? total : undefined;
+}

package/src/verify-coverage-run.ts

@@ -9,6 +9,13 @@
 //
 // It costs nothing measurable: four slice processes took 9.7 s against 12.4 s for `--parallel=4`
 // over the same files, on a loaded 12-core box.
+//
+// ORDER, NOT MEMBERSHIP, FOLLOWS THE CLOCK. Each slice also writes a junit report; its per-file
+// durations go into the run's timings cache (`TEST_TIMINGS_FILE`, `test-timings.ts`) and the NEXT
+// run starts the slices longest-first from it. The slices themselves stay a pure function of the
+// file list — the coverage a slice measures never depends on a cache. Measured on bank-integrations
+// (1 192 files, 102 slices, 8 processes): sorted order 64.1 s, longest-first 56.3 s, the floor
+// 56.1 s — the pool used to start its 50 s slice last.
 
 // why: Bun ships no recursive delete and no path-join primitive; the lcov parts live under `.x/`.
 import { rm } from 'node:fs/promises';
@@ -24,6 +31,14 @@ import { countsOf } from './test-counts';
 import { testEnvOverrides } from './test-dotenv';
 import { failureOf } from './test-shards';
 import { SLOT_HELD_ENV } from './test-slots';
+import {
+  costOf,
+  junitDurations,
+  loadTimings,
+  longestFirst,
+  recordTimings,
+  slowestOf,
+} from './test-timings';
 import type { MachinePace } from './verify-pace';
 import { defaultTimeoutArgs, paceEnv } from './verify-pace';
 import type { StepOutcome } from './verify-step';
@@ -87,6 +102,11 @@ export interface CoveredRunOptions {
   readonly sliceFiles?: number;
   /** The machine's pace (`verify-pace.ts`): each test's default and declared deadline stretch by it. */
   readonly pace?: MachinePace;
+  /**
+   * The timings cache (`TEST_TIMINGS_FILE` under the root): the slices start longest-first from it,
+   * and every file's duration this run measured is written back. Absent: sorted order, nothing kept.
+   */
+  readonly timings?: string;
 }
 
 export interface CoveredRun extends StepOutcome {
@@ -94,12 +114,19 @@ export interface CoveredRun extends StepOutcome {
   readonly coverage: CoverageMap;
 }
 
-/** One slice's argv. An explicit file list, never a re-glob, for `testArgs`' reason. */
+/** The slice's junit report, beside its lcov: one `<testsuite>` per file, with its duration. */
+export const JUNIT_FILE = 'junit.xml';
+
+/**
+ * One slice's argv. An explicit file list, never a re-glob, for `testArgs`' reason. `junit` adds
+ * the report the per-file durations are read from — Bun still prints to the terminal beside it.
+ */
 export const coveredArgs = (
   files: readonly string[],
   dir: string,
   isolate: boolean,
   pace?: MachinePace,
+  junit = false,
 ): readonly string[] => [
   'bun',
   'test',
@@ -108,6 +135,7 @@ export const coveredArgs = (
   '--coverage',
   '--coverage-reporter=lcov',
   `--coverage-dir=${dir}`,
+  ...(junit ? ['--reporter=junit', `--reporter-outfile=${join(dir, JUNIT_FILE)}`] : []),
   ...files,
 ];
 
@@ -125,11 +153,14 @@ export async function runCovered(options: CoveredRunOptions): Promise<CoveredRun
     ...paceEnv(options.pace),
   };
   const results = new Array<ExecResult>(slices.length);
+  // Longest first by what earlier runs measured; the slices and their indices are unchanged.
+  const known = options.timings === undefined ? {} : await loadTimings(options.timings);
+  const order = longestFirst(slices.map((slice) => costOf(known, slice)));
   let next = 0;
   // Each pool worker names its own numbered test database, as `--parallel`'s workers do.
   const worker = async (slot: number): Promise<void> => {
-    while (next < slices.length) {
-      const index = next;
+    while (next < order.length) {
+      const index = order[next] as number;
       next += 1;
       results[index] = await options.runner(
         coveredArgs(
@@ -137,15 +168,24 @@ export async function runCovered(options: CoveredRunOptions): Promise<CoveredRun
           join(base, String(index)),
           isolate,
           options.pace,
+          options.timings !== undefined,
         ),
         { cwd: options.root, env: { ...overrides, ULTIMATE_TEST_WORKER: String(slot) } },
       );
     }
   };
   let maps: CoverageMap[];
+  let measured: Record<string, number> = {};
   try {
     await Promise.all(Array.from({ length: width }, (_, slot) => worker(slot)));
     maps = await Promise.all(slices.map((_, index) => readPart(join(base, String(index)))));
+    if (options.timings !== undefined) {
+      const reports = await Promise.all(
+        slices.map((_, index) => readReport(join(base, String(index)))),
+      );
+      measured = Object.assign({}, ...reports.map(junitDurations));
+      await recordTimings(options.timings, measured);
+    }
   } finally {
     lease?.release();
     await rm(base, { recursive: true, force: true });
@@ -183,10 +223,17 @@ export async function runCovered(options: CoveredRunOptions): Promise<CoveredRun
     ...(options.widthReason === undefined ? {} : { widthReason: options.widthReason }),
     tests: countsOf(results),
     ...(first === undefined ? {} : { output }),
+    ...(Object.keys(measured).length === 0 ? {} : { slowest: slowestOf(measured, options.files) }),
     coverage: mergeCoverage(maps),
   };
 }
 
+/** A slice's junit report, or `''` when it wrote none (it died first): no durations, no throw. */
+const readReport = (dir: string): Promise<string> =>
+  Bun.file(join(dir, JUNIT_FILE))
+    .text()
+    .catch(() => '');
+
 /**
  * One slice's lcov as a map, kept to the app's own tree: a slice loads a thousand framework files
  * for every hundred of the app's, and none of those is what the floor measures. No file is no

package/src/verify-run.ts

@@ -295,6 +295,9 @@ async function runStep(
         : { warnings: outcome.warnings }),
       ...(outcome.workers === undefined ? {} : { workers: outcome.workers }),
       ...(outcome.widthReason === undefined ? {} : { widthReason: outcome.widthReason }),
+      ...(outcome.slowest === undefined || outcome.slowest.length === 0
+        ? {}
+        : { slowest: outcome.slowest }),
       ...(outcome.shard === undefined ? {} : { shard: outcome.shard }),
       ...(tests === undefined ? {} : { tests }),
     },

package/src/verify-step.ts

@@ -6,7 +6,7 @@ import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { CoverageMap } from './coverage-lcov';
 import type { ExecResult, Runner } from './exec';
 import { execOutput } from './exec';
-import type { Finding, ShardFacts, StepResult } from './output';
+import type { Finding, ShardFacts, SlowFile, StepResult } from './output';
 import type { TestCounts } from './test-counts';
 import type { StepTimeouts } from './verify-deadline';
 import type { MachinePace } from './verify-pace';
@@ -159,6 +159,8 @@ export interface StepOutcome {
   readonly workers?: number;
   /** Why `workers` is what it is — `4 workers (budget 4.0 GB)`. Printed on the step line. */
   readonly widthReason?: string;
+  /** The step's slowest test files, slowest first (`test-timings.ts`): where its time went. */
+  readonly slowest?: readonly SlowFile[];
   /** The CI slice this step ran, under `--shard`: which files, and a hash of the whole list. */
   readonly shard?: ShardFacts;
   /**

package/src/verify-test-run.ts

@@ -13,6 +13,7 @@ import { testEnvOverrides } from './test-dotenv';
 import { tidyBeforeTestRun } from './test-housekeeping';
 import type { TestFile } from './test-select';
 import { failureOf, TEST_TIMINGS_FILE, testArgs } from './test-shards';
+import { loadTimings, slowestOf } from './test-timings';
 import { BATCH_FILES_PER_WORKER, SHARED_BATCH_FILES_PER_WORKER } from './test-workers';
 import type { MachinePace } from './verify-pace';
 import { defaultTimeoutArgs, paceEnv } from './verify-pace';
@@ -101,6 +102,8 @@ export async function runParallel(options: ParallelRunOptions): Promise<StepOutc
           ...(options.isolate === true ? { isolate: true } : {}),
         }),
       ];
+  // Where the time went: Bun rewrote the timings cache (`--update-timings`) as the batches ended.
+  const slowest = slowestOf(await loadTimings(join(options.root, TEST_TIMINGS_FILE)), files);
   // The width the run REACHED: a batch the machine pool narrowed ran narrower than planned, and a
   // step line that printed the plan would name a width that never ran.
   const reached = Math.max(1, ...result.widths);
@@ -119,6 +122,7 @@ export async function runParallel(options: ParallelRunOptions): Promise<StepOutc
     // Per batch: each process printed its own summary, and one parse of the joined text would
     // read only the last one.
     tests: countsOf(result.results),
+    ...(slowest.length === 0 ? {} : { slowest }),
     // Only on failure: a green run's summary is already the step table's, and the reader of a red
     // gate needs the assertion diff.
     ...(result.ok ? {} : { output: result.output }),

package/src/verify-tests.ts

@@ -21,6 +21,7 @@ import { testEnvOverrides } from './test-dotenv';
 import { IGNORED_TEST_PATTERNS } from './test-ignores';
 import type { TestFile } from './test-select';
 import { discoverTests } from './test-select';
+import { TEST_TIMINGS_FILE } from './test-shards';
 import { machineLease } from './test-slots';
 import type { WorkerPlan } from './test-workers';
 import { availableCpus, SERIAL_TYPES, totalMemory, workerPlan } from './test-workers';
@@ -317,6 +318,8 @@ const coveredUnit = async (
     ...(run.lease === undefined ? {} : { lease: run.lease }),
     ...(ctx.env === undefined ? {} : { env: ctx.env }),
     ...(run.pace === undefined ? {} : { pace: run.pace }),
+    // Orders the slices longest-first and learns this run's per-file durations (`test-timings.ts`).
+    timings: join(ctx.root, TEST_TIMINGS_FILE),
   });
   if (!outcome.ok) return run.shard === undefined ? outcome : { ...outcome, shard: run.shard };
   if (run.shard !== undefined) {