@ultimat3/cli 20.2.1 → 22.0.0

package/src/role-start-types.ts

@@ -0,0 +1,112 @@
+// The options `startRoles` takes and what it answers. Split from `role-start.ts` at its line
+// ceiling; `role-start.ts` re-exports both, so every importer keeps its path.
+
+import type { DrainConfig, Role } from '@ultimat3/core';
+import type { Route, ServerHandle, ServerHooks } from '@ultimat3/http';
+import type { Scheduler, Worker } from '@ultimat3/jobs';
+import type { LiveQueryRegistry, LiveReplicator } from '@ultimat3/realtime/server';
+import type { MetricsEndpoint } from './metrics-endpoint';
+import type { RunningReplicator } from './role-replicator';
+import type { Env } from './runtime-bindings';
+import type { LiveFeed } from './runtime-live-feed';
+import type { RuntimeOverrides } from './runtime-overrides';
+import type { RunningServices } from './runtime-services';
+import type { WebBinding } from './web-binding';
+
+/** The roles `x dev` starts when `--role` names none, in boot order. */
+export const DEV_ROLES: readonly Role[] = ['web', 'sync', 'worker', 'scheduler'];
+
+export interface StartRolesOptions {
+  readonly roles: readonly Role[];
+  readonly port: number;
+  readonly buildId: string;
+  readonly runtime: RunningServices;
+  /** Routes the web role serves: `/_x`, the actions, the pages. */
+  readonly routes: readonly Route[];
+  /** The process environment, for the roles that resolve a driver from it. */
+  readonly env: Env;
+  /**
+   * How the web role binds and what it admits about itself. `x dev` keeps the default —
+   * loopback, `dev: true`, so a laptop on a café network is not serving the app to the café. A
+   * container passes `{ dev: false, hostname: '0.0.0.0' }`: a process bound to `localhost` inside
+   * a container is unreachable from the port mapping, the load balancer and every PaaS health
+   * probe, which is the same failure in four costumes.
+   */
+  readonly http?: WebBinding;
+  /**
+   * The app's `auth.signInPath`. Threaded rather than read from the config here because
+   * `startRoles` takes plain values — a test starts a web role with no `app.config.ts` at all.
+   */
+  readonly signInPath?: string | null;
+  /**
+   * The app root, for the one seam that is a FILE and not a value: `apps/web/site/errors/404.html`
+   * and its siblings. Bound HERE rather than passed by each caller, because `x dev` and `serve.ts`
+   * both boot through this function and an override wired at one of them alone is a page that
+   * appears in dev and not in production — `/favicon.ico`'s rule, one seam over.
+   *
+   * Optional for the reason `signInPath` is: `startRoles` takes plain values, and a test starts a
+   * web role with no app on disk at all. Absent, every error page is the framework's.
+   */
+  readonly root?: string;
+  /**
+   * Inline `<style>` bodies this process serves that the app's own surfaces do not account for —
+   * `/_x`'s shell. The surfaces themselves are read from the stylesheet registry here rather than
+   * passed, so no caller of `startRoles` can ship a web server whose CSP blocks the pages it
+   * serves: that policy is what rendered every deployed app completely unstyled.
+   */
+  readonly inlineStyles?: readonly string[];
+  /** `script-src` sources beyond the hydration runtime's — the theme boot's hash. */
+  readonly inlineScripts?: readonly string[];
+  /**
+   * Non-fatal findings the browser overlay shows next to an error, for the request being answered.
+   * Only `x dev` supplies one — `serve.ts` boots through this same function and omits it, so a
+   * production process never has a diagnostic to call (axiom 6).
+   */
+  readonly devNotices?: ServerHooks['devNotices'];
+  /**
+   * Where the scrape listener binds. Defaults to `DEFAULT_METRICS_PORT`, except when `port` is 0
+   * — a caller asking the kernel for an ephemeral HTTP port is a test, and a test that grabbed
+   * 9090 would fail the next one to run beside it.
+   */
+  readonly metricsPort?: number;
+  /**
+   * What the host substituted for a boot decision. Read here for the three seams that are not
+   * services — the rate-limit store, the middleware chain and the sync authenticator — while the
+   * drivers themselves arrive already resolved on `runtime`.
+   */
+  readonly overrides?: RuntimeOverrides;
+  /**
+   * `app.config.ts`'s `drain` section, for the web server — its readiness grace is how long
+   * `/readyz` answers 503 before the listener closes. `serve.ts` passes it; absent, core's own
+   * default stands.
+   */
+  readonly drain?: Partial<DrainConfig>;
+  /**
+   * A scrape listener the caller opened before its own boot work, adopted rather than bound twice:
+   * `serve.ts` opens it before loading the app and building islands, so a cold pod answers
+   * `/metrics` — and the chart's startup probe — while it boots. Stopped with the roles.
+   */
+  readonly metrics?: MetricsEndpoint;
+}
+
+export interface RunningRoles {
+  readonly roles: readonly Role[];
+  /** `http://…` once the web role is up; null when it was not selected. */
+  readonly url: string | null;
+  /** Where the sync role accepts websockets; null when it was not selected. */
+  readonly syncUrl: string | null;
+  /** `http://…` — the scrape base. Never null: every role publishes a signal worth scaling on. */
+  readonly metricsUrl: string;
+  readonly server: ServerHandle | null;
+  readonly worker: Worker | null;
+  readonly scheduler: Scheduler | null;
+  /** The slot and feed this process holds; null when the replicator was not selected. */
+  readonly replicator: RunningReplicator | null;
+  /** What feeds the sync node: this process's own writes, the WAL decoder, or nothing. */
+  readonly liveFeed: LiveFeed;
+  /** The in-process bridge when `liveFeed` is `in-process`, so a test can await `settled()`. */
+  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;
+  stop(): Promise<void>;
+}

