@ultimat3/cli 23.0.0 → 24.0.0

package/src/cmd-mcp.ts

@@ -3,17 +3,24 @@
 // supplies only the app, the caller and the socket. A tool answered here would be a second answer
 // to a question the framework already answers.
 
-import { markListening, nanoid, timingSafeEqual } from '@ultimat3/core';
+import {
+  markListening,
+  nanoid,
+  renderFixShellArg,
+  timingSafeEqual,
+  UltimateError,
+} from '@ultimat3/core';
 import { mcpHttpRoute, serveStdio } from '@ultimat3/mcp';
 import { requireAppRoot } from './app-root';
 import { DEFAULT_PORT, mcpSpec } from './cmd-mcp-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError } from './errors';
-import { intFlagOr, PORT_RANGE } from './flag-number';
+import { intFlagOr, neighbouringPort, PORT_RANGE } from './flag-number';
 import { holdUntilShutdown } from './hold';
 import type { CliMcpServer } from './mcp-host';
 import { createDevMcpServer, DEV_TOOL_SCOPES } from './mcp-host';
 import { msg } from './messages';
+import { isAddressInUse } from './metrics-endpoint';
 import type { CommandResult } from './output';
 import { flagString } from './parse';
 
@@ -56,6 +63,21 @@ const notFound = (path: string): Response =>
     { status: 404, headers: { 'content-type': 'application/json' } },
   );
 
