@ultimat3/cli 23.0.0 → 24.0.0

package/src/runtime-realtime.ts

@@ -1,55 +1,19 @@
-// `realtime.enabled`, `realtime.transport` and `realtime.urlEnv`, read out of the app's own
-// `app.config.ts` for the boot. The sibling of `runtime-notify-retention.ts` and `runtime-cache.ts`, and
-// structural for their reason: `startServices` holds no `AppConfig`, and `defineConfig` returns a
-// plain object. Until 22.0.0 no boot read any of the three and `NATS_URL` alone decided the bus.
+// `realtime.enabled`, `realtime.transport` and `realtime.urlEnv` for the boot, out of the config
+// `startServices` loads once (`app-config-load.ts`). Until 22.0.0 no boot read any of the three
+// and `NATS_URL` alone decided the bus.
 
-// why: Bun ships no path-joining API — `Object.keys(Bun)` has `file`, `write`, `Glob`,
-// `pathToFileURL` and `fileURLToPath`, and nothing that joins a path.
-import { join } from 'node:path';
-import { ConfigInvalidError, type RealtimeConfig, type RealtimeTransport } from '@ultimat3/core';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import type { AppConfig, RealtimeConfig } from '@ultimat3/core';
 
-/** Core's `defaults()` for the section, restated as the answer for a config that names none. */
+/** Core's `defaults()` for the section — the answer for a root with no `app.config.ts`. */
 export const REALTIME_DEFAULTS: RealtimeConfig = Object.freeze({
   enabled: true,
   transport: 'memory',
   urlEnv: undefined,
 });
 
-const TRANSPORTS: readonly RealtimeTransport[] = ['memory', 'nats'];
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-/** A transport this boot can build, or a refusal — never a guess at a bus. */
-function transportOf(section: Record<string, unknown>): RealtimeTransport {
-  const value = section['transport'];
-  if (value === undefined) return REALTIME_DEFAULTS.transport;
-  const known = TRANSPORTS.find((transport) => transport === value);
-  if (known !== undefined) return known;
-  throw new ConfigInvalidError({
-    cause: `realtime.transport in ${APP_CONFIG_FILE} is not one of ${TRANSPORTS.join(', ')}`,
-    fix: `set realtime: { transport: 'memory' } in ${APP_CONFIG_FILE}, or { transport: 'nats', urlEnv: 'NATS_URL' } for more than one node`,
-    meta: { key: 'realtime.transport' },
-  });
-}
-
 /**
- * The section as the boot obeys it. A key the file does not name keeps core's default, the same
- * per-key merge `defineConfig` performs, so the boot and the app's own config object agree.
+ * The section as the boot obeys it — `defineConfig`'s per-key merge, so the boot and the app's own
+ * config object agree, and a transport nothing builds is core's `X_CONFIG_INVALID`.
  */
-export async function loadRealtimeConfig(root: string): Promise<RealtimeConfig> {
-  const path = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(path).exists())) return REALTIME_DEFAULTS;
-  const module = (await import(path)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  const section = isRecord(config) ? config['realtime'] : undefined;
-  if (!isRecord(section)) return REALTIME_DEFAULTS;
-  const { enabled, urlEnv } = section;
-  return {
-    enabled: typeof enabled === 'boolean' ? enabled : REALTIME_DEFAULTS.enabled,
-    transport: transportOf(section),
-    urlEnv: typeof urlEnv === 'string' && urlEnv.trim() !== '' ? urlEnv.trim() : undefined,
-  };
-}
+export const realtimeConfigOf = (config: AppConfig | undefined): RealtimeConfig =>
+  config?.realtime ?? REALTIME_DEFAULTS;

package/src/runtime-render.ts

@@ -1,30 +1,21 @@
-// Projecting the route table onto HTTP routes `x dev` can serve. Every mode goes through
+// Projecting the route table onto HTTP routes both boots serve. Every mode goes through
 // `@ultimat3/render`'s own function for that mode — the CLI picks the mode and supplies the
