@ultimat3/cli 20.2.1 → 22.0.0

package/src/runtime-jobs.ts

@@ -0,0 +1,87 @@
+// `jobs.queues`, `jobs.concurrency` and `jobs.visibilityTimeoutMs`, read out of the app's own
+// `app.config.ts` for the `worker` role — the sibling of `runtime-realtime.ts`, and structural
+// for its reason. Until 22.0.0 `createWorker` was called with none of them: every worker served
+// `default` at its own concurrency whatever the config said, so a `mail` queue ran nothing.
+
+// 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 { registeredJobs, type WorkerOptions } from '@ultimat3/jobs';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+
+/** What the worker takes from the config. An absent number keeps the worker's own default. */
+export interface WorkerConfig {
+  readonly queues: readonly string[];
+  readonly concurrency: number | undefined;
+  readonly visibilityTimeoutMs: number | undefined;
+}
+
+const NO_WORKER_CONFIG: WorkerConfig = Object.freeze({
+  queues: [],
+  concurrency: undefined,
+  visibilityTimeoutMs: undefined,
+});
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * A number is handed on AS WRITTEN, never screened here: `createWorker`'s `resolveWorkerTimings`
+ * is the one refusal for a non-finite knob, and core's `defineConfig` screens both counts first.
+ */
+const numberOf = (value: unknown): number | undefined =>
+  typeof value === 'number' ? value : undefined;
+
+export async function loadWorkerConfig(root: string): Promise<WorkerConfig> {
+  const path = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(path).exists())) return NO_WORKER_CONFIG;
+  const module = (await import(path)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  const jobs = isRecord(config) ? config['jobs'] : undefined;
+  if (!isRecord(jobs)) return NO_WORKER_CONFIG;
+  const queues = Array.isArray(jobs['queues'])
+    ? jobs['queues'].filter((queue): queue is string => typeof queue === 'string' && queue !== '')
+    : [];
+  return {
+    queues,
+    concurrency: numberOf(jobs['concurrency']),
+    visibilityTimeoutMs: numberOf(jobs['visibilityTimeoutMs']),
+  };
+}
+
+/**
+ * The queues a worker serves: the configured ones, then every queue a registered job is enqueued
+ * on. The union and not the list, decided 2026-09-23: `x new` and the deployed demo configure
+ * `['<app>-default']` while a `job()` naming no queue lands on `default`, so obeying the list alone
+ * would leave every such job queued for ever — the silent direction. `undefined` when both are
+ * empty, which is `createWorker`'s own `['default']`.
+ */
+export function workerQueuesFor(
+  configured: readonly string[],
+  registered: readonly string[],
+): readonly string[] | undefined {
+  const served = [...new Set([...configured, ...registered])];
+  return served.length === 0 ? undefined : served;
+}
+
+type WorkerConfigOptions = Pick<WorkerOptions, 'queues' | 'concurrency' | 'visibilityTimeoutMs'>;
+
+/**
+ * The `createWorker` options the config supplies, read at START so every job the app registered
+ * on import is counted. A key the config leaves unset is omitted, never passed as `undefined`, so
+ * the worker's own default applies (`exactOptionalPropertyTypes`).
+ */
+export function workerOptionsFor(config: WorkerConfig | undefined): WorkerConfigOptions {
+  const queues = workerQueuesFor(
+    config?.queues ?? [],
+    registeredJobs().map((handle) => handle.queue),
+  );
+  return {
+    ...(queues === undefined ? {} : { queues }),
+    ...(config?.concurrency === undefined ? {} : { concurrency: config.concurrency }),
+    ...(config?.visibilityTimeoutMs === undefined
+      ? {}
+      : { visibilityTimeoutMs: config.visibilityTimeoutMs }),
+  };
+}

package/src/{dev-live-feed.ts → runtime-live-feed.ts}

@@ -4,17 +4,22 @@
 // subscription under `x dev` took its snapshot and then heard nothing, so every `--live` query in
 // every scaffolded app was dead in development — which is where an author first tries one.
 //
