@ultimat3/cli 29.4.0 → 30.0.0

package/src/retained-assets.ts

@@ -0,0 +1,171 @@
+// Earlier builds' hashed files, kept readable across a deploy (`assets.retain`): a web pod
+// publishes what it serves to a shared disk before it reports ready. This file is the publish and
+// the key layout; the sweep is `retained-assets-sweep.ts`, the read `retained-assets-read.ts`.
+
+import type { Clock } from '@ultimat3/core';
+import {
+  finiteCount,
+  isUltimateError,
+  logger,
+  renderCauseValue,
+  renderThrowable,
+  systemClock,
+  UltimateError,
+} from '@ultimat3/core';
+import type { BuildManifest, RetainedScope } from './retained-assets-layout';
+import { inBatches, manifestKey, retainedFileKey } from './retained-assets-layout';
+import { sweepRetained } from './retained-assets-sweep';
+
+/**
+ * How long a publish may hold the pod out of readiness. Past it the pod serves without having
+ * published: a stalled bucket must not turn a deploy into one that never finishes.
+ */
+export const RETAIN_PUBLISH_DEADLINE_MS = 30_000;
+
+/** One file a build serves, at the content-addressed URL its documents name. */
+export interface BuildAsset {
+  readonly url: string;
+  readonly contentType: string;
+  /** A `Blob` (`Bun.file`) for a file on disk: a disk refuses one past its ceiling unread. */
+  readonly body: Uint8Array | Blob;
+}
+
+/** The two levels a publish speaks at; `logger` unless a test records them. */
+export interface RetainLog {
+  warn(message: string, fields: Readonly<Record<string, unknown>>): void;
+  error(message: string, fields: Readonly<Record<string, unknown>>): void;
+}
+
+export interface PublishBuildAssetsInput extends RetainedScope {
+  /** As `defineStorage` named it — in every log line, so the operator knows which bucket. */
+  readonly diskName: string;
+  readonly buildId: string;
+  /** `assets.retain.builds`: how many builds' manifests, newest first, the sweep keeps. */
+  readonly builds: number;
+  readonly assets: readonly BuildAsset[];
+  readonly clock?: Clock | undefined;
+  readonly log?: RetainLog | undefined;
+  /** Defaults to `RETAIN_PUBLISH_DEADLINE_MS`. */
+  readonly deadlineMs?: number | undefined;
+}
+
+export interface PublishReport {
+  /** `present`: another pod of this build published it; this one healed and re-dated it. */
+  readonly outcome: 'published' | 'present' | 'failed';
+  readonly put: number;
+  /** URLs over the disk's put ceiling: served by their own build's pods only. */
+  readonly skipped: readonly string[];
+  /** Objects the sweep deleted. */
+  readonly swept: number;
+}
+
+/** A put, list or delete the disk refused during a publish, or its deadline. Logged, not thrown. */
+export class AssetRetainFailedError extends UltimateError {
+  constructor(input: { readonly disk: string; readonly buildId: string; readonly error: unknown }) {
+    super({
+      code: 'X_ASSET_RETAIN_FAILED',
+      cause: `publishing build ${renderCauseValue(input.buildId)} to the retained-asset disk ${renderCauseValue(input.disk)} failed (${renderThrowable(input.error)}) — this pod serves, but a tab holding an earlier build's document may meet a 404 for its stylesheet or island until it reloads`,
+      fix: 'x doctor --json',
+      meta: { disk: input.disk, buildId: input.buildId },
+    });
+  }
+}
+
+/** The deadline's own failure, named so the cause says which limit was hit. */
+class PublishDeadlineError extends UltimateError {
+  constructor(ms: number) {
+    super({
+      code: 'X_ASSET_RETAIN_FAILED',
+      cause: `the publish did not finish within ${String(ms)}ms`,
+      fix: 'x doctor --json',
+    });
+  }
+}
+
+const isTooLarge = (error: unknown): boolean =>
+  isUltimateError(error) && error.code === 'X_STORAGE_TOO_LARGE';
+
+/**
+ * Never throws for the disk and never outlasts its deadline: a failure is one
+ * `X_ASSET_RETAIN_FAILED` line and the pod serves, because a stale tab is a smaller harm than a
+ * deploy that cannot start. A deadline that is not a whole number of at least 1 ms is refused up
+ * front (`X_INVARIANT`): `setTimeout` fires a `NaN` at once. A publish
+ * abandoned at the deadline may still finish in the background; every step of it is idempotent.
+ */
+export async function publishBuildAssets(input: PublishBuildAssetsInput): Promise<PublishReport> {
+  const log = input.log ?? logger;
+  const ms = finiteCount(
+    'publishBuildAssets',
+    'deadlineMs',
+    input.deadlineMs ?? RETAIN_PUBLISH_DEADLINE_MS,
+    1,
+  );
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new PublishDeadlineError(ms)), ms);
+  });
+  try {
+    return await Promise.race([publish(input, log), deadline]);
+  } catch (error) {
+    const failed = new AssetRetainFailedError({
+      disk: input.diskName,
+      buildId: input.buildId,
+      error,
+    });
+    log.error(failed.code, {
+      code: failed.code,
+      cause: failed.cause,
+      fix: failed.fix,
+      disk: input.diskName,
+      buildId: input.buildId,
+    });
+    return { outcome: 'failed', put: 0, skipped: [], swept: 0 };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * The same steps whether or not the build was published before: put each missing file, write the
+ * manifest dated NOW, put back anything a sweep took meanwhile. So a build whose files a bad sweep
+ * removed heals on its next pod, and a rolled-back build — the one live — is the newest manifest.
+ */
+async function publish(input: PublishBuildAssetsInput, log: RetainLog): Promise<PublishReport> {
+  const { disk, prefix, buildId } = input;
+  const present = await disk.exists(manifestKey(prefix, buildId));
+  const skipped: string[] = [];
+  let put = 0;
+  const ensure = async (asset: BuildAsset): Promise<void> => {
+    const key = retainedFileKey(prefix, asset.url);
+    if (await disk.exists(key)) return;
+    try {
+      await disk.put(key, asset.body, { contentType: asset.contentType });
+      put += 1;
+    } catch (error) {
+      if (!isTooLarge(error)) throw error;
+      if (!skipped.includes(asset.url)) skipped.push(asset.url);
+    }
+  };
+  await inBatches(input.assets, ensure);
+  if (skipped.length > 0) {
+    log.warn('assets.retain_skipped', {
+      disk: input.diskName,
+      buildId,
+      urls: [...skipped].sort(),
+      cause: "over the disk's maxPutBytes, so only this build's own pods serve them",
+      fix: 's3Driver({ bucket, maxPutBytes: <bytes> })   # the disk assets.retain.disk names, in its defineStorage; localDriver takes the same option',
+    });
+  }
+  const kept = input.assets.filter((asset) => !skipped.includes(asset.url));
+  const now = (input.clock ?? systemClock).now().getTime();
+  const manifest: BuildManifest = { buildId, publishedAt: now, urls: kept.map((a) => a.url) };
+  await disk.put(manifestKey(prefix, buildId), new TextEncoder().encode(JSON.stringify(manifest)), {
+    contentType: 'application/json',
+  });
+  // A sweep on another pod may have read the manifests before this one existed and deleted a file
+  // this build found present: asked again now that the manifest protects it from the next sweep.
+  await inBatches(kept, ensure);
+  if (present) return { outcome: 'present', put, skipped: [...skipped].sort(), swept: 0 };
+  const swept = await sweepRetained({ disk, prefix }, input.builds, now);
+  return { outcome: 'published', put, skipped: [...skipped].sort(), swept };
+}

package/src/revalidated-response.ts

@@ -4,8 +4,8 @@
 // name that outlives its bytes is a file no client refreshes for a year.
 
 import type { UltimateRequest } from '@ultimat3/http';
+import { notModified } from '@ultimat3/http';
 import { contentHash } from '@ultimat3/render/server';
-import { etagMatches } from './runtime-storage';
 
 /**
  * The document's own posture (`@ultimat3/render`'s `render-static.ts`), for the same reason: the
@@ -32,8 +32,11 @@ export function revalidatedResponse(
     'cache-control': REVALIDATE_CACHE_CONTROL,
     etag,
   };
-  if (etagMatches(request.header('if-none-match'), etag)) {
-    return new Response(null, { status: 304, headers });
-  }
-  return new Response(bytes, { headers });
+  // The length on the 200 only: `compress` reads nothing undeclared, and a 304 has no content.
+  return (
+    notModified(request, etag, headers) ??
+    new Response(bytes, {
+      headers: { ...headers, 'content-length': String(bytes.byteLength) },
+    })
+  );
 }

package/src/role-replicator.ts

@@ -137,7 +137,13 @@ function standBy(replicator: Replicator, key: string): () => void {
       // Voided: both outcomes are handled here, and a timer has nobody to hand a promise to.
       void replicator.start().then(
         (held) => {
-          if (held) logger.info('replicator.slot_taken_over', { key });
+          // Granted after the role stopped: its stop has already run, so nothing else would ever
+          // release this slot — a stopped role would hold it and decode. Given straight back.
+          if (held && cancelled) {
+            void replicator.stop().catch((thrown: unknown) => {
+              logger.warn('replicator.standby_failed', { key, error: renderThrowable(thrown) });
+            });
+          } else if (held) logger.info('replicator.slot_taken_over', { key });
           else if (!cancelled) ask(attempt + 1);
         },
         (thrown: unknown) => {

package/src/role-start-devices.ts

@@ -0,0 +1,119 @@
+// The device sockets one process hosts: every declared `deviceSocket()` attached to its bus, and —
+// on the web role — one listener mount per path that resolves the declaration PER UPGRADE. A
+// container's declarations never change; `x dev`'s rescan re-declares a saved path in a new
+// generation, and `refresh()` attaches that value and drains the one it replaced.
+
+import type { Role } from '@ultimat3/core';
+import type {
+  DeviceAttachment,
+  DeviceSocket,
+  DeviceUpgradeTarget,
+  DeviceWs,
+  Transport,
+} from '@ultimat3/realtime/server';
+import { declaredDeviceSockets } from '@ultimat3/realtime/server';
+
+/** What the listener is handed: a declaration's own mount shape, so `httpServer` takes it as one. */
+export type DeviceMount = Pick<DeviceSocket, 'path' | 'fetch' | 'websocket'>;
+
+export interface DeviceHosting {
+  /** One per path declared at boot; empty without the web role, which is where devices dial. */
+  readonly mounts: readonly DeviceMount[];
+  /**
+   * After a rescan: each re-declared path's new value attached, the old one's sockets told to
+   * reconnect and closed, its attachment stopped. Answers the declared paths the listener does not
+   * serve — added after it bound, which only a new process can open.
+   */
+  refresh(): Promise<readonly string[]>;
+  /** Every attachment stopped, newest first. */
+  stop(): Promise<void>;
+}
+
+interface Held {
+  readonly link: DeviceSocket;
+  readonly attachment: DeviceAttachment;
+}
+
+/**
+ * The listener's door for one path. The upgrade is answered by the path's CURRENT declaration, and
+ * each socket's events go back to the declaration that upgraded it — keyed by the `data` it handed
+ * `server.upgrade`, `joinWebSocketMounts`'s rule — so a socket opened before a reload is closed by
+ * the host that holds it, never handed to one that does not.
+ */
+function pathMount(path: string, current: () => DeviceSocket): DeviceMount {
+  const owners = new WeakMap<object, DeviceSocket>();
+  const ownerOf = (ws: DeviceWs): DeviceSocket | undefined => owners.get(ws.data);
+  // Bun's per-listener limits are fixed when it binds; the framework's frame limit is a constant.
+  const { maxPayloadLength, idleTimeout } = current().websocket;
+  return {
+    path,
+    fetch(request, server) {
+      const link = current();
+      const recording: DeviceUpgradeTarget = {
+        upgrade(upgraded, options) {
+          owners.set(options.data, link);
+          return server.upgrade(upgraded, options);
+        },
+        requestIP: (asked) => server.requestIP(asked),
+      };
+      return link.fetch(request, recording);
+    },
+    websocket: {
+      open: (ws) => ownerOf(ws)?.websocket.open(ws),
+      message: (ws, message) => ownerOf(ws)?.websocket.message(ws, message),
+      close: (ws) => ownerOf(ws)?.websocket.close(ws),
+      maxPayloadLength,
+      idleTimeout,
+    },
+  };
+}
+
+export async function hostDeviceSockets(
+  transport: Transport,
+  roles: readonly Role[],
+): Promise<DeviceHosting> {
+  const serve = roles.includes('web');
+  const held = new Map<string, Held>();
+  const attach = async (link: DeviceSocket): Promise<Held> => ({
+    link,
+    attachment: await link.attach({ transport, serve }),
+  });
+  const stopAll = (): void => {
+    for (const entry of [...held.values()].reverse()) entry.attachment.stop();
+  };
+  try {
+    for (const link of declaredDeviceSockets()) held.set(link.path, await attach(link));
+  } catch (error) {
+    stopAll();
+    throw error;
+  }
+  const served = serve ? [...held.keys()] : [];
+  // `held` replaces a served path's entry and never drops one; the boot's is the type's fallback.
+  const mounts = serve
+    ? [...held].map(([path, boot]) => pathMount(path, () => (held.get(path) ?? boot).link))
+    : [];
+  return {
+    mounts,
+    async refresh() {
+      for (const link of declaredDeviceSockets()) {
+        const was = held.get(link.path);
+        if (was?.link === link) continue;
+        // The new value takes the door BEFORE the old one sheds its sockets, so a device that
+        // redials on the drain's `reconnect` frame reaches the edited handler.
+        held.set(link.path, await attach(link));
+        if (was === undefined) continue;
+        // No spread and no grace: one developer's devices, and the save is waiting on it.
+        await was.attachment.drain({ graceMs: 0, spreadMs: 0 });
+        was.attachment.stop();
+      }
+      return serve
+        ? declaredDeviceSockets()
+            .map((link) => link.path)
+            .filter((path) => !served.includes(path))
+        : [];
+    },
+    async stop() {
+      stopAll();
+    },
+  };
+}

package/src/role-start-types.ts

@@ -108,5 +108,11 @@ export interface RunningRoles {
   readonly liveBridge: LiveReplicator | null;
   /** The sync node's registry, so a test can hold a real subscription; null without the role. */
   readonly liveRegistry: LiveQueryRegistry | null;
+  /**
+   * `x dev`'s rescan seam (`dev-rebuild.ts`): every `deviceSocket()` a save re-declared attached
+   * and served in place of the old one, whose sockets are told to redial. Answers the declared
+   * paths this listener cannot serve — added after it bound. A container never calls it.
+   */
+  refreshDevices(): Promise<readonly string[]>;
   stop(): Promise<void>;
 }

package/src/role-start.ts

@@ -38,6 +38,7 @@ import {
 } from './metrics-endpoint';
 import { rolesUnderRealtime } from './role-realtime';
 import { startReplicator } from './role-replicator';
+import { type DeviceMount, hostDeviceSockets } from './role-start-devices';
 import type { RunningRoles, StartRolesOptions } from './role-start-types';
 import { DEV_ROLES } from './role-start-types';
 import { prepareSync, type RunningSync, syncReadsChanges } from './role-sync';
@@ -160,9 +161,17 @@ function rateLimitStoreFor(options: StartRolesOptions): RateLimitStore | undefin
   return supplied;
 }
 
