@ultimat3/cli 9.0.0 → 10.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "9.0.0",
+  "version": "10.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,31 +37,31 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "9.0.0",
-    "@ultimat3/admin": "9.0.0",
-    "@ultimat3/ai": "9.0.0",
-    "@ultimat3/auth": "9.0.0",
-    "@ultimat3/cache": "9.0.0",
-    "@ultimat3/core": "9.0.0",
-    "@ultimat3/db": "9.0.0",
-    "@ultimat3/entity": "9.0.0",
-    "@ultimat3/http": "9.0.0",
-    "@ultimat3/i18n": "9.0.0",
-    "@ultimat3/jobs": "9.0.0",
-    "@ultimat3/mail": "9.0.0",
-    "@ultimat3/manifest": "9.0.0",
-    "@ultimat3/mcp": "9.0.0",
-    "@ultimat3/policy": "9.0.0",
-    "@ultimat3/pwa": "9.0.0",
-    "@ultimat3/query": "9.0.0",
-    "@ultimat3/realtime": "9.0.0",
-    "@ultimat3/render": "9.0.0",
-    "@ultimat3/schema": "9.0.0",
-    "@ultimat3/scraping": "9.0.0",
-    "@ultimat3/seo": "9.0.0",
-    "@ultimat3/storage": "9.0.0",
-    "@ultimat3/testing": "9.0.0",
-    "@ultimat3/time": "9.0.0",
+    "@ultimat3/action": "10.0.0",
+    "@ultimat3/admin": "10.0.0",
+    "@ultimat3/ai": "10.0.0",
+    "@ultimat3/auth": "10.0.0",
+    "@ultimat3/cache": "10.0.0",
+    "@ultimat3/core": "10.0.0",
+    "@ultimat3/db": "10.0.0",
+    "@ultimat3/entity": "10.0.0",
+    "@ultimat3/http": "10.0.0",
+    "@ultimat3/i18n": "10.0.0",
+    "@ultimat3/jobs": "10.0.0",
+    "@ultimat3/mail": "10.0.0",
+    "@ultimat3/manifest": "10.0.0",
+    "@ultimat3/mcp": "10.0.0",
+    "@ultimat3/policy": "10.0.0",
+    "@ultimat3/pwa": "10.0.0",
+    "@ultimat3/query": "10.0.0",
+    "@ultimat3/realtime": "10.0.0",
+    "@ultimat3/render": "10.0.0",
+    "@ultimat3/schema": "10.0.0",
+    "@ultimat3/scraping": "10.0.0",
+    "@ultimat3/seo": "10.0.0",
+    "@ultimat3/storage": "10.0.0",
+    "@ultimat3/testing": "10.0.0",
+    "@ultimat3/time": "10.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/affected.ts

@@ -13,7 +13,6 @@
 // directory is checkout-relative while a caller's scan yields paths relative to its own root.
 import { join, relative } from 'node:path';
 import { singleLine, UltimateError } from '@ultimat3/core';
-import { docsFor } from './error-codes';
 import { BadFlagError } from './errors';
 import type { ExecResult, Runner } from './exec';
 import { execOutput } from './exec';
@@ -193,7 +192,6 @@ export async function gitRoot(runner: Runner, cwd: string, command: string): Pro
     code: 'X_CLI_UNEXPECTED',
     cause: `x ${command} reads its diff from git and "git rev-parse --show-toplevel" exited ${result.code} in ${cwd}: ${singleLine(execOutput(result))}`,
     fix: `run x ${command} from inside a git checkout — confirm with: git rev-parse --show-toplevel`,
-    docs: docsFor('X_CLI_UNEXPECTED'),
   });
 }
 
@@ -245,7 +243,6 @@ export async function changedFiles(
       code: 'X_CLI_UNEXPECTED',
       cause: `"${failed.command.join(' ')}" exited ${failed.code} in ${options.cwd}: ${singleLine(execOutput(failed))}`,
       fix: `run it yourself to see why: ${failed.command.join(' ')}`,
-      docs: docsFor('X_CLI_UNEXPECTED'),
     });
   }
   return [...new Set(runs.flatMap((run) => paths(run.stdout)))].sort();