-// The bridge is `@ultimat3/testing`'s `startLiveReplicator`, the same in-process row observer the
+// The bridge is `@ultimat3/realtime/server`'s `startLiveReplicator`, the same in-process row observer the
 // framework's own live tests run on: a repository write in THIS process becomes a `ChangeEvent`
 // shaped exactly as the WAL decoder shapes one, fanned into the node's registry. Its honest bound
 // is stated there and repeated here — a write another process makes is invisible — and `x dev` is
 // the one boot where that bound holds by construction: every role runs in this one process.
 
 import { logger, renderThrowable } from '@ultimat3/core';
-import type { LiveReplicator } from '@ultimat3/testing';
-import { startLiveReplicator } from '@ultimat3/testing';
-import type { ServiceMode } from './dev-services';
-import type { RunningSync } from './dev-sync';
+// `@ultimat3/realtime/server`, never `@ultimat3/testing`: this module is on the production boot
+// path (`serve.ts` → `role-start.ts` → here), and the test harness was 38 modules of every image.
+import {
+  type LiveReplicator,
+  RealtimeTopologyError,
+  startLiveReplicator,
+} from '@ultimat3/realtime/server';
+import type { RunningSync } from './role-sync';
+import type { ServiceMode } from './runtime-bindings';
 
 /** What feeds the sync node, said out loud on the boot line and in `--json`. */
 export type LiveFeed = 'in-process' | 'replication' | 'none';
@@ -31,6 +36,10 @@ export interface LiveFeedInput {
   readonly sync: RunningSync | null;
   /** The database's binding: `embedded` is PGlite, which has no log to decode. */
   readonly dbMode: ServiceMode;
+  /** The bus this process fans out on (`Transport.name`): `in-process` reaches no other process. */
+  readonly transport: string;
+  /** Whether the `replicator` role runs in THIS process. */
+  readonly replicatorHere: boolean;
 }
 
 /** The label the `x dev` boot line carries beside `db=`, `events=` and `storage=`. */