-/** `mount` is the sync node's socket, served on THIS port as well as its own — why, in `role-sync`.
- * Undefined without the `sync` role, and then this server opens no websocket, as it always did. */
-function startWeb(options: StartRolesOptions, mount?: WebSocketMount<SyncWs>): ServerHandle {
+/**
+ * `mount` is the sync node's socket, served on THIS port as well as its own — why, in `role-sync`;
+ * undefined without the `sync` role. Beside it, a door per declared `deviceSocket()` path: this
+ * listener is where a device dials, and `hostDeviceSockets` made this process their host before it
+ * binds. Neither, and this server opens no websocket, as it always did.
+ */
+function startWeb(
+  options: StartRolesOptions,
+  devices: readonly DeviceMount[],
+  mount?: WebSocketMount<SyncWs>,
+): ServerHandle {
   warnIfUnauthenticatable(options.routes);
   const binding = options.http ?? DEV_BINDING;
   const hops = trustedHopsFromEnv(options.env);
@@ -170,7 +179,7 @@ function startWeb(options: StartRolesOptions, mount?: WebSocketMount<SyncWs>): S
   return httpServer({
     routes: options.routes,
     role: 'web',
-    ...(mount === undefined ? {} : { websocket: mount }),
+    websocket: [...(mount === undefined ? [] : [mount]), ...devices],
     ...(options.drain === undefined ? {} : { drain: options.drain }),
     hooks: devHooks({
       ...(options.devNotices === undefined ? {} : { devNotices: options.devNotices }),
@@ -288,12 +297,18 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
         // `x dev` is one process running several roles: its `process_info` says which.
         role: selected.join('+'),
         whenTaken: whenMetricsPortTaken(binding.dev, options.env),
+        dev: binding.dev,
         reserved: rolePorts(options.port, selected),
       });
     started.push(async () => metrics.stop());
     // Opened here or adopted from `serve-boot.ts`, this is where the build id is known (#734).
     metrics.announceBuild(options.buildId);
 
+    // Every declared `deviceSocket()` on this process's bus, before any role serves: a job or an
+    // action anywhere may `request()` a device, and the web role holds their sockets.
+    const devices = await hostDeviceSockets(options.runtime.transport, selected);
+    started.push(() => devices.stop());
+
     // BUILT here, BOUND below, the web role between them: `web` serves the node's socket on its
     // own port and a listening server cannot be handed one, while the neighbouring-port refusals
     // are only the right answer once the web port's own has been given.
@@ -305,7 +320,7 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
     let releaseSync = prepared?.stop ?? null;
     let server: ServerHandle | null;
     try {
-      server = selected.includes('web') ? startWeb(options, prepared?.mount) : null;
+      server = selected.includes('web') ? startWeb(options, devices.mounts, prepared?.mount) : null;
     } catch (error) {
       await releaseSync?.().catch(() => undefined);
       throw error;
@@ -323,6 +338,7 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
     const worker = selected.includes('worker')
       ? jobWorker({
           driver: options.runtime.jobs,
+          build: options.buildId,
           context: () => ctxOf({ role: 'worker', buildId: options.buildId }),
           ...workerOptionsFor(options.runtime.workerConfig),
         })
@@ -415,6 +431,7 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
       liveFeed: live.feed,
       liveBridge: live.bridge,
       liveRegistry: sync?.registry ?? null,
+      refreshDevices: () => devices.refresh(),
       async stop() {
         // `started` IS the stop list, in boot order: released newest first — the live feed, the
         // replicator (so the slot is released before the bus it published to closes), the

package/src/role-sync.ts

@@ -310,7 +310,7 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
     },
     listen: async (appUrl) => {
       origins.push(...devOrigins(options, origins, appUrl));
-      return await listen(options, node, { registry, hub }, appUrl);
+      return await listen(options, node, { registry, hub }, appUrl, stopWaiting);
     },
   };
 }
@@ -335,6 +335,8 @@ async function listen(
   node: SyncNode,
   feeds: Pick<RunningSync, 'registry' | 'hub'>,
   appUrl: string | null,
+  /** `startOrWaitForBus`'s cancel: a node stopped while it waits must not start on a reconnect. */
+  stopWaiting: () => void,
 ): Promise<RunningSync> {
   const port = syncPortFor(options.port);
   try {
@@ -365,11 +367,15 @@ async function listen(
       url: listener.url,
       ...feeds,
       stop: async () => {
+        // First, as `prepareSync`'s own stop does: the bus's reconnect subscription otherwise
+        // outlived the node and called `node.start()` on it after this stop returned.
+        stopWaiting();
         listener.stop();
         await node.stop();
       },
     };
   } catch (error) {
+    stopWaiting();
     await node.stop();
     const refusal = await syncBindRefusal(options.port, port);
     if (refusal !== undefined) throw refusal;

package/src/route-islands.ts

@@ -7,6 +7,7 @@ import { posix } from 'node:path';
 import type { IslandCollector, RouteEntry } from '@ultimat3/render';
 import {
   clientBootTags,
+  hydrateRuntime,
   islandCollector,
   islandModuleId,
   islandModuleIds,
@@ -71,3 +72,44 @@ export function bootScript(
   });
   return reaches ? renderHead(clientBootTags(options.sync)) : '';
 }
+
+/** A stream document's boot and hydration scripts: its first flush's, and each hole chunk's. */
+export interface StreamScripts {
+  readonly first: string;
+  /** For a hole's chunk, after its reveal: `''` while nothing it shows can hold an island. */
+  readonly after: (outcome: 'filled' | 'failed') => string;
+}
+
+/**
+ * An inline module waits for parsing to end, and a document with a hole open is still parsing, so
+ * the runtime is `async` while nothing has to run before it. Once a boot is in the document it stays
+ * deferred: the boot must run first (`bootScript`), at the cost a Known-Gaps row states.
+ *
+ * `after` re-runs the whole runtime once any hole recorded an island, rather than comparing against
+ * what the last chunk took: holes record while running and reveal in completion order, so an island
+ * recorded by a hole still open would otherwise be spent on another hole's chunk, before its root is
+ * in the DOM. `each` visits a root once, so an extra run does nothing; every body is already hashed.
+ * A FAILED hole shows its `error` markup, walked at shell time — so counted in `flushed` — yet not in
+ * the DOM until this chunk: it re-runs whenever the page recorded any island at all.
+ */
+export function streamScripts(
+  entry: RouteEntry,
+  islands: IslandCollector,
+  options: DocumentOptions,
+  scope: string | undefined,
+  holes: boolean,
+): StreamScripts {
+  const boot = bootScript(entry, islands, options, scope);
+  const flushed = islands.directives.length;
+  let booted = boot !== '';
+  return {
+    first: `${boot}${hydrateRuntime(islands.directives, { async: holes && !booted })}`,
+    after: (outcome) => {
+      const recorded = islands.directives.length;
+      if (recorded === (outcome === 'failed' ? 0 : flushed)) return '';
+      const late = booted ? '' : bootScript(entry, islands, options, scope);
+      booted = booted || late !== '';
+      return `${late}${hydrateRuntime(islands.directives, { async: !booted })}`;
+    },
+  };
+}

package/src/route-table.ts

@@ -8,6 +8,7 @@ import { describePages } from '@ultimat3/render';
 import { apiRoutes } from './api-routes';
 import { loadAppRuntime } from './app-runtime';
 import type { JsonValue } from './output';
+import { plainRoutes } from './plain-routes';
 
 /** One printed and one JSON row per served route: a page, a mounted page, or an API route. */
 export interface RouteRow {
@@ -94,7 +95,7 @@ export function routeRows(plain: readonly Route[] = []): readonly RouteRow[] {
  * 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 ?? [];
+  return plainRoutes((await loadAppRuntime(root))?.routes);
 }
 
 /** Fixed-width columns so the output diffs cleanly between runs and between machines. */

package/src/row-security-boot.ts

@@ -0,0 +1,58 @@
+// Single responsibility: arming the database's tenant guard for a booted role. With
+// `database.rowSecurity` on, the serving role must be one Postgres applies policies to
+// (`X_DB_ROW_SECURITY_BYPASSED` otherwise), every BEGIN carries the actor's tenant, and a bare
+// statement is wrapped in a transaction that does. Off, nothing here runs.
+
+import type { AppConfig } from '@ultimat3/core';
+import {
+  assertRowSecurityBinds,
+  db,
+  holdMigratorRole,
+  raw,
+  rowSecureClient,
+  serveAsAppRole,
+  setDbClient,
+  setTransactionSettings,
+} from '@ultimat3/db';
+import { rowSecuritySettings } from '@ultimat3/entity';
+import { loadAppConfig } from './app-config-load';
+
+/** `database.rowSecurity` on a loaded config; no `app.config.ts` at all is off. */
+export function rowSecurityDeclared(config: AppConfig | undefined): boolean {
+  return config?.database.rowSecurity === true;
+}
+
+/**
+ * Judge the role on the ambient client, then install the seam and the wrapper. Judged FIRST: a boot
+ * refused here installs nothing, so a test that catches the refusal leaves the process as it was.
+ * `embedded` is PGlite, whose one session is a superuser and whose roles are ours: it switches to
+ * `x_app` before the judgement (`serveAsAppRole`). An external database's roles are the operator's
+ * and are only ever judged. Returns the undo, which `stop()` runs so a second boot starts clean.
+ */
+export async function armRowSecurity(
+  enabled: boolean,
+  options: { readonly embedded?: boolean } = {},
+): Promise<() => Promise<void>> {
+  if (!enabled) return async () => undefined;
+  const ambient = db();
+  if (options.embedded === true) await serveAsAppRole(ambient);
+  await assertRowSecurityBinds(ambient);
+  setTransactionSettings(rowSecuritySettings);
+  setDbClient(rowSecureClient(ambient));
+  return async () => {
+    setTransactionSettings(undefined);
+    setDbClient(ambient);
+    if (options.embedded === true) await ambient.execute(raw('reset role'));
+  };
+}
+
+/**
+ * The migrate step on PGlite, whose roles are ours — never called for an external database, whose
+ * migrator is the operator's `DATABASE_URL`. With the flag on, the app's migrations run as
+ * `x_migrator`, so it owns what they create and `x_app`, what `x dev` serves as, owns nothing.
+ * Off, nothing runs. Returns the undo.
+ */
+export async function migrateAsMigrator(root: string): Promise<() => Promise<void>> {
+  if (!rowSecurityDeclared(await loadAppConfig(root))) return async () => undefined;
+  return holdMigratorRole(db());
+}

package/src/row-security-wanted.ts

@@ -0,0 +1,32 @@
+// Single responsibility: what `x db gen` and the gate's `drift` step read about row security — the
+// app's `database.rowSecurity` and each tenant table's column — and the drift step's verdict on it.
+// One reader for both, so the gate can never expect a policy the generator would not write.
+
+import type { EntityDescriptionLike, RowSecurityOption, SchemaDescription } from '@ultimat3/db';
+import { rowSecurityDifferences, rowSecurityDrift } from '@ultimat3/db';
+import { describeTenancy } from '@ultimat3/entity';
+import { loadAppConfig } from './app-config-load';
+import { MIGRATIONS_DIR } from './migrations';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+import { rowSecurityDeclared } from './row-security-boot';
+
+/** The app's answer, read after `loadApp` filled the registry. Injected for tests. */
+export type RowSecurityWanted = (root: string) => Promise<RowSecurityOption>;
+
+export const appRowSecurity: RowSecurityWanted = async (root) => ({
+  enabled: rowSecurityDeclared(await loadAppConfig(root)),
+  tenants: describeTenancy(),
+});
+
+/** One `X_DB_ROW_SECURITY_DRIFT` per tenant table the flag and the newest snapshot disagree on. */
+export function rowSecurityFindings(
+  entities: readonly EntityDescriptionLike[],
+  recorded: SchemaDescription,
+  option: RowSecurityOption,
+): readonly Finding[] {
+  return rowSecurityDifferences(entities, recorded, option).map((difference) => ({
+    ...findingFrom(rowSecurityDrift(difference)),
+    at: MIGRATIONS_DIR,
+  }));
+}

package/src/runtime-admin.ts

@@ -44,7 +44,6 @@ const entryFor = (route: AdminRouteConfig, body: unknown): RouteEntry => ({
   // An admin screen is behind sign-in: it carries the `app/` surface's stylesheet, never `site/`'s.
   surface: 'app',
   config: route.config,
-  suspenseBoundaries: 0,
   islands: [],
   pattern: compilePattern(route.path),
   component: () => body,