package/src/app-boundaries.ts

@@ -14,6 +14,7 @@
 import { join as joinPath } from 'node:path';
 // The POSIX variants resolve specifiers against import-graph keys, which are POSIX on every host.
 import { dirname, join, normalize, relative } from 'node:path/posix';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { BoundaryRule, ImportGraph } from '@ultimat3/render';
 import { checkSurfaceBoundary, importGraph, SURFACES } from '@ultimat3/render';
 import type { Finding } from './output';
@@ -48,8 +49,6 @@ const CODE_OF: Readonly<Record<BoundaryRule, BoundaryCode>> = {
  */
 export const boundaryCodeOf = (rule: BoundaryRule): BoundaryCode => CODE_OF[rule];
 
-const docs = (code: BoundaryCode): string => `https://ultimate.dev/errors/${code}`;
-
 const isRoute = (path: string): boolean => /\/(page|layout|route)\.[cm]?tsx?$/.test(path);
 const isService = (path: string): boolean => /\/service\.[cm]?ts$/.test(path);
 const isDbSpecifier = (specifier: string): boolean =>
@@ -128,7 +127,7 @@ const surfaceFindings = (graph: ImportGraph): readonly Finding[] =>
       code,
       cause: violation.cause,
       fix: violation.fix,
-      docs: docs(code),
+      docs: ERROR_DOCS_URL,
       at: violation.importer,
     };
   });
@@ -198,7 +197,7 @@ function layerFindings(scanned: readonly ScannedFile[]): readonly Finding[] {
           code: 'X_BOUNDARY_ROUTE_TO_DB',
           cause: `route imports the database ("${specifier}") — routes call actions and queries`,
           fix: generate('query', file.path, 'then call it from'),
-          docs: docs('X_BOUNDARY_ROUTE_TO_DB'),
+          docs: ERROR_DOCS_URL,
           at: file.path,
         });
       }
@@ -207,7 +206,7 @@ function layerFindings(scanned: readonly ScannedFile[]): readonly Finding[] {
           code: 'X_BOUNDARY_SERVICE_TO_HTTP',
           cause: `service imports HTTP ("${specifier}") — a service that knows about requests cannot be reused by a job`,
           fix: generate('action', file.path, 'read the request there and pass plain values to'),
-          docs: docs('X_BOUNDARY_SERVICE_TO_HTTP'),
+          docs: ERROR_DOCS_URL,
           at: file.path,
         });
       }

package/src/app-env.ts

@@ -7,7 +7,12 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import type { EnvSchema, EnvVarDecl } from '@ultimat3/core';
-import { checkEnvExample, ENV_EXAMPLE_PATH, renderEnvExample } from '@ultimat3/core';
+import {
+  checkEnvExample,
+  ENV_EXAMPLE_PATH,
+  ERROR_DOCS_URL,
+  renderEnvExample,
+} from '@ultimat3/core';
 import { APP_CONFIG_FILE } from './app-root';
 import type { Finding } from './output';
 import { findingFrom } from './output';
@@ -63,7 +68,7 @@ const driftFinding = (cause: string): Finding => ({
   // The generator, not the assertion: `assertEnvExample`'s own fix is a `Bun.write(…)` call for
   // an app that has a schema object in scope, and a gate reader has a shell.
   fix: 'x env example',
-  docs: 'https://ultimate.dev/errors/X_ENV_EXAMPLE_DRIFT',
+  docs: ERROR_DOCS_URL,
   at: ENV_EXAMPLE_PATH,
 });
 

package/src/browser-launcher.ts

@@ -7,7 +7,6 @@ import { existsSync } from 'node:fs';
 import { UltimateError } from '@ultimat3/core';
 import type { CdpLauncherLike, ScrapeDriver } from '@ultimat3/scraping';
 import { localBrowser } from '@ultimat3/scraping';