@@ -45,10 +54,16 @@ export const liveFeedLabel = (feed: LiveFeed): string => `live=${feed}`;
 export async function startLiveFeed(input: LiveFeedInput): Promise<RunningLiveFeed> {
   if (input.sync === null) return { feed: 'none', bridge: null, stop: () => undefined };
   if (input.dbMode !== 'embedded') {
+    // A decoder this node can hear: in this process, or on a bus other processes share. Neither
+    // is a sync node that reported `replication` while nothing could ever reach it.
+    if (input.transport === 'in-process' && !input.replicatorHere)
+      throw new RealtimeTopologyError();
     return { feed: 'replication', bridge: null, stop: () => undefined };
   }
   const bridge = await startLiveReplicator({
     registry: input.sync.registry,
+    // The same changes the channels read — a real node's change subscription feeds both.
+    channels: input.sync.hub,
     // Logged, never thrown: one change nobody could fan out must not take the dev server down.
     onError: (error) =>
       logger.warn('live.bridge_delivery_failed', { error: renderThrowable(error) }),

package/src/{dev-notify-retention.ts → runtime-notify-retention.ts}

@@ -1,5 +1,5 @@
 // `notify.inboxReadRetentionMs` and `notify.inboxUnreadRetentionMs`, read out of the app's own
-// `app.config.ts`. The sibling of `app-auth.ts`'s `loadSignInPath` and `dev-cache.ts`'s
+// `app.config.ts`. The sibling of `app-auth.ts`'s `loadSignInPath` and `runtime-cache.ts`'s
 // `loadCacheTiers`, and structural for the same reason: `defineConfig` returns a plain object, so
 // a config that resolved through an older core simply has no `notify` section.
 //

package/src/{dev-purge.ts → runtime-purge.ts}

@@ -23,8 +23,8 @@ import type { PostgresRateLimitStore } from '@ultimat3/http';
 import type { JobHandle, PurgeInput, PurgeTarget } from '@ultimat3/jobs';
 import { DEFAULT_PURGE_CRON, getJob, getTask, purge, task } from '@ultimat3/jobs';
 import { purgeNotifyDeliveries, purgeNotifyInbox } from '@ultimat3/notify';
-import type { InboxRetention } from './dev-notify-retention';
-import { NO_INBOX_RETENTION } from './dev-notify-retention';
+import type { InboxRetention } from './runtime-notify-retention';
+import { NO_INBOX_RETENTION } from './runtime-notify-retention';
 
 /** The durable queue key. Pinned, like every framework-owned job name — rows carry it. */
 export const PURGE_JOB_NAME = 'x.purge';

package/src/{dev-queue.ts → runtime-queue.ts}

@@ -1,5 +1,5 @@
 // The database and the job queue, started together and released together. Split from
-// `dev-runtime.ts` because `x jobs` needs exactly this pair and nothing else — and because a
+// `runtime-services.ts` because `x jobs` needs exactly this pair and nothing else — and because a
 // process that installs ambient accessors (`db()`, `jobDriver()`, the jobs facade, the event bus)
 // must have one place that takes them all back, or the next command in the same process inherits
 // a driver over a closed socket.
@@ -32,10 +32,10 @@ import {
   setJobDriver,
   setJobsFacade,
 } from '@ultimat3/jobs';
-import { attachReplica, type ReplicaEnv, replicaUrlFor } from './dev-replica';
-import type { DevServices } from './dev-services';
 import { applyFrameworkSchema } from './framework-schema';
+import type { DevServices } from './runtime-bindings';
 import type { RuntimeOverrides } from './runtime-overrides';
+import { attachReplica, type ReplicaEnv, replicaUrlFor } from './runtime-replica';
 
 /** Both embedded and external clients boot lazily and close explicitly. */
 export type DevDbClient = PgliteClient | PostgresClient;
@@ -51,7 +51,7 @@ export interface RunningQueue {
   readonly jobs: JobDriver;
   /**
    * The `x_outbox` store this boot installed behind `handle.enqueue()`. Returned because the
-   * relay that drains it is a ROLE's decision, not the queue's — `dev-roles.ts` starts one.
+   * relay that drains it is a ROLE's decision, not the queue's — `role-start.ts` starts one.
    */
   readonly outbox: OutboxStore;
   /** The `x_job_events` bus a `step.waitForEvent` resumes from. Durable, not per-process. */

package/src/runtime-realtime.ts

@@ -0,0 +1,55 @@
+// `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.
+
+// 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';
+
+/** Core's `defaults()` for the section, restated as the answer for a config that names none. */
+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.
+ */
+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,
+  };
+}

package/src/{dev-render.ts → runtime-render.ts}

@@ -14,15 +14,32 @@
 // navigation, with a re-parse on top. The static export writes the file (`writeStyles`), so the
 // "second file" cost is one `Bun.write`.
 
+// 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 { clientScopeOf } from '@ultimat3/auth';
 import type { Ctx } from '@ultimat3/core';
+import { CLIENT_SCOPE_HEADER } from '@ultimat3/core';
 import type { RouteMeta as HttpRouteMeta, Route, RouteParams } from '@ultimat3/http';
 import { asCtx, html, stream } from '@ultimat3/http';
 import { currentLocale } from '@ultimat3/i18n';
-import type { IslandCollector, RenderResult, RouteData, RouteEntry } from '@ultimat3/render';
+import type {
+  ClientSyncHead,
+  IslandCollector,
+  RenderResult,
+  RouteData,
+  RouteEntry,
+} from '@ultimat3/render';
 import {
+  clientBootTags,
+  clientPersistTags,
+  clientScopeTag,
+  clientSyncTags,
   createIslandCollector,
+  documentCarriesScope,
   headFromMeta,
   hydrateRuntime,
+  islandModuleId,
+  islandModuleIds,
   metaContextFor,
   renderHead,
   routeDataFor,
@@ -39,9 +56,11 @@ import {
   ROOT_ELEMENT_ID,
   renderComponent,
   renderSsr,
+  ssrHeaders,
   staticHeaders,
   streamResult,
 } from '@ultimat3/render/server';
+import { realtimeIslandFiles } from './island-realtime';
 import { styleBundle } from './style-bundle';
 
 /**
@@ -71,6 +90,18 @@ export interface DocumentOptions {
    * decided by `app.config.ts`, which the boot read and the renderer cannot.
    */
   readonly themeHead?: string;
+  /**
+   * The page's sync target — `pageSync(…).head` — rendered as render's `clientSyncTags` on every
+   * document this process serves. Principal-free, so a shareable document carries it too; absent
+   * for a caller that serves no socket at all (the static export).
+   */
+  readonly sync?: ClientSyncHead;
+  /**
+   * The record types the app persists (`entity(…, { persist: true })`), read per render. Rendered
+   * as `ultimate-persist` beside the scope tag only — persistence is per principal, so a document
+   * with no scope carries none.
+   */
+  readonly persisted?: () => readonly string[];
 }
 
 export interface DevRenderOptions extends DocumentOptions {
@@ -94,16 +125,32 @@ export interface DevRouteData extends Record<string, unknown> {
  */
 const lang = (): string => currentLocale();
 
+/**
+ * `scope` is present only on a PRIVATE document (a gated `ssr` page, every `stream`): the page's
+ * client scope (`@ultimat3/auth`'s `clientScopeOf`), which core's `pageClient()` reads to fence its
+ * one store per principal. A shareable document (`static`, `isr`, ungated `ssr`) carries NO scope
+ * tag — absent means "not rendered for anyone", a different answer from `''`, the anonymous page.
+ */
 const headFor = async (
   entry: RouteEntry,
   ctx: DevRouteData,
   data: RouteData,
   options: DocumentOptions,
+  scope?: string,
 ): Promise<string> =>
   renderHead(
     headFromMeta(
       await entry.config.meta(metaContextFor(ctx, data)),
       seoRenderers({ path: new URL(ctx.url).pathname }),
+      [
+        ...(options.sync === undefined ? [] : clientSyncTags(options.sync)),
+        // The page boot rides the scope tag: its whole job — restoring a principal's persisted
+        // records and replaying its queued writes — is per principal, and a shareable document
+        // (no scope tag) has neither. Cheaper than walking the page's islands, and exact.
+        ...(scope === undefined
+          ? []
+          : [clientScopeTag(scope), ...clientPersistTags(options.persisted?.() ?? [])]),
+      ],
     ),
   ) +
   (options.themeHead ?? '') +
@@ -166,6 +213,33 @@ export async function routeBody(
  * an island never declares its own timing, and `resolve` is the build's — identity when nothing
  * built any, which fails at the first island by name rather than emitting an unusable entry.
  */
+/**
+ * Realtime's page boot, as one deferred script — or nothing. Two conditions, both exact: the
+ * document carries a principal scope (restoring persisted records and replaying queued writes are
+ * per principal; a shareable document has neither), AND one of the islands this render emitted
+ * reaches `@ultimat3/realtime` (a page whose islands never touch a record has nothing to restore
+ * into and no write to replay). After the body, because which islands rendered is a fact the walk
+ * just recorded; still before the hydration runtime, so it runs first among the deferred scripts.
+ */
+function bootScript(
+  entry: RouteEntry,
+  islands: IslandCollector,
+  options: DocumentOptions,
+  scope: string | undefined,
+): string {
+  if (scope === undefined || options.sync === undefined) return '';
+  const rendered = new Set(islandModuleIds(islands.directives));
+  if (rendered.size === 0) return '';
+  // An island's module id is derived from its `src`, written relative to the page that renders it:
+  // each realtime island file, spelled from THIS page, is the id its directive would carry.
+  const pageDir = posix.dirname(entry.file);
+  const reaches = [...realtimeIslandFiles()].some((file) => {
+    const src = posix.relative(pageDir, file);
+    return rendered.has(islandModuleId(src.startsWith('.') ? src : `./${src}`));
+  });
+  return reaches ? renderHead(clientBootTags(options.sync)) : '';
+}
+
 const collectorFor = (entry: RouteEntry, options: DocumentOptions): IslandCollector =>
   createIslandCollector({
     file: entry.file,
@@ -199,15 +273,16 @@ async function documentFrom(
   ctx: DevRouteData,
   data: RouteData,
   options: DocumentOptions,
+  scope?: string,
 ): Promise<string> {
   const islands = collectorFor(entry, options);
   const [head, body] = await Promise.all([
-    headFor(entry, ctx, data, options),
+    headFor(entry, ctx, data, options, scope),
     routeBody(entry, ctx, data, islands),
   ]);
   return (
     `<!doctype html><html lang="${lang()}"><head>${head}${styleTag(entry)}</head>` +
-    `<body>${body}${hydrateRuntime(islands.directives)}</body></html>`
+    `<body>${body}${bootScript(entry, islands, options, scope)}${hydrateRuntime(islands.directives)}</body></html>`
   );
 }
 
@@ -256,31 +331,55 @@ async function resultFor(
       // correct output, no streaming benefit.
       const islands = collectorFor(entry, options);
       const [head, shell] = await Promise.all([
-        headFor(entry, request, data, options),
+        // A stream is always `private, no-store` (`streamResult`), so it always carries the scope.
+        headFor(entry, request, data, options, clientScopeOf(ctx.actor)),
         routeBody(entry, request, data, islands),
       ]);
-      return streamResult(
-        {
-          head: `<!doctype html><html lang="${lang()}"><head>${head}${styleTag(entry)}</head><body>`,
-          // The runtime rides the first flush, with the shell it boots. A later chunk would leave
-          // the window between flush one and the close with inert islands and no listeners on
-          // them — which is exactly the first-click-lost failure `interaction` replay exists for.
-          shell: `${shell}${hydrateRuntime(islands.directives)}`,
-          holes: [],
-        },
-        { buildId: options.buildId },
-        status,
+      return withScope(
+        streamResult(
+          {
+            head: `<!doctype html><html lang="${lang()}"><head>${head}${styleTag(entry)}</head><body>`,
+            // The runtime rides the first flush, with the shell it boots. A later chunk would leave
+            // the window between flush one and the close with inert islands and no listeners on
+            // them — which is exactly the first-click-lost failure `interaction` replay exists for.
+            shell: `${shell}${bootScript(entry, islands, options, clientScopeOf(ctx.actor))}${hydrateRuntime(islands.directives)}`,
+            holes: [],
+          },
+          { buildId: options.buildId },
+          status,
+        ),
+        clientScopeOf(ctx.actor),
       );
     }
-    default:
-      return renderSsr(
-        { entry, params: request.params, url, ctx },
-        () => documentFrom(entry, request, data, options),
-        { buildId: options.buildId, status },
+    default: {
+      // Asked of the headers `renderSsr` is about to send: a gated page is private and carries the
+      // scope; an ungated one is `public, s-maxage` and a CDN may hand it to anyone, so it carries
+      // none — absent, which core reads as "not rendered for anyone", never as anonymous.
+      const scope = documentCarriesScope(ssrHeaders(entry, { buildId: options.buildId }))
+        ? clientScopeOf(ctx.actor)
+        : undefined;
+      return withScope(
+        await renderSsr(
+          { entry, params: request.params, url, ctx },
+          () => documentFrom(entry, request, data, options, scope),
+          { buildId: options.buildId, status },
+        ),
+        scope,
       );
+    }
   }
 }
 
+/**
+ * A private document's scope, as a RESPONSE header too: the service worker partitions its offline
+ * pages by principal and never parses HTML, so the meta alone cannot reach it. Exactly the
+ * documents that carry the scope tag carry this — a shareable one carries neither.
+ */
+const withScope = (result: RenderResult, scope: string | undefined): RenderResult =>
+  scope === undefined
+    ? result
+    : { ...result, headers: { ...result.headers, [CLIENT_SCOPE_HEADER]: scope } };
+
 const responseOf = (result: RenderResult): Response =>
   typeof result.body === 'string'
     ? html(result.body, { status: result.status, headers: result.headers })

package/src/{dev-replica.ts → runtime-replica.ts}

@@ -6,7 +6,7 @@
 //
 // 1. `defaultClient()` is the one place db composes `replicatedClient(primary, replica)` from
 //    `DATABASE_REPLICA_URL`, and it runs only from `baseClient()` — "the client an app installed
-//    none for". Every process the framework boots installs one: `dev-queue.ts` calls
+//    none for". Every process the framework boots installs one: `runtime-queue.ts` calls
 //    `setDbClient(createPgliteClient(…) | createPostgresClient({ url }))`, so `defaultClient()` was
 //    unreachable from `x dev`, from `apps/web/server.ts` and from every container role.
 // 2. Routing needs an OPEN scope as well as a configured replica, and nothing opened one.
@@ -24,7 +24,7 @@ import {
   withReplicaReads,
 } from '@ultimat3/db';
 import type { Middleware } from '@ultimat3/http';
-import type { ServiceBinding } from './dev-services';
+import type { ServiceBinding } from './runtime-bindings';
 import type { RuntimeOverrides } from './runtime-overrides';
 
 export type ReplicaEnv = Readonly<Record<string, string | undefined>>;

package/src/{dev-runtime.ts → runtime-services.ts}

@@ -1,4 +1,4 @@
-// Starting the services `dev-services.ts` resolved. Resolution answers "which database"; this
+// Starting the services `runtime-bindings.ts` resolved. Resolution answers "which database"; this
 // answers "it is running, and every ambient accessor in the framework now points at it" — so
 // `db()`, `jobDriver()`, `mailDriver()` and the realtime transport are the objects a production
 // boot installs, only backed by embedded drivers.
@@ -10,6 +10,7 @@ import type { PurgeDriver } from '@ultimat3/cache';
 import { isNoopPurgeDriver, selectPurgeDriver } from '@ultimat3/cache';
 import {
   isLocal,
+  type RealtimeConfig,
   registerReadinessCheck,
   renderThrowable,
   resolveEnvironment,
@@ -30,15 +31,17 @@ 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 { loadCacheTiers, startCacheTiers } from './dev-cache';
-import { loadInboxRetention } from './dev-notify-retention';
-import { installRetentionSweep } from './dev-purge';
-import type { DevDbClient } from './dev-queue';
-import { pgExecutorFor, startQueue } from './dev-queue';
-import type { DevServices, Env } from './dev-services';
 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 type { RuntimeOverrides } from './runtime-overrides';
+import { installRetentionSweep } from './runtime-purge';
+import type { DevDbClient } from './runtime-queue';
+import { pgExecutorFor, startQueue } from './runtime-queue';
+import { loadRealtimeConfig } from './runtime-realtime';
 
 export interface RunningServices {
   readonly services: DevServices;
@@ -48,6 +51,17 @@ export interface RunningServices {
   readonly outbox: OutboxStore;
   readonly events: EventBus;
   readonly transport: Transport;
+  /**
+   * `app.config.ts`'s `realtime` section as this boot obeyed it. `transport` and `urlEnv` chose
+   * `transport` above; `enabled` is what `startRoles` reads before it starts `sync` or a replicator.
+   */
+  readonly realtime: RealtimeConfig;
+  /**
+   * `app.config.ts`'s `jobs.queues` / `concurrency` / `visibilityTimeoutMs`, for the `worker` role.
+   * Optional because a `RunningServices` can be hand-built, and a test runtime with none keeps the
+   * worker's own defaults — the answer it always got. `startServices` always sets it.
+   */
+  readonly workerConfig?: WorkerConfig;
   readonly storage: Storage;
   readonly mail: MailDriver;
   /**
@@ -193,8 +207,13 @@ export function startStorage(services: DevServices, env: Env, override?: Storage
   // `usesDevStorageSecret({ env })` left bare, refuse a boot whose own env carries a real
   // `STORAGE_SIGNING_SECRET` because the PROCESS does not. Which environment, whether a secret
   // exists, and the name the message prints are one question about one table.
-  if (!isLocal({ env }) && usesDevStorageSecret({ env })) {
-    throw new LocalDiskUnsafeError({ environment: resolveEnvironment({ env }), root });
+  // `fallback: 'production'` on both, the reading `localDriver` itself takes: a boot that names no
+  // environment is not a development one, and this message beats the driver's to it.
+  if (!isLocal({ env, fallback: 'production' }) && usesDevStorageSecret({ env })) {
+    throw new LocalDiskUnsafeError({
+      environment: resolveEnvironment({ env, fallback: 'production' }),
+      root,
+    });
   }
   try {
     mkdirSync(root, { recursive: true });
@@ -293,12 +312,15 @@ export async function startServices(
   // Same reason, same place: building a purge driver reads env and dials nothing, so a half-set
   // `FASTLY_API_TOKEN` without its service id fails here rather than on the first stale page.
   const cdn = selectPurgeDriver(env);
-  // Third of the same kind. `NATS_URL` selects the bus rather than quietly keeping the in-process
-  // one — dev pointed at compose is a parity check, and a parity check that silently ran the
-  // embedded driver is worse than none. 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.
-  const bus: TransportSelection = selectTransport(env);
+  // Third of the same kind. `realtime.transport` selects the bus and `realtime.urlEnv` names the
+  // variable holding its url; a config and an environment that disagree refuse here, before any
+  // 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));
+  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.
@@ -335,7 +357,7 @@ export async function startServices(
     // ships a `purgeExpired()` that nothing called, so every row written was a row kept —
     // `x_rate_limit` takes one upsert per request the web role serves, assets included.
     //
-    // `inboxRetention` is READ HERE and not defaulted in `dev-purge.ts`: the two windows are the
+    // `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.
     started.push(
@@ -347,7 +369,7 @@ export async function startServices(
     );
     // One readiness check per resource this boot OWNS, released with it. Nothing in the tree
     // registered one, so `/readyz` was `markReady()` alone — "this process bound a socket" — and
-    // `packages/http/src/server.ts` calls that BEFORE `Bun.serve`, while `dev-roles.ts` calls it
+    // `packages/http/src/server.ts` calls that BEFORE `Bun.serve`, while `role-start.ts` calls it
     // before `sync`, `worker` and `scheduler` start. The chart's `readinessProbe` and the container
     // healthcheck both route on it, so a replica whose pool was gone kept taking traffic.
     started.push(probedReadinessCheck('database', () => db.ping()));
@@ -399,6 +421,8 @@ export async function startServices(
       outbox,
       events,
       transport,
+      realtime,
+      workerConfig,
       storage,
       mail,
       mailDetail: selection.detail,

package/src/{dev-storage.ts → runtime-storage.ts}

@@ -1,6 +1,6 @@
 // Single responsibility: the one HTTP surface that SERVES a stored object. `@ultimat3/storage`
 // owns keys, bytes and the tenant boundary and owns no `Response`; `@ultimat3/policy` owns the
-// one authz decision; this file is where those two meet a `Route` — the same shape `dev-assets.ts`
+// one authz decision; this file is where those two meet a `Route` — the same shape `runtime-assets.ts`
 // uses for `/icons` and `/media`, so `x dev` and `apps/web/server.ts` mount one read path, not two.
 //
 // The base path is `@ultimat3/storage`'s `DEFAULT_SIGNED_URL_BASE`, imported and never restated:
@@ -37,7 +37,7 @@ export const STORAGE_READ_PERMISSION = 'storage:read';
  * augments `PermissionRegistry` — and this package compiles against no app, so the bare literal is
  * a type error inside a generated project (`scaffold-typecheck` is what proves it). The check that
  * decides is the runtime one anyway: `can()` calls `assertPermission`, which throws
- * `X_PERMISSION_UNKNOWN` naming the `definePermissions` edit. `dev-hooks.ts` narrows a route's
+ * `X_PERMISSION_UNKNOWN` naming the `definePermissions` edit. `runtime-hooks.ts` narrows a route's
  * structurally-typed permission for the same reason.
  */
 const READ_PERMISSION = STORAGE_READ_PERMISSION as unknown as KnownPermission;
@@ -94,7 +94,7 @@ export function authorizeStorageRead(input: StorageReadInput, ctx: RequestContex
  * (never 403 — `error-map.ts` maps `X_STORAGE_ORG_MISMATCH` there so a refusal cannot confirm that
  * a key exists).
  *
- * Split out of `readStorageObject` because `/media/*key` (`dev-assets.ts`) has to make the same
+ * Split out of `readStorageObject` because `/media/*key` (`runtime-assets.ts`) has to make the same
  * decision and made none at all: it passed a client-supplied key straight to `disk().get`, so every
  * object on the app's only disk was one unauthenticated URL away. A second copy of this test is how
  * one of the two surfaces would drift back — `storage-surfaces.test.ts` is what holds them level.
@@ -198,7 +198,7 @@ export function storageResponse(request: UltimateRequest, read: StorageRead): Re
     headers.set('content-range', `bytes */${size}`);
     return new Response(null, { status: 416, headers });
   }
-  // Copied at each call, not through a helper, for `dev-assets.ts`'s reason: a
+  // Copied at each call, not through a helper, for `runtime-assets.ts`'s reason: a
   // `Uint8Array<ArrayBufferLike>` may be backed by a `SharedArrayBuffer`, which `Response` does
   // not accept — and a helper's declared return type widens the copy back to the type it refuses.
   if (range === undefined) {