@ultimat3/cli 22.14.0 → 23.0.0

package/src/island-store.ts

@@ -1,21 +1,22 @@
-// The island chunks a container serves, built ONCE by `x build --target docker` into
-// `.x/islands/` and read back at boot. Without it every role's boot ran `Bun.build` — Babel, the
-// JSX transform, a minifier — for every island, in the image, on every start, and a chunk whose
-// URL is a hash of its sources was rebuilt from sources that could not have changed.
+// The island chunks a container serves, built ONCE inside the image build by
+// `x build --target prebuilt` and read back at boot. Without it every web pod's boot ran
+// `Bun.build` — Babel, the JSX transform, a minifier — for every island, on every start, and a
+// chunk whose URL is a hash of its sources was rebuilt from sources that could not have changed.
 //
 // Load-and-VERIFY, never load-and-trust: a store written by another framework or Bun version, one
 // that names a different set of islands than the app has, or a chunk whose bytes do not hash to
-// what the index recorded is refused, and the boot builds instead — with the reason logged.
+// what the index recorded is refused, and the boot builds instead — and says so.
 
 import { join, relative, sep } from 'node:path'; // why: Bun ships no path-join primitive.
-import { frameworkVersion, logger } from '@ultimat3/core';
+import { frameworkVersion } from '@ultimat3/core';
 import { contentHash, loadStylesheet } from '@ultimat3/render/server';
 import type { IslandBundle, IslandChunk, SharedChunk } from './island-bundle';
 import { buildIslands, discoverIslands, islandBundle } from './island-bundle';
 import { islandStylesheets } from './island-styles';
+import { PREBUILT_ISLANDS_DIR } from './serve-prebuilt-paths';
 