-import { docsFor } from './error-codes';
 
 /**
  * The one library this works against. Playwright is not an alternative and is not a flag:
@@ -33,7 +32,6 @@ export class ShotBrowserMissingError extends UltimateError {
       // one literal, and a fix line the gate cannot read is a fix line nothing holds to the
       // contract. `browser-launcher.test.ts` pins it against the constant instead.
       fix: 'bun add -d puppeteer-core',
-      docs: docsFor('X_SHOT_BROWSER_MISSING'),
       meta: { root: input.root, package: BROWSER_PACKAGE },
     });
   }

package/src/budgets.ts

@@ -8,6 +8,7 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest, RouteFact } from '@ultimat3/manifest';
 import { formatBytes, parseByteBudget } from '@ultimat3/render';
 import type { Finding } from './output';
@@ -75,7 +76,7 @@ function unmeasuredFinding(url: string, declared: string, built: boolean): Findi
     fix: built
       ? `x build --target static --json   # its "unmeasured" list says why ${url} could not be weighed`
       : 'x build --target static --json && x verify --json',
-    docs: 'https://ultimate.dev/errors/X_BUDGET_UNMEASURED',
+    docs: ERROR_DOCS_URL,
     at: url,
   };
 }
@@ -106,7 +107,7 @@ export function checkBudgets(
         code: 'X_BUDGET_EXCEEDED',
         cause: `${route.url} ships ${formatBytes(measured.jsBytes)} of JS over a ${formatBytes(js)} budget via ${chainOf(measured)}`,
         fix: `x routes --json to see the chain, then move the heavy import behind hydrate: 'interaction'`,
-        docs: 'https://ultimate.dev/errors/X_BUDGET_EXCEEDED',
+        docs: ERROR_DOCS_URL,
         at: route.url,
       });
     }
@@ -115,7 +116,7 @@ export function checkBudgets(
         code: 'X_BUDGET_EXCEEDED',
         cause: `${route.url} LCP ${measured.lcpMs}ms over the ${lcp}ms budget`,
         fix: `raise the budget in defineRoute, or switch render to 'isr' to serve it prebuilt`,
-        docs: 'https://ultimate.dev/errors/X_BUDGET_EXCEEDED',
+        docs: ERROR_DOCS_URL,
         at: route.url,
       });
     }

package/src/cmd-build.ts

@@ -3,7 +3,7 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { frameworkVersion, VERSION_DEFINE } from '@ultimat3/core';
+import { ERROR_DOCS_URL, frameworkVersion, VERSION_DEFINE } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
 import { runVerify } from './cmd-verify';
 import type { CliCommand, CommandContext } from './command';
@@ -143,7 +143,7 @@ export function buildResult(input: {
             code: 'X_BUILD_FAILED',
             cause: `${input.command.join(' ')} exited ${result.code}`,
             fix: target === 'docker' ? 'x doctor --json && docker info' : 'x verify --json',
-            docs: 'https://ultimate.dev/errors/X_BUILD_FAILED',
+            docs: ERROR_DOCS_URL,
           },
         ],
     data: {

package/src/cmd-db-branch.ts

@@ -3,7 +3,7 @@
 // `x db branch ls` used to clone a database called `ls`, because the argument was the name.
 // The facts (what a branch is, per mode) are `db-branch.ts`; the client lifetime is here.
 
-import { nearestName } from '@ultimat3/core';
+import { ERROR_DOCS_URL, nearestName } from '@ultimat3/core';
 import { createPostgresClient, type DbClient } from '@ultimat3/db';
 import type { CommandContext } from './command';
 import type { BranchRow } from './db-branch';
@@ -215,6 +215,6 @@ function notABranch(services: DevServices, name: string): CommandResult {
     code: 'X_DB_BRANCH_FAILED',
     cause: `"${name}" is not a branch of this database, so nothing was dropped (it would be ${target})`,
     fix: LIST_FIX,
-    docs: 'https://ultimate.dev/errors/X_DB_BRANCH_FAILED',
+    docs: ERROR_DOCS_URL,
   });
 }

package/src/cmd-deploy.ts

@@ -3,6 +3,7 @@
 // anything that runs containers can execute.
 
 import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, UnknownCommandError } from './errors';
@@ -31,6 +32,13 @@ import { quoteArg } from './shell-quote';
  * honours. Both compose definitions carry it — `docker/docker-compose.prod.yml`'s `backfill` and
  * the one `templates/scaffold-container.ts` scaffolds, which also gates on `migrate` completing.
  * This paragraph said they "still owe" both for as long as they have had them.
+ *
+ * COMPOSE-ONLY, and `backfill` is why that has to be written down. `docker/helm`'s `roles:` map is
+ * `web|sync|worker|scheduler|replicator` plus a `migrate` Job — there is no `backfill` object in
+ * the chart at all — and the helm plan is one `helm upgrade --install`, so this list describes
+ * neither the objects a chart deploy creates nor the steps it runs. Every reader of it is therefore
+ * inside the compose branch; the SUMMARY reads `plan.steps` instead, or `x deploy --method helm`
+ * reports a post-deploy sweep to an operator that nothing will ever run.
  */
 export const DEPLOY_ROLES = ['migrate', 'web', 'sync', 'worker', 'scheduler', 'backfill'] as const;
 