package/src/{dev-roles.ts → role-start.ts}

@@ -8,13 +8,7 @@
 
 import type { Role } from '@ultimat3/core';
 import { createContext, isRole, logger, ROLES } from '@ultimat3/core';
-import type {
-  RateLimitStore,
-  Route,
-  ServerHandle,
-  ServerHooks,
-  WebSocketMount,
-} from '@ultimat3/http';
+import type { RateLimitStore, Route, ServerHandle, WebSocketMount } from '@ultimat3/http';
 import {
   configuredAuthenticator,
   configuredHttp,
@@ -23,7 +17,7 @@ import {
   MAX_PROXY_HOPS,
   mergeHttpConfig,
 } from '@ultimat3/http';
-import type { OutboxRelay, Scheduler, Worker } from '@ultimat3/jobs';
+import type { OutboxRelay } from '@ultimat3/jobs';
 import {
   createOutboxRelay,
   createPgLeaseLeader,
@@ -32,27 +26,27 @@ import {
   jobDriver,
   pgSchedulerState,
 } from '@ultimat3/jobs';
-import type { LiveQueryRegistry, SyncWs } from '@ultimat3/realtime/server';
-import type { LiveReplicator } from '@ultimat3/testing';
-import { devHooks } from './dev-hooks';
-import type { LiveFeed } from './dev-live-feed';
-import { startLiveFeed } from './dev-live-feed';
-import { pgExecutorFor } from './dev-queue';
-import type { RunningReplicator } from './dev-replicator';
-import { startReplicator } from './dev-replicator';
-import type { RunningServices } from './dev-runtime';
-import type { Env } from './dev-services';
-import { prepareSync, type RunningSync } from './dev-sync';
+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 type { RuntimeOverrides } from './runtime-overrides';
+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 type { Env } from './runtime-bindings';
+import { devHooks } from './runtime-hooks';
+import { workerOptionsFor } from './runtime-jobs';
+import { startLiveFeed } from './runtime-live-feed';
+import { pgExecutorFor } from './runtime-queue';
+import type { RunningServices } from './runtime-services';
 import { inlineScriptSources } from './script-csp';
 import { inlineStyleSources } from './style-csp';
-import { DEV_BINDING, type WebBinding } from './web-binding';
+import { DEV_BINDING } from './web-binding';
 
-/** The roles `x dev` starts when `--role` names none, in boot order. */
-export const DEV_ROLES: readonly Role[] = ['web', 'sync', 'worker', 'scheduler'];
+// Declared beside the option types so `x dev`'s spec reads it without loading this module.
+export { DEV_ROLES } from './role-start-types';
 
 /**
  * What `--role` accepts. The replicator is here but not in `DEV_ROLES`: opt-in, because it takes
@@ -61,93 +55,13 @@ export const DEV_ROLES: readonly Role[] = ['web', 'sync', 'worker', 'scheduler']
  */
 export const SELECTABLE_ROLES: readonly Role[] = [...DEV_ROLES, 'replicator'];
 
-export interface StartRolesOptions {
-  readonly roles: readonly Role[];
-  readonly port: number;
-  readonly buildId: string;
-  readonly runtime: RunningServices;
-  /** Routes the web role serves: `/_x`, the actions, the pages. */
-  readonly routes: readonly Route[];
-  /** The process environment, for the roles that resolve a driver from it. */
-  readonly env: Env;
-  /**
-   * How the web role binds and what it admits about itself. `x dev` keeps the default —
-   * loopback, `dev: true`, so a laptop on a café network is not serving the app to the café. A
-   * container passes `{ dev: false, hostname: '0.0.0.0' }`: a process bound to `localhost` inside
-   * a container is unreachable from the port mapping, the load balancer and every PaaS health
-   * probe, which is the same failure in four costumes.
-   */
-  readonly http?: WebBinding;
-  /**
-   * The app's `auth.signInPath`. Threaded rather than read from the config here because
-   * `startRoles` takes plain values — a test starts a web role with no `app.config.ts` at all.
-   */
-  readonly signInPath?: string | null;
-  /**
-   * The app root, for the one seam that is a FILE and not a value: `apps/web/site/errors/404.html`
-   * and its siblings. Bound HERE rather than passed by each caller, because `x dev` and `serve.ts`
-   * both boot through this function and an override wired at one of them alone is a page that
-   * appears in dev and not in production — `/favicon.ico`'s rule, one seam over.
-   *
-   * Optional for the reason `signInPath` is: `startRoles` takes plain values, and a test starts a
-   * web role with no app on disk at all. Absent, every error page is the framework's.
-   */
-  readonly root?: string;
-  /**
-   * Inline `<style>` bodies this process serves that the app's own surfaces do not account for —
-   * `/_x`'s shell. The surfaces themselves are read from the stylesheet registry here rather than
-   * passed, so no caller of `startRoles` can ship a web server whose CSP blocks the pages it
-   * serves: that policy is what rendered every deployed app completely unstyled.
-   */
-  readonly inlineStyles?: readonly string[];
-  /** `script-src` sources beyond the hydration runtime's — the theme boot's hash. */
-  readonly inlineScripts?: readonly string[];
-  /**
-   * Non-fatal findings the browser overlay shows next to an error, for the request being answered.
-   * Only `x dev` supplies one — `serve.ts` boots through this same function and omits it, so a
-   * production process never has a diagnostic to call (axiom 6).
-   */
-  readonly devNotices?: ServerHooks['devNotices'];
-  /**
-   * Where the scrape listener binds. Defaults to `DEFAULT_METRICS_PORT`, except when `port` is 0
-   * — a caller asking the kernel for an ephemeral HTTP port is a test, and a test that grabbed
-   * 9090 would fail the next one to run beside it.
-   */
-  readonly metricsPort?: number;
-  /**
-   * What the host substituted for a boot decision. Read here for the three seams that are not
-   * services — the rate-limit store, the middleware chain and the sync authenticator — while the
-   * drivers themselves arrive already resolved on `runtime`.
-   */
-  readonly overrides?: RuntimeOverrides;
-}
+// The two shapes this module takes and answers, in a file of their own at the line ceiling.
+export type { RunningRoles, StartRolesOptions } from './role-start-types';
 
-// Re-exported, not re-declared: `web-binding.ts` is a leaf so `dev-sync` can read the default
+// Re-exported, not re-declared: `web-binding.ts` is a leaf so `role-sync` can read the default
 // without importing this module, which imports it.
 export { DEV_BINDING, type WebBinding } from './web-binding';
 
-export interface RunningRoles {
-  readonly roles: readonly Role[];
-  /** `http://…` once the web role is up; null when it was not selected. */
-  readonly url: string | null;
-  /** Where the sync role accepts websockets; null when it was not selected. */
-  readonly syncUrl: string | null;
-  /** `http://…` — the scrape base. Never null: every role publishes a signal worth scaling on. */
-  readonly metricsUrl: string;
-  readonly server: ServerHandle | null;
-  readonly worker: Worker | null;
-  readonly scheduler: Scheduler | null;
-  /** The slot and feed this process holds; null when the replicator was not selected. */
-  readonly replicator: RunningReplicator | null;
-  /** What feeds the sync node: this process's own writes, the WAL decoder, or nothing. */
-  readonly liveFeed: LiveFeed;
-  /** The in-process bridge when `liveFeed` is `in-process`, so a test can await `settled()`. */
-  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;
-  stop(): Promise<void>;
-}
-
 /**
  * `--role web,worker` picks a subset. An unknown or out-of-scope role is a flag error with the
  * working invocation in the fix line, never a silently ignored value — which is what it was.
@@ -278,7 +192,7 @@ 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 `dev-sync`.
+/** `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 {
   warnIfUnauthenticatable(options.routes);
@@ -289,9 +203,12 @@ function startWeb(options: StartRolesOptions, mount?: WebSocketMount<SyncWs>): S
     routes: options.routes,
     role: 'web',
     ...(mount === undefined ? {} : { websocket: mount }),
+    ...(options.drain === undefined ? {} : { drain: options.drain }),
     hooks: devHooks({
       ...(options.devNotices === undefined ? {} : { devNotices: options.devNotices }),
-      ...(options.root === undefined ? {} : { errorPage: errorPageHook(options.root) }),
+      ...(options.root === undefined
+        ? {}
+        : { errorPage: errorPageHook(options.root, { perRequest: binding.dev }) }),
     }),
     // Both seams `createServer` already had and `startRoles` passed neither of, so an app's own
     // middleware could not reach the pipeline any process the framework boots actually runs.
@@ -363,7 +280,8 @@ function assertOneJobDriver(runtime: RunningServices): void {
 }
 
 export async function startRoles(options: StartRolesOptions): Promise<RunningRoles> {
-  const selected = options.roles;
+  // `realtime.enabled` read here, before anything binds: a refusal leaves nothing to unwind.
+  const selected = rolesUnderRealtime(options.roles, options.runtime.realtime);
   assertOneJobDriver(options.runtime);
   // Roles bind sockets in order, so a role that fails to start has to release the ones before it.
   // Without this a failed `sync` leaves the web server bound and unreachable by any caller.
@@ -376,10 +294,13 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
     // the metrics endpoint on Bun's `0.0.0.0` for exactly the caller that asked for loopback —
     // `x dev`, which passes no `http` at all — so the same gap the sync node had was here too.
     const binding = options.http ?? DEV_BINDING;
-    const metrics = startMetricsEndpoint({
-      port: options.metricsPort ?? (options.port === 0 ? 0 : DEFAULT_METRICS_PORT),
-      hostname: binding.hostname,
-    });
+    // A container's boot opened it already, before its slow work (`serve-boot.ts`): adopted.
+    const metrics =
+      options.metrics ??
+      startMetricsEndpoint({
+        port: options.metricsPort ?? (options.port === 0 ? 0 : DEFAULT_METRICS_PORT),
+        hostname: binding.hostname,
+      });
     started.push(async () => metrics.stop());
 
     // BUILT here, BOUND below, the web role between them: `web` serves the node's socket on its
@@ -401,6 +322,7 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
       ? createWorker({
           driver: options.runtime.jobs,
           context: () => createContext({ role: 'worker', buildId: options.buildId }),
+          ...workerOptionsFor(options.runtime.workerConfig),
         })
       : null;
     worker?.start();
@@ -456,9 +378,14 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
     if (replicator !== null) started.push(() => replicator.stop());
 
     // What feeds the sync node this process booted. The embedded database has no log to decode,
-    // so under it the node is fed by this process's own repository writes (`dev-live-feed.ts`);
+    // so under it the node is fed by this process's own repository writes (`runtime-live-feed.ts`);
     // with a real database the WAL decoder above is the feed, here or in another process.
-    const live = await startLiveFeed({ sync, dbMode: options.runtime.services.db.mode });
+    const live = await startLiveFeed({
+      sync,
+      dbMode: options.runtime.services.db.mode,
+      transport: options.runtime.transport.name,
+      replicatorHere: replicator !== null,
+    });
     started.push(async () => live.stop());
 
     return {

package/src/{dev-sync.ts → role-sync.ts}

@@ -1,5 +1,5 @@
 // The `sync` role: which live queries this node serves, who is dialling it, and the socket it owns.
-// Split from `dev-roles.ts` because it is the one role with an authenticator, a presence registry
+// Split from `role-start.ts` because it is the one role with an authenticator, a presence registry
 // 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';
@@ -16,9 +16,9 @@ import {
   RingChangeBuffer,
   SocketRegistry,
 } from '@ultimat3/realtime/server';
-import type { StartRolesOptions } from './dev-roles';
 import { neighbouringPort, PORT_RANGE, portPairAfter } from './flag-number';
 import { portFree } from './port-probe';
+import type { StartRolesOptions } from './role-start';
 import { syncAuthenticator } from './sync-authenticator';
 import { DEV_BINDING } from './web-binding';
 
@@ -131,6 +131,8 @@ export interface RunningSync {
   readonly url: string;
   /** The node's registry, so the boot can hand it a change feed the database cannot produce. */
   readonly registry: LiveQueryRegistry;
+  /** The node's channel hub — fed the same changes, so a declared channel's `records` flow in dev. */
+  readonly hub: ChannelHub;
   stop(): Promise<void>;
 }
 
@@ -162,8 +164,13 @@ export function registerLiveQueries(options: StartRolesOptions): LiveQueryRegist
     onRowDenied: (event) => logger.debug('live.rows_denied', { ...event }),
   });
   const ctx = createContext({ role: 'sync', buildId: options.buildId });