-// document, it never decides what a mode means or what headers it earns.
-//
-// The document is head + the route's own component, rendered by `@ultimat3/render`'s server JSX
-// writer, with the surface's compiled CSS LINKED — one content-hashed file per surface
-// (`style-bundle.ts`), served `immutable`.
-//
-// It was inlined until 2026-09-06, on the argument that a `site/` page is a 0kb-JS artifact a CDN
-// serves as one file and a link would add a round trip. The round trip is real and it is paid
-// once: measured against ai-maxxing, every `app/` document carried the SAME 156,738-byte `<style>`
-// block — 92% of the dashboard document — inside a response the pipeline sends
-// `Cache-Control: private, no-store`, so the trip that argument saved was re-paid in full on every
-// navigation, with a re-parse on top. The static export writes the file (`writeStyles`), so the
-// "second file" cost is one `Bun.write`.
+// document (head + the route's component, the surface's CSS LINKED, `style-bundle.ts`), it never
+// decides what a mode means or what headers it earns.
 
 // why: Bun ships no path API; an island's file is its route file's directory joined to its `src`.
 import { posix } from 'node:path';
 import { actionPathStyle } from '@ultimat3/action';
 import { clientScopeOf } from '@ultimat3/auth';
 import type { Ctx } from '@ultimat3/core';
-import { CLIENT_SCOPE_HEADER } from '@ultimat3/core';
+import { CLIENT_SCOPE_HEADER, createSingleFlight } from '@ultimat3/core';
 import type {
   RouteMeta as HttpRouteMeta,
   RedirectIntent,
+  RequestContext,
   Route,
   RouteParams,
+  UltimateRequest,
 } from '@ultimat3/http';
 import { asCtx, html, NO_STORE, redirect, stream, takeRedirect } from '@ultimat3/http';
 import { currentLocale, localeConfig } from '@ultimat3/i18n';
