@ultimat3/cli 25.0.0 → 25.2.0

package/package.json

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

package/src/cmd-routes-spec.ts

@@ -5,7 +5,7 @@ import type { CommandSpec } from './parse';
 
 export const routesSpec: CommandSpec = {
   name: 'routes',
-  summary: 'the route table: path, surface, render mode, hydrate, offline',
+  summary: 'every served route: pages, then actions, queries and runtime.ts routes',
   usage: 'x routes [--surface site|app|api|shared] [--json]',
   requiresApp: true,
   flags: [{ name: 'surface', type: 'string', summary: 'filter by surface' }],

package/src/cmd-routes.ts

@@ -1,63 +1,20 @@
 // `x routes` — the route table as a table, or as JSON. Replaces grepping a router directory, which
 // is what an agent does when the framework has no answer to "what URLs exist".
 //
-// The rows are `@ultimat3/render`'s own `describePages()`: the CLI prints the route table, it
-// does not keep a second one.
+// The rows are `route-table.ts`'s — the one builder the MCP dev tool `routes.list` reads too — so
+// the CLI keeps no second table.
 
-import type { RouteDescriptor, Surface } from '@ultimat3/render';
-import { describePages, SURFACES } from '@ultimat3/render';
+import type { Surface } from '@ultimat3/render';
+import { SURFACES } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import { routesSpec } from './cmd-routes-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, UnknownCommandError } from './errors';
 import { msg } from './messages';
-import type { CommandResult, JsonValue } from './output';
+import type { CommandResult } from './output';
 import { flagString } from './parse';
-
-/**
- * Where a route comes from. A file route names its file; a MOUNTED one names the call that
- * mounted it and every permission that gates it — there is no `page.tsx` to name, and printing the
- * package would send a reader looking for a route file inside `node_modules`.
- */
-const declaredBy = (route: RouteDescriptor): string =>
-  route.mount === undefined
-    ? route.file
-    : `${route.mount.by}() · ${route.mount.permissions.join(' + ')}`;
-
-/** Fixed-width columns so the output diffs cleanly between runs and between machines. */
-export function renderRouteTable(routes: readonly RouteDescriptor[]): readonly string[] {
-  const rows = routes.map((route) => [
-    route.path,
-    route.surface,
-    route.mode,
-    route.hydrate,
-    route.offline,
-    declaredBy(route),
-  ]);
-  const header = ['path', 'surface', 'render', 'hydrate', 'offline', 'file'];
-  const widths = header.map((title, index) =>
-    Math.max(title.length, ...rows.map((row) => (row[index] ?? '').length)),
-  );
-  const line = (cells: readonly string[]): string =>
-    cells.map((value, index) => value.padEnd(widths[index] ?? 0)).join('  ');
-  return [line(header), ...rows.map(line)];
-}
-
-const routeJson = (routes: readonly RouteDescriptor[]): JsonValue =>
-  routes.map((route) => ({
-    path: route.path,
-    surface: route.surface,
-    file: route.file,
-    render: route.mode,
-    hydrate: route.hydrate,
-    offline: route.offline,
-    budget: { js: route.budgetJs },
-    // Absent on a file route, never `null`: only a mounted route has the fact.
-    ...(route.mount === undefined
-      ? {}
-      : { mount: { by: route.mount.by, permissions: [...route.mount.permissions] } }),
-  }));
+import { plainAppRoutes, renderRouteRows, routeRows } from './route-table';
 
 /**
  * A closed set, because the filter was a bare `===`: `x routes --surface App` and `--surface pages`
@@ -97,7 +54,7 @@ export const routesCommand: CliCommand = {
     // `--transport` already follows.
     const surface = readSurfaceFilter(flagString(ctx.args, 'surface'));
     const { findings } = await loadApp(root);
-    const routes = describePages().filter(
+    const routes = routeRows(await plainAppRoutes(root)).filter(
       (route) => surface === undefined || route.surface === surface,
     );
     return {
@@ -107,9 +64,9 @@ export const routesCommand: CliCommand = {
         routes.length === 0
           ? msg('cli.routes.empty')
           : msg('cli.routes.count', { count: routes.length }),
-      lines: routes.length === 0 ? [] : renderRouteTable(routes).map((line) => `  ${line}`),
+      lines: routes.length === 0 ? [] : renderRouteRows(routes).map((line) => `  ${line}`),
       findings,
-      data: { routes: routeJson(routes) },
+      data: { routes: routes.map((route) => route.json) },
     };
   },
 };

package/src/doctor-guards.ts

@@ -1,12 +1,14 @@
-// `x doctor`'s guard listing: the guards the framework ships that this app's `guards/` does not
-// hold, each with the command that adds it. A LISTING, never a finding: every shipped guard says
-// "delete this file to drop the rule", so an app without one may have decided — and a red
-// `x doctor` over a decision would be the framework overruling the convention it handed over.
+// `x doctor`'s guard listing: the shipped guards this app's `guards/` does not hold, and the ones
+// it holds in a form that is not the current template — each with the command that writes it. A
+// LISTING, never a finding: every shipped guard is the app's copy ("delete this file to drop the
+// rule"), so a missing or edited one may be a decision the framework must not overrule.
 
+// why: Bun exposes no path-join primitive; Bun.file takes one already joined.
+import { join } from 'node:path';
 import { GUARD_DIR, guardPaths } from './guards';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
-import { SHIPPED_GUARD_NAMES } from './templates/scaffold-guards';
+import { SHIPPED_GUARD_NAMES, shippedGuardSource } from './templates/scaffold-guards';
 
 export interface MissingGuard {
   readonly name: string;
@@ -23,9 +25,51 @@ export function missingShippedGuards(present: readonly string[]): readonly Missi
   }));
 }
 
+export interface DifferingGuard {
+  readonly name: string;
+  /** Rewrites the guard and its test from the current template. Review the diff, then keep it. */
+  readonly refresh: string;
+}
+
+/** One line of the listing: a shipped guard the app lacks, or holds in another form. */
+export type GuardListingEntry = MissingGuard | DifferingGuard;
+
+/** A guard file as the app holds it, path relative to the app root. */
+export interface HeldGuard {
+  readonly path: string;
+  readonly source: string;
+}
+
+/** A checkout on Windows may write CRLF; the rule is the same text either way. */
+const sameText = (a: string, b: string): boolean =>
+  a.replaceAll('\r\n', '\n') === b.replaceAll('\r\n', '\n');
+
+/**
+ * The rule, pure: which held guards carry a shipped name and are not that guard's current
+ * template. A guard with a name the framework never shipped is the app's own, and has no template.
+ */
+export function differingShippedGuards(held: readonly HeldGuard[]): readonly DifferingGuard[] {
+  const differing: DifferingGuard[] = [];
+  for (const { path, source } of held) {
+    const name = path.slice(`${GUARD_DIR}/`.length).replace(/\.tsx?$/, '');
+    const template = shippedGuardSource(name);
+    if (template === undefined || sameText(source, template)) continue;
+    differing.push({ name, refresh: `x g guard ${name} --force` });
+  }
+  return differing;
+}
+
 /** The I/O half: the same enumeration the `boundaries` step runs, so the two cannot disagree. */
