@ultimat3/cli 2.0.0 → 4.0.0

package/src/db-seed.ts

@@ -0,0 +1,294 @@
+// `x db seed`, everything except the argv: where a seed is declared, which tier this environment
+// takes, and what one pass reports. A driver plus plain strings in, plain rows out — the
+// `db-backfill.ts` split repeated, so every rule here is testable with no `ParsedArgs` and no boot.
+//
+// The decisions a seed itself owns are `@ultimat3/entity`'s: `seedTiersFor` is the one table saying
+// which tiers an environment runs, and two copies of "may this seed run" would be two answers.
+
+// `node:path` for the joiner and the app-root-relative spelling every finding is keyed by; Bun
+// exposes neither.
+import { relative, sep } from 'node:path';
+import type { Environment } from '@ultimat3/core';
+import { UltimateError } from '@ultimat3/core';
+import type { Driver, Seed, SeedTier } from '@ultimat3/entity';
+import { isSeed, SEED_TIERS, seedTiersFor } from '@ultimat3/entity';
+import { docsFor } from './error-codes';
+import { BadFlagError } from './errors';
+import type { Finding, JsonValue } from './output';
+import { findingFrom } from './output';
+import { renderTable } from './table';
+
+/**
+ * Where an app keeps seeds: a `seeds` directory in a package, or a `seed*.ts` beside its entities —
+ * the two layouts the tracked apps already use, and nothing wider. `loadApp`'s whole-src glob was
+ * the alternative and it is the wrong tool here: importing every module of every package to find a
+ * fixture graph makes an unrelated module that will not import into a failed seed run.
+ * `apps/` is deliberately absent: a fixture graph is data, and data lives in a package.
+ */
+export const SEED_GLOBS = ['packages/*/seeds/**/*.ts', 'packages/*/src/seed*.ts'] as const;
+
+/**
+ * `x db seed <name>` named a seed no module declared. `X_DECLARATION_UNKNOWN` is the code the
+ * registries already answer this with — a seed is a declaration, and a second code for "no such
+ * name" is the synonym the registry exists to prevent. The known names ARE listed, unlike
+ * `DeclarationUnknownError`'s count: an app has one to five seeds, not two hundred actions, and
+ * picking another one is the entire remedy.
+ *
+ * Both classes live HERE rather than in `errors.ts` for one reason, stated so nobody has to guess:
+ * that file is at the 500-line ceiling `x verify`'s `filesize` step enforces, and these two are
+ * `x db seed`'s alone. The codes stay CLI-owned in `error-codes.ts`, as every code does.
+ */
+export class SeedUnknownError extends UltimateError {
+  constructor(input: { name: string; known: readonly string[] }) {
+    super({
+      code: 'X_DECLARATION_UNKNOWN',
+      cause:
+        input.known.length === 0
+          ? `no seed named "${input.name}" — this app declares none (a seed is an exported defineSeed() in packages/<pkg>/seeds or packages/<pkg>/src/seed.ts)`
+          : `no seed named "${input.name}" is declared (known: ${input.known.join(', ')})`,
+      // A dry run, never a bare `x db seed`: the command that answers "which seeds are there" must
+      // not be the command that writes them.
+      fix: 'x db seed --dry-run --json',
+      docs: docsFor('X_DECLARATION_UNKNOWN'),
+    });
+  }
+}
+
+/**
+ * The seed's tier is not one this environment runs. `dev` fixtures reaching production is the one
+ * irreversible mistake `x db seed` can make, so it is refused rather than confirmed.
+ *
+ * `X_SEED_ENVIRONMENT` is its own code, not `X_CLI_BAD_FLAG`: the argv was well formed and the
+ * answer is still no. A flag code says "you typed it wrong" and sends the reader to `x help`; this
+ * says "this environment does not run that tier", whose one remedy is naming the tier. The env var
+ * is named in the cause and not in the `fix:`, because a `fix:` is one pasteable line and a
+ * container with a fixed command line is the case that needs the other half.
+ */
+export class SeedEnvironmentError extends UltimateError {
+  constructor(input: {
+    seed: string;
+    tier: string;
+    environment: string;
+    tiers: readonly string[];
+  }) {
+    super({
+      code: 'X_SEED_ENVIRONMENT',
+      cause: `seed "${input.seed}" is tier ${input.tier} and ULTIMATE_ENV resolved ${input.environment}, where x db seed runs ${input.tiers.join(', ')} — ULTIMATE_SEED_TIER=${input.tier} says this deploy takes it anyway`,
+      fix: `x db seed ${input.seed} --tier ${input.tier} --json`,
+      docs: docsFor('X_SEED_ENVIRONMENT'),
+    });
+  }
+}
+
+export interface DiscoveredSeed {
+  readonly seed: Seed;
+  /** App-root-relative POSIX path of the module that declared it. */
+  readonly file: string;
+}
+
+export interface SeedDiscovery {
+  readonly seeds: readonly DiscoveredSeed[];
+  /** Modules that would not import. Reported, never swallowed: one of them may hold the seed. */
+  readonly findings: readonly Finding[];
+}
+
+/**
+ * Every seed the app declares, by importing the modules that declare them — the same rule
+ * `loadApp` follows, because importing IS the declaration. Sorted by file, so a run's order is the
+ * one a reader can predict from the tree (`01_orgs.ts` before `02_posts.ts`) rather than the one a
+ * glob happened to yield.
+ */
+export async function discoverSeeds(root: string): Promise<SeedDiscovery> {
+  const seeds: DiscoveredSeed[] = [];
+  const findings: Finding[] = [];
+  const seen = new Set<string>();
+  for (const pattern of SEED_GLOBS) {
+    for await (const absolute of new Bun.Glob(pattern).scan({ cwd: root, absolute: true })) {
+      if (absolute.includes('node_modules') || absolute.includes('.test.')) continue;
+      if (seen.has(absolute)) continue;
+      seen.add(absolute);
+      const file = relative(root, absolute).split(sep).join('/');
+      let module: Record<string, unknown>;
+      try {
+        module = (await import(absolute)) as Record<string, unknown>;
+      } catch (error) {
+        findings.push({ ...findingFrom(error), at: file });
+        continue;
+      }
+      for (const value of Object.values(module)) {
+        if (isSeed(value)) seeds.push({ seed: value, file });
+      }
+    }
+  }
+  return {
+    seeds: seeds.toSorted((left, right) => left.file.localeCompare(right.file)),
+    findings,
+  };
+}
+
+/** `--tier`, or `ULTIMATE_SEED_TIER` for a container whose command line is fixed. */
+export function parseSeedTierFlag(value: string | undefined): SeedTier | undefined {
+  if (value === undefined || value === '') return undefined;
+  if ((SEED_TIERS as readonly string[]).includes(value)) return value as SeedTier;
+  throw new BadFlagError({
+    flag: 'tier',
+    command: 'db seed',
+    reason: `unknown tier "${value}" (known: ${SEED_TIERS.join(', ')})`,
+    fix: 'x db seed --dry-run --json',
+  });
+}
+
+export interface SeedSelection {
+  readonly discovered: readonly DiscoveredSeed[];
+  /** The positional. Absent runs every seed whose tier this environment takes. */
+  readonly name?: string | undefined;
+  readonly environment: Environment;
+  readonly requested?: SeedTier | undefined;
+}
+
+/**
+ * Which seeds this invocation runs, and the two refusals that are not a run.
+ *
+ * The environment check is HERE and again in `cmd-db.ts` before the driver is booted, on purpose:
+ * seeding is the one irreversible thing this command does, and the layer that boots a connection
+ * to production must not be the only layer that decided it was allowed to.
+ */
+export function selectSeeds(input: SeedSelection): readonly DiscoveredSeed[] {
+  const tiers = seedTiersFor(input.environment, input.requested);
+  const known = input.discovered.map((entry) => entry.seed.name);
+  if (input.name === undefined) {
+    return input.discovered.filter((entry) => tiers.includes(entry.seed.tier));
+  }
+  const chosen = input.discovered.filter((entry) => entry.seed.name === input.name);
+  const first = chosen[0];
+  if (first === undefined) throw new SeedUnknownError({ name: input.name, known });
+  if (chosen.length > 1) {
+    throw new BadFlagError({
+      flag: 'name',
+      command: 'db seed',
+      reason: `"${input.name}" names ${chosen.length} seeds (${chosen.map((entry) => entry.file).join(', ')}) — a seed name is how a run is asked for, so two of them make the ask unanswerable`,
+      fix: 'x db seed --dry-run --json',
+    });
+  }
+  if (!tiers.includes(first.seed.tier)) {
+    throw new SeedEnvironmentError({
+      seed: first.seed.name,
+      tier: first.seed.tier,
+      environment: input.environment,
+      tiers,
+    });
+  }
+  return chosen;
+}
+
+export type SeedStatus = 'ok' | 'failed';
+
+export interface SeedPassRow {
+  readonly file: string;
+  readonly name: string;
+  readonly tier: SeedTier;
+  readonly status: SeedStatus;
+  readonly ms: number;
+  readonly inserted: number;
+  readonly updated: number;
+  readonly skipped: number;
+  readonly finding: Finding | null;
+}
+
+export interface SeedPassOptions {
+  readonly seeds: readonly DiscoveredSeed[];
+  readonly driver: Driver;
+  readonly dryRun: boolean;
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  /**
+   * One transaction PER SEED, never one around the run: a seed that fails must not roll back the
+   * ones that already succeeded, and a fixture graph half-written is worse than one not written.
+   * Injected so this stays testable with no database; `cmd-db.ts` passes `withTransaction`.
+   */
+  readonly transaction: <T>(work: () => Promise<T>) => Promise<T>;
+}
+
+/** Each seed, in file order, each isolated from the next. Never throws — a failure is a row. */
+export async function runSeeds(options: SeedPassOptions): Promise<readonly SeedPassRow[]> {
+  const rows: SeedPassRow[] = [];
+  for (const entry of options.seeds) {
+    const started = Bun.nanoseconds();
+    const elapsed = (): number => Math.round((Bun.nanoseconds() - started) / 1_000_000);
+    try {
+      const run = await options.transaction(() =>
+        entry.seed.run({ driver: options.driver, dryRun: options.dryRun, env: options.env }),
+      );
+      rows.push({
+        file: entry.file,
+        name: run.name,
+        tier: run.tier,
+        status: 'ok',
+        ms: elapsed(),
+        ...run.metrics,
+        finding: null,
+      });
+    } catch (error) {
+      rows.push({
+        file: entry.file,
+        name: entry.seed.name,
+        tier: entry.seed.tier,
+        status: 'failed',
+        ms: elapsed(),
+        inserted: 0,
+        updated: 0,
+        skipped: 0,
+        finding: { ...findingFrom(error), at: entry.file },
+      });
+    }
+  }
+  return rows;
+}
+
+export interface SeedTotals {
+  readonly inserted: number;
+  readonly updated: number;
+  readonly skipped: number;
+  readonly failed: number;
+}
+
+export const seedTotals = (rows: readonly SeedPassRow[]): SeedTotals => ({
+  inserted: rows.reduce((sum, row) => sum + row.inserted, 0),
+  updated: rows.reduce((sum, row) => sum + row.updated, 0),
+  skipped: rows.reduce((sum, row) => sum + row.skipped, 0),
+  failed: rows.filter((row) => row.status === 'failed').length,
+});
+
+/**
+ * Slowest first, in both renderers: a seed run that got slow is diagnosed by which FILE took the
+ * time, and a list in run order buries that under whatever happens to be alphabetically first.
+ */
+const slowestFirst = (rows: readonly SeedPassRow[]): readonly SeedPassRow[] =>
+  rows.toSorted((left, right) => right.ms - left.ms);
+
+export const seedPassToJson = (rows: readonly SeedPassRow[]): JsonValue => ({
+  seeds: slowestFirst(rows).map((row) => ({
+    file: row.file,
+    name: row.name,
+    tier: row.tier,
+    status: row.status,
+    ms: row.ms,
+    inserted: row.inserted,
+    updated: row.updated,
+    skipped: row.skipped,
+  })),
+  totals: { ...seedTotals(rows) },
+});
+
+export const renderSeedTable = (rows: readonly SeedPassRow[]): readonly string[] =>
+  renderTable(
+    ['seed', 'tier', 'status', 'ms', 'inserted', 'updated', 'skipped'],
+    slowestFirst(rows).map((row) => [
+      row.name,
+      row.tier,
+      row.status,
+      String(row.ms),
+      String(row.inserted),
+      String(row.updated),
+      String(row.skipped),
+    ]),
+  );

