@ultimat3/cli 2.0.0 → 3.0.0

package/src/cmd-verify.ts

@@ -31,6 +31,7 @@ import { msg } from './messages';
 import type { CommandResult, Finding, StepResult } from './output';
 import { findingFrom } from './output';
 import type { ParsedArgs } from './parse';
+import { WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
 import {
   floorProblemFindings,
   floorRequires,
@@ -44,6 +45,9 @@ import { TEST_STEPS } from './verify-tests';
 import { checkFileSizes, checkPackageShape, hasWorkspacePackages } from './workspace-checks';
 
 /** The whole contract, in cost order. Every check the framework knows how to make lives here. */
+/** The one file that makes the `roadmap` step answerable, and therefore what `applies` reads. */
+const ROADMAP_FILE = join('docs', 'idea', '14-roadmap.md');
+
 export const VERIFY_STEPS: readonly VerifyStep[] = [
   {
     name: 'typecheck',
@@ -224,8 +228,11 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     name: 'roadmap',
     summary: "every roadmap milestone's status marker matches what is actually on disk",
     // A generated app ships no `docs/idea/14-roadmap.md` — only the framework monorepo does, so
-    // only a host that registers this check has anything for the step to verify.
-    applies: async (ctx) => ctx.hostChecks?.roadmap !== undefined,
+    // the FILE is what decides. It keyed on `ctx.hostChecks?.roadmap` until `As of 2026-08`, which
+    // is a fact about the CALL: a caller of the exported `runVerify(VERIFY_STEPS, ctx)` passing no
+    // `hostChecks`, in a repo whose committed `x.verify.json` names `roadmap`, got
+    // `X_VERIFY_SUITE_VANISHED` — whose `fix:` is the command that had just failed.
+    applies: async (ctx) => existsSync(join(ctx.root, ROADMAP_FILE)),
     run: async (ctx) => fromFindings(await hostFindings(ctx, 'roadmap')),
   },
 ];
@@ -390,7 +397,7 @@ export const verifyCommand: CliCommand = {
       {
         name: 'workers',
         type: 'string',
-        summary: 'test processes per parallel step (default: CPUs - 1, max 8)',
+        summary: `test processes per parallel step (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
       },
     ],
   },
@@ -405,13 +412,24 @@ export const verifyCommand: CliCommand = {
   },
 };
 
-/** `x test --workers` refuses the same values for the same reason — and now through the same
- * reader, so the claim is enforced rather than asserted in a comment. */
-const readWorkers = (args: ParsedArgs): number | undefined =>
+/**
+ * Both bounds are the constants the flag summary already names, so `x help verify` and the reader
+ * cannot disagree. Exported for the test that pins them: the command's `run` reaches this only
+ * after the whole gate would have started.
+ *
+ * `max` is the ceiling. Without it `--workers 5000` parsed, `planShards` clamped only to the file
+ * count, and `runParallel` `Promise.all`ed one Bun process per test file. `min` is `WORKER_FLOOR`,
+ * the same number `defaultWorkers` will not go below — the gate spreads or it does not shard, and
+ * `--workers 1` was a serial run the summary said was impossible. `x test --workers 1` stays legal
+ * and is deliberately NOT this reader: `runShards` clamps the width to the file count, so a
+ * one-file corpus makes `X_TEST_SHARD_FAILED`'s own `fix:` say `--workers 1`.
+ */
+export const readWorkers = (args: ParsedArgs): number | undefined =>
   readIntFlag(args, {
     name: 'workers',
     command: 'verify',
-    min: 1,
+    min: WORKER_FLOOR,
+    max: WORKER_CEILING,
     example: 'x verify --workers 4',
   });
 

package/src/db-branch.ts

@@ -48,6 +48,24 @@ export function isBranchName(value: string): boolean {
   }
 }
 
+/**
+ * The database a connection URL names. `url.split('/').at(-1)` took the query string with it, so
+ * a refusal built from it named `postly?sslmode=require_branch_x` — a database that does not exist
+ * — in a message whose whole point is that a reader can check it. `pathname` is the one part that
+ * IS the database, and it arrives percent-encoded, which `pg_database` does not.
+ *
+ * Falls back rather than throwing: the caller is already reporting a failure, and a second throw
+ * from the reporter replaces a checkable refusal with a stack trace.
+ */
+export function databaseNameOf(url: string, fallback = 'postgres'): string {
+  try {
+    const name = decodeURIComponent(new URL(url).pathname.replace(/^\//, ''));
+    return name === '' ? fallback : name;
+  } catch {
+    return fallback;
+  }
+}
+
 /** Where a branch's app answers once something serves it — the preview half of the design. */
 export const previewUrl = (branch: string, port: number): string =>
   `http://${branch}.localhost:${port}`;

package/src/db-generate.ts

@@ -14,7 +14,7 @@ import {
 } from '@ultimat3/db';
 import { describeEntities } from '@ultimat3/entity';
 import { loadApp } from './app-load';
-import { writeSchemaHash } from './drift';
+import { reconcileSchemaHash, writeSchemaHash } from './drift';
 import { hashFileName, MIGRATIONS_DIR, readMigrations, snapshotFileName } from './migrations';
 import type { Finding } from './output';
 
@@ -24,11 +24,20 @@ export interface GenerateMigrationOptions {
   readonly allowDestructive?: boolean | undefined;
 }
 
+/**
+ * What this run actually did — four different things, and `--json` has to tell them apart. A
+ * `hash-recorded` run wrote a file and generated no migration; reporting it as `generated` would
+ * claim a migration nobody can apply, and reporting it as `unchanged` would hide the one write.
+ */
+export type GenerateOutcome = 'generated' | 'hash-recorded' | 'unchanged' | 'blocked';
+
 export interface GeneratedFiles {
-  /** Absent when the entities and the migrations already agree — nothing was written. */
+  readonly outcome: GenerateOutcome;
+  /** Absent unless `outcome` is `generated` — the other three write no migration. */
   readonly migration?: GeneratedMigration | undefined;
   /** App-root-relative paths written, in write order. Empty when there was nothing to write. */
   readonly files: readonly string[];
+  /** What the source hashes to, whenever this run was in a position to record it. */
   readonly schemaHash?: string | undefined;
   /** Modules that would not load. Non-empty means nothing was generated. */
   readonly findings: readonly Finding[];
@@ -72,7 +81,7 @@ export async function generateAppMigration(
   options: GenerateMigrationOptions,
 ): Promise<GeneratedFiles> {
   const app = await loadApp(root);
-  if (app.findings.length > 0) return { files: [], findings: app.findings };
+  if (app.findings.length > 0) return { outcome: 'blocked', files: [], findings: app.findings };
 
   const migrations = await readMigrations(root);
   const current = declaredSchema(migrations);
@@ -90,9 +99,31 @@ export async function generateAppMigration(
     name: options.name,
     ...(options.allowDestructive === true ? { allowDestructive: true } : {}),
   });
-  // An empty diff writes nothing. A migration with no statement still takes a ledger row, a
-  // checksum and a place in the apply order — a permanent record that nothing changed.
-  if (migration.up.trim().length === 0) return { files: [], findings: [] };
+  // An empty diff writes no MIGRATION — one with no statement still takes a ledger row, a checksum
+  // and a place in the apply order, a permanent record that nothing changed. It re-records the
+  // sidecar instead, and that is what makes `X_DB_DRIFT`'s `fix:` a real instruction: the hash
+  // covers every non-test file under `packages/db/src`, so editing a seed or a helper moves it with
+  // no DDL behind it, and the command the error names used to write nothing at all.
+  //
+  // Nothing is masked, because of what has already been proved above: `loadApp` reported no
+  // findings, so the registry is whole rather than short; `declaredSchema` returned a real snapshot
+  // rather than `undefined`, so the diff had something to run against; and the emptiness is the
+  // generator's OWN verdict — the same call, the same classifier — as the written path. A DDL
+  // change that reaches here is a `generateMigration` that missed it, and the sidecar was never the
+  // thing that caught that: an author following the fix simply stayed red with nothing left to run.
+  if (migration.up.trim().length === 0) {
+    const newest = migrations[migrations.length - 1];
+    // No migration to record against, which in this branch means no entity is declared either —
+    // a registry against zero migrations is `create table` for all of it, never an empty diff.
+    if (newest === undefined) return { outcome: 'unchanged', files: [], findings: [] };
+    const reconciled = await reconcileSchemaHash(root, newest.id);
+    return {
+      outcome: reconciled.written ? 'hash-recorded' : 'unchanged',
+      schemaHash: reconciled.hash,
+      files: reconciled.written ? [`${MIGRATIONS_DIR}/${hashFileName(newest.id)}`] : [],
+      findings: [],
+    };
+  }
 
   const dir = join(root, MIGRATIONS_DIR);
   const sql = `${migration.id}.sql`;
@@ -104,6 +135,7 @@ export async function generateAppMigration(
   const schemaHash = await writeSchemaHash(root, migration.id);
 
   return {
+    outcome: 'generated',
     migration,
     schemaHash,
     files: [sql, snapshot, hashFileName(migration.id)].map((file) => `${MIGRATIONS_DIR}/${file}`),

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-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-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));