@ultimat3/cli 22.15.0 → 24.0.0

package/src/registry.ts

@@ -7,6 +7,7 @@
 // dev server it never started (plan 101 slice 12 d).
 
 import { affectedSpec } from './cmd-affected-spec';
+import { authSpec } from './cmd-auth-spec';
 import { buildSpec } from './cmd-build-spec';
 import { ciSpec } from './cmd-ci-spec';
 import { dbSpec } from './cmd-db-spec';
@@ -85,6 +86,7 @@ export const LAZY_COMMANDS: readonly LazyCommand[] = [
   lazy(deploySpec, async () => (await import('./cmd-deploy')).deployCommand),
   lazy(envSpec, async () => (await import('./cmd-env')).envCommand),
   lazy(secretsSpec, async () => (await import('./cmd-secrets')).secretsCommand),
+  lazy(authSpec, async () => (await import('./cmd-auth')).authCommand),
   lazy(manifestSpec, async () => (await import('./cmd-manifest')).manifestCommand),
   lazy(routesSpec, async () => (await import('./cmd-routes')).routesCommand),
   lazy(actionsSpec, async () => (await import('./cmd-registries')).actionsCommand),

package/src/revalidated-response.ts

@@ -4,6 +4,7 @@
 // name that outlives its bytes is a file no client refreshes for a year.
 
 import type { UltimateRequest } from '@ultimat3/http';
+import { contentHash } from '@ultimat3/render/server';
 import { etagMatches } from './runtime-storage';
 
 /**
@@ -14,8 +15,8 @@ import { etagMatches } from './runtime-storage';
 export const REVALIDATE_CACHE_CONTROL = 'public, max-age=0, must-revalidate';
 
 /**
- * A strong validator from the bytes — xxHash32, the function `contentHash` applies to a document,
- * taken here over bytes because an icon is not a string. Revalidating costs a request and no body.
+ * A strong validator from the bytes — `@ultimat3/render`'s `contentHash`, the function a document's
+ * ETag is, taken here over bytes because an icon is not a string. Revalidating costs a request and no body.
  */
 export function revalidatedResponse(
   request: UltimateRequest,
@@ -25,7 +26,7 @@ export function revalidatedResponse(
   // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
   // `SharedArrayBuffer`, which `Response` does not accept — `runtime-assets.ts`'s rule, verbatim.
   const bytes = typeof body === 'string' ? new TextEncoder().encode(body) : new Uint8Array(body);
-  const etag = `"${Bun.hash.xxHash32(bytes).toString(16).padStart(8, '0')}"`;
+  const etag = `"${contentHash(bytes)}"`;
   const headers = {
     'content-type': contentType,
     'cache-control': REVALIDATE_CACHE_CONTROL,

package/src/role-load.ts

@@ -0,0 +1,143 @@
+// What a container role imports of the app. `web`, `sync` and `replicator` answer for registries a
+// request, a subscription or the WAL names — routes, queries, entities — so they import every
+// module. `worker` and `scheduler` run jobs and tasks: they import the API index and every module
+// that brings no document (a component, a stylesheet) with it, and nothing else.
+
+// why: Bun ships no path API; the API index is named app-root-relative and imported absolute.
+import { join, resolve } from 'node:path';
+import type { Role } from '@ultimat3/core';
+import { isJsonObject, logger, UltimateError } from '@ultimat3/core';
+import { registeredJobs, registeredTasks } from '@ultimat3/jobs';
+import type { AppScan } from './app-load';
+import { scanAppModules } from './app-load';
+import { API_INDEX } from './app-root';
+import { createDocumentGraph } from './document-graph';
+
+/** `everything`: the scan every tool runs. `background`: no document a job does not import. */
+export type RoleLoad = 'everything' | 'background';
+
+/**
+ * Typed over `Role`, so a seventh role does not compile until somebody decides what it imports.
+ * `migrate` never reaches a load — `runMigrations` reads SQL files — and says `everything` so a
+ * caller that boots it by hand is given the whole app rather than a guess.
+ */
+const DECLARED: Readonly<Record<Role, RoleLoad>> = {
+  web: 'everything',
+  // A subscription names a live query, and a page module may export one.
+  sync: 'everything',
+  // The slot decodes every table an entity declares, wherever the entity is declared.
+  replicator: 'everything',
+  worker: 'background',
+  scheduler: 'background',
+  migrate: 'everything',
+};
+
+/** A `Map`, so the read below is an own-key lookup — never a member of `Object.prototype`. */
+export const ROLE_LOADS: ReadonlyMap<Role, RoleLoad> = new Map(
+  Object.entries(DECLARED) as [Role, RoleLoad][],
+);
+
+/** What `role` imports. A value that is no role — an untyped caller's — is given everything. */
+export const roleLoadFor = (role: Role): RoleLoad => ROLE_LOADS.get(role) ?? 'everything';
+
+/** The file the gate holds fresh (`manifest` step) and every image carries beside the source. */
+const MANIFEST_FILE = 'x.manifest.json';
+
+/**
+ * A background load that left out a job or task the committed manifest names. Logged, never
+ * thrown: the boot answers it by importing the rest of the app, so the role runs everything it
+ * ran before — it only pays for the documents this load exists to leave out.
+ */
+export class RoleLoadIncompleteError extends UltimateError {
+  constructor(input: { role: Role; missing: readonly string[] }) {
+    super({
+      code: 'X_ROLE_LOAD_INCOMPLETE',
+      cause: `the ${input.role} role imported ${API_INDEX} and every module that reaches no component or stylesheet, and ${MANIFEST_FILE} names ${String(input.missing.length)} job(s) or task(s) that load did not register (${input.missing.join(', ')}), so the whole app was imported instead`,
+      fix: `add import * as <module> from the file that declares it and <module> to jobs: [...] or tasks: [...] in ${API_INDEX}, then x manifest`,
+      meta: { role: input.role, missing: input.missing },
+    });
+  }
+}
+
+/** `name` of every entry of one manifest list — `[]` for a list that is absent or malformed. */
+function namesIn(manifest: Record<string, unknown>, key: 'jobs' | 'tasks'): readonly string[] {
+  const list = manifest[key];
+  if (!Array.isArray(list)) return [];
+  return list.flatMap((entry: unknown) =>
+    isJsonObject(entry) && typeof entry['name'] === 'string' ? [entry['name']] : [],
+  );
+}
+
+/**
+ * Every job and task the committed manifest names that this process has not registered —
+ * `undefined` when there is no manifest to check against, which is not the same answer as "none".
+ */
+export async function unregisteredFromManifest(
+  root: string,
+): Promise<readonly string[] | undefined> {
+  const parsed: unknown = await Bun.file(join(root, MANIFEST_FILE))
+    .json()
+    .catch(() => undefined);
+  if (!isJsonObject(parsed)) return undefined;
+  const jobs = new Set(registeredJobs().map((job) => job.name));
+  const tasks = new Set(registeredTasks().map((task) => task.name));
+  return [
+    ...namesIn(parsed, 'jobs').filter((name) => !jobs.has(name)),
+    ...namesIn(parsed, 'tasks').filter((name) => !tasks.has(name)),
+  ].sort();
+}
+
+/**
+ * The background scan alone, with no proof and no fallback: the API index and every module that
+ * brings no document. What a worker imports when nothing is wrong — and what the gate imports in a
+ * child to compare against the whole app (`verify-role-load.ts`).
+ */
+export async function scanBackground(root: string): Promise<AppScan> {
+  const index = resolve(root, API_INDEX);
+  // why `require.cache`: Bun 1.4 lists every evaluated ES module there, by absolute path — the
+  // same table `app-reload-graph.ts` evicts from.
+  const loaded = (absolute: string): boolean => absolute in require.cache;
+  const graph = createDocumentGraph(loaded);
+  return scanAppModules(root, {
+    track: false,
+    // The index first (`appModulePaths` leads with it): what it imports is what the app runs.
+    // Then every module already here, and every one that brings no document with it — a service,
+    // a catalog, a storage declaration registers on import and no job names it.
+    include: async (absolute) =>
+      absolute === index || loaded(absolute) || !(await graph.reachesDocument(absolute)),
+  });
+}
+
+/**
+ * The background load, then the proof it was enough. A job runs by NAME — the queue row carries
+ * it — so the one thing this load must not do is leave a named job unregistered. The gate already
+ * requires every job and task to be named from a `defineApi()` call (`X_JOB_UNREGISTERED`); the
+ * manifest is the list that call produced, and a name it holds that this load did not register is
+ * answered by importing everything, loudly.
+ */
+async function loadBackground(root: string, role: Role): Promise<AppScan> {
+  const scan = await scanBackground(root);
+  const missing = await unregisteredFromManifest(root);
+  if (missing !== undefined && missing.length === 0) return scan;
+  if (missing === undefined) {
+    logger.warn('ultimate role load unverified', {
+      role,
+      cause: `${MANIFEST_FILE} is absent or unreadable, so nothing names the jobs this role must run and the whole app was imported`,
+      fix: 'x manifest',
+    });
+  } else {
+    const error = new RoleLoadIncompleteError({ role, missing });
+    logger.error(error.format(), { code: error.code, role, missing });
+  }
+  return scanAppModules(root, { track: false });
+}
+
+/**
+ * What `serve-boot.ts` calls instead of `loadApp`: the scan a role needs and none of what a tool
+ * reads from it afterwards — no reload graph, no error-code walk of the app's source.
+ */
+export async function loadAppForRole(root: string, role: Role): Promise<AppScan> {
+  return roleLoadFor(role) === 'background'
+    ? loadBackground(root, role)
+    : scanAppModules(root, { track: false });
+}

package/src/role-replicator.ts

@@ -3,6 +3,7 @@
 // a `ROLE=replicator` container starts; the only difference is that this process also runs the
 // roles reading the other end of that transport.
 
+import { registerReadinessCheck } from '@ultimat3/core';
 import { describeEntities } from '@ultimat3/entity';
 import { ReplicatorSlotHeldError } from '@ultimat3/realtime';
 import type { Replicator, Transport } from '@ultimat3/realtime/server';
@@ -72,6 +73,18 @@ const noEntitiesRefusal = (): BadFlagError =>
     fix: 'x g entity Post title:text — then x dev --role replicator',
   });
 
+/** The name `/readyz` reports the replicator under. */
+export const REPLICATOR_READINESS_CHECK = 'replicator';
+
+/**
+ * Ready means REPLICATING. A stream that ends is restarted by the replicator itself, and until it
+ * is back `running` is `false`: this process holds no slot and publishes nothing, so it must not be
+ * counted as the database's replicator. Returns the unregister.
+ */
+export function watchReplicatorReadiness(replicator: Pick<Replicator, 'running'>): () => void {
+  return registerReadinessCheck(REPLICATOR_READINESS_CHECK, () => replicator.running);
+}
+
 /**
  * Lock first, feed second. A replicator that opened its slot before losing the lock race would
  * have already consumed WAL the holder is responsible for, and `pg_try_advisory_lock` is the only
@@ -95,11 +108,14 @@ export async function startReplicator(options: StartReplicatorOptions): Promise<
   if (!(await replicator.start())) {
     throw new ReplicatorSlotHeldError({ key: replicatorLockKey(slot) });
   }
+  const unregister = watchReplicatorReadiness(replicator);
   return {
     replicator,
     slot,
     detail: selection.detail,
     async stop() {
+      // First: a replicator being stopped on purpose is not a failing one.
+      unregister();
       await replicator.stop();
     },
   };

package/src/role-start.ts

@@ -7,7 +7,7 @@
 // something every `x dev` in a team should do to the same server by simply starting.
 
 import type { Role } from '@ultimat3/core';
-import { createContext, isRole, logger, ROLES } from '@ultimat3/core';
+import { createContext, isRole, logger, markReady, ROLES } from '@ultimat3/core';
 import type { RateLimitStore, Route, ServerHandle, WebSocketMount } from '@ultimat3/http';
 import {
   configuredAuthenticator,
@@ -28,13 +28,18 @@ import {
 } from '@ultimat3/jobs';
 import type { SyncWs } from '@ultimat3/realtime/server';
 import { errorPageHook } from './error-pages';
-import { BadFlagError, PortInvalidError, RuntimeDriverSplitError } from './errors';
-import { DEFAULT_METRICS_PORT, startMetricsEndpoint } from './metrics-endpoint';
+import { BadFlagError, RuntimeDriverSplitError } from './errors';
+import {
+  DEFAULT_METRICS_PORT,
+  startMetricsEndpoint,
+  whenMetricsPortTaken,
+} from './metrics-endpoint';
 import { rolesUnderRealtime } from './role-realtime';
 import { startReplicator } from './role-replicator';
 import type { RunningRoles, StartRolesOptions } from './role-start-types';
 import { DEV_ROLES } from './role-start-types';
 import { prepareSync, type RunningSync } from './role-sync';
+import { startWorkerWake } from './role-wake';
 import type { Env } from './runtime-bindings';
 import { devHooks } from './runtime-hooks';
 import { workerOptionsFor } from './runtime-jobs';
@@ -44,6 +49,7 @@ import type { RunningServices } from './runtime-services';
 import { inlineScriptSources } from './script-csp';
 import { inlineStyleSources } from './style-csp';
 import { syncConnectSources } from './sync-url';
+import { TrustedProxyHopsInvalidError } from './trusted-hops-error';
 import { DEV_BINDING } from './web-binding';
 
 // Declared beside the option types so `x dev`'s spec reads it without loading this module.
@@ -155,8 +161,8 @@ export function trustedHopsFromEnv(env: Env): number | null {
   const hops = Number(raw);
   // A malformed count is refused rather than defaulted: reading the header at the wrong index is
   // trusting a value the client typed, which is the failure trusting a proxy exists to avoid.
-  if (!Number.isInteger(hops) || hops < 1 || hops > MAX_PROXY_HOPS) {
-    throw new PortInvalidError({ value: raw, name: 'TRUSTED_PROXY_HOPS' });
+  if (!/^\d+$/.test(raw) || !Number.isInteger(hops) || hops < 1 || hops > MAX_PROXY_HOPS) {
+    throw new TrustedProxyHopsInvalidError({ value: raw });
   }
   return hops;
 }
@@ -304,6 +310,9 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
       startMetricsEndpoint({
         port: options.metricsPort ?? (options.port === 0 ? 0 : DEFAULT_METRICS_PORT),
         hostname: binding.hostname,
+        // `x dev` is one process running several roles: its `process_info` says which.
+        role: selected.join('+'),
+        whenTaken: whenMetricsPortTaken(binding.dev, options.env),
       });
     started.push(async () => metrics.stop());
 
@@ -350,6 +359,13 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
     // one hands the failure rollback the same window a dropped `await` gives the teardown below.
     if (relay !== null) started.push(() => relay.stop());
 
+    // The cross-process wake: one LISTEN session, so a job another pod committed starts now
+    // instead of at the next poll. On `worker` alone — it is the role whose two loops (the claim
+    // and the relay above) hear it; a web or scheduler pod holding a session would pin a
+    // connection per replica to wake nothing (`role-wake.ts`).
+    const wake = selected.includes('worker') ? startWorkerWake(options.runtime.db) : null;
+    if (wake !== null) started.push(() => wake.stop());
+
     // `state` and `leader`, not the defaults. `createMemorySchedulerState` forgets every watermark
     // on restart, so a rolling deploy re-fires or skips whatever was due across it, and
     // `soleLeader()` makes every replica the leader — three `scheduler` pods, three of every task.
@@ -391,6 +407,10 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
       replicatorHere: replicator !== null,
     });
     started.push(async () => live.stop());
+    // The web server and the sync node mark ready when they bind; a process with neither — a
+    // worker, scheduler or replicator pod — is ready once its roles started, which is what the
+    // scrape port's `/readyz` answers (`metrics-endpoint.ts`). The checks still decide after this.
+    if (server === null && sync === null) markReady();
 
     return {
       roles: selected,
@@ -413,6 +433,8 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
         // and AWAITED, because a pass is a `driver.enqueue` followed by a `markPublished`. Dropped,
         // this returns between the two and the lines below close the pool under the row it was
         // about to mark: re-published next boot at best, a rejection against a closed pool at worst.
+        // The session first: a notification arriving after this wakes a loop that is about to stop.
+        await wake?.stop();
         await relay?.stop();
         await worker?.stop('x dev stopped');
         await sync?.stop();

package/src/role-sync.ts

@@ -3,7 +3,7 @@
 // and a listener of its own — and because that file is the boot's index, not its detail.
 
 import { createContext, logger, UltimateError } from '@ultimat3/core';
-import type { WebSocketMount } from '@ultimat3/http';
+import { configuredHttp, type WebSocketMount } from '@ultimat3/http';
 import { listQueries } from '@ultimat3/query';
 import type { SyncNode, SyncWs } from '@ultimat3/realtime/server';
 import {
@@ -120,7 +120,8 @@ export interface PreparedSync {
   readonly mount: WebSocketMount<SyncWs>;
   /**
    * Bind `PORT + 1`, and answer with the same object `startSync` always did. `appUrl` is the web
-   * role's own origin when one runs here, for the line below that names both doors.
+   * role's own origin when one runs here: named in the boot line beside the node's, and — under
+   * `x dev` with an `APP_URL` declared — admitted as a page origin (`devOrigins`).
    */
   listen(appUrl: string | null): Promise<RunningSync>;
   /** Release the node when nothing ever bound it — a `web` role that threw after it was built. */
@@ -176,6 +177,35 @@ export function registerLiveQueries(options: StartRolesOptions): LiveQueryRegist
   return registry;
 }
 
+const healthDetailPeersOf = (
+  peers: readonly string[] | undefined,
+): { readonly healthDetailPeers?: readonly string[] } =>
+  peers === undefined ? {} : { healthDetailPeers: peers };
+
+/**
+ * What `x dev` adds to a DECLARED list: the origin its own web role is serving pages on, under
+ * each loopback spelling a browser may have been pointed at. A declaration is the whole list, and
+ * the scaffold's `.env` declares `APP_URL=http://localhost:3000` — so `x dev --port 4000`, or dev
+ * opened as `127.0.0.1`, was a page on an origin nothing named and every socket was refused.
+ *
+ * Nothing is added to an EMPTY list: an undeclared node admits the origin it was reached on, which
+ * already covers these and a forwarded host besides — and one entry would end that rule. Nothing
+ * is added outside dev either: in a container the declaration is the operator's, and a wrong one
+ * must refuse rather than be papered over by whatever address the process bound.
+ */
+function devOrigins(
+  options: StartRolesOptions,
+  declared: readonly string[],
+  appUrl: string | null,
+): string[] {
+  if (!(options.http ?? DEV_BINDING).dev || appUrl === null || declared.length === 0) return [];
+  const own = new URL(appUrl);
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].map(
+    (host) => `${own.protocol}//${host}:${own.port}`,
+  );
+  return [own.origin, ...loopback].filter((origin) => !declared.includes(origin));
+}
+
 /**
  * The node itself: its hub, its registry, its authenticator and its change subscription. Nothing
  * bound — `listen()` and the `web` role's mount are the two doors, and this is what is behind both.
@@ -195,6 +225,7 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
   // `exp`), or resolves identity from a header the adapter deliberately does not retain.
   const authenticate = options.overrides?.syncAuthenticate ?? syncAuthenticator(options.buildId);
   const registry = registerLiveQueries(options);
+  const origins = syncOriginsFrom(options.env);
   const node = createSyncNode({
     hub,
     registry,
@@ -202,9 +233,17 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
     buildId: options.buildId,
     sockets,
     ...(authenticate === undefined ? {} : { authenticate }),
-    // The page's origin when it is served on another host than this node; the node's own host is
-    // admitted without it. Anything else is refused before `authenticate` (X_SOCKET_ORIGIN_REFUSED).
-    allowedOrigins: syncOriginsFrom(options.env),
+    // `APP_URL`'s origin, and when one is declared it is the WHOLE list: the origin this node was
+    // reached on is no longer admitted beside it. Undeclared, that origin (and its https spelling
+    // when TLS ended at a proxy) is what is admitted; anything else is refused before
+    // `authenticate` (X_SOCKET_ORIGIN_REFUSED). Held by reference: `listen` adds `x dev`'s own.
+    allowedOrigins: origins,
+    // Dev may keep the reached-on origin beside a declaration and a container may not: `x dev`
+    // binds loopback, so a `Host` reaches it only through a forward its own user set up.
+    ...((options.http ?? DEV_BINDING).dev ? { admitReachedOrigin: true } : {}),
+    // Who this node's OWN `/healthz` and `/readyz` tell the detail to: the app's one declaration,
+    // the same list the web role reads. Unset, the node keeps its default (the box itself).
+    ...healthDetailPeersOf(configuredHttp()?.healthDetailPeers),
     // Tier 1 is presence, and without a registry the node answers a topic subscribe with no member
     // list at all — the KV bucket the transport just created would hold nothing and every `sync`
     // container would run a presence-less protocol. It reads and writes `transport.shared`, so it
@@ -223,7 +262,10 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
     // second copy of `/_x/sync` here is the copy that stays behind when it moves.
     mount: { path: node.path, fetch: node.fetch, websocket: node.websocket },
     stop: () => node.stop(),
-    listen: async (appUrl) => await listen(options, node, { registry, hub }, appUrl),
+    listen: async (appUrl) => {
+      origins.push(...devOrigins(options, origins, appUrl));
+      return await listen(options, node, { registry, hub }, appUrl);
+    },
   };
 }
 
@@ -235,27 +277,20 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
  * neighbouring port, and reversing the order would answer a second `x dev` on this checkout with
  * "port 3001 is in use" when the fact worth printing is that 3000 is.
  *
- * Port 0 is NOT passed through to the kernel. It cannot be incremented (`+ 1` would ask for port
- * 1), but the web role has bound by the time this runs and `appUrl` carries the port it got — and
- * `PORT + 1` is the contract every scaffolded `sync-url.ts` computes from and the wiki states. A
- * scratch server (`x shot`, `ui.shot`) always asks for 0, so before this every one of its
- * pictures carried `WebSocket … ERR_CONNECTION_REFUSED` for every live island, on the framework's
- * own account. With no web role to follow, 0 still goes to the kernel. The reported url is the
- * listener's own bound address either way, never a string built from the port that was requested.
+ * Port 0 IS passed through to the kernel, web role or not. A scratch server (`x shot`, `ui.shot`,
+ * a test) asks for 0, and its pages dial `/_x/sync` on their OWN origin — the web role's mount
+ * (`sync-url.ts`) — so nothing computes this listener's port from the web port's. Deriving
+ * `PORT + 1` from the kernel's answer asked for one specific port nobody had checked, and under
+ * load another socket held it: the boot died `X_PORT_IN_USE` (role-realtime.test.ts, 6 of 20 with
+ * 12,000 loopback connections held). The reported url is the listener's own bound address.
  */