+/**
+ * The MCP port is bound already — by another `x mcp serve`, or by the inspector, whose default
+ * 9229 this one shares. `metrics-endpoint.ts`'s pattern: an `EADDRINUSE` throw becomes the
+ * framework's `X_PORT_IN_USE`, with the invocation one port over.
+ */
+export class McpPortInUseError extends UltimateError {
+  constructor(input: { port: number }) {
+    super({
+      code: 'X_PORT_IN_USE',
+      cause: `port ${String(input.port)} is already bound, so x mcp serve could not open its HTTP transport`,
+      fix: `x mcp serve --transport http --port ${renderFixShellArg(String(neighbouringPort(input.port)), '9230')}`,
+    });
+  }
+}
+
 /** A running HTTP transport. `stop()` releases the socket AND the host's lazily booted services. */
 export interface McpHttpServer {
   readonly result: CommandResult;
@@ -70,7 +92,7 @@ export interface McpHttpServer {
  * directory outlive `run()` otherwise, and nothing — a test, an embedding caller, or a signal —
  * could ever release them.
  */
-export function startMcpHttp(host: CliMcpServer, port: number): McpHttpServer {
+export async function startMcpHttp(host: CliMcpServer, port: number): Promise<McpHttpServer> {
   const token = nanoid(32);
   const route = mcpHttpRoute({
     server: host.server,
@@ -83,17 +105,26 @@ export function startMcpHttp(host: CliMcpServer, port: number): McpHttpServer {
         ? { actor: host.caller.actor, scopes: DEV_TOOL_SCOPES }
         : null,
   });
-  const handle = Bun.serve({
-    port,
-    hostname: 'localhost',
-    fetch: (request: Request): Response | Promise<Response> => {
-      const url = new URL(request.url);
-      if (request.method !== route.method || url.pathname !== route.path) {
-        return notFound(route.path);
-      }
-      return route.handle(request);
-    },
-  });
+  let handle: ReturnType<typeof Bun.serve>;
+  try {
+    handle = Bun.serve({
+      port,
+      hostname: 'localhost',
+      fetch: (request: Request, server): Response | Promise<Response> => {
+        const url = new URL(request.url);
+        if (request.method !== route.method || url.pathname !== route.path) {
+          return notFound(route.path);
+        }
+        // The socket's peer: failed tokens are metered per address, and only the server knows it.
+        return route.handle(request, { address: server.requestIP(request)?.address });
+      },
+    });
+  } catch (error) {
+    // The host booted before the bind; a refusal that left it open would leak its database.
+    await host.close();
+    if (isAddressInUse(error)) throw new McpPortInUseError({ port });
+    throw error;
+  }
   // Announces the socket as this process's own, so a caller on it is never mistaken for egress.
   const stopListening = markListening(handle.url.origin);
   const url = `${handle.url.origin}${route.path}`;
@@ -179,7 +210,7 @@ export const mcpCommand: CliCommand = {
     // starts is what releases the socket and the database. Registering a shutdown hook and
     // returning was the older shape — nothing installed a signal handler, so the hook was never
     // reached and the exit code closed the socket the line above had just announced.
-    const served = startMcpHttp(host, port);
+    const served = await startMcpHttp(host, port);
     return { ...served.result, hold: holdUntilShutdown('mcp', () => served.stop()) };
   },
 };

package/src/cmd-planned.ts

@@ -3,8 +3,8 @@
 // does not exist", which is false and sends an agent looking for a typo. X_NOT_IMPLEMENTED plus a
 // fix naming the closest shipped command says the true thing, and `x help` lists them honestly.
 
+import { NotImplementedError } from '@ultimat3/core';
 import type { CliCommand } from './command';
-import { CliNotImplementedError } from './errors';
 import type { CommandResult } from './output';
 import type { CommandSpec } from './parse';
 
@@ -134,18 +134,28 @@ export const PLANNED_SUBCOMMANDS: readonly PlannedSubcommand[] = [
  * the error rather than throwing it, because a `run` that throws synchronously escapes the
  * promise its signature promises — the caller does `throw plannedSubcommand(...)`.
  */
-export function plannedSubcommand(command: string, subcommand: string): CliNotImplementedError {
+export function plannedSubcommand(command: string, subcommand: string): NotImplementedError {
   const planned = PLANNED_SUBCOMMANDS.find(
     (entry) => entry.command === command && entry.subcommand === subcommand,
   );
-  return new CliNotImplementedError({
-    feature: `x ${command} ${subcommand}`,
+  return new NotImplementedError({
+    cause: `x ${command} ${subcommand} is not implemented in this build`,
     // `x help <command>`, not `x <command> --help`: for a command that declares subcommands and no
     // default, the latter is refused by the parser before help is ever rendered.
     fix: planned?.fix ?? `x help ${command}`,
   });
 }
 
+/**
+ * What every invocation of a planned command answers — its `run`, and the dispatcher when the
+ * parser refused a flag before any `run` was reached. One builder, so the two cannot drift.
+ */
+export const plannedCommandError = (planned: PlannedCommand): NotImplementedError =>
+  new NotImplementedError({
+    cause: `x ${planned.name} is not implemented in this build`,
+    fix: planned.fix,
+  });
+
 const specFor = (planned: PlannedCommand): CommandSpec => ({
   name: planned.name,
   summary: `${planned.summary} (planned)`,
@@ -167,10 +177,7 @@ const toCommand = (planned: PlannedCommand): CliCommand => ({
   // `async` is load-bearing: a synchronous throw would escape every caller that awaits the
   // promise this signature promises, including the dispatcher's own error path.
   async run(): Promise<CommandResult> {
-    throw new CliNotImplementedError({
-      feature: `x ${planned.name}`,
-      fix: planned.fix,
-    });
+    throw plannedCommandError(planned);
   },
 });
 

package/src/cmd-routes.ts

@@ -10,7 +10,7 @@ import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import { routesSpec } from './cmd-routes-spec';
 import type { CliCommand, CommandContext } from './command';
-import { BadFlagError } from './errors';
+import { BadFlagError, UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import { flagString } from './parse';
@@ -52,7 +52,7 @@ const routeJson = (routes: readonly RouteDescriptor[]): JsonValue =>
     render: route.mode,
     hydrate: route.hydrate,
     offline: route.offline,
-    budget: { js: route.budgetJs, lcp: route.budgetLcp },
+    budget: { js: route.budgetJs },
     // Absent on a file route, never `null`: only a mounted route has the fact.
     ...(route.mount === undefined
       ? {}
@@ -83,6 +83,16 @@ export const routesCommand: CliCommand = {
   spec: routesSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('routes', ctx.cwd).dir;
+    // No positional: `x routes list --json` ran only because a stray word was ignored, which is
+    // how a retired spelling stayed in the route-miss fix lines. Refused before the app loads.
+    const stray = ctx.args.positionals[0];
+    if (stray !== undefined) {
+      throw new UnknownCommandError({
+        path: `routes ${stray}`,
+        known: ['routes'],
+        suggestion: 'routes --json',
+      });
+    }
     // Read before the app is loaded: a typo must not cost a boot to report, the rule `x mcp`'s
     // `--transport` already follows.
     const surface = readSurfaceFilter(flagString(ctx.args, 'surface'));

package/src/cmd-secrets.ts

@@ -25,6 +25,7 @@ import {
   SecretsPlaintextInvalidError,
   secretsFileExists,
   serializeSecretValues,
+  UltimateError,
   writeMasterKeyFile,
   writeSecretsFile,
 } from '@ultimat3/core';
@@ -33,12 +34,7 @@ import { requireAppRoot } from './app-root';
 import { appSecrets, dropRetired, retire, retiredKeyIds } from './cmd-secrets-ring';
 import { secretsSpec } from './cmd-secrets-spec';
 import type { CliCommand, CommandContext } from './command';
-import {
-  MissingPositionalError,
-  SecretsEditFailedError,
-  SecretsEditorMissingError,
-  SecretsExistsError,
-} from './errors';
+import { MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import { flagString } from './parse';
@@ -46,6 +42,51 @@ import { recoverRotation, rotateMasterKey } from './secrets-rotation';
 import { shredOnSignal } from './signal-shred';
 import { renderTable } from './table';
 
+/**
+ * `x secrets edit` decrypts into a buffer and hands it to `$EDITOR`. There is no fallback editor:
+ * guessing one and opening a decrypted file in it is the last place a surprise belongs.
+ */
+export class SecretsEditorMissingError extends UltimateError {
+  constructor(input: { vars: readonly string[] }) {
+    super({
+      code: 'X_SECRETS_EDITOR_MISSING',
+      cause: `x secrets edit opens the decrypted secrets in an editor and none of ${input.vars.join(', ')} is set`,
+      fix: 'EDITOR=nano x secrets edit',
+    });
+  }
+}
+
+/**
+ * The editor exited non-zero — a crash, or a deliberate abort. The buffer is discarded either way
+ * and the committed file is left exactly as it was: resealing a buffer whose editor failed would
+ * commit whatever half-written state the crash left behind.
+ */
+export class SecretsEditFailedError extends UltimateError {
+  constructor(input: { editor: string; code: number }) {
+    super({
+      code: 'X_SECRETS_EDIT_FAILED',
+      cause: `"${input.editor}" exited ${input.code}, so the decrypted buffer was discarded and the committed secrets file was not rewritten`,
+      fix: 'x secrets edit',
+    });
+  }
+}
+
+/**
+ * `x secrets init` would overwrite a file that already exists. `X_GENERATE_CONFLICT` is this
+ * package's own code for exactly that, and a second name for "a generator would clobber something"
+ * is the duplication the code registry exists to prevent. Losing a master key is unrecoverable —
+ * the committed file it opens is then ciphertext nobody can read again.
+ */
+export class SecretsExistsError extends UltimateError {
+  constructor(input: { path: string; fix: string }) {
+    super({
+      code: 'X_GENERATE_CONFLICT',
+      cause: `${input.path} already exists, and x secrets init would replace it`,
+      fix: input.fix,
+    });
+  }
+}
+
 export { SECRETS_SUBCOMMANDS } from './cmd-secrets-spec';
 
 /** In order of precedence. `VISUAL` outranks `EDITOR` by POSIX convention on an interactive tty. */

package/src/cmd-shot-matrix.ts

@@ -5,6 +5,7 @@
 
 // why: no Bun native joins a path.
 import { join, relative } from 'node:path';
+import { escapeHtml } from '@ultimat3/core';
 import { routeEntries } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import type { ShotRun } from './cmd-shot';
@@ -94,9 +95,6 @@ export interface MatrixShot {
   readonly image: string;
 }
 
-const escapeHtml = (text: string): string =>
-  text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-
 /**
  * The contact sheet. System colours only (`Canvas`, `CanvasText`, `Mark`): a generated review page
  * has no design tokens to read, and a literal colour would be the one this repo refuses.

package/src/cmd-shot.ts

@@ -339,6 +339,14 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
   }
 }
 
+/**
+ * Where the artifacts land. A relative `--out` is a path the caller typed from where they stand,
+ * so it resolves against the cwd — `x build --out`'s rule. Against the app root it landed
+ * somewhere else whenever `x shot` ran from `apps/web`.
+ */
+export const shotOutDir = (cwd: string, out: string | undefined, fallback: string): string =>
+  out === undefined ? fallback : resolve(cwd, out);
+
 export const shotResult = (artifacts: ShotArtifacts): CommandResult => ({
   ok: artifacts.verdict.ok,
   command: 'shot',
@@ -426,7 +434,8 @@ export const shotCommand: CliCommand = {
     const boot = (): Promise<ShotServer> => devServerFor(root, ctx.env, port);
     const shared = {
       root,
-      ...(out === undefined ? {} : { out }),
+      // Absolute here, so the island sweep's own `resolve(root, out)` keeps the caller's path.
+      ...(out === undefined ? {} : { out: shotOutDir(ctx.cwd, out, root) }),
       settleMs,
       timeoutMs,
       ...(executablePath === undefined ? {} : { executablePath }),
@@ -465,7 +474,7 @@ export const shotCommand: CliCommand = {
         defaultLocale: app.defaultLocale,
         ...(theme === undefined ? {} : { themes: [theme] }),
       });
-      const outDir = out === undefined ? join(root, MATRIX_DIR) : resolve(root, out);
+      const outDir = shotOutDir(ctx.cwd, out, join(root, MATRIX_DIR));
       return runShotMatrix({ cells, outDir, boot, shoot: runShot, base });
     }
     const shown = locale ?? app.defaultLocale;
@@ -474,7 +483,7 @@ export const shotCommand: CliCommand = {
       await runShot({
         ...base,
         route: path,
-        outDir: out === undefined ? join(root, SHOT_DIR, shotSlug(path)) : resolve(root, out),
+        outDir: shotOutDir(ctx.cwd, out, join(root, SHOT_DIR, shotSlug(path))),
         boot,
         // Pinned whether or not `--locale` was given: the default locale, never the box's own.
         acceptLanguage: shown,

package/src/cmd-tasks.ts

@@ -7,6 +7,7 @@
 import { nearestName, systemClock } from '@ultimat3/core';
 import type { JobDriver, TaskFire, TaskHandle } from '@ultimat3/jobs';
 import type { CronPhrases } from '@ultimat3/time';
+import { fromEpochMs, isoInZone } from '@ultimat3/time';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import { tasksSpec } from './cmd-tasks-spec';
@@ -19,7 +20,6 @@ import { flagString } from './parse';
 import { renderTable } from './table';
 import {
   findTaskHandle,
-  isoInZone,
   knownTaskNames,
   listTaskFacts,
   parseCountFlag,
@@ -58,7 +58,7 @@ const lastFireOf = (fires: ReadonlyMap<string, TaskFire>, name: string, tz: stri
   if (fire === undefined) return NEVER_FIRED;
   return {
     lastMs: fire.occurrenceMs,
-    last: isoInZone(fire.occurrenceMs, tz),
+    last: isoInZone(fromEpochMs(fire.occurrenceMs), tz),
     lastFiredAtMs: fire.firedAt,
   };
 };

package/src/cmd-test-spec.ts

@@ -10,7 +10,7 @@ export const testSpec: CommandSpec = {
   name: 'test',
   summary:
     'run one test type — or the whole suite — across N workers, one isolated database per worker',
-  usage: `x test [${TEST_TYPES.join('|')}] [--filter path[,path…]] [--allow-empty] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--worker I] [--isolate] [--json] [-- <bun test flags>]`,
+  usage: `x test [${TEST_TYPES.join('|')}] [--filter path[,path…]] [--allow-empty] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--isolate] [--json] [-- <bun test flags>]`,
   positionalChoices: TEST_TYPES,
   // The one command that hands a tail to another tool — `bun test` — and the reason
   // `CommandSpec.passthrough` exists: `x test unit -- --coverage --bail` parsed both flags and
@@ -28,12 +28,6 @@ export const testSpec: CommandSpec = {
       summary:
         'a fresh global per test file (bun test --isolate) — off by default since 22.7; x.verify.json "isolate": true makes it the repo default',
     },
-    {
-      name: 'worker',
-      type: 'string',
-      summary:
-        'run only shard I of an N-way split of the selection, serially — one CI job\u2019s share',
-    },
     {
       name: 'filter',
       type: 'string',

package/src/cmd-test.ts

@@ -40,22 +40,20 @@ import type { TestType } from './verify-tests';
 import { TEST_TYPES } from './verify-tests';
 
 /**
- * `--workers` and `--shard`. `Number.parseInt` alone accepted `4abc` and `4.9` as four, while
- * `cmd-verify.ts`'s own comment claimed `x test --workers` refused the same values `x verify`
- * does — so the two commands disagreed about the same flag. One reader now answers for both.
+ * `--workers`. `Number.parseInt` alone accepted `4abc` and `4.9` as four, while `cmd-verify.ts`'s
+ * own comment claimed `x test --workers` refused the same values `x verify` does — so the two
+ * commands disagreed about the same flag. One reader now answers for both.
  */
-const readIndex = (args: ParsedArgs, name: string, min: number): number | undefined =>
+const readWorkers = (args: ParsedArgs): number | undefined =>
   readIntFlag(args, {
-    name,
+    name: 'workers',
     command: 'test',
-    min,
+    min: 1,
     // The ceiling the summary already claimed and the reader never enforced: `--workers 5000` was
     // accepted and the run clamps only to the file count, which is one Bun worker per test FILE,
-    // each with the framework module graph and a cloned database. `--worker` is an index into an
-    // N-way split, so the same bound holds it (the exact upper index is `workers - 1`, refused a
-    // line below by the check that knows the real width).
+    // each with the framework module graph and a cloned database.
     max: WORKER_CEILING,
-    example: `x test --${name} ${Math.max(min, 1)}`,
+    example: 'x test --workers 1',
   });
 
 /**
@@ -168,29 +166,17 @@ export const testCommand: CliCommand = {
       });
     }
     const files = sample === undefined ? selected : sampleFiles(selected, sample);
-    const explicit = readIndex(ctx.args, 'workers', 1);
+    const explicit = readWorkers(ctx.args);
     const plan =
       explicit === undefined ? workerPlan(availableCpus(), totalMemory(), ctx.env) : undefined;
     const requested = explicit ?? (plan as WorkerPlan).workers;
     const floor = await readVerifyFloor(ctx.cwd);
     const isolate = flagBool(ctx.args, 'isolate') || floor?.isolate === true;
-    // The width a `--worker` index is judged against, and nothing else: which files really run one
-    // at a time is `test-passes.ts`, off the FILES rather than off the positional. This line read
-    // the positional alone until 2026-09 and the comment here claimed it made a serial type serial
-    // — true for `x test live`, false for the bare `x test --workers 8` that selects every type,
-    // which ran the same `live` and `e2e` files eight at a time. It stays because a `--worker` run
-    // is one process per CI JOB: sharding a serial type across N of them is the cluster-wide race
-    // in a second disguise, and refusing the index is where that is caught.
+    // A serial type is one worker whatever `--workers` says. `test-passes.ts` makes the same call
+    // off the FILES, which is what decides which files really run one at a time; this keeps the
+    // width the run reports and reproduces with the one it ran at.
     const ceiling = type !== undefined && SERIAL_TYPES.includes(type) ? 1 : files.length;
     const workers = Math.max(1, Math.min(requested, ceiling));
-    const only = readIndex(ctx.args, 'worker', 0);
-    if (only !== undefined && only >= workers) {
-      throw new BadFlagError({
-        flag: 'worker',
-        command: 'test',
-        reason: `shard ${only} does not exist in a ${workers}-worker split (0..${workers - 1})`,
-      });
-    }
     const result = await runShards({
       root: ctx.cwd,
       runner: ctx.runner,
@@ -201,11 +187,9 @@ export const testCommand: CliCommand = {
       // A default-width run leases its workers from the machine pool, so a second `x test` or
       // gate on the same box runs narrower instead of doubling its memory.
       ...(plan === undefined ? {} : withLease(machineLease(plan.workers, ctx.env))),
-      ...(only === undefined ? {} : { only }),
       ...(filter === undefined ? {} : { filter }),
       ...(type === undefined ? {} : { type }),
-      // `kept` is the corpus the split saw; a `--worker` rerun must name it, not its own shard.
-      // `selected`, not `discovered`: with `--affected` the sample was taken from the narrowed
+      // `kept` is the corpus the run saw. `selected`, not `discovered`: with `--affected` the sample was taken from the narrowed
       // set, and reporting the whole tree as its total would name a corpus no run ever had.
       ...(sample === undefined ? {} : { sample: { kept: files.length, total: selected.length } }),
       // The fourth input to the split. Without it a failing shard's `fix:` re-splits the whole

package/src/cmd-verify.ts

@@ -20,14 +20,13 @@ import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
 import { WORKER_CEILING, WORKER_FLOOR } from './test-workers';
 import { VERIFY_STEPS } from './verify-checks';
-import { VerifyMergeInputError, VerifyShardInvalidError } from './verify-errors';
 import { readVerifyFloor } from './verify-floor';
 import type { VerifyPart } from './verify-merge';
-import { coverageRiders, mergeParts, parsePart } from './verify-merge';
+import { coverageRiders, mergeParts, parsePart, VerifyMergeInputError } from './verify-merge';
 import { stepStream } from './verify-progress';
 import { runVerify } from './verify-run';
 import type { ShardSpec, Timings } from './verify-shard';
-import { assertShardable, parseShard, readTimings } from './verify-shard';
+import { assertShardable, parseShard, readTimings, VerifyShardInvalidError } from './verify-shard';
 import type { VerifyStepName } from './verify-step';
 import { VERIFY_STEP_NAMES } from './verify-step';
 import { writeErrorLine } from './write-line';
@@ -150,8 +149,9 @@ export const readOnlySteps = (args: ParsedArgs): readonly VerifyStepName[] | und
   if (unknown.length === 0) {
     return VERIFY_STEP_NAMES.filter((name) => items.includes(name));
   }
+  // An empty item corrects to nothing — never to whichever step is nearest to ''.
   const corrected = items.map((item) =>
-    isStepName(item) ? item : nearestName(item, VERIFY_STEP_NAMES),
+    isStepName(item) ? item : item === '' ? undefined : nearestName(item, VERIFY_STEP_NAMES),
   );
   const fix = corrected.every((item) => item !== undefined)
     ? `x verify --only ${renderFixShellArg([...new Set(corrected)].join(','), '<step,step>')} --json`

package/src/db-subscribes.ts

@@ -1,8 +1,9 @@
-// Single responsibility: which tables `x db gen` must grant `REPLICA IDENTITY FULL`, read off the
-// live queries' DECLARED `subscribes:` — and the refusal for a declared name no entity's table
-// matches. This tier is the only one holding both registries, so it is the only one that can ask.
+// Single responsibility: which tables `x db gen` must grant `REPLICA IDENTITY FULL` — the live
+// queries' DECLARED `subscribes:` plus the `records` tables of every channel with params — and the
+// refusal for a declared name no entity's table matches. Only this tier holds all the registries.
 
 import { UltimateError } from '@ultimat3/core';
+import { paramsChannelTables } from '@ultimat3/realtime/server';
 
 /**
  * The two fields this reads, and nothing else. Structurally satisfied by `QueryDescriptor` (whose
@@ -63,12 +64,19 @@ export class QuerySubscribesUnknownError extends UltimateError {
  * Every name is checked against `tables` BEFORE any of them is returned: a run that emitted the
  * good half and refused afterwards would leave an author with a migration that is right for one
  * table and silently absent for the other.
+ *
+ * `channelTables` defaults to what the declared channels need (`paramsChannelTables()`): a channel
+ * with params routes a DELETE to the topic the OLD row names, and under the default identity that
+ * image is the key alone — no topic, no `remove`, and members keep the deleted record. They are
+ * derived from entity projections rather than typed by an author, so one outside `tables` is
+ * dropped, not refused: there is no declaration to send anyone back to.
  */
 export function replicaIdentityTables(
   queries: readonly SubscribingQuery[],
   tables: ReadonlySet<string>,
+  channelTables: readonly string[] = paramsChannelTables(),
 ): readonly string[] {
-  const wanted = new Set<string>();
+  const wanted = new Set<string>(channelTables.filter((table) => tables.has(table)));
   for (const query of queries) {
     for (const table of query.subscribes ?? []) {
       if (!tables.has(table)) {

package/src/dev-dashboard-guard.ts

@@ -0,0 +1,76 @@
+// The doors in front of `/_x` that a browser can knock on. `x dev` binds loopback, but a page the
+// developer has open can still reach it: by DNS rebinding (a hostile name that resolves to
+// 127.0.0.1, read back same-origin) and by a cross-site request to the SQL panel.
+
+import { proveSameOrigin, renderFixShellArg, UltimateError } from '@ultimat3/core';
+import type { UltimateRequest } from '@ultimat3/http';
+import { csrfBlocked, HttpError, json as jsonResponse, selfOrigin } from '@ultimat3/http';
+import { t } from '@ultimat3/schema';
+import { isLoopbackHostname } from './loopback-host';
+
+/** A `/_x` request named a Host that is not this machine. Never echoes the Host it was sent. */
+export class DevHostRefusedError extends UltimateError {
+  constructor(input: { devUrl: string }) {
+    super({
+      code: 'X_DEV_HOST_REFUSED',
+      cause:
+        'a /_x request named a Host that is not localhost, a *.localhost name or a loopback address — the shape of a DNS-rebinding page reading the dev dashboard',
+      fix: `curl -sS -H 'accept: application/json' ${renderFixShellArg(`${input.devUrl}/_x`, 'http://localhost:3000/_x')}`,
+    });
+  }
+}
+
+/** The Host as sent, else the one the URL was built from — Bun builds it from the header. */
+const hostnameOf = (request: UltimateRequest): string | undefined => {
+  const header = request.header('host') ?? request.url.host;
+  return URL.parse(`http://${header}`)?.hostname;
+};
+
+/**
+ * `421 Misdirected Request` for a Host that is not this machine, on every `/_x` route. The status
+ * says "not this server", which is the truth: a rebound name was never meant to reach it.
+ */
+export function hostRefusal(request: UltimateRequest, devUrl: string): Response | undefined {
+  const hostname = hostnameOf(request);
+  if (hostname !== undefined && isLoopbackHostname(hostname)) return undefined;
+  const error = new DevHostRefusedError({ devUrl });
+  return jsonResponse(
+    { ok: false, error: { code: error.code, cause: error.cause, fix: error.fix } },
+    { status: 421 },
+  );
+}
+
+/**
+ * A statement runs on a POST that came from this origin — core's `proveSameOrigin`, the rule the
+ * app's own writes and the sync upgrade answer to, asked HERE rather than left to the pipeline's
+ * CSRF stage: an app with `csrf: { mode: 'off' }` must not switch the dev database's door off with
+ * it. Neither header present is `curl`, as `checkCsrf` reads it: no page can drive that client.
+ */
+export function assertSameOrigin(request: UltimateRequest): void {
+  const origin = request.header('origin');
+  const secFetchSite = request.header('sec-fetch-site');
+  if (origin === null && secFetchSite === null) return;
+  const verdict = proveSameOrigin({
+    selfOrigins: [selfOrigin(request.url, request.ctx.https)],
+    origin,
+    secFetchSite,
+    listed: () => false,
+    listName: 'no list — /_x admits its own origin only',
+  });
+  if (!verdict.ok) throw csrfBlocked(request.pathname, verdict.reason, request.ctx.ip);
+}
+
+/** The SQL panel's one input, from a form or a JSON body — `request.body` parses either. */
+export const SQL_BODY = t.object({ sql: t.string });
+
+/**
+ * A statement on the query string is refused rather than run: a GET is what `<img src>` and a
+ * prefetch send cross-site with nobody's consent. The fix is the POST that does run it.
+ */
+export const sqlOnGet = (devUrl: string): HttpError =>
+  new HttpError({
+    code: 'X_METHOD_NOT_ALLOWED',
+    cause:
+      '/_x/db runs a statement on a same-origin POST only — a GET carrying ?sql= is what a cross-site page can send',
+    fix: `curl -sS -H 'accept: application/json' --data-urlencode 'sql=select 1' ${renderFixShellArg(`${devUrl}/_x/db`, 'http://localhost:3000/_x/db')}`,
+  });