@@ -202,11 +210,14 @@ export const deployCommand: CliCommand = {
       env: { ...plan.env },
       steps: plan.steps.map((step) => ({ role: step.role, command: step.command.join(' ') })),
     };
+    // The roles THIS plan has, never the compose list: on `--method helm` there is one step,
+    // `all`, and naming `backfill` there promises an operator a sweep the chart cannot run.
+    const roles = plan.steps.map((step) => step.role).join(',');
     if (flagBool(ctx.args, 'dry-run')) {
       return {
         ok: true,
         command: 'deploy',
-        summary: msg('cli.deploy.plan', { images: 1, roles: DEPLOY_ROLES.join(',') }),
+        summary: msg('cli.deploy.plan', { images: 1, roles }),
         data: planJson,
         lines: plan.steps.map(
           (step) => `  ${step.role.padEnd(10)} ${stepLine(plan.env, step.command)}`,
@@ -225,7 +236,7 @@ export const deployCommand: CliCommand = {
               code: 'X_DEPLOY_FAILED',
               cause: `role "${step.role}" step exited ${result.code}`,
               fix: `${stepLine(plan.env, step.command)}   # run it directly to see the full output`,
-              docs: 'https://ultimate.dev/errors/X_DEPLOY_FAILED',
+              docs: ERROR_DOCS_URL,
             },
           ],
           data: planJson,
@@ -235,7 +246,7 @@ export const deployCommand: CliCommand = {
     return {
       ok: true,
       command: 'deploy',
-      summary: msg('cli.deploy.plan', { images: 1, roles: DEPLOY_ROLES.join(',') }),
+      summary: msg('cli.deploy.plan', { images: 1, roles }),
       data: planJson,
     };
   },

package/src/cmd-docs.ts

@@ -4,6 +4,7 @@
 // should not have to guess which of 29 packages holds the answer, and it must never be handed a
 // URL: `node_modules` already contains every doc, because the published artifact IS the source.
 
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { DocEntry, DocHit } from '@ultimat3/manifest';
 import { nearestTopics, scanInstalledDocs, searchDocs } from '@ultimat3/manifest';
 import type { CliCommand, CommandContext } from './command';
@@ -22,7 +23,7 @@ const unresolvedFinding = (): Finding => ({
   code: 'X_CLI_UNEXPECTED',
   cause: '@ultimat3/core does not resolve from the installed CLI, so no docs could be read',
   fix: 'bun install && x doctor --json',
-  docs: 'https://ultimate.dev/errors/X_CLI_UNEXPECTED',
+  docs: ERROR_DOCS_URL,
   at: import.meta.dir,
 });
 

package/src/cmd-doctor.ts

@@ -4,7 +4,7 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { tryResolveEnvironment, usesDevCursorSecret } from '@ultimat3/core';
+import { ERROR_DOCS_URL, tryResolveEnvironment, usesDevCursorSecret } from '@ultimat3/core';
 import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
 import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
 import type { CliCommand, CommandContext } from './command';
@@ -49,12 +49,10 @@ export interface DoctorProbe {
   snapshots(): Promise<readonly Finding[]>;
 }
 
-const docs = (code: string): string => `https://ultimate.dev/errors/${code}`;
-
 const finding = (code: string, cause: string, fix: string, at?: string): Finding =>
   at === undefined
-    ? { code, cause, fix, docs: docs(code) }
-    : { code, cause, fix, docs: docs(code), at };
+    ? { code, cause, fix, docs: ERROR_DOCS_URL }
+    : { code, cause, fix, docs: ERROR_DOCS_URL, at };
 
 export const OFFLINE_FALLBACK = 'apps/web/app/offline.tsx';
 

package/src/cmd-env.ts

@@ -4,7 +4,7 @@
 
 // Bun ships no path-join primitive, and `.env.example` is written app-root-relative.
 import { join } from 'node:path';
-import { checkEnv, ENV_EXAMPLE_PATH, maskedEnvValues } from '@ultimat3/core';
+import { checkEnv, ENV_EXAMPLE_PATH, ERROR_DOCS_URL, maskedEnvValues } from '@ultimat3/core';
 import { ENV_SCHEMA_EXPORT, envExampleFor, loadEnvSchema } from './app-env';
 import { APP_CONFIG_FILE, requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
@@ -54,7 +54,7 @@ async function checkProcessEnv(ctx: CommandContext): Promise<CommandResult> {
     code: 'X_ENV_MISSING',
     cause: `${issue.key} is ${issue.reason} (expected ${issue.expected})`,
     fix: issue.fix,
-    docs: 'https://ultimate.dev/errors/X_ENV_MISSING',
+    docs: ERROR_DOCS_URL,
     at: ENV_EXAMPLE_PATH,
   }));
   return {

package/src/cmd-fix.ts

@@ -3,7 +3,7 @@
 // (`docs/architecture/02-boundaries.md`) — a caller runs the printed edit, or the generated
 // `git mv`, itself.
 
-import { nearestName } from '@ultimat3/core';
+import { ERROR_DOCS_URL, nearestName } from '@ultimat3/core';
 import { appImportGraph, readAppSources } from './app-boundaries';
 import { requireAppRoot } from './app-root';
 import type { BoundaryCut } from './boundary-cuts';
@@ -18,8 +18,6 @@ export { planBoundaryCuts };
 
 export const FIX_SUBCOMMANDS = ['boundary'] as const;
 
-const docsUrl = (code: string): string => `https://ultimate.dev/errors/${code}`;
-
 /**
  * Accept either an app-root-relative path or a suffix that matches exactly one scanned file —
  * an agent copying the path out of a `fix:` line has the short form
@@ -81,7 +79,7 @@ const findingForCut = (cut: BoundaryCut): Finding => ({
   code: cut.code,
   cause: cut.cause,
   fix: cut.edit,
-  docs: docsUrl(cut.code),
+  docs: ERROR_DOCS_URL,
   at: cut.at,
 });
 

package/src/cmd-new.ts

@@ -5,7 +5,7 @@
 import { existsSync } from 'node:fs';
 import { chmod } from 'node:fs/promises';
 import { isAbsolute, join, resolve } from 'node:path';
-import { renderThrowable } from '@ultimat3/core';
+import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
 import { dedupe } from './cmd-generate';
 import type { CliCommand, CommandContext } from './command';
 import { MissingPositionalError } from './errors';
@@ -195,7 +195,7 @@ export const newCommand: CliCommand = {
             code: 'X_GENERATE_CONFLICT',
             cause: `${target} already exists`,
             fix: `x new ${app.kebab} --force, or choose another name`,
-            docs: 'https://ultimate.dev/errors/X_GENERATE_CONFLICT',
+            docs: ERROR_DOCS_URL,
             at: target,
           },
         ],

package/src/cmd-shot.ts

@@ -164,6 +164,17 @@ const intFlag = (
     fallback,
   );
 
+/**
+ * How `devServerFor` starts a scratch server. A parameter with a default rather than a direct
+ * call, for the reason every `Runner` in this package is one: the failure path below — a boot that
+ * throws, and the lock it has to hand back — is otherwise only reachable by breaking a real app.
+ */
+export type BootDevServer = (input: {
+  readonly root: string;
+  readonly port: number;
+  readonly env: Readonly<Record<string, string | undefined>>;
+}) => Promise<{ readonly url: string; stop(): Promise<void> }>;
+
 export interface ShotServer {
   readonly url: string;
   /** Which server the picture is of. Reported, because the two have different failure modes. */
@@ -272,6 +283,7 @@ export async function devServerFor(
   root: string,
   env: Readonly<Record<string, string | undefined>>,
   port: number,
+  boot: BootDevServer = (input) => startDev(input),
 ): Promise<ShotServer> {
   const services = resolveServices(root, env);
   const file = Bun.file(lockPath(services.stateDir));
@@ -281,13 +293,21 @@ export async function devServerFor(
       return { url: lock.url, origin: 'reused', stop: () => Promise.resolve() };
     }
   }
-  await preflight({
+  const { release } = await preflight({
     stateDir: services.stateDir,
     port,
     hostname: DEV_BINDING.hostname,
     embeddedDb: services.db.mode === 'embedded',
   });
-  const dev = await startDev({ root, port, env });
+  // The directory is CLAIMED from here down — `preflight` returns holding it, never having merely
+  // looked — so a boot that throws has to give it back. `cmd-dev.ts` states the same rule at the
+  // same seam. Without it one failed `x shot` refused every later `x dev` and `x shot` on this
+  // checkout, naming a pid that had already exited. The original error is re-thrown untouched: a
+  // teardown must never replace the failure it is cleaning up after.
+  const dev = await boot({ root, port, env }).catch((error: unknown) => {
+    release();
+    throw error;
+  });
   await writeLock(services.stateDir, {
     pid: process.pid,
     port,

package/src/db-finding.ts

@@ -3,7 +3,7 @@
 // step that failed. Its own module because `cmd-db.ts` and `cmd-db-branch.ts` both need it and
 // neither may import the other.
 
-import { renderThrowable } from '@ultimat3/core';
+import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
 import type { Finding } from './output';
 import { findingFrom, isUltimateErrorShape } from './output';
 
@@ -24,5 +24,5 @@ export const stepFinding = (error: unknown, code: string): Finding =>
         // a TypeError raised while reporting it.
         cause: renderThrowable(error),
         fix: 'x doctor --json',
-        docs: `https://ultimate.dev/errors/${code}`,
+        docs: ERROR_DOCS_URL,
       };

package/src/db-seed.ts

@@ -12,7 +12,6 @@ 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';
@@ -49,7 +48,6 @@ export class SeedUnknownError extends UltimateError {
       // 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'),
     });
   }
 }
@@ -75,7 +73,6 @@ export class SeedEnvironmentError extends UltimateError {
       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'),
     });
   }
 }