-export async function shippedGuardsProbe(root: string): Promise<readonly MissingGuard[]> {
-  return missingShippedGuards(await guardPaths(root));
+export async function shippedGuardsProbe(root: string): Promise<readonly GuardListingEntry[]> {
+  const paths = await guardPaths(root);
+  const held = await Promise.all(
+    paths.map(async (path) => ({ path, source: await Bun.file(join(root, path)).text() })),
+  );
+  const entries: GuardListingEntry[] = [
+    ...missingShippedGuards(paths),
+    ...differingShippedGuards(held),
+  ];
+  return entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 }
 
 /**
@@ -34,21 +78,32 @@ export async function shippedGuardsProbe(root: string): Promise<readonly Missing
  */
 export function withGuardListing(
   result: CommandResult,
-  missing: readonly MissingGuard[],
+  entries: readonly GuardListingEntry[],
 ): CommandResult {
   const data = typeof result.data === 'object' && result.data !== null ? result.data : {};
-  const listed: JsonValue = missing.map(({ name, add }) => ({ name, add }));
+  const missing = entries.filter((entry): entry is MissingGuard => 'add' in entry);
+  const differs = entries.filter((entry): entry is DifferingGuard => 'refresh' in entry);
+  const lines = [
+    ...(missing.length === 0
+      ? []
+      : [
+          msg('cli.doctor.guards', { count: missing.length }),
+          ...missing.map(({ add }) => `  ${add}`),
+        ]),
+    ...(differs.length === 0
+      ? []
+      : [
+          msg('cli.doctor.guardsDiffer', { count: differs.length }),
+          ...differs.map(({ refresh }) => `  ${refresh}`),
+        ]),
+  ];
+  const guards: JsonValue = {
+    missing: missing.map(({ name, add }) => ({ name, add })),
+    differs: differs.map(({ name, refresh }) => ({ name, refresh })),
+  };
   return {
     ...result,
-    data: { ...(data as Record<string, JsonValue>), guards: { missing: listed } },
-    ...(missing.length === 0
-      ? {}
-      : {
-          lines: [
-            ...(result.lines ?? []),
-            msg('cli.doctor.guards', { count: missing.length }),
-            ...missing.map(({ add }) => `  ${add}`),
-          ],
-        }),
+    data: { ...(data as Record<string, JsonValue>), guards },
+    ...(lines.length === 0 ? {} : { lines: [...(result.lines ?? []), ...lines] }),
   };
 }

package/src/index.ts

@@ -31,12 +31,6 @@ export { GENERATORS, generate, writeFiles } from './cmd-generate';
 export { JOBS_SUBCOMMANDS } from './cmd-jobs';
 export { newCommand, planNewApp, writeNewApp } from './cmd-new';
 export { PLANNED_COMMANDS, PLANNED_SUBCOMMANDS, plannedSubcommand } from './cmd-planned';
-// `shotCommand`, `prCommand` and `ciCommand` are deliberately NOT re-exported here. They reach
-// `x` through `registry.ts`, which is the only thing that makes a command exist — and the barrel
-// is the surface an APP imports. Exporting them would put the browser driver and the GitHub client
-// in the module graph of every app that imports `@ultimat3/cli`, for tools it never calls. The app
-// path does not pay for the tool path.
-export { renderRouteTable } from './cmd-routes';
 export { runVerify, VERIFY_STEPS, verifyCommand, verifyStepNames } from './cmd-verify';
 export type { CliCommand } from './command';
 export { failed, ok } from './command';
@@ -130,6 +124,12 @@ export { loadPwaArtifacts } from './pwa-artifacts';
 export { COMMANDS, cliVersion, SPECS } from './registry';
 export type { RunningRoles, WebBinding } from './role-start';
 export { DEV_BINDING, DEV_ROLES, startRoles } from './role-start';
+// `shotCommand`, `prCommand` and `ciCommand` are deliberately NOT re-exported here. They reach
+// `x` through `registry.ts`, which is the only thing that makes a command exist — and the barrel
+// is the surface an APP imports. Exporting them would put the browser driver and the GitHub client
+// in the module graph of every app that imports `@ultimat3/cli`, for tools it never calls. The app
+// path does not pay for the tool path.
+export { renderRouteTable } from './route-table';
 export { assetRoutes, MEDIA_BASE_PATH } from './runtime-assets';
 export { resolveServices } from './runtime-bindings';
 export { devHooks } from './runtime-hooks';

package/src/mcp-host.ts

@@ -36,7 +36,6 @@ import type {
   VerifyStep,
 } from '@ultimat3/mcp';
 import { DEV_SCOPES, devHost, devMcpServer, frameworkIntrospection } from '@ultimat3/mcp';
-import { describePages } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import { appManifest, policyFacts } from './app-manifest';
 import { runVerify, VERIFY_STEPS } from './cmd-verify';
@@ -50,6 +49,7 @@ import { testRunOf } from './mcp-test-run';
 import { type UiCapabilities, uiCapabilities } from './mcp-ui';
 import { readMigrations } from './migrations';
 import { retryMemo } from './retry-memo';
+import { plainAppRoutes, routeRows } from './route-table';
 import type { DevServices, Env } from './runtime-bindings';
 import { resolveServices } from './runtime-bindings';
 import type { RunningServices } from './runtime-services';
@@ -346,10 +346,12 @@ export async function createDevMcpServer(input: DevHostInput): Promise<CliMcpSer
   // scratch boot re-imported the app after declaring — rendered. Idempotent; a set key stays.
   declareDevEnvironment(input.env);
   await Promise.all([loadApp(input.root), loadCodeFixes()]);
+  // The plain `runtime.ts` routes, read once: `routes.list` answers the table `x routes` prints.
+  const plain = await plainAppRoutes(input.root);
   const lazy = lazyServices(input);
   const ui = uiCapabilities({ root: input.root, env: input.env });
   const introspection = frameworkIntrospection({
-    routes: () => describePages(),
+    routes: () => routeRows(plain).map((row) => row.json),
     policies: () => policyFacts(),
   });
   const server = devMcpServer({ host: devHost(introspection, capabilities(input, lazy, ui)) });

package/src/messages.ts

@@ -102,6 +102,8 @@ const CATALOG = {
   'cli.doctor.findings': '{count} finding(s)',
   'cli.doctor.guards':
     '{count} shipped guard(s) this app does not hold — each line adds one, then x verify reports what it finds:',
+  'cli.doctor.guardsDiffer':
+    '{count} shipped guard(s) differ from the current template — an older copy or your own edit; each line rewrites one and its test, review the diff before keeping it:',
   // `x doctor`'s other listing: what the coverage floor in x.verify.json does not see, and why.
   'cli.doctor.coverageExclude':
     '{count} path(s) x.verify.json excludes from the coverage floor — each with the reason it gives:',

package/src/role-start.ts

@@ -8,6 +8,7 @@
 
 import type { Role } from '@ultimat3/core';
 import { ctxOf, isRole, logger, markReady, ROLES } from '@ultimat3/core';
+import { dbExecutor } from '@ultimat3/db';
 import type { RateLimitStore, Route, ServerHandle, WebSocketMount } from '@ultimat3/http';
 import {
   adoptRateLimitStore,
@@ -43,7 +44,6 @@ import { startWorkerWake } from './role-wake';
 import { devHooks } from './runtime-hooks';
 import { workerOptionsFor } from './runtime-jobs';
 import { startLiveFeed } from './runtime-live-feed';
-import { pgExecutorFor } from './runtime-queue';
 import { type RunningServices, releaseOrThrow } from './runtime-services';
 import { inlineScriptSources } from './script-csp';
 import { inlineStyleSources } from './style-csp';
@@ -359,7 +359,7 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
     // SESSION-scoped, and the session ends the moment the connection goes back to the pool, so
     // every node reads itself as leader anyway. An expiring row is correct on the executor this
     // package is actually handed.
-    const executor = pgExecutorFor(options.runtime.db);
+    const executor = dbExecutor(() => options.runtime.db);
     const scheduler = selected.includes('scheduler')
       ? jobScheduler({
           driver: options.runtime.jobs,

package/src/role-wake.ts

@@ -5,10 +5,9 @@
 
 import { gauge } from '@ultimat3/core';
 import type { DbClient } from '@ultimat3/db';
-import { canListen } from '@ultimat3/db';
+import { canListen, dbExecutor } from '@ultimat3/db';
 import type { QueueWake } from '@ultimat3/jobs';
 import { startQueueWake } from '@ultimat3/jobs';
-import { pgExecutorFor } from './runtime-queue';
 
 // The wake the gauge reads. One observer for the life of the process: a gauge redeclared with a
 // different `observe` is refused, and `x dev` starts the roles again on every restart-in-place.
@@ -32,7 +31,7 @@ export function startWorkerWake(db: DbClient): QueueWake | null {
       observe: wakeLive,
     });
   }
-  const wake = startQueueWake({ listener: db, executor: pgExecutorFor(db) });
+  const wake = startQueueWake({ listener: db, executor: dbExecutor(() => db) });
   current = wake;
   return {
     live: () => wake.live(),

package/src/route-table.ts

@@ -0,0 +1,113 @@
+// The served route table, as rows: the pages (`describePages()`), then every API route — the
+// action and query projections `apiRoutes()` builds for `x dev` and the container, and the plain
+// routes of `apps/<app>/runtime.ts`. `x routes` and the MCP dev tool `routes.list` both read it.
+
+import type { Route } from '@ultimat3/http';
+import type { RouteDescriptor, Surface } from '@ultimat3/render';
+import { describePages } from '@ultimat3/render';
+import { apiRoutes } from './api-routes';
+import { loadAppRuntime } from './app-runtime';
+import type { JsonValue } from './output';
+
+/** One printed and one JSON row per served route: a page, a mounted page, or an API route. */
+export interface RouteRow {
+  readonly surface: Surface;
+  readonly path: string;
+  readonly cells: readonly string[];
+  readonly json: JsonValue;
+}
+
+/**
+ * Where a route comes from. A file route names its file; a MOUNTED one names the call that
+ * mounted it and every permission that gates it — there is no `page.tsx` to name, and printing the
+ * package would send a reader looking for a route file inside `node_modules`.
+ */
+const declaredBy = (route: RouteDescriptor): string =>
+  route.mount === undefined
+    ? route.file
+    : `${route.mount.by}() · ${route.mount.permissions.join(' + ')}`;
+
+const pageRow = (route: RouteDescriptor): RouteRow => ({
+  surface: route.surface,
+  path: route.path,
+  cells: [
+    'GET',
+    route.path,
+    route.surface,
+    route.mode,
+    route.hydrate,
+    route.offline,
+    declaredBy(route),
+  ],
+  json: {
+    method: 'GET',
+    path: route.path,
+    surface: route.surface,
+    file: route.file,
+    render: route.mode,
+    hydrate: route.hydrate,
+    offline: route.offline,
+    budget: { js: route.budgetJs },
+    // Absent on a file route, never `null`: only a mounted route has the fact.
+    ...(route.mount === undefined
+      ? {}
+      : { mount: { by: route.mount.by, permissions: [...route.mount.permissions] } }),
+  },
+});
+
+/**
+ * An action or query projection, or a plain `runtime.ts` route (`primitive: null`). It renders
+ * nothing, so the page columns read `-`; where a page names its file this names what declared it
+ * and the permission its policy asks for.
+ */
+const apiRow = (route: Route): RouteRow => {
+  const primitive = route.meta.primitive ?? null;
+  const policy = route.meta.policy ?? null;
+  const from = primitive === null ? 'runtime.ts routes' : primitive;
+  const by = `${from} ${route.meta.name}${policy === null ? '' : ` · ${policy}`}`;
+  return {
+    surface: 'api',
+    path: route.path,
+    cells: [route.method, route.path, 'api', '-', '-', '-', by],
+    json: {
+      method: route.method,
+      path: route.path,
+      surface: 'api',
+      primitive,
+      name: route.meta.name,
+      auth: route.meta.auth,
+      policy,
+    },
+  };
+};
+
+const byPath = (a: RouteRow, b: RouteRow): number =>
+  a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+
+/** Pages first, in the page table's order; then the API, by path, so the listing diffs cleanly. */
+export function routeRows(plain: readonly Route[] = []): readonly RouteRow[] {
+  return [...describePages().map(pageRow), ...[...apiRoutes(), ...plain].map(apiRow).sort(byPath)];
+}
+
+/**
+ * The plain HTTP routes `apps/<app>/runtime.ts` declares — the ones `X_BODY_INVALID` is about,
+ * since an action or query validates its own input. Loaded as `x dev` loads them.
+ */
+export async function plainAppRoutes(root: string): Promise<readonly Route[]> {
+  return (await loadAppRuntime(root))?.routes ?? [];
+}
+
+/** Fixed-width columns so the output diffs cleanly between runs and between machines. */
+export function renderRouteTable(routes: readonly RouteDescriptor[]): readonly string[] {
+  return renderRouteRows(routes.map(pageRow));
+}
+
+export function renderRouteRows(rows: readonly RouteRow[]): readonly string[] {
+  const header = ['method', 'path', 'surface', 'render', 'hydrate', 'offline', 'declared by'];
+  const widths = header.map((title, index) =>
+    Math.max(title.length, ...rows.map((row) => (row.cells[index] ?? '').length)),
+  );
+  const line = (cells: readonly string[]): string =>
+    cells.map((value, index) => value.padEnd(widths[index] ?? 0)).join('  ');
+  return [line(header), ...rows.map((row) => line(row.cells))];
+}

package/src/runtime-queue.ts

@@ -11,17 +11,18 @@ import {
   resetIdempotency,
   setIdempotencyStore,
 } from '@ultimat3/action';
-import type { DbClient, PgliteClient, PostgresClient, SqlFragment } from '@ultimat3/db';
+import type { PgliteClient, PostgresClient } from '@ultimat3/db';
 import {
   baseClient,
   currentTx,
+  dbExecutor,
   pgliteClient,
   pgliteDataDir,
   postgresClient,
   setDbClient,
 } from '@ultimat3/db';
 import type { Tx } from '@ultimat3/entity';
-import type { EventBus, JobDriver, OutboxStore, PgExecutor } from '@ultimat3/jobs';
+import type { EventBus, JobDriver, OutboxStore } from '@ultimat3/jobs';
 import {
   outboxJobsFacade,
   postgresEventBus,
@@ -109,20 +110,6 @@ export function startDb(services: DevServices, env: ReplicaEnv): StartedDb {
   return { client, replica: attached.replica };
 }
 
-/**
- * `@ultimat3/jobs` deliberately depends on no database package: Postgres reaches it as an
- * injected `PgExecutor`. Boot code is what supplies one, and this is the boot.
- *
- * The fragment is assembled by hand rather than through `sql`` ` because the driver hands over
- * `$1..$n` text it wrote itself plus already-bound values — there is no interpolation to guard.
- */
-export function pgExecutorFor(client: DbClient): PgExecutor {
-  return {
-    query: <R>(text: string, values: readonly unknown[]): Promise<readonly R[]> =>
-      client.query<R>({ text, values } satisfies SqlFragment),
-  };
-}
-
 /**
  * Every table this process's framework packages own, applied before anything reads one.
  *
@@ -183,13 +170,15 @@ async function startJobs(
   schema: SchemaMode,
 ): Promise<RunningQueue> {
   await applySchema(client, schema);
-  const executor = pgExecutorFor(client);
+  // Bound to `client`, never the ambient `db()`: the queue, the event bus and the idempotency
+  // reservations stay on the boot's pool whatever transaction is open.
+  const executor = dbExecutor(() => client);
   const driver = overrides?.jobs ?? postgresJobDriver({ executor });
   setJobDriver(driver);
   const outbox = postgresOutboxStore({
     executor,
     // The open transaction is a client on its own connection; the `Tx` token is not that object.
-    txExecutor: () => pgExecutorFor(currentTx() ?? client),
+    txExecutor: () => dbExecutor(() => currentTx() ?? client),
   });
   setJobsFacade(
     outboxJobsFacade({ store: outbox, driver }, () => currentTx() as unknown as Tx | undefined),

package/src/runtime-services.ts

@@ -15,6 +15,7 @@ import {
   resolveEnvironment,
   systemClock,
 } from '@ultimat3/core';
+import { dbExecutor } from '@ultimat3/db';
 import type { RateLimitStore } from '@ultimat3/http';
 import { adoptRateLimitStore, postgresRateLimitStore } from '@ultimat3/http';
 import type { EventBus, JobDriver, OutboxStore } from '@ultimat3/jobs';
@@ -40,7 +41,7 @@ import { inboxRetentionOf } from './runtime-notify-retention';
 import type { RuntimeOverrides } from './runtime-overrides';
 import { installRetentionSweep } from './runtime-purge';
 import type { DevDbClient, SchemaMode } from './runtime-queue';
-import { pgExecutorFor, startQueue } from './runtime-queue';
+import { startQueue } from './runtime-queue';
 import { realtimeConfigOf } from './runtime-realtime';
 
 export interface RunningServices {
@@ -351,7 +352,7 @@ export async function startServices(
   // The same executor the jobs driver, the outbox, the event bus and the idempotency store run
   // on — one pool, one `Bun.sql` that does NOT satisfy `PgExecutor` (`Bun.sql.query` is
   // `undefined`), one wrapper.
-  const executor = pgExecutorFor(db);
+  const executor = dbExecutor(() => db);
   const rateLimitStore = postgresRateLimitStore({ executor });
   // Boot is a sequence of external resources, and every step after the first can reject — the
   // queue is already up, so from here an unwind must release it exactly like everything after it.

package/src/templates/scaffold-guards.ts

@@ -75,6 +75,18 @@ export const SHIPPED_GUARD_NAMES: readonly string[] = SHIPPED.map(([name]) => na
 export const shippedGuardFiles = (name: string): readonly GeneratedFile[] | undefined =>
   SHIPPED.find(([shipped]) => shipped === name)?.[1]();
 
+/**
+ * The current text of a shipped guard's rule file (`guards/<name>.ts`), or `undefined` when the
+ * name was never shipped — what `x doctor` compares an app's copy against.
+ */
+export const shippedGuardSource = (name: string): string | undefined => {
+  const contents = shippedGuardFiles(name)?.find(
+    (file) => file.path === `guards/${name}.ts`,
+  )?.contents;
+  // A guard is source text; bytes would be a template bug, and comparing them as text would hide it.
+  return typeof contents === 'string' ? contents : undefined;
+};
+
 /**
  * Every guard `x new` ships, each with its test. One module per guard, because an app deletes a
  * rule it does not want by deleting one file — and a guard the app then writes for itself is