-/** App-root-relative: `COPY . .` carries it into the image with the rest of `.x/`. */
-export const ISLAND_STORE_DIR = '.x/islands';
+/** App-root-relative, inside the image's prebuilt store (`serve-prebuilt-paths.ts` says why there). */
+export const ISLAND_STORE_DIR = PREBUILT_ISLANDS_DIR;
 const INDEX = 'index.json';
 
 interface StoredChunk {
@@ -200,16 +201,23 @@ export async function readIslandStore(root: string): Promise<StoreRead> {
   return { bundle: islandBundle(chunks, shared) };
 }
 
+/** The container's islands, and — when this boot had to build them — why and how many. */
+export interface LoadedIslands {
+  readonly bundle: IslandBundle;
+  readonly built?: { readonly chunks: number; readonly reason: string };
+}
+
 /**
  * The container's islands: the verified store, or a build when there is none to trust. A build is
- * correct and only slower, so a stale store is a warning with its reason, never a refusal.
+ * correct and only slower, so a stale store is never a refusal — the caller is handed the reason,
+ * and `serve-boot.ts` logs it once with everything else the boot built (`X_IMAGE_NOT_PREBUILT`).
  */
-export async function loadOrBuildIslands(root: string): Promise<IslandBundle> {
+export async function loadOrBuildIslands(root: string): Promise<LoadedIslands> {
   const read = await readIslandStore(root);
-  if (read.bundle !== undefined) return read.bundle;
-  logger.warn('islands built at boot', {
-    reason: read.stale,
-    fix: 'x build --target docker',
-  });
-  return buildIslands(root);
+  if (read.bundle !== undefined) return { bundle: read.bundle };
+  const bundle = await buildIslands(root);
+  return {
+    bundle,
+    built: { chunks: bundle.chunks.length + bundle.shared.length, reason: read.stale },
+  };
 }

package/src/jobs-drain.ts

@@ -3,8 +3,8 @@
 // that safe — lease, copy steps, enqueue, then ack — has to be readable in one screen.
 
 import { uuid } from '@ultimat3/core';
-import type { JobDriver, JobRecord, JobState } from '@ultimat3/jobs';
-import { inspectJobList } from '@ultimat3/jobs';
+import type { ClaimedJob, JobDriver, JobRecord, JobState } from '@ultimat3/jobs';
+import { claimOf, inspectJobList } from '@ultimat3/jobs';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 
@@ -57,7 +57,7 @@ export interface DrainOutcome {
 function leaseCandidates(
   source: JobDriver,
   candidates: readonly JobRecord[],
-): Promise<readonly JobRecord[]> {
+): Promise<readonly ClaimedJob[]> {
   if (candidates.length === 0) return Promise.resolve([]);
   return source.claim({
     queues: [...new Set(candidates.map((record) => record.queue))],
@@ -82,9 +82,14 @@ async function copySteps(source: JobDriver, target: JobDriver, runId: string): P
  * `countsAsAttempt: false` was the only bit the drivers had and `step.sleep` had claimed it;
  * `NackOptions.park` now carries the suspension, so the two callers no longer share one meaning.
  */
-async function releaseLease(source: JobDriver, id: string): Promise<void> {
+async function releaseLease(source: JobDriver, leased: ClaimedJob): Promise<void> {
   try {
-    await source.nack(id, { delayMs: 0, countsAsAttempt: false });
+    // Fenced on the drain's own claim, like every settle: a lease that lapsed is not handed back.
+    await source.nack(leased.id, {
+      ...claimOf(leased),
+      delayMs: 0,
+      countsAsAttempt: false,
+    });
   } catch {
     // The lease expires on its own. Masking the transfer's real error with this one helps nobody.
   }
@@ -141,14 +146,16 @@ export async function drainJobs(
       // Only now is the ack the drain's to make: the lease proves no source worker holds this
       // job, and the target already has both the row and its steps. A crash between the two
       // leaves the job live on both drivers, where `idempotencyKey` dedupes it.
-      await source.ack(record.id);
+      // `counted: false`: the row is finished HERE because it left, and a job that was moved is
+      // not a job that completed — it must add nothing to the source's `done` history.
+      await source.ack(record.id, { ...claimOf(record), counted: false });
       // Report the row as the drain FOUND it: `claim()` returns it mid-lease (`running`, one
       // attempt higher), a state nothing on either driver is in once this returns.
       moved.push(found.get(record.id) ?? record);
     } catch (error) {
       // A failed enqueue left nothing on the target, so the lease goes back. A failed ack did
       // not: the job is already live there, and releasing it would race the target's worker.
-      if (!enqueued) await releaseLease(source, record.id);
+      if (!enqueued) await releaseLease(source, record);
       failures.push({ id: record.id, name: record.name, finding: findingFrom(error) });
     }
   }

package/src/jobs-json.ts

@@ -7,9 +7,11 @@ import type {
   DeadLetterEntry,
   JobRecord,
   JobTrace,
+  PausedName,
   QueueDepthReport,
   QueueStats,
   StepTrace,
+  WorkerRecord,
 } from '@ultimat3/jobs';
 import type { DrainFailure, DrainSkip } from './jobs-drain';
 import type { JsonValue } from './output';
@@ -59,15 +61,61 @@ export function jobTraceToJson(trace: JobTrace): JsonValue {
     runId: trace.runId,
     runAt: trace.runAt,
     lastError: trace.lastError,
+    // The failure's stack, bounded by the queue. `null` when the thrown value carried none.
+    stack: trace.stack,
+    // The payload with every key the app declared secret already replaced (`redactInput`), so it
+    // is the queue's promise that this is safe to print — never this file's.
+    input: toJson(trace.input),
+    progress:
+      trace.progress === null
+        ? null
+        : {
+            done: trace.progress.done,
+            total: trace.progress.total,
+            note: trace.progress.note ?? null,
+            at: trace.progress.at,
+          },
     tenantId: trace.tenantId,
     steps: trace.steps.map(stepTraceToJson),
     retryDelaysMs: trace.retryDelaysMs.map((ms) => ms),
+    // `concurrency.key(input)` for a keyed job, `null` for every other: which lease this run waits on.
+    concurrencyKey: trace.concurrencyKey,
     // `null` for every job that is not a `backfill()` pass. Dropped, `x jobs show <id> --json`
     // would answer "how far has it got" with silence for the one job kind that can say.
     backfill: trace.backfill === null ? null : backfillToJson(trace.backfill),
   };
 }
 
+/**
+ * An app payload as plain JSON. A round trip through the serialiser is the proof: whatever a
+ * payload held that JSON cannot carry — a bigint, a function, a cycle — degrades to `null` rather
+ * than failing the command that was asked to show it.
+ */
+function toJson(value: unknown): JsonValue {
+  try {
+    const text: string | undefined = JSON.stringify(value);
+    return text === undefined ? null : (JSON.parse(text) as JsonValue);
+  } catch {
+    return null;
+  }
+}
+
+export function pausedToJson(paused: PausedName): JsonValue {
+  return { name: paused.name, pausedAt: paused.pausedAt };
+}
+
+export function workerToJson(worker: WorkerRecord): JsonValue {
+  return {
+    id: worker.id,
+    host: worker.host,
+    startedAt: worker.startedAt,
+    heartbeatAt: worker.heartbeatAt,
+    queues: [...worker.queues],
+    concurrency: worker.concurrency,
+    inFlight: [...worker.inFlight],
+  };
+}
+
 /**
  * `input` is deliberately excluded: it is `unknown` at the driver boundary (an app-defined
  * payload, not something this package can prove is JSON-safe), and `JobTrace` already sets the
@@ -100,6 +148,7 @@ function queueStatsToJson(stats: QueueStats): JsonValue {
     delayed: stats.delayed,
     running: stats.running,
     suspended: stats.suspended,
+    failed: stats.failed,
     dead: stats.dead,
     oldestReadyMs: stats.oldestReadyMs,
   };
@@ -114,6 +163,7 @@ export function depthToJson(depth: QueueDepthReport): JsonValue {
       delayed: depth.totals.delayed,
       running: depth.totals.running,
       suspended: depth.totals.suspended,
+      failed: depth.totals.failed,
       dead: depth.totals.dead,
     },
     oldestReadyMs: depth.oldestReadyMs,

package/src/jobs-report.ts

@@ -72,6 +72,8 @@ export interface JobsListFilter {
   readonly state?: string | undefined;
   readonly name?: string | undefined;
   readonly limit?: string | undefined;
+  /** `jobCursor(lastRow)` of the page before — the keyset the next page seeks from. */
+  readonly after?: string | undefined;
 }
 
 export interface JobsListResult {
@@ -103,6 +105,7 @@ export async function listJobs(
     ...(filter.name === undefined ? {} : { name: filter.name }),
     ...(state === undefined ? {} : { state }),
     ...(limit === undefined ? {} : { limit }),
+    ...(filter.after === undefined ? {} : { after: filter.after }),
   };
   const [depth, rows, deadLetters, backfills] = await Promise.all([
     inspectQueues(driver),

package/src/json-merge.ts

@@ -38,3 +38,49 @@ export function mergeJsonDeep(
   }
   return { merged, gained };
 }
+
+/** Code units, never `localeCompare`: the bytes must not move with the machine's ICU. */
+const byCodeUnit = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+const isSorted = (keys: readonly string[]): boolean =>
+  keys.every((key, index) => index === 0 || byCodeUnit(keys[index - 1] ?? '', key) <= 0);
+
+/** Every key of every level, sorted — the order a generator's own fresh output is written in. */
+export function sortJsonDeep(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortJsonDeep);
+  if (!isObject(value)) return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort(byCodeUnit)
+      .map((key) => [key, sortJsonDeep(value[key])]),
+  );
+}
+
+/**
+ * `mergeJsonDeep`, for a file that is ALREADY ON DISK: the same union, written back in the order
+ * the file is in. A catalog a team keeps grouped by screen was re-sorted wholesale by a merge
+ * that sorted every level — 424 changed lines for 22 added keys — which buries the keys a run
+ * added and turns every generator run into a merge conflict.
+ *
+ * Per level: a held key stays where it is. A new key takes its SORTED place when that level is
+ * sorted already — which is every level a generator wrote, so two runs in either order still write
+ * the same bytes — and goes to the END, in sorted order among the new ones, when it is not. A
+ * wholly new subtree is the generator's own and arrives sorted.
+ */
+export function mergeJsonInPlace(held: JsonObject, incoming: JsonObject): JsonObject {
+  const heldKeys = Object.keys(held);
+  const added = Object.keys(incoming)
+    .filter((key) => !Object.hasOwn(held, key))
+    .sort(byCodeUnit);
+  const order = isSorted(heldKeys)
+    ? [...heldKeys, ...added].sort(byCodeUnit)
+    : [...heldKeys, ...added];
+  return Object.fromEntries(
+    order.map((key) => {
+      if (!Object.hasOwn(held, key)) return [key, sortJsonDeep(incoming[key])];
+      const current = held[key];
+      const next = incoming[key];
+      return [key, isObject(current) && isObject(next) ? mergeJsonInPlace(current, next) : current];
+    }),
+  );
+}

package/src/mcp-errors.ts

@@ -43,6 +43,14 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_VERIFY_MERGE_INCOMPLETE:
     'x verify merge parts/*.json --json   # after every CI job uploaded its part',
   X_VERIFY_MERGE_INPUT: 'x verify --only unit --json > part.json   # one document per part',
+  X_VERIFY_STEP_TIMEOUT:
+    'x verify --only unit --json   # reproduce the step alone; one that needs longer states it under "stepTimeoutMs" in x.verify.json',
+  X_COVERAGE_BELOW_FLOOR:
+    'x verify --only unit --json   # names the ten files losing the most lines; cover the worst with a test beside it',
+  X_COVERAGE_FLOOR_UNSTATED:
+    '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',
   X_SCAFFOLD_PATH_ESCAPE: 'x g route posts --json   # a path with no ".." segment',
   X_GENERATE_JSON_INVALID:
@@ -233,18 +241,30 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_GUARD_FAILED: 'x verify --json   # the cause carries the throw the guard raised, verbatim',
   X_GUARD_FINDING_INVALID:
     'x verify --json   # then give the finding an X_ code, a cause and a fix naming a command',
+  // The finding's own `fix:` is this command plus the edit — the line, and what replaces the call.
+  X_BROWSER_TRANSPORT_BYPASS:
+    'x verify --only boundaries --json   # each finding names the line and the transport to use instead',
+  X_BROWSER_SERVER_BARREL:
+    'x verify --only boundaries --json   # each finding names the import and the browser entry to import instead',
   // `EDITOR=` inline rather than `export`: the variable is only needed for the one invocation, and
   // an agent copying this line gets a working command instead of a shell it has to keep.
   X_SECRETS_EDITOR_MISSING: 'EDITOR=nano x secrets edit',
   X_SECRETS_EDIT_FAILED: 'x secrets show --json   # then re-open the buffer: x secrets edit',
+  X_SEAL_RESEAL_PENDING:
+    'x doctor --json   # names the sealed columns and the retired key; re-seal with a backfill(), then: x secrets rotate --drop <keyId>',
   // Render's code, thrown here by the bundler half: the cause names the specifier and the file it
   // resolved to, and `x g island` is what puts that file where the page already says it is.
   X_ISLAND_INVALID: 'x routes --json   # the cause names the src; then: x g island <name>',
   // The four slice-11 codes: generated code that passed the gate and failed at runtime.
+  // The role map's file is the app's: the finding's `at` names it, so this line never guesses one.
   X_PERMISSION_UNGRANTED:
-    'x verify --only policy --json   # then add the permission to a role in apps/web/shared/roles.ts',
+    'x verify --only policy --json   # then add the permission to a role in the file the finding names (at)',
   X_JOB_UNREGISTERED:
     'x manifest --json   # after listing the module under jobs: [...] in apps/web/api/index.ts',
+  // The boot's twin of the line above: the worker or scheduler loaded only what the API index
+  // imports, and the manifest names a job or task that load did not register.
+  X_ROLE_LOAD_INCOMPLETE:
+    'x manifest --json   # after importing the module the cause names from apps/web/api/index.ts',
   X_FEATURE_UNKNOWN:
     'x entities --json   # then x g resource <feature> for the one the cause names',
   X_BUDGET_PARAMS_UNDECLARED:
@@ -256,6 +276,14 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_DEV_RESTART_REQUIRED:
     'x dev --json   # a fresh process; the supervised x dev restarts itself on such a save',
   X_DEV_ROOT_GONE: 'x dev --json   # from the app root, once it exists again',
+  X_DB_HANDLE_UNREGISTERED:
+    'x g entity widget --dry-run --json   # lists the files; the finding names the two lines to add to packages/db/src/client.ts',
+  X_ADMIN_RESOURCE_UNWIRED:
+    'x g resource widget --admin --dry-run --json   # lists the files; the finding names the two lines to add to apps/admin/app/admin/admin.ts',
+  X_IMAGE_NOT_PREBUILT:
+    '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',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/messages.ts

@@ -50,12 +50,21 @@ const CATALOG = {
   'cli.db.branch.unknown': '-',
   'cli.db.gen.failed': 'migration not generated',
   'cli.db.gen.unchanged': 'entities and migrations agree — nothing to generate',
+  'cli.db.gen.blocked':
+    'nothing was compared — the app did not load ({count} finding(s)); fix them, then run x db gen again',
   // A THIRD outcome, and it is neither of the other two: nothing to generate, but the sidecar the
   // `drift` step reads did move — an edit under `packages/db/src` that implies no DDL. Rendering it
   // as `written` would name a migration nobody can apply; as `unchanged`, it would hide a file this
   // command wrote. `GeneratedFiles.outcome` is what `--json` carries the same distinction on.
   'cli.db.gen.recorded': 'no migration needed — schema hash re-recorded in {file}',
+  // The fourth: no DDL and no sidecar moved, but `packages/db/schema/` did — a hand edit repaired,
+  // or a framework table that changed under an upgrade. `unchanged` would deny a write the lines
+  // below it list, and this command is `X_SCHEMA_DUMP_DRIFT`'s whole `fix:`.
+  'cli.db.gen.dumped': 'no migration needed — schema dump rewritten ({count} file(s))',
   'cli.db.gen.written': 'migration {id} generated',
+  // Exit 1 and a migration on disk at once: the summary carries the half the exit code hides.
+  'cli.db.gen.writtenDumpFailed':
+    'migration {id} generated and written — the schema dump was not; do not generate it again',
   'cli.db.migrate.applied': 'migrations applied',
   'cli.db.migrate.failed': 'migration failed',
   'cli.db.reset.done': 'database reset and migrated',
@@ -88,6 +97,11 @@ const CATALOG = {
   'cli.deploy.plan': 'containers only: {images} image, roles {roles}',
   'cli.doctor.clean': 'no findings — environment is shippable',
   'cli.doctor.findings': '{count} finding(s)',
+  'cli.doctor.guards':
+    '{count} shipped guard(s) this app does not hold — each line adds one, then x verify reports what it finds:',
+  // `x doctor`'s other listing: what the coverage floor in x.verify.json does not see, and why.
+  'cli.doctor.coverageExclude':
+    '{count} path(s) x.verify.json excludes from the coverage floor — each with the reason it gives:',
   'cli.docs.code': '{code} is an error code — x errors explain answers it',
   'cli.docs.exports': 'exports: {list}',
   'cli.docs.installed': 'installed: {list}',
@@ -110,6 +124,8 @@ const CATALOG = {
   'cli.fix.plan':
     '{count} boundary violation(s) involve {file} — {edits} edit(s) to make, nothing written',
   'cli.generate.wrote': 'wrote {count} file(s) for {kind} {name}',
+  // The run that declared a table: `{next}` is commands, joined with `&&`, that run as printed.
+  'cli.generate.wroteNext': 'wrote {count} file(s) for {kind} {name} — next: {next}',
   // A distinct key, not the same sentence with a flag beside it: `--dry-run` reported "wrote 4
   // file(s)" while `data.dryRun` said nothing had landed, so an agent branching on `summary`
   // believed the files were on disk.
@@ -131,7 +147,13 @@ const CATALOG = {
   'cli.jobs.drainedPartial':
     'drained {count} job(s) from {from} to {to} — {skipped} left on {from}',
   'cli.jobs.listed': '{count} job(s)',
+  'cli.jobs.nextPage': 'more — next page: x jobs ls --after {cursor}',
   'cli.jobs.noError': 'no error recorded',
+  'cli.jobs.paused': 'queue {queue} paused — no worker claims from it; enqueues still land',
+  'cli.jobs.pausedQueues': 'paused queue(s): {queues}',
+  'cli.jobs.promoted': 'job {id} promoted — due now',
+  'cli.jobs.removed': 'job {id} removed — it was {state}',
+  'cli.jobs.resumed': 'queue {queue} resumed',
   'cli.jobs.retried': 'job {id} re-queued — {state}',
   'cli.jobs.shown': 'job {id} — {state}, attempt {attempt} of {attempts}',
   'cli.jobs.skipped': '{count} job(s) left on {from} — re-run the drain once each is claimable:',
@@ -296,6 +318,12 @@ const CATALOG = {
   // no skipped test to read a reason off, so the files the step selected hold no test.
   'cli.verify.ranNothing': 'found no test to run in the file(s) it selected',
   'cli.verify.merged': 'merged {parts} part(s) — {summary}',
+  // The `unit` step's own measurement, in `output`: what the suite covered of the app's whole
+  // source tree, beside the floor it was held to. A shard says it measured a slice instead.
+  'cli.verify.coverage':
+    'coverage: {lines}% of lines, {funcs}% of functions over {files} source file(s) — floor {floor}',
+  'cli.verify.coverageDeferred':
+    'coverage: this shard measured its own slice — x verify merge folds every shard and judges the floor',
   'cli.verify.serial': 'serial',
   'cli.verify.workers': '{workers} workers',
   'cli.env.checked': '{count} declared variable(s), all present and valid',
@@ -314,6 +342,11 @@ const CATALOG = {
   'cli.secrets.set': 'sealed {name} into {path} — {count} secret(s)',
   'cli.secrets.rotated':
     'rotated {path} from master key {from} to {to} — {count} secret(s) resealed',
+  'cli.secrets.retired':
+    '  master key {kid} is retired, not gone: values it sealed still open — once they are re-sealed, x secrets rotate --drop {kid}',
+  'cli.secrets.dropped':
+    'dropped retired master key {kid} from {path} — {count} retired key(s) still declared',
+  'cli.secrets.ring': 'retired master key(s) that still open sealed values: {kids}',
 } as const;
 
 export type MessageKey = keyof typeof CATALOG;

package/src/metrics-endpoint.ts

@@ -1,6 +1,7 @@
 // Single responsibility: the scrape listener every role opens. `@ultimat3/core` declares the
 // series and renders the body; this is the one place a process answers `METRICS_PATH` with it, so
-// `docker/helm`'s HPAs read a number instead of `<unknown>`.
+// `docker/helm`'s HPAs read a number instead of `<unknown>`. Opening it starts the process's own
+// series (`process_*`): a role that can be scraped reports what it costs.
 
 import {
   finiteCount,
@@ -9,6 +10,7 @@ import {
   METRICS_PATH,
   markListening,
   metricsText,
+  startProcessMetrics,
   stringField,
   UltimateError,
 } from '@ultimat3/core';
@@ -64,6 +66,55 @@ export interface MetricsEndpointOptions {
   readonly port?: number;
   /** A container must bind every interface; a laptop must not. Same decision as the web role. */
   readonly hostname?: string;
+  /**
+   * The `process_info{role}` label: `ROLE` in a container, the roles `x dev` runs joined by `+`.
+   * A host that opens the listener itself and names none is labelled `unknown`.
+   */
+  readonly role?: string;
+  /**
+   * What a taken port means. `refuse` (the default, and every container's): `X_PORT_IN_USE` —
+   * Prometheus is configured against the declared port, so listening anywhere else is a scrape
+   * that silently finds nothing. `free`: bind whichever port the kernel hands out and say which —
+   * `x dev` with no `METRICS_PORT`, where two apps on one laptop both default to 9090.
+   */
+  readonly whenTaken?: 'refuse' | 'free';
+}
+
+/**
+ * Which answer a boot gives. A laptop that named no port takes a free one when 9090 is another
+ * app's; a declared `METRICS_PORT` — and every container — is the port a scraper was told, so it
+ * refuses rather than listen where nothing will look.
+ */
+export const whenMetricsPortTaken = (
+  dev: boolean,
+  env: Readonly<Record<string, string | undefined>>,
+): 'refuse' | 'free' => {
+  const declared = env['METRICS_PORT'];
+  return dev && (declared === undefined || declared.trim().length === 0) ? 'free' : 'refuse';
+};
+
+/**
+ * The bind and its one retry. `bind` is `Bun.serve` behind a seam: whether a kernel refuses a
+ * second bind is the OS's answer, and the rule here is testable without racing a socket for it.
+ * Port 0 is never retried — the kernel chose it, so a refusal there is not a collision.
+ */
+export function bindScrapePort<T>(
+  port: number,
+  whenTaken: 'refuse' | 'free',
+  bind: (port: number) => T,
+): T {
+  try {
+    return bind(port);
+  } catch (error) {
+    if (!isAddressInUse(error)) throw error;
+    if (whenTaken === 'refuse' || port === 0) throw new MetricsPortInUseError({ port });
+    logger.warn('ultimate metrics port taken', {
+      port,
+      cause: `the metrics port ${String(port)} is already bound — another x dev, or a Prometheus — so this process listens on a free one`,
+      fix: `METRICS_PORT=${String(neighbouringPort(port))} x dev --json`,
+    });
+    return bind(0);
+  }
 }
 
 export interface MetricsEndpoint {
@@ -86,29 +137,24 @@ export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): Metr
   const port = finiteCount('startMetricsEndpoint', 'port', options.port ?? DEFAULT_METRICS_PORT);
   // `startRoles` opens this FIRST, before any role, so `Bun.serve`'s own bare `Error` was what a
   // second `x dev` on one machine reported: no code, no fix, at the boot path this package owns.
-  // The return type is inferred, keeping `Bun.serve`'s own shape stated once.
-  function listen() {
-    try {
-      return Bun.serve({
-        port,
-        hostname: options.hostname ?? 'localhost',
-        fetch(request: Request): Response {
-          if (new URL(request.url).pathname !== METRICS_PATH) {
-            return new Response('not found', { status: 404 });
-          }
-          // `collectMetrics()` is cumulative and never reset by a read, so two scrapers cannot
-          // steal each other's samples — but a cache would hand the second one a stale window.
-          return new Response(metricsText(), {
-            headers: { 'content-type': METRICS_CONTENT_TYPE, 'cache-control': 'no-store' },
-          });
-        },
-      });
-    } catch (error) {
-      if (!isAddressInUse(error)) throw error;
-      throw new MetricsPortInUseError({ port });
-    }
-  }
-  const server = listen();
+  const server = bindScrapePort(port, options.whenTaken ?? 'refuse', (candidate) =>
+    Bun.serve({
+      port: candidate,
+      hostname: options.hostname ?? 'localhost',
+      fetch(request: Request): Response {
+        if (new URL(request.url).pathname !== METRICS_PATH) {
+          return new Response('not found', { status: 404 });
+        }
+        // `collectMetrics()` is cumulative and never reset by a read, so two scrapers cannot
+        // steal each other's samples — but a cache would hand the second one a stale window.
+        return new Response(metricsText(), {
+          headers: { 'content-type': METRICS_CONTENT_TYPE, 'cache-control': 'no-store' },
+        });
+      },
+    }),
+  );
+  // After the bind: a port that was taken starts no sampler nobody would stop.
+  const stopProcessMetrics = startProcessMetrics({ role: options.role ?? 'unknown' });
   // Same rule as every other socket the framework opens: announce it, so a request back to it is
   // recognisably this process calling itself rather than egress the test seal must refuse.
   const stopListening = markListening(server.url.origin);
@@ -118,6 +164,7 @@ export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): Metr
     stop(): void {
       server.stop(true);
       stopListening();
+      stopProcessMetrics();
     },
   };
 }

package/src/migration-extensions.ts

@@ -0,0 +1,29 @@
+// Which Postgres extensions an app's migrations create. One reader for the two embedded boots
+// that must agree — `x dev`'s database (`runtime-queue.ts`) and the schema dump's scratch replay
+// (`db-schema-dump.ts`): PGlite links an extension only when it is named at boot, and an app that
+// replays in the gate and fails in `x dev` was the result of only one of them asking.
+
+import type { Migration } from '@ultimat3/db';
+import { readMigrations } from './migrations';
+
+const CREATE_EXTENSION = /\bcreate\s+extension\s+(?:if\s+not\s+exists\s+)?"?([a-z][a-z0-9_-]*)"?/gi;
+
+/**
+ * Every extension the migrations create, sorted. Matched on the raw text, comments included, on
+ * purpose: over-reading costs one bundle that is never created, and a name nothing ships is
+ * refused later by `create extension` itself. Blanking quoted identifiers first would lose
+ * `"uuid-ossp"`, the one spelling that needs its quotes.
+ */
+export function migrationExtensions(migrations: readonly Migration[]): readonly string[] {
+  const names = new Set<string>();
+  for (const migration of migrations) {
+    for (const match of migration.up.matchAll(CREATE_EXTENSION)) {
+      if (match[1] !== undefined) names.add(match[1].toLowerCase());
+    }
+  }
+  return [...names].sort();
+}
+
+/** The same list for an app on disk — what an embedded boot hands `createPgliteClient`. */
+export const appExtensions = async (root: string): Promise<readonly string[]> =>
+  migrationExtensions(await readMigrations(root));

package/src/module-imports.ts

@@ -0,0 +1,47 @@
+// The files one module's source imports, resolved the way Bun will resolve them. One function for
+// the two graphs built over it: the reload graph (`app-reload-graph.ts`), which follows every file
+// a module NAMES, and the document graph (`document-graph.ts`), which follows only what
+// EVALUATING the module evaluates. Each caller keeps its own rule for which targets it walks.
+
+// why: Bun ships no path API; an import specifier resolves against the importing file's directory.
+import { dirname } from 'node:path';
+
+/**
+ * `referenced`: every file the module names, an `await import()` target included — a save to one
+ * must reload its importer. `evaluated`: what importing the module evaluates, so the lazy targets
+ * are left out. Each keeps the transpiler pass its graph was built on (`scanImports`, the fast
+ * one, and `scan`); measured on Bun 1.4.0 the two agree on every static shape — both drop
+ * `import type` and an inline `type` specifier, both keep a value import used only as a type.
+ */
+export type ImportEdges = 'referenced' | 'evaluated';
+
+const transpilers = {
+  ts: new Bun.Transpiler({ loader: 'ts' }),
+  tsx: new Bun.Transpiler({ loader: 'tsx' }),
+};
+
+/**
+ * Absolute paths, in source order. A file that will not parse imports nothing yet, and a
+ * specifier that will not resolve contributes no edge: the module's own import reports both.
+ */
+export function resolvedImports(path: string, source: string, edges: ImportEdges): string[] {
+  const transpiler = path.endsWith('x') ? transpilers.tsx : transpilers.ts;
+  let specifiers: readonly { readonly path: string; readonly kind: string }[];
+  try {
+    specifiers =
+      edges === 'referenced'
+        ? transpiler.scanImports(source)
+        : transpiler.scan(source).imports.filter((one) => one.kind !== 'dynamic-import');
+  } catch {
+    return [];
+  }
+  const found: string[] = [];
+  for (const { path: specifier } of specifiers) {
+    try {
+      found.push(Bun.resolveSync(specifier, dirname(path)));
+    } catch {
+      // Unresolvable: no edge.
+    }
+  }
+  return found;
+}