@@ -52,7 +43,6 @@ import {
 import type { IsrController } from '@ultimat3/render/server';
 import {
   contentHash,
-  createIsrController,
   isrKey,
   ROOT_ELEMENT_ID,
   renderComponent,
@@ -69,6 +59,7 @@ import {
   navigationTagsOf,
   principalRelocation,
 } from './page-navigation';
+import { attachedIsr } from './runtime-isr';
 import type { StaticResult } from './static-document';
 import { createStaticMemo, staticMemoKey, staticResponse } from './static-document';
 import { styleBundle } from './style-bundle';
@@ -77,7 +68,11 @@ export type { DocumentOptions, IslandResolver } from './document-options';
 
 export interface DevRenderOptions extends DocumentOptions {
   readonly buildId: string;
-  /** Injected so a test can drive the ISR store without a timer. */
+  /**
+   * The boot's own controller, attached and released by it (`runtime-isr.ts`). Omitted, one is
+   * built AND attached here, never released — a caller with no stop list (a contract test) still
+   * gets pages a tag bust reaches; the revalidator slot is the latest attach's.
+   */
   readonly isr?: IsrController;
   /**
    * Keep each `static` document after its first render (`static-document.ts`). The container sets
@@ -156,7 +151,8 @@ const headFor = async (
 
 /**
  * `<link rel="stylesheet">` for the surface's own stylesheets, or nothing at all when the surface
- * imports none.
+ * imports none. Inlined until 2026-09-06: every `app/` document of ai-maxxing then carried the same
+ * 156,738-byte `<style>` (92% of it) under `no-store`, re-paid on every navigation.
  *
  * In `<head>`, which is what keeps this a swap and not a regression: a `<link rel="stylesheet">`
  * there is render-blocking in every browser, exactly as the inline block was, so there is no
@@ -429,8 +425,11 @@ const metaOf = (entry: RouteEntry, head?: NavigationDocumentHead): HttpRouteMeta
  * only a test does — and then guard and page fall back together.
  */
 export function appRoutes(options: DevRenderOptions): readonly Route[] {
-  const isr = options.isr ?? createIsrController({ buildId: options.buildId });
+  const isr = options.isr ?? attachedIsr({ buildId: options.buildId }).isr;
   const memo = createStaticMemo();
+  // A cold static key is ONE render however many requests arrive during it: the memo alone was
+  // check-then-act, so a burst at boot ran `load` and the render once per request.
+  const firstRender = createSingleFlight();
   return routeEntries().map((registered) => ({
     method: 'GET' as const,
     path: registered.path,
@@ -450,23 +449,51 @@ export function appRoutes(options: DevRenderOptions): readonly Route[] {
           : undefined;
       const kept = key === undefined ? undefined : memo.get(key);
       if (kept !== undefined) return staticResponse(request, kept);
-      const data: DevRouteData = { url: request.url.href, params: ctx.params };
-      // ONCE per request, before the mode is chosen: every branch of `resultFor` reads this same
-      // object, so a route's `load` runs exactly once however its mode splits head from body.
-      const loaded = await routeDataFor(entry.config, data);
-      // `setRedirect()` inside `load` — the same slot an action's handler fills — answers here,
-      // before a document is rendered for a page the visitor is leaving. `withStatus` refuses a
-      // 3xx because a rendered document has no `Location`; this is the path that has one.
-      const to = takeRedirect(ctx);
-      if (to !== undefined) return loadRedirect(entry, to);
-      const result = await resultFor(entry, data, loaded, options, isr, asCtx(ctx));
-      if (entry.config.render !== 'static' || typeof result.body !== 'string') {
-        return responseOf(result);
-      }
-      const document: StaticResult = { ...result, body: result.body };
-      if (key !== undefined) memo.set(key, document);
+      let led = false;
+      const render = async (): Promise<Rendered> => {
+        led = true;
+        const rendered = await renderEntry(entry, request, ctx, options, isr);
+        if (key !== undefined && rendered.document !== undefined) memo.set(key, rendered.document);
+        return rendered;
+      };
+      const shared = key === undefined ? await render() : await firstRender.run(key, render);
+      // Only a DOCUMENT is shared. A redirect `load` decided was its request's own, so a request
+      // that joined one renders for itself rather than answer with another request's `Location`.
+      const rendered = shared.document !== undefined || led ? shared : await render();
       // The ETag was only ever a header: a matching `If-None-Match` is a 304, not the page again.
-      return staticResponse(request, document);
+      return rendered.document === undefined
+        ? rendered.respond()
+        : staticResponse(request, rendered.document);
     },
   }));
 }
+
+/** A static document a joined request can share, or how to answer when there is none. */
+interface Rendered {
+  readonly document?: StaticResult;
+  readonly respond: () => Response;
+}
+
+async function renderEntry(
+  entry: RouteEntry,
+  request: UltimateRequest,
+  ctx: RequestContext,
+  options: DevRenderOptions,
+  isr: IsrController,
+): Promise<Rendered> {
+  const data: DevRouteData = { url: request.url.href, params: ctx.params };
+  // ONCE per request, before the mode is chosen: every branch of `resultFor` reads this same
+  // object, so a route's `load` runs exactly once however its mode splits head from body.
+  const loaded = await routeDataFor(entry.config, data);
+  // `setRedirect()` inside `load` — the same slot an action's handler fills — answers here,
+  // before a document is rendered for a page the visitor is leaving. `withStatus` refuses a
+  // 3xx because a rendered document has no `Location`; this is the path that has one.
+  const to = takeRedirect(ctx);
+  if (to !== undefined) return { respond: () => loadRedirect(entry, to) };
+  const result = await resultFor(entry, data, loaded, options, isr, asCtx(ctx));
+  if (entry.config.render !== 'static' || typeof result.body !== 'string') {
+    return { respond: () => responseOf(result) };
+  }
+  const document: StaticResult = { ...result, body: result.body };
+  return { document, respond: () => responseOf(document) };
+}

package/src/runtime-services.ts

@@ -4,7 +4,6 @@
 // boot installs, only backed by embedded drivers.
 
 import { mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
 import { configureAuthLimiters, postgresAuthLimiter, resetAuthLimiters } from '@ultimat3/auth';
 import type { PurgeDriver } from '@ultimat3/cache';
 import { isNoopPurgeDriver, selectPurgeDriver } from '@ultimat3/cache';
@@ -31,17 +30,18 @@ import type { Transport, TransportSelection } from '@ultimat3/realtime/server';
 import { selectTransport } from '@ultimat3/realtime/server';
 import type { Storage } from '@ultimat3/storage';
 import { defineStorage, localDriver, s3Driver, usesDevStorageSecret } from '@ultimat3/storage';
+import { loadAppConfig } from './app-config-load';
 import { LocalDiskUnsafeError, StorageUnwritableError } from './errors';
 import { msg } from './messages';
 import type { DevServices, Env } from './runtime-bindings';
-import { loadCacheTiers, startCacheTiers } from './runtime-cache';
-import { loadWorkerConfig, type WorkerConfig } from './runtime-jobs';
-import { loadInboxRetention } from './runtime-notify-retention';
+import { cacheTiersOf, startCacheTiers } from './runtime-cache';
+import { type WorkerConfig, workerConfigOf } from './runtime-jobs';
+import { inboxRetentionOf } from './runtime-notify-retention';
 import type { RuntimeOverrides } from './runtime-overrides';
 import { installRetentionSweep } from './runtime-purge';
-import type { DevDbClient } from './runtime-queue';
+import type { DevDbClient, SchemaMode } from './runtime-queue';
 import { pgExecutorFor, startQueue } from './runtime-queue';
-import { loadRealtimeConfig } from './runtime-realtime';
+import { realtimeConfigOf } from './runtime-realtime';
 
 export interface RunningServices {
   readonly services: DevServices;
@@ -305,6 +305,8 @@ export async function startServices(
   services: DevServices,
   env: Env,
   overrides?: RuntimeOverrides,
+  /** `'verify'` for a serving role on an external database — `runtime-queue.ts`'s `SchemaMode`. */
+  schema: SchemaMode = 'apply',
 ): Promise<RunningServices> {
   // Before the queue: selection is pure — it parses `SMTP_URL` and builds a transport, it does
   // not dial. A typo'd credential must fail on the spot rather than after PGlite has started and
@@ -318,14 +320,16 @@ export async function startServices(
   // service starts, rather than quietly keeping the in-process bus. Which transport, which KV
   // bucket and which presence TTL is `@ultimat3/realtime`'s decision, and it is the same call a
   // `ROLE=sync` container makes, so this process cannot resolve the bus differently from the
-  // container it stands in for. The root is `dirname(stateDir)`, as `loadCacheTiers` reads it.
-  const realtime = await loadRealtimeConfig(dirname(services.stateDir));
-  const workerConfig = await loadWorkerConfig(dirname(services.stateDir));
+  // container it stands in for. The app's config is loaded ONCE, here, and every section below is
+  // read out of that one validated object.
+  const config = await loadAppConfig(services.root);
+  const realtime = realtimeConfigOf(config);
+  const workerConfig = workerConfigOf(config);
   const bus: TransportSelection = selectTransport(env, realtime);
   // `env`, not the ambient one: this function is HANDED the boot's environment and every other
   // reader here already uses it, so a queue that asked `process.env` would decide the standby from
   // a different answer than the middleware that routes to it.
-  const queue = await startQueue(services, overrides, env);
+  const queue = await startQueue(services, overrides, env, schema);
   const { db, jobs, outbox, events } = queue;
   // 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
@@ -359,13 +363,14 @@ export async function startServices(
     // `x_rate_limit` takes one upsert per request the web role serves, assets included.
     //
     // `inboxRetention` is READ HERE and not defaulted in `runtime-purge.ts`: the two windows are the
-    // app's, `startServices` holds no `AppConfig`, and a loader that silently answered "never
-    // sweep" from inside the sweep would be indistinguishable from an app that chose it.
+    // app's, and a loader that silently answered "never sweep" from inside the sweep would be
+    // indistinguishable from an app that chose it.
     started.push(
       installRetentionSweep({
         idempotency: queue.idempotency,
         rateLimit: rateLimitStore,
-        inboxRetention: await loadInboxRetention(services.root),
+        events,
+        inboxRetention: inboxRetentionOf(config),
       }),
     );
     // One readiness check per resource this boot OWNS, released with it. Nothing in the tree
@@ -409,10 +414,8 @@ export async function startServices(
     // process that has stopped.
     // The ladder is the app's declaration, never the environment's. `cache.tiers` was declared,
     // validated and documented while NOTHING read it — so an app asking for one rung got four,
-    // and one asking for a shared tier got whatever `REDIS_URL` happened to say. `.x` is
-    // `resolveServices`' own join, so its parent is the app root: the one fact this function needs
-    // and does not already carry.
-    const tiers = await loadCacheTiers(dirname(services.stateDir));
+    // and one asking for a shared tier got whatever `REDIS_URL` happened to say.
+    const tiers = cacheTiersOf(config);
     started.push(startCacheTiers({ env, purge, transport, tiers }));
 
     return {

package/src/runtime-storage.ts

@@ -24,6 +24,7 @@ import {
   orgMismatch,
 } from '@ultimat3/storage';
 import { storageUploadRoute } from './runtime-storage-upload';
+import { storedObjectHeaders } from './stored-object-headers';
 
 /**
  * The one capability that gates reading a stored object, on every disk. A permission and not a
@@ -103,11 +104,10 @@ export function authorizeStorageRead(input: StorageReadInput, ctx: RequestContex
  */
 export function assertReadableKey(key: string, actor: Actor): string {
   const safe = assertSafeKey(key);
-  // An actor with no org is inside no org, so every tenant-scoped key is somebody else's. Checked
-  // before `isWithinOrg`, which reads an empty org as a malformed key and would blame the caller's
-  // URL for the actor's missing claim.
+  // An actor with no org is inside no org, so every tenant-scoped key is somebody else's —
+  // `isWithinOrg` answers exactly that for an empty org, without throwing.
   const orgId = actor.orgId ?? '';
-  if (isTenantScoped(safe) && (orgId === '' || !isWithinOrg(safe, orgId))) {
+  if (isTenantScoped(safe) && !isWithinOrg(safe, orgId)) {
     throw orgMismatch(safe, orgId);
   }
   return safe;
@@ -185,9 +185,14 @@ export function storageResponse(request: UltimateRequest, read: StorageRead): Re
   const headers = new Headers({
     'content-type': read.object.contentType,
     etag,
-    'last-modified': read.object.lastModified.toUTCString(),
     'accept-ranges': 'bytes',
+    // A type a browser would RUN (html, svg, xml) is a download, never a page on this origin.
+    ...storedObjectHeaders(read.object.contentType),
   });
+  // Omitted, never invented: a disk whose provider reported no date has none, and a `Last-Modified`
+  // made up for it is a validator a cache would go on to trust.
+  const modified = read.object.lastModified;
+  if (modified !== undefined) headers.set('last-modified', modified.toUTCString());
   // Revalidation costs a request and no bytes, which is the trade an authorized response wants:
   // the bytes never change under a key, but the actor's permission to read them can be revoked.
   if (etagMatches(request.header('if-none-match'), etag)) {

package/src/schema-diff.ts

@@ -40,6 +40,11 @@ export interface SchemaDifference {
 
 const DECLARED_ONLY = 'is declared by the entities and no migration recorded it';
 const RECORDED_ONLY = 'was recorded by the newest migration and no entity declares it';
+/** The difference's name — what `x db gen "record …"` is told to write down. */
+const REPLICA_IDENTITY_FULL = 'replica identity full';
+const REPLICA_IDENTITY_UNRECORDED =
+  'needs REPLICA IDENTITY FULL — a channel with params or a live query subscribes to it — and no ' +
+  'migration recorded it';
 
 const columns = (names: readonly string[]): string => names.join(', ');
 
@@ -187,6 +192,17 @@ function compareTable(declared: TableDescription, recorded: TableDescription): S
       detail: `declares primary key (${columns(declared.primaryKey)}) and the migration recorded (${columns(recorded.primaryKey)})`,
     });
   }
+  // One direction: `replica-identity.ts` never reverts the identity, so a recorded FULL nothing
+  // needs any more is what `x db gen` leaves behind on purpose, not a difference.
+  if (declared.replicaIdentityFull === true && recorded.replicaIdentityFull !== true) {
+    out.push({
+      direction: 'unmigrated',
+      part: 'table',
+      table,
+      name: REPLICA_IDENTITY_FULL,
+      detail: REPLICA_IDENTITY_UNRECORDED,
+    });
+  }
   out.push(
     ...compareList({
       part: 'column',

package/src/schema-drift.ts

@@ -15,10 +15,15 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { EntityDescriptionLike, UnrenderedDeclaration } from '@ultimat3/db';
-import { declaredSchema, snapshotOf, unrenderedOf } from '@ultimat3/db';
+import { declaredSchema, shellInertIdentifier, snapshotOf, unrenderedOf } from '@ultimat3/db';
 import { describeEntities } from '@ultimat3/entity';
 import { loadApp } from './app-load';
 import { checkSourceDrift, DB_PACKAGE } from './drift';
+import {
+  appReplicaIdentity,
+  type ReplicaIdentityWanted,
+  wantedReplicaIdentity,
+} from './drift-replica-identity';
 import { MIGRATIONS_DIR, readMigrations } from './migrations';
 import type { Finding } from './output';
 import { diffDeclaredSchema, type SchemaDifference } from './schema-diff';
@@ -50,10 +55,17 @@ const appEntities: DeclaredEntities = async (root) => {
  * silently and the result is green. In that state the unrendered entry's own `fix:` is the
  * instruction: `@ultimat3/db` owns that wording, and a second one here would drift from it.
  */
+interface Repair {
+  /** One runnable command or one edit — never a second option behind a shell comment. */
+  readonly fix: string;
+  /** Why this fix and not the obvious one, appended to the cause where the reader sees it. */
+  readonly why?: string;
+}
+
 function repairFix(
   unrendered: readonly UnrenderedDeclaration[],
   difference: SchemaDifference,
-): string {
+): Repair {
   // The entry ABOUT this difference first, then any entry at all. Reading `unrendered[0]`
   // unconditionally meant that in any app carrying an unrendered DEFAULT, every difference —
   // a dropped CHECK included — was answered with the default's edit, which is an instruction for
@@ -62,7 +74,7 @@ function repairFix(
     (entry) => entry.table === difference.table && entry.name === difference.name,
   );
   // The entry ABOUT this difference carries the edit that repairs it, so it is the whole answer.
-  if (named !== undefined) return named.fix;
+  if (named !== undefined) return { fix: named.fix };
   // Otherwise `x db gen` is still unsafe — it would drop what the other entries name — but the
   // reader must NOT be handed a different declaration's edit as the instruction for this one.
   // Reading `unrendered[0]` did exactly that: a column default and an index each got
@@ -72,16 +84,26 @@ function repairFix(
   // app — not only for the one the entry names.
   const blocker = unrendered[0];
   if (blocker !== undefined) {
-    return `${blocker.fix}   # ${blocker.table}.${blocker.name} reaches no SQL, so regenerating would drop it; repair that before recording ${difference.name}`;
+    return {
+      fix: blocker.fix,
+      why: `${blocker.table}.${blocker.name} reaches no SQL, so regenerating would drop it — repair that before recording ${difference.name}`,
+    };
   }
   // "record", not "add": one finding covers a declaration the migrations never carried AND one they
-  // carry differently, so `add` would be a wrong migration name for half of them. `undeclared` gets
-  // both branches, in the order they are safe — regenerating emits the DROP, and the declaration
-  // may have been LOST rather than removed, which is the whole reason this direction is its own
-  // finding.
-  return difference.direction === 'unmigrated'
-    ? `x db gen "record ${difference.name}"`
-    : `x db gen "drop ${difference.name}"   # or re-declare ${difference.name} on the entity`;
+  // carry differently, so `add` would be a wrong migration name for half of them. `undeclared` runs
+  // the DROP, and the other branch — the declaration may have been LOST rather than removed, which
+  // is the whole reason this direction is its own finding — rides in the cause: a `fix:` is one
+  // command, and a `# or …` after it was a shell comment nobody's paste would run.
+  if (difference.direction === 'unmigrated') return { fix: `x db gen "record ${difference.name}"` };
+  // The name was read off a sidecar on disk and lands inside double quotes, where `$(…)` and a
+  // backtick still run: one the shell would act on is named in the cause only, never the command.
+  const inert = shellInertIdentifier(difference.name) !== null;
+  return {
+    fix: inert
+      ? `x db gen "drop ${difference.name}"`
+      : 'x db gen "drop what the entities no longer declare"',
+    why: `if ${difference.name} was lost rather than removed, re-declare it on the entity instead — this command drops it`,
+  };
 }
 
 /**
@@ -95,8 +117,10 @@ export const schemaDifferenceCause = (difference: SchemaDifference): string =>
     ? `table "${difference.table}" ${difference.detail}`
     : `${difference.part} "${difference.name}" on table "${difference.table}" ${difference.detail}`;
 
-function findingFor(difference: SchemaDifference, fix: string): Finding {
-  const cause = schemaDifferenceCause(difference);
+function findingFor(difference: SchemaDifference, repair: Repair): Finding {
+  const { fix } = repair;
+  const stated = schemaDifferenceCause(difference);
+  const cause = repair.why === undefined ? stated : `${stated} — ${repair.why}`;
   return difference.direction === 'unmigrated'
     ? { code: 'X_DB_SCHEMA_UNMIGRATED', cause, fix, docs: ERROR_DOCS_URL, at: MIGRATIONS_DIR }
     : { code: 'X_DB_SCHEMA_UNDECLARED', cause, fix, docs: ERROR_DOCS_URL, at: MIGRATIONS_DIR };
@@ -114,6 +138,7 @@ function findingFor(difference: SchemaDifference, fix: string): Finding {
 export async function checkSnapshotDrift(
   root: string,
   declared: DeclaredEntities = appEntities,
+  identity: ReplicaIdentityWanted = appReplicaIdentity,
 ): Promise<readonly Finding[]> {
   if (!existsSync(join(root, DB_PACKAGE))) return [];
   const entities = await declared(root);
@@ -122,7 +147,11 @@ export async function checkSnapshotDrift(
   if (migrations.length === 0) return [];
   const recorded = declaredSchema(migrations);
   if (recorded === undefined) return [];
-  const differences = diffDeclaredSchema(snapshotOf(entities), recorded);
+  // Read only over a WHOLE registry (`entities` is `undefined` otherwise), the rule `x db gen`
+  // states for the same call: a short one makes every subscribed name in the missing module a typo.
+  const wanted = wantedReplicaIdentity(identity, new Set(entities.map((entity) => entity.table)));
+  if ('finding' in wanted) return [wanted.finding];
+  const differences = diffDeclaredSchema(snapshotOf(entities, wanted.tables), recorded);
   if (differences.length === 0) return [];
   // `recorded` and not the entities alone: whether an `assert` is a LOSS depends on whether a
   // migration recorded a CHECK for it, which only the sidecar knows.
@@ -145,8 +174,9 @@ export async function checkMigrationDrift(
   root: string,
   declared: DeclaredEntities = appEntities,
   hashDrift: (root: string) => Promise<readonly Finding[]> = checkSourceDrift,
+  identity: ReplicaIdentityWanted = appReplicaIdentity,
 ): Promise<readonly Finding[]> {
-  const snapshot = await checkSnapshotDrift(root, declared);
+  const snapshot = await checkSnapshotDrift(root, declared, identity);
   if (snapshot.length > 0) return snapshot;
   return hashDrift(root);
 }

package/src/seo-routes.ts

@@ -1,11 +1,14 @@
-// `GET /robots.txt` and `GET /sitemap.xml` from a running web role — the files the static export
-// writes, answered by the process for a deploy that serves its pages from a container. Mounted by
-// `x dev` and `runRole` alike, before the app's pages, for `style-routes.ts`' reason.
+// `GET /robots.txt`, `GET /sitemap.xml` and its parts (`/sitemaps/<n>.xml`) from a running web
+// role — the files the static export writes, for a deploy that serves its pages from a container.
+// Mounted by `x dev` and `runRole` alike, before the app's pages, for `style-routes.ts`' reason.
 
 import { DEFAULT_ENVIRONMENT, type Environment, tryResolveEnvironment } from '@ultimat3/core';
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders } from '@ultimat3/http';
+import { applyCacheHeaders, json, NO_STORE } from '@ultimat3/http';
+import { SITEMAP_PARTS_DIR } from '@ultimat3/seo';
+import { quoteArg } from './shell-quote';
 import { NO_SITE_SETTINGS, publicOrigin, type SiteSettings } from './site-config';
+import type { SiteSeo } from './site-seo';
 import { ROBOTS_PATH, SITEMAP_PATH, siteSeo } from './site-seo';
 
 export interface SeoRoutesOptions {
@@ -26,22 +29,57 @@ function originOf(options: SeoRoutesOptions, request: UltimateRequest): string {
 }
 
 /**
- * Per request, never cached across one: `prerender()` may enumerate rows that change, and a
- * crawler asks for these a handful of times a day. An hour of shared cache is what a CDN keeps.
+ * An hour of shared cache is what a CDN keeps of either file, and what this process keeps of the
+ * answer behind both. `prerender()` may enumerate rows that change, so the memo is never longer
+ * than the response's own `max-age` — a crawler that bypasses the CDN sees what one behind it
+ * would. Before it, every `/robots.txt` hit recomputed the whole sitemap, each dynamic route's
+ * `prerender()` included.
  */
 const SEO_CACHE = { mode: 'public', maxAgeSeconds: 3600 } as const;
 
+/**
+ * Origins remembered at once. With no declared origin the request's own is the key, and a `Host`
+ * header is the caller's to choose — so the memo is bounded, oldest out first.
+ */
+const SEO_MEMO_ORIGINS = 8;
+
+interface Memo {
+  readonly at: number;
+  readonly answer: Promise<SiteSeo>;
+}
+
 export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
   const environment: Environment =
     tryResolveEnvironment({ env: options.env }) ?? DEFAULT_ENVIRONMENT;
-  const answer = async (request: UltimateRequest) =>
-    await siteSeo({
-      baseUrl: originOf(options, request),
+  const compute = (baseUrl: string): Promise<SiteSeo> =>
+    siteSeo({
+      baseUrl,
       environment,
       disallow: options.site?.disallow ?? [],
       ...(options.site === undefined ? {} : { sitemap: options.site.sitemap }),
       ...(options.root === undefined ? {} : { root: options.root }),
     });
+  // Single-flight per origin: concurrent requests share the one computation in progress. A failed
+  // one is dropped, so the next request asks again rather than serving the failure for an hour.
+  const memo = new Map<string, Memo>();
+  const answer = (request: UltimateRequest): Promise<SiteSeo> => {
+    const origin = originOf(options, request);
+    const now = Date.now();
+    const kept = memo.get(origin);
+    if (kept !== undefined && now - kept.at < SEO_CACHE.maxAgeSeconds * 1000) return kept.answer;
+    memo.delete(origin);
+    if (memo.size >= SEO_MEMO_ORIGINS) {
+      const oldest = memo.keys().next().value;
+      if (oldest !== undefined) memo.delete(oldest);
+    }
+    const computed = compute(origin);
+    memo.set(origin, { at: now, answer: computed });
+    // Voided: the request awaits `computed` itself and reports its failure; this branch only forgets it.
+    void computed.catch(() => {
+      if (memo.get(origin)?.answer === computed) memo.delete(origin);
+    });
+    return computed;
+  };
 
   return [
     {
@@ -69,5 +107,38 @@ export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
           SEO_CACHE,
         ),
     },
+    {
+      method: 'GET',
+      path: `${SITEMAP_PARTS_DIR}/:file`,
+      meta: { name: 'seo.sitemapPart', auth: 'public', tags: ['seo'] },
+      // A part of a split sitemap, from the same answer the index came from — so a part the index
+      // names always exists here, and the static export writes the same paths.
+      handler: async (request: UltimateRequest): Promise<Response> => {
+        const seo = await answer(request);
+        const part = seo.sitemaps.find((file) => file.path === request.pathname);
+        if (part !== undefined && part.path !== SITEMAP_PATH) {
+          return applyCacheHeaders(
+            new Response(part.xml, {
+              headers: { 'content-type': 'application/xml; charset=utf-8' },
+            }),
+            SEO_CACHE,
+          );
+        }
+        const index = new URL(SITEMAP_PATH, originOf(options, request)).href;
+        const missing = json(
+          {
+            ok: false,
+            error: {
+              code: 'X_ROUTE_NOT_FOUND',
+              cause: `${request.pathname} is no part of this site's sitemap: the index names ${String(Math.max(seo.sitemaps.length - 1, 0))} part(s)`,
+              fix: `curl -sS ${quoteArg(index)}`,
+            },
+          },
+          { status: 404 },
+        );
+        // `no-store`: the part may exist once the site grows, and a cached miss would hide it.
+        return applyCacheHeaders(missing, NO_STORE);
+      },
+    },
   ];
 }