+  // The position a snapshot claims: the newest change this node had received when the read began.
+  // The read then holds at least that change, so claiming it is true, and every later change is
+  // above it. Unwired, every snapshot claimed `''` and a read that landed after any fan-out was
+  // discarded as older than its own window (plan 101, slice 06 c).
+  const lsn = (): string => registry.lastLsn;
   for (const target of listQueries()) {
-    if (target.isLive) registry.register(liveQueryDefinition(target, { ctx }));
+    if (target.isLive) registry.register(liveQueryDefinition(target, { ctx, lsn }));
   }
   return registry;
 }
@@ -212,7 +219,7 @@ 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, appUrl),
+    listen: async (appUrl) => await listen(options, node, { registry, hub }, appUrl),
   };
 }
 
@@ -241,7 +248,7 @@ function syncPortFrom(requested: number, appUrl: string | null): number {
 async function listen(
   options: StartRolesOptions,
   node: SyncNode,
-  registry: LiveQueryRegistry,
+  feeds: Pick<RunningSync, 'registry' | 'hub'>,
   appUrl: string | null,
 ): Promise<RunningSync> {
   const port = syncPortFrom(options.port, appUrl);
@@ -251,11 +258,16 @@ async function listen(
     // so the one socket that streams live database patches was the one socket on every
     // interface — and `WebBinding`'s own docstring is about not serving a laptop's app to a café.
     const binding = options.http ?? DEV_BINDING;
-    // No drain grace: there is one node here and it is the one going away. Its clients reconnect
-    // to it when `x dev` is back, and a grace that kept their patches flowing meanwhile was five
-    // seconds of every Ctrl-C (measured 2026-09-06, 5.0s of 5.1s) spent on a reconnect frame
-    // whose target does not exist yet.
-    const listener = listenSyncNode(node, { port, hostname: binding.hostname, drainGraceMs: 0 });
+    // No drain grace UNDER `x dev`: there is one node and it is the one going away, and a grace
+    // there was five seconds of every Ctrl-C (measured 2026-09-06, 5.0s of 5.1s) spent on a
+    // reconnect frame whose target does not exist yet. A container is the opposite case — other
+    // sync pods are up — and a grace of 0 there dropped every socket at once on SIGTERM, so it
+    // takes the node's own default and spreads the reconnects.
+    const listener = listenSyncNode(node, {
+      port,
+      hostname: binding.hostname,
+      ...(binding.dev ? { drainGraceMs: 0 } : {}),
+    });
     // BOTH doors, named, once. `sync node ready` said only that a node existed: the first question
     // a failing browser socket raises — "is the ws server up, and where?" — had no answer anywhere
     // in the boot output, and the port was never printed at all. It is also what an editor's port
@@ -266,7 +278,7 @@ async function listen(
     });
     return {
       url: listener.url,
-      registry,
+      ...feeds,
       stop: async () => {
         listener.stop();
         await node.stop();

package/src/root-env.ts

@@ -0,0 +1,67 @@
+// The `.env*` files of the APP ROOT, whatever directory `x` was started from. Bun auto-loads them
+// from the process cwd only, while every command finds its root by walking up — so `x db migrate`
+// run from `apps/web` found the app and none of its `.env`, and silently used the embedded
+// database. Loaded once, after the root is known, never overriding a variable already set.
+
+import { isAbsolute, join, resolve } from 'node:path'; // why: Bun ships no path join/resolve.
+import { findAppRoot } from './app-root';
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+/** `--cwd <dir>` / `--cwd=<dir>` from raw argv, resolved against `cwd` — for the hand-over. */
+export function cwdFromArgv(argv: readonly string[], cwd: string): string {
+  const at = argv.findIndex((token) => token === '--cwd' || token.startsWith('--cwd='));
+  if (at === -1) return cwd;
+  const token = argv[at] ?? '';
+  const value = token.startsWith('--cwd=') ? token.slice('--cwd='.length) : argv[at + 1];
+  if (value === undefined || value === '') return cwd;
+  return isAbsolute(value) ? value : resolve(cwd, value);
+}
+
+/** The files Bun itself would load at the root, lowest precedence first. */
+export const rootEnvFiles = (envName: string): readonly string[] => [
+  '.env',
+  `.env.${envName}`,
+  `.env.${envName}.local`,
+];
+
+/**
+ * One dotenv line: `KEY=value`, an optional `export `, a `#` comment, a value in single or double
+ * quotes (double quotes read `\n`). No `${VAR}` expansion — a root-level default that needs one
+ * belongs in the process environment, which always wins here anyway.
+ */
+export function parseDotenv(text: string): ReadonlyMap<string, string> {
+  const out = new Map<string, string>();
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line === '' || line.startsWith('#')) continue;
+    const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_.]*)\s*=\s*(.*)$/.exec(line);
+    if (match === null) continue;
+    const value = (match[2] ?? '').trim();
+    const quote = value[0];
+    if ((quote === '"' || quote === "'") && value.lastIndexOf(quote) > 0) {
+      const inner = value.slice(1, value.lastIndexOf(quote));
+      out.set(match[1] ?? '', quote === '"' ? inner.replaceAll('\\n', '\n') : inner);
+    } else {
+      out.set(match[1] ?? '', value.replace(/\s+#.*$/, ''));
+    }
+  }
+  return out;
+}
+
+/**
+ * The variables the root's `.env*` files add to `env`: only keys `env` does not already hold, so a
+ * real environment variable — and anything Bun already loaded from the cwd — always wins. Empty
+ * when there is no app root or the cwd IS the root (Bun loaded those files itself).
+ */
+export async function rootEnvAdditions(cwd: string, env: Env): Promise<Record<string, string>> {
+  const root = findAppRoot(cwd);
+  if (root === undefined || resolve(root.dir) === resolve(cwd)) return {};
+  const merged = new Map<string, string>();
+  for (const name of rootEnvFiles(env['NODE_ENV'] ?? 'development')) {
+    const file = Bun.file(join(root.dir, name));
+    if (!(await file.exists())) continue;
+    for (const [key, value] of parseDotenv(await file.text())) merged.set(key, value);
+  }
+  return Object.fromEntries([...merged].filter(([key]) => env[key] === undefined));
+}

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

@@ -3,7 +3,7 @@
 // `@ultimat3/pwa` the icons a web manifest promises — and `@ultimat3/core`'s pipeline owns every
 // pixel, so this file picks the two base paths they hang off and decides nothing else. The one
 // thing it does NOT decide is who may read a stored object: `/media` borrows that whole answer
-// from `dev-storage.ts`, because the same bytes are reachable through both.
+// from `runtime-storage.ts`, because the same bytes are reachable through both.
 
 import { probeImage } from '@ultimat3/core';
 import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
@@ -12,12 +12,6 @@ import type { ImageQuery, ImageTransformDriver } from '@ultimat3/seo';
 import { builtinImageDriver, DEFAULT_WIDTHS, parseImageQuery } from '@ultimat3/seo';
 import type { ImageTransform, Storage, VariantFormat } from '@ultimat3/storage';
 import { isTenantScoped, isVariantFormat, variantKey } from '@ultimat3/storage';
-import {
-  AUTHORIZED_OBJECT_CACHE,
-  assertReadableKey,
-  authorizeStorageRead,
-  STORAGE_READ_PERMISSION,
-} from './dev-storage';
 import { faviconRoute } from './favicon';
 // The icon matrix's source, its base path and its renderer live in their own module so that
 // `pwa-artifacts.ts` — which this file imports for the manifest route — can reach them without
@@ -26,6 +20,12 @@ import { faviconRoute } from './favicon';
 import { iconPlan, iconRenderer } from './icon-assets';
 import type { PwaArtifacts } from './pwa-artifacts';
 import { pwaManifestRoute } from './pwa-artifacts';
+import {
+  AUTHORIZED_OBJECT_CACHE,
+  assertReadableKey,
+  authorizeStorageRead,
+  STORAGE_READ_PERMISSION,
+} from './runtime-storage';
 
 /**
  * Storage-backed images. `responsiveImage({ src: '/media/<key>' })` mints its variants under it.

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

@@ -4,6 +4,8 @@
 
 import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
+import type { RealtimeConfig } from '@ultimat3/core';
+import { REALTIME_DEFAULTS } from './runtime-realtime';
 import { safeUrlLabel } from './safe-url-label';
 
 export type ServiceMode = 'embedded' | 'external';
@@ -39,15 +41,22 @@ const nonEmpty = (value: string | undefined): string | undefined =>
  * Embedded Postgres is PGlite on disk under `.x/`, so a restart keeps the data and a `x db reset`
  * is a directory delete rather than a container dance.
  */
-export function resolveServices(root: string, env: Env): DevServices {
-  const stateDir = join(root, '.x');
+export function resolveServices(
+  root: string,
+  env: Env,
+  realtime: RealtimeConfig = REALTIME_DEFAULTS,
+): DevServices {
+  // `ULTIMATE_STATE_DIR` relocates the whole of `.x/` — the embedded database, the local disk and
+  // the dev lock — for one process tree. It is how an e2e run boots the app on a THROWAWAY database
+  // (`e2e-app.ts`) instead of resetting the developer's own, beside a running `x dev`.
+  const stateDir = nonEmpty(env['ULTIMATE_STATE_DIR']) ?? join(root, '.x');
   const databaseUrl = nonEmpty(env['DATABASE_URL']);
-  const natsUrl = nonEmpty(env['NATS_URL']);
   const s3Endpoint = nonEmpty(env['S3_ENDPOINT']);
-  // Created only when something will actually live in it. A container whose bindings are all
-  // external runs non-root over a read-only app directory, and an unconditional mkdir there is an
-  // EACCES at boot for a directory that would have stayed empty.
-  if (databaseUrl === undefined || natsUrl === undefined || s3Endpoint === undefined) {
+  // Created only when something will actually live in it: the embedded database and the local disk
+  // do, in-process events never touch the disk. A container whose bindings are external runs
+  // non-root over a read-only app directory, and a mkdir there is an EACCES at boot for a directory
+  // that would have stayed empty — which an unset NATS_URL alone used to trigger.
+  if (databaseUrl === undefined || s3Endpoint === undefined) {
     mkdirSync(stateDir, { recursive: true });
   }
   return {
@@ -62,15 +71,7 @@ export function resolveServices(root: string, env: Env): DevServices {
             detail: 'PGlite in this process — set DATABASE_URL to use a real Postgres',
           }
         : { name: 'db', mode: 'external', url: databaseUrl, detail: 'DATABASE_URL' },
-    events:
-      natsUrl === undefined
-        ? {
-            name: 'events',
-            mode: 'embedded',
-            url: 'inproc://events',
-            detail: 'in-process fanout — set NATS_URL to use NATS',
-          }
-        : { name: 'events', mode: 'external', url: natsUrl, detail: 'NATS_URL' },
+    events: eventsBinding(env, realtime),
     storage:
       s3Endpoint === undefined
         ? {
@@ -88,7 +89,7 @@ export function resolveServices(root: string, env: Env): DevServices {
  * `x dev --json` emitted `DATABASE_URL` and `NATS_URL` verbatim — passwords included — into a
  * field that is printed to a terminal, piped into a log and scraped by a script, while the rule
  * against it was already written three lines from the emitting code and applied only to mail and
- * cdn. The bindings keep the real url because `dev-queue.ts` has to connect with it; only this
+ * cdn. The bindings keep the real url because `runtime-queue.ts` has to connect with it; only this
  * projection is redacted, so a leak cannot come back as a caller forgetting to call a helper.
  */
 export const reportedUrls = (services: DevServices): Record<ServiceBinding['name'], string> => ({
@@ -101,3 +102,28 @@ export const describeServices = (services: DevServices): string =>
   [services.db, services.events, services.storage]
     .map((binding) => `${binding.name}=${binding.mode}`)
     .join(' ');
+
+/**
+ * The bus as `realtime.transport` chose it, and the variable `realtime.urlEnv` names — the pair
+ * `@ultimat3/realtime`'s `selectTransport` obeys. It read `NATS_URL` literally, so an app naming
+ * its own variable reported `events=embedded` over a boot that had dialled NATS.
+ */
+export function eventsBinding(env: Env, realtime: RealtimeConfig): ServiceBinding {
+  const name = realtime.urlEnv;
+  const url = realtime.transport === 'nats' && name !== undefined ? nonEmpty(env[name]) : undefined;
+  return url === undefined
+    ? {
+        name: 'events',
+        mode: 'embedded',
+        url: 'inproc://events',
+        detail: "in-process fanout — set realtime: { transport: 'nats', urlEnv } to use NATS",
+      }
+    : { name: 'events', mode: 'external', url, detail: name ?? 'NATS_URL' };
+}
+
+/** `services` with the events binding the booted runtime actually chose (`RunningServices.realtime`). */
+export const withRealtimeEvents = (
+  services: DevServices,
+  env: Env,
+  realtime: RealtimeConfig,
+): DevServices => ({ ...services, events: eventsBinding(env, realtime) });

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

@@ -24,7 +24,7 @@ import { CACHE_TIERS, defineConfig, logger, renderThrowable } from '@ultimat3/co
 import type { Transport, TransportSubscription } from '@ultimat3/realtime/server';
 import { APP_CONFIG_EXPORT } from './app-auth';
 import { APP_CONFIG_FILE } from './app-root';
-import type { Env } from './dev-services';
+import type { Env } from './runtime-bindings';
 
 /**
  * The subject every replica of every app publishes tag invalidations on. One subject and not one
@@ -101,7 +101,7 @@ function redisUrl(env: Env): string | undefined {
  *
  * `X_CACHE_DRIVER_UNAVAILABLE` is BORROWED from `@ultimat3/cache` rather than twinned: "this tier
  * cannot be built here" is what that code already means, and its shipped `fix:` is this one. The
- * precedent is `dev-assets.ts` throwing `@ultimat3/pwa`'s `PwaIconMissingError`.
+ * precedent is `runtime-assets.ts` throwing `@ultimat3/pwa`'s `PwaIconMissingError`.
  */
 function buildTier(name: CacheTierName, options: CacheTiersOptions): CacheTier {
   switch (name) {