package/src/dev-cache.ts

@@ -20,7 +20,7 @@ import {
   resetTiers,
 } from '@ultimat3/cache';
 import type { CacheTierName } from '@ultimat3/core';
-import { CACHE_TIERS, defineConfig, logger } from '@ultimat3/core';
+import { CACHE_TIERS, defineConfig, logger, renderThrowable } from '@ultimat3/core';
 import type { Transport, TransportSubscription } from '@ultimat3/realtime/server';
 import { APP_CONFIG_EXPORT } from './app-auth';
 import { APP_CONFIG_FILE } from './app-root';
@@ -187,7 +187,7 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void>
       void applyBroadcast(payload);
     })
     .catch((error: unknown) => {
-      logger.warn('cache.broadcast.subscribe-failed', { error: messageOf(error) });
+      logger.warn('cache.broadcast.subscribe-failed', { error: broadcastErrorText(error) });
       return undefined;
     });
 
@@ -199,8 +199,15 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void>
   };
 }
 
-const messageOf = (error: unknown): string =>
-  error instanceof Error ? error.message : 'unknown error';
+/**
+ * `renderThrowable`, never `instanceof Error` + `.message`. Both run on a value this process did
+ * not build — a `Proxy` traps `getPrototypeOf` and a `message` getter can raise — and a throw here
+ * is inside the handler whose whole job is to keep the subscriber loop alive: losing it ends
+ * cross-instance cache invalidation for the process, quietly, which is the failure the loop's own
+ * `try` exists to prevent. The old form also answered `'unknown error'` for every non-`Error`
+ * throw, so a driver rejecting with a string reported nothing at all.
+ */
+export const broadcastErrorText = (error: unknown): string => renderThrowable(error);
 
 /**
  * A peer's wire tags, applied here. Never throws: a malformed frame or an undeclared tag must not
@@ -214,6 +221,6 @@ async function applyBroadcast(payload: string): Promise<void> {
     const wire = parsed.filter((value): value is string => typeof value === 'string');
     if (wire.length > 0) await receiveInvalidationBroadcast(wire);
   } catch (error) {
-    logger.warn('cache.broadcast.apply-failed', { error: messageOf(error) });
+    logger.warn('cache.broadcast.apply-failed', { error: broadcastErrorText(error) });
   }
 }

package/src/dev-lock.ts

@@ -16,8 +16,7 @@
 
 import { closeSync, mkdirSync, openSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { UltimateError } from '@ultimat3/core';
-import { docsFor } from './error-codes';
+import { stringField, UltimateError } from '@ultimat3/core';
 import { exec, type Runner } from './exec';
 import { quoteArg } from './shell-quote';
 
@@ -68,7 +67,11 @@ export const isProcessAlive = (pid: number): boolean => {
     return true;
   } catch (error) {
     // EPERM means it exists and belongs to another user. Alive, and not ours to signal.
-    return (error as { code?: string }).code === 'EPERM';
+    // `stringField`, never a cast plus a property read: the rule `metrics-endpoint.ts` states and
+    // `caught-value-reads.test.ts` enforces — a getter that throws would take this path down one
+    // line before the guard meant to make it safe, and this guard decides whether a second `x dev`
+    // is allowed to open a single-writer data directory.
+    return stringField(error, 'code') === 'EPERM';
   }
 };
 
@@ -96,7 +99,6 @@ export class DevAlreadyRunningError extends UltimateError {
       code: 'X_DEV_ALREADY_RUNNING',
       cause: `pid ${input.lock.pid} is already running x dev on ${input.lock.url} and holds ${input.stateDir}${single}`,
       fix: `use the one already running at ${input.lock.url}, or stop it: kill ${input.lock.pid}`,
-      docs: docsFor('X_DEV_ALREADY_RUNNING'),
       meta: { pid: input.lock.pid, port: input.lock.port, stateDir: input.stateDir },
     });
   }
@@ -118,7 +120,6 @@ export class DevLockUnreadableError extends UltimateError {
       code: 'X_DEV_LOCK_UNREADABLE',
       cause: `${input.path} could not be parsed as a dev lock and could not be removed, so x dev cannot tell whether another process owns ${input.stateDir}`,
       fix: `rm ${quoteArg(input.path)}   # then re-run x dev`,
-      docs: docsFor('X_DEV_LOCK_UNREADABLE'),
       meta: { path: input.path, stateDir: input.stateDir },
     });
   }
@@ -198,7 +199,6 @@ export class DevPortInUseError extends UltimateError {
         holder.pid === undefined
           ? `x dev --port ${input.suggestion}`
           : `x dev --port ${input.suggestion}   # or free it, if that pid is yours: kill ${holder.pid}`,
-      docs: docsFor('X_PORT_IN_USE'),
       meta: { port: input.port, ...holder },
     });
   }
@@ -247,7 +247,8 @@ function claimExclusive(path: string, lock: DevLock): boolean {
   try {
     fd = openSync(path, 'wx');
   } catch (error) {
-    if ((error as { code?: string }).code === 'EEXIST') return false;
+    // Same rule as `isProcessAlive` above: read the field, never cast and dereference.
+    if (stringField(error, 'code') === 'EEXIST') return false;
     throw error;
   }
   try {

package/src/dev-runtime.ts

@@ -186,8 +186,14 @@ export function startStorage(services: DevServices, env: Env, override?: Storage
   // missing" from a helper the operator never configured. Not an outright ban on the local disk in
   // production: a single-node Compose deploy on a mounted volume WITH a real secret is a rung on
   // the scale ladder, and refusing it would be a deploy-shape decision, not a security fix.
-  if (!isLocal() && usesDevStorageSecret()) {
-    throw new LocalDiskUnsafeError({ environment: resolveEnvironment(), root });
+  // `{ env }` on ALL THREE, never the ambient `process.env`: this function is HANDED the boot's
+  // environment and reads `S3_BUCKET` off it one branch above, so a guard asking a second source
+  // could answer `development` for a process booting as `production` — or, with
+  // `usesDevStorageSecret({ env })` left bare, refuse a boot whose own env carries a real
+  // `STORAGE_SIGNING_SECRET` because the PROCESS does not. Which environment, whether a secret
+  // exists, and the name the message prints are one question about one table.
+  if (!isLocal({ env }) && usesDevStorageSecret({ env })) {
+    throw new LocalDiskUnsafeError({ environment: resolveEnvironment({ env }), root });
   }
   try {
     mkdirSync(root, { recursive: true });
@@ -198,7 +204,9 @@ export function startStorage(services: DevServices, env: Env, override?: Storage
       `mount a writable volume at ${root}, or set S3_ENDPOINT and S3_BUCKET to use object storage instead`,
     );
   }
-  return defineStorage({ disks: { local: localDriver({ root }) }, default: 'local' });
+  // The guard three lines up reads `env`; so must the disk it guards. Otherwise the boot's
+  // environment decides whether signing is allowed and the process's decides what key is used.
+  return defineStorage({ disks: { local: localDriver({ root, env }) }, default: 'local' });
 }
 
 /**

package/src/dev-storage.ts

@@ -151,8 +151,14 @@ export function parseByteRange(
   if (from === '' && to === '') return undefined;
   if (from === '') {
     const wanted = Number(to);
-    // A suffix longer than the object is the whole object, not a refusal.
-    return wanted === 0 ? UNSATISFIABLE : { start: Math.max(size - wanted, 0), end: size - 1 };
+    // A suffix longer than the object is the whole object, not a refusal — but there is no whole
+    // object to fall back to at `size === 0`, and the arithmetic below answers `{ start: 0, end:
+    // -1 }`, which the route renders as `content-range: bytes 0--1/0` with status 206. RFC 9110
+    // requires 416. The non-suffix branch already gets this right through `start >= size`; this
+    // one had no equivalent test.
+    return size === 0 || wanted === 0
+      ? UNSATISFIABLE
+      : { start: Math.max(size - wanted, 0), end: size - 1 };
   }
   const start = Number(from);
   const end = to === '' ? size - 1 : Math.min(Number(to), size - 1);