-function syncPortFrom(requested: number, appUrl: string | null): number {
-  if (requested !== 0 || appUrl === null) return syncPortFor(requested);
-  const bound = Number(new URL(appUrl).port);
-  return Number.isInteger(bound) && bound > 0 ? syncPortFor(bound) : 0;
-}
-
 async function listen(
   options: StartRolesOptions,
   node: SyncNode,
   feeds: Pick<RunningSync, 'registry' | 'hub'>,
   appUrl: string | null,
 ): Promise<RunningSync> {
-  const port = syncPortFrom(options.port, appUrl);
+  const port = syncPortFor(options.port);
   try {
     // The SAME interface the web role binds, resolved from the same option and the same default.
     // Without this the sync node took Bun's `0.0.0.0` while `x dev`'s web role took `localhost`,

package/src/role-wake.ts

@@ -0,0 +1,45 @@
+// The worker role's cross-process wake, and the one series that says whether it is PROVEN. The
+// mechanism is `@ultimat3/jobs`' (`startQueueWake`); this decides who holds the LISTEN session —
+// the worker, and only over a client that can listen — and publishes `queue_wake_live`, because a
+// transaction-pooling proxy disables the wake in silence and the poll hides that it did.
+
+import { gauge } from '@ultimat3/core';
+import type { DbClient } from '@ultimat3/db';
+import { canListen } 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.
+let current: QueueWake | undefined;
+let declared = false;
+
+const wakeLive = (): number => (current?.live() === true ? 1 : 0);
+
+/**
+ * Starts the wake for a worker, or answers `null` when the client cannot hold a session (a
+ * hand-built runtime): the claim loop and the relay then keep the poll they always had.
+ */
+export function startWorkerWake(db: DbClient): QueueWake | null {
+  if (!canListen(db)) return null;
+  if (!declared) {
+    declared = true;
+    gauge('queue_wake_live', {
+      unit: '1',
+      description:
+        '1 while a notification has crossed the worker LISTEN session, 0 while jobs start on the poll alone',
+      observe: wakeLive,
+    });
+  }
+  const wake = startQueueWake({ listener: db, executor: pgExecutorFor(db) });
+  current = wake;
+  return {
+    live: () => wake.live(),
+    async stop(): Promise<void> {
+      // Only the wake still published: a stop of one that was already replaced silences nothing.
+      if (current === wake) current = undefined;
+      await wake.stop();
+    },
+  };
+}

package/src/runtime-admin.ts

@@ -0,0 +1,141 @@
+// Mounting the app's generated admin. `defineAdmin()` declares it; this file is the whole of what
+// serves it — one catch-all under each admin's base path, in `x dev` and in the container alike,
+// through the same document pipeline every page uses. The CLI contributes the HTTP crossing and
+// nothing else: which screen a URL names, who may see it and what it renders are the admin's.
+
+import type { AdminApp, AdminRouteConfig } from '@ultimat3/admin';
+import type { Route, RouteMeta } from '@ultimat3/http';
+import { asCtx, html, redirect, routeNotFound } from '@ultimat3/http';
+import type { RouteEntry } from '@ultimat3/render';
+import { compilePattern } from '@ultimat3/render';
+import { renderSsr } from '@ultimat3/render/server';
+import type { DocumentOptions } from './document-options';
+import { routeDocument } from './runtime-render';
+
+/**
+ * `@ultimat3/admin`'s `ADMIN_MOUNTS`, read off the GLOBAL symbol registry rather than imported.
+ * Importing that package loads every screen and registers its stylesheets, so an app that declared
+ * no admin would carry one into its documents (axiom 6); asking the registry costs nothing. An app
+ * that DID declare one has already loaded the package, which is when `screens()` below imports it.
+ */
+const ADMIN_MOUNTS: symbol = Symbol.for('ultimate.admin.mounts');
+
+/** The file a mounted screen is attributed to — a package, because no app file declares it. */
+export const ADMIN_MOUNT_FILE = '@ultimat3/admin';
+
+const declared = (): ReadonlyMap<string, AdminApp> => {
+  const held = (globalThis as { [key: symbol]: unknown })[ADMIN_MOUNTS];
+  return held instanceof Map ? (held as ReadonlyMap<string, AdminApp>) : new Map();
+};
+
+export interface AdminMountOptions extends Pick<DocumentOptions, 'themeHead' | 'origin'> {
+  readonly buildId: string;
+}
+
+/**
+ * The route table's own entry shape, for a screen nobody registered there: the document builder
+ * reads a `RouteEntry`, and an admin screen is a route — `ssr`, gated, `hydrate: 'never'` — whose
+ * component is the body the screen just answered with.
+ */
+const entryFor = (route: AdminRouteConfig, body: unknown): RouteEntry => ({
+  file: ADMIN_MOUNT_FILE,
+  path: route.path,
+  // 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,
+});
+
+/**
+ * `auth: 'required'` is the pipeline's half — nobody anonymous reaches a screen, and a sign-in
+ * redirect is the app's own. `enforcedBy: 'handler'` is the other half: the screen holds the row a
+ * row-level rule reads, so deciding in the `authz` stage too would be a second authz system that
+ * knows strictly less and answers first.
+ */
+const metaFor = (base: string): RouteMeta => ({
+  name: `admin:${base}`,
+  auth: 'required',
+  policy: 'admin:read',
+  enforcedBy: 'handler',
+  render: 'ssr',
+  tags: ['admin'],
+});
+
+async function answer(
+  base: string,
+  method: 'GET' | 'POST',
+  options: AdminMountOptions,
+  request: Parameters<Route['handler']>[0],
+  context: Parameters<Route['handler']>[1],
+): Promise<Response> {
+  // Read per request, never captured: `x dev` re-evaluates the module that declares the admin
+  // when it changes, and the admin a request meets is the one the author just saved.
+  const app = declared().get(base);
+  // Dynamic, and only here: reached only when an admin is mounted, by which point the app has
+  // already loaded the package — and after `loadApp` installed the `.tsx` loader its screens need.
+  const { adminRouteMatch } = await import('@ultimat3/admin');
+  const matched = app === undefined ? null : adminRouteMatch(app, request.url.pathname);
+  if (app === undefined || matched === null) throw routeNotFound(method, request.url.pathname);
+
+  const form = method === 'POST' ? await request.bodyRaw() : null;
+  const response = await matched.route.respond({
+    ctx: await app.requestCtx(request.raw),
+    params: matched.params,
+    url: request.url.href,
+    method,
+    // A POST with no body is a form with no fields — a button-only form posts exactly that.
+    form: method === 'POST' ? (isRecord(form) ? form : {}) : null,
+  });
+  if (response.kind === 'redirect') {
+    // 303, always: the browser must GET the page it lands on, not re-POST the form at it.
+    const moved = redirect(response.location, 303);
+    moved.headers.set('cache-control', 'private, no-store');
+    return moved;
+  }
+
+  const entry = entryFor(matched.route, response.body);
+  const data = { url: request.url.href, params: matched.params };
+  const result = await renderSsr(
+    { entry, params: matched.params, url: request.url, ctx: asCtx(context) },
+    () =>
+      routeDocument(entry, data, {
+        ...(options.themeHead === undefined ? {} : { themeHead: options.themeHead }),
+        ...(options.origin === undefined ? {} : { origin: options.origin }),
+      }),
+    { buildId: options.buildId, status: response.status },
+  );
+  // `renderSsr` answers the string the render function returned; a stream is `stream`'s shape.
+  const document = typeof result.body === 'string' ? result.body : '';
+  return html(document, { status: result.status, headers: result.headers });
+}
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const METHODS: readonly ('GET' | 'POST')[] = ['GET', 'POST'];
+
+/**
+ * Two paths per admin and two methods on each: the base path itself (the dashboard) and one
+ * catch-all under it. The admin's own table is matched INSIDE the handler, against the table as
+ * it is now — so a page added in a save is served without this list being rebuilt, and a URL the
+ * admin does not declare is the framework's ordinary 404.
+ *
+ * Empty for an app that declared no admin: nothing is mounted, and nothing is imported.
+ */
+export function adminMountRoutes(options: AdminMountOptions): readonly Route[] {
+  return [...declared().keys()].flatMap((base) =>
+    [base, `${base}/*rest`].flatMap((path) =>
+      METHODS.map(
+        (method): Route => ({
+          method,
+          path,
+          meta: metaFor(base),
+          handler: (request, context) => answer(base, method, options, request, context),
+        }),
+      ),
+    ),
+  );
+}