package/src/dev-assets.ts

@@ -14,7 +14,7 @@ import { applyCacheHeaders } from '@ultimat3/http';
 import type { IconPlan } from '@ultimat3/pwa';
 import { BuiltinImagePipeline, PwaIconMissingError, planIcons } from '@ultimat3/pwa';
 import type { ImageQuery, ImageTransformDriver } from '@ultimat3/seo';
-import { builtinImageDriver, parseImageQuery } from '@ultimat3/seo';
+import { builtinImageDriver, DEFAULT_WIDTHS, parseImageQuery } from '@ultimat3/seo';
 import type { ImageFormat, ImageTransform, Storage } from '@ultimat3/storage';
 import { IMAGE_FORMATS, isTenantScoped, variantKey } from '@ultimat3/storage';
 import {
@@ -49,6 +49,24 @@ export const MEDIA_BASE_PATH = '/media';
  */
 const IMMUTABLE_IMAGE: CacheHint = { mode: 'immutable' };
 
+/**
+ * Whether a variant is one the framework itself can MINT, and therefore one worth storing.
+ *
+ * The cache key is built entirely from caller-supplied query values, and a signed-in reader
+ * holding `storage:read` may ask for any of them on their own objects — so `?w=1`, `?w=2`, … each
+ * wrote a new object to the app's only disk. `@ultimat3/seo`'s `MAX_IMAGE_WIDTH` (8192) bounds the
+ * blast radius and does not close it: 8192 stored objects per source, per format, is amplification
+ * a tenant drives with a `for` loop.
+ *
+ * The set is `DEFAULT_WIDTHS` **plus the source's intrinsic width**, which is exactly what
+ * `usableWidths` puts in a `srcset` — clamping to the constant alone would refuse the widest entry
+ * of every image whose intrinsic width is not one of the eight, a URL the framework mints itself.
+ * Anything outside it is still SERVED: this decides what is written, not what is answered, so no
+ * caller gains a new 4xx and the disk stops growing on a stranger's key.
+ */
+const isMintableWidth = (width: number | undefined, intrinsic: number): boolean =>
+  width === undefined || width === intrinsic || DEFAULT_WIDTHS.includes(width);
+
 const imageResponse = (bytes: Uint8Array, contentType: string, cache: CacheHint): Response =>
   applyCacheHeaders(
     // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
@@ -112,6 +130,7 @@ async function transformedVariant(
   }
 
   const source = await disk.get(key);
+  const intrinsic = probeImage(source.bytes).width;
   // The seam is WHICH driver transforms, not who resolves the bytes: `TransformRequest.width` is
   // required, and a request with no `?w=` gets its width from the source's own header — so the
   // read happens either way and a supplied driver is handed the same resolved request the builtin
@@ -122,11 +141,11 @@ async function transformedVariant(
     src: key,
     // A header read, not a decode: `?f=webp` alone still needs a width, and the source's own is
     // the only one that does not resize an image the caller never asked to resize.
-    width: query.width ?? probeImage(source.bytes).width,
+    width: query.width ?? intrinsic,
     ...(query.format === undefined ? {} : { format: query.format }),
     ...(query.quality === undefined ? {} : { quality: query.quality }),
   });
-  if (cached !== undefined) {
+  if (cached !== undefined && isMintableWidth(query.width, intrinsic)) {
     await disk.put(cached, variant.bytes, { contentType: variant.contentType });
   }
   return imageResponse(variant.bytes, variant.contentType, cache);

package/src/dev-cache.ts

@@ -79,25 +79,25 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void>
   registerInvalidationBroadcast(async (wireTags) => {
     await options.transport.publish(CACHE_INVALIDATE_SUBJECT, JSON.stringify(wireTags));
   });
-  let subscription: TransportSubscription | undefined;
-  // Not awaited: the boot must not block on a subscribe, and a bus that refuses one is a process
-  // that misses peer invalidations, never a process that fails to start.
-  void options.transport
+  // Not awaited HERE: the boot must not block on a subscribe, and a bus that refuses one is a
+  // process that misses peer invalidations, never a process that fails to start. The PROMISE is
+  // held rather than a handle assigned inside a `.then`, because the release ran first whenever
+  // `stop()` beat the round trip — a NATS bus plus a boot that throws in `bootRoles`, or a test
+  // that boots and stops immediately — and the subscription that landed afterwards was live with
+  // nobody left holding it. `mcp-host.ts`'s lazy `started` is the same shape.
+  const subscribing: Promise<TransportSubscription | undefined> = options.transport
     .subscribe(CACHE_INVALIDATE_SUBJECT, (payload: string) => {
       void applyBroadcast(payload);
     })
-    .then((handle) => {
-      subscription = handle;
-    })
     .catch((error: unknown) => {
       logger.warn('cache.broadcast.subscribe-failed', { error: messageOf(error) });
+      return undefined;
     });
 
   // `resetTiers()` drops the registry AND the broadcast in one call: this boot is the only thing
   // that registers either, and a tier left behind would purge for a process that has stopped.
   return async () => {
-    subscription?.unsubscribe();
-    subscription = undefined;
+    (await subscribing)?.unsubscribe();
     resetTiers();
   };
 }

package/src/dev-render.ts

@@ -24,6 +24,7 @@ import {
   createIsrController,
   headFromMeta,
   hydrateRuntime,
+  isrKey,
   metaContextFor,
   renderComponent,
   renderHead,
@@ -185,7 +186,11 @@ async function resultFor(
       return { status: 200, headers: staticHeaders(contentHash(body), options.buildId), body };
     }
     case 'isr': {
-      const served = await isr.serve(url.pathname, () =>
+      // `isrKey(url)`, never `url.pathname`: the query is part of what was rendered — this
+      // route's own `meta` reads `data.url` — so two URLs differing only in their query are two
+      // documents. Keyed on the pathname alone, the first render answered every later query
+      // string (#171). Render owns the derivation so no second caller can invent another.
+      const served = await isr.serve(isrKey(url), () =>
         documentFrom(entry, request, data, options),
       );
       return served.result;

package/src/dev-roles.ts

@@ -294,9 +294,11 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
     // — every enqueue in a request handler silently becomes a job that never runs.
     //
     // On `worker`, and on `worker` alone: it is the role that exists wherever jobs run at all, and
-    // a relay is safe to duplicate (publish-then-mark is at-least-once and the idempotency key
-    // collapses the repeat) but pointless to spread. A deployment with no `worker` has no one to
-    // run the jobs either way.
+    // a relay is safe to duplicate — the claim is a LEASE taken in the statement that locks the
+    // row, so two relays never hold one batch — but pointless to spread. The idempotency key is
+    // not the reason and never was: its conflict target is a partial index over live states, so it
+    // collapses a repeat only while the first job is still live. A deployment with no `worker` has
+    // no one to run the jobs either way.
     const relay: OutboxRelay | null = selected.includes('worker')
       ? createOutboxRelay({ store: options.runtime.outbox, driver: options.runtime.jobs })
       : null;

package/src/dev-runtime.ts

@@ -6,7 +6,7 @@
 import { mkdirSync } from 'node:fs';
 import type { PurgeDriver } from '@ultimat3/cache';
 import { isNoopPurgeDriver, selectPurgeDriver } from '@ultimat3/cache';
-import { isLocal, resolveEnvironment } from '@ultimat3/core';
+import { isLocal, renderThrowable, resolveEnvironment } from '@ultimat3/core';
 import type { EventBus, JobDriver, OutboxStore } from '@ultimat3/jobs';
 import type { MailDriver } from '@ultimat3/mail';
 import {
@@ -167,7 +167,7 @@ export function startStorage(services: DevServices, env: Env, override?: Storage
   try {
     mkdirSync(root, { recursive: true });
   } catch (cause) {
-    const detail = cause instanceof Error ? cause.message : String(cause);
+    const detail = renderThrowable(cause);
     throw new StorageUnwritableError(
       `the embedded storage disk needs ${root} and it could not be created: ${detail}`,
       `mount a writable volume at ${root}, or set S3_ENDPOINT and S3_BUCKET to use object storage instead`,

package/src/dev-storage.ts

@@ -2,6 +2,10 @@
 // owns keys, bytes and the tenant boundary and owns no `Response`; `@ultimat3/policy` owns the
 // one authz decision; this file is where those two meet a `Route` — the same shape `dev-assets.ts`
 // uses for `/icons` and `/media`, so `x dev` and `apps/web/server.ts` mount one read path, not two.
+//
+// The base path is `@ultimat3/storage`'s `DEFAULT_SIGNED_URL_BASE`, imported and never restated:
+// `localDriver` SIGNS `/_storage/<disk>/<key>`, so a local `'/_storage'` here is a second statement
+// of one constant — and a signer and a reader that disagree serve 404 for every signed URL.
 
 import { actorOf } from '@ultimat3/action';
 import type { Actor } from '@ultimat3/core';
@@ -12,15 +16,13 @@ import { can, codeOf, evaluate, forbidden, reasonOf } from '@ultimat3/policy';
 import type { Storage, StorageRead } from '@ultimat3/storage';
 import {
   assertSafeKey,
+  DEFAULT_SIGNED_URL_BASE,
   isTenantScoped,
   isWithinOrg,
   objectNotFound,
   orgMismatch,
 } from '@ultimat3/storage';
 
-/** `localDriver` signs `/_storage/<disk>/<key>`, so the read half hangs off the same base. */
-export const STORAGE_BASE_PATH = '/_storage';
-
 /**
  * The one capability that gates reading a stored object, on every disk. A permission and not a
  * per-disk family: `disk` is in the policy's `input`, so an app that wants a per-disk rule writes
@@ -223,7 +225,7 @@ export function storageRoutes(options: StorageRoutesOptions): readonly Route[] {
   return [
     {
       method: 'GET',
-      path: `${STORAGE_BASE_PATH}/:disk/*key`,
+      path: `${DEFAULT_SIGNED_URL_BASE}/:disk/*key`,
       meta: {
         name: 'storage.read',
         auth: 'required',

package/src/dev-traces.ts

@@ -71,9 +71,27 @@ function requestFacts(root: ReadableSpan): { method: string; path: string } {
   };
 }
 
+/** `http.request_id` is stamped by the pipeline's root and by nothing else; the name is a fallback. */
 const isHttpRoot = (span: ReadableSpan): boolean =>
-  span.parentSpanId === undefined &&
-  (span.attributes['http.request_id'] !== undefined || /^[A-Z]+ \//.test(span.name));
+  span.attributes['http.request_id'] !== undefined || /^[A-Z]+ \//.test(span.name);
+
+/**
+ * The request's own span among a trace's. `parentSpanId === undefined` was a third CONDITION
+ * until `As of 2026-08`, and it dropped every request that arrived with an inbound
+ * `traceparent`: `pipeline.ts` passes `parent: correlation.parent`, so the root has a defined
+ * `parentSpanId`, `spans.find(isHttpRoot)` answered `undefined`, and the whole trace vanished
+ * from `/_x/timeline` for any caller behind an instrumented client, an ingress or a service
+ * mesh. It survives as the TIE-BREAK: the outermost candidate is the one whose parent is not
+ * itself in this recording, so a nested candidate can never outrank the request's own span.
+ */
+function httpRootOf(spans: readonly ReadableSpan[]): ReadableSpan | undefined {
+  const candidates = spans.filter(isHttpRoot);
+  const recorded = new Set(spans.map((span) => span.context.spanId));
+  const outermost = candidates.find(
+    (span) => span.parentSpanId === undefined || !recorded.has(span.parentSpanId),
+  );
+  return outermost ?? candidates[0];
+}
 
 function toTrace(root: ReadableSpan, spans: readonly ReadableSpan[]): RequestTrace {
   const { method, path } = requestFacts(root);
@@ -121,7 +139,11 @@ export function createTraceRecorder(options: { limit?: number } = {}): TraceReco
     const spans = byTrace.get(traceId);
     if (spans === undefined) {
       byTrace.set(traceId, [span]);
-      // Bounded by trace, not by span: dropping half a request would leave a flame with holes.
+      // Bounded by TRACE, not by span: dropping half a request would leave a flame with holes.
+      // The cost is stated rather than capped — one trace's span array has no bound of its own, so
+      // a request issuing 50k statements holds 50k `ReadableSpan`s until it is evicted. That is a
+      // dev-only recorder (`serve.ts` installs none), and a per-trace cap would silently produce
+      // the holed flame this bound exists to prevent.
       while (byTrace.size > limit) {
         const oldest = byTrace.keys().next();
         if (oldest.done === true) break;
@@ -137,7 +159,7 @@ export function createTraceRecorder(options: { limit?: number } = {}): TraceReco
     traces(): readonly RequestTrace[] {
       const traces: RequestTrace[] = [];
       for (const spans of byTrace.values()) {
-        const root = spans.find(isHttpRoot);
+        const root = httpRootOf(spans);
         if (root !== undefined) traces.push(toTrace(root, spans));
       }
       return traces.sort((a, b) => b.startedAt.localeCompare(a.startedAt));

package/src/dispatch.ts

@@ -3,10 +3,11 @@
 // path as results, so a failure is machine-readable exactly like a success.
 
 import { isAbsolute, resolve } from 'node:path';
-import { requireBunVersion } from './app-root';
+import { requireAppRoot, requireBunVersion } from './app-root';
 import { createHelpCommand } from './cmd-help';
+import { plannedCommandFor } from './cmd-planned';
 import type { CommandContext } from './command';
-import { UnknownCommandError } from './errors';
+import { CliNotImplementedError, UnknownCommandError } from './errors';
 import type { Runner } from './exec';
 import { exec } from './exec';
 import type { CommandResult } from './output';
@@ -42,14 +43,33 @@ const errorResult = (command: string, error: unknown): CommandResult => ({
  * end without terminating the test runner.
  */
 export async function dispatch(options: DispatchOptions): Promise<number> {
-  let args: ParsedArgs;
+  // Its own branch, ahead of the parse: an unsupported Bun is a fact about the environment and
+  // outranks anything argv says, including the planned pre-empt below.
   try {
     requireBunVersion(options.bunVersion);
+  } catch (error) {
+    options.write(render(errorResult('x', error), wantsJson(options.argv)));
+    return 1;
+  }
+
+  let args: ParsedArgs;
+  try {
     args = parseArgs(options.argv, SPECS);
   } catch (error) {
+    // A PLANNED command is not built, so every invocation of one must say that and nothing else.
+    // The parser refuses an undeclared flag before any `run` is reached and a planned command
+    // declares only the four globals, so `x logs tail --follow` reported X_CLI_BAD_FLAG — a flag
+    // list for a command that does not exist yet — while `x logs tail` reported the honest
+    // X_NOT_IMPLEMENTED with a runnable fix. Substituted here rather than in `parse.ts`, which is
+    // pure and knows nothing about what a command means; the precedent is the help swap below.
+    const planned = plannedCommandFor(commandFor(options.argv[0] ?? '')?.spec.name);
+    const failure =
+      planned === undefined
+        ? error
+        : new CliNotImplementedError({ feature: `x ${planned.name}`, fix: planned.fix });
     // `wantsJson`, not `includes('--json')`: a typo'd flag or a typo'd command is exactly the case
     // an agent hits while always passing `-j`, and the short form rendered prose it then parsed.
-    const result = errorResult('x', error);
+    const result = errorResult(planned?.name ?? 'x', failure);
     options.write(render(result, wantsJson(options.argv)));
     return 1;
   }
@@ -85,6 +105,15 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
   };
 
   try {
+    // The reader `CommandSpec.requiresApp` never had. Its doc said "the dispatcher enforces it" and
+    // `dispatch` did not read the field at all: the guarantee held only because all 17 declaring
+    // commands happen to call `requireAppRoot` themselves, so a new command that declares it and
+    // forgets the call ran outside an app with no refusal. Each of those 17 calls stays — they are
+    // what hands a command the root it works in, and several name a subcommand this cannot see
+    // (`env init`, `secrets set`) — but the DECLARATION is now what decides, ahead of any check a
+    // command makes about its own arguments. `--help` is exempt because `target` is then the help
+    // command, which declares nothing: usage for a command must be readable from anywhere.
+    if (target.spec.requiresApp === true) requireAppRoot(target.spec.name, ctx.cwd);
     const result = await target.run(ctx);
     options.write(render(result, args.json, args.flags.get('verbose') === true));
     // `x dev` and `x mcp serve --transport http` are still listening here: report first, so the

package/src/drift.ts

@@ -62,6 +62,41 @@ export async function writeSchemaHash(root: string, migrationId: string): Promis
   return hash;
 }
 
+/**
+ * "Some migration recorded this hash" — the one predicate, read by the check below AND by the
+ * reconcile above it. Two spellings would let `x db gen` report the sidecar written while
+ * `x verify` still reports drift over the same two files.
+ */
+const isRecorded = (records: readonly MigrationRecord[], hash: string): boolean =>
+  records.some((record) => record.hash === hash);
+
+export interface HashReconciliation {
+  readonly hash: string;
+  /** False when a sidecar already held this hash — nothing was written, and nothing needed to be. */
+  readonly written: boolean;
+}
+
+/**
+ * Re-record the sidecar for a migration that is already the right one. `SCHEMA_GLOB` covers every
+ * non-test file under `packages/db/src`, not only the ones that imply DDL, so editing a seed or a
+ * helper moves the hash with no diff behind it — and `X_DB_DRIFT`'s `fix:` has to have somewhere to
+ * land or the instruction is unfollowable. The caller owes the proof that the DDL genuinely did not
+ * move (`db-generate.ts` reaches this only on an empty diff off a fully loaded registry); this
+ * function decides only whether a write is needed.
+ *
+ * A hash an OLDER migration recorded is left alone: `checkSourceDrift` already answers clean on it,
+ * and stamping the newest sidecar would claim that migration produced a schema it did not.
+ */
+export async function reconcileSchemaHash(
+  root: string,
+  migrationId: string,
+): Promise<HashReconciliation> {
+  const hash = await schemaHash(root);
+  if (isRecorded(await recordedHashes(root), hash)) return { hash, written: false };
+  await Bun.write(join(root, MIGRATIONS_DIR, hashFileName(migrationId)), `${hash}\n`);
+  return { hash, written: true };
+}
+
 /**
  * How many entities the app declares. Injected so this module's own tests need no app on disk, and
  * so a caller that has already loaded the app can answer without loading it twice.
@@ -90,6 +125,11 @@ export async function checkSourceDrift(
     // `x db gen "initial"`, which has an empty diff there, writes no `.hash`, and exits ok: a fix
     // that succeeds and changes nothing. Drift resumes the moment the author declares an entity,
     // and by then the fix genuinely writes one.
+    //
+    // An empty diff still writes no `.hash` HERE, and must: `reconcileSchemaHash` needs a migration
+    // id to record against and there is no migration at all in this branch. With an entity declared
+    // the diff is never empty — a registry against zero migrations is `create table` for all of
+    // it — so this branch's fix stays the real generation it always was.
     if ((await declaredEntities()) === 0) return [];
     return [
       {
@@ -101,7 +141,7 @@ export async function checkSourceDrift(
       },
     ];
   }
-  if (records.some((record) => record.hash === current)) return [];
+  if (isRecorded(records, current)) return [];
   return [
     {
       code: 'X_DB_DRIFT',