@ultimat3/cli 27.6.1 → 27.7.0

package/src/i18n-index.ts

@@ -9,7 +9,10 @@
 // why: Bun has no synchronous existence check — `Bun.file(p).exists()` is async, and this decides
 // whether to write at all, before any await the caller could interleave with.
 import { existsSync } from 'node:fs';
+import { stripComments } from '@ultimat3/core';
 import { APP_CATALOGS_PATH } from '@ultimat3/i18n/app-catalogs';
+import type { GenerateDisk } from './generate-disk';
+import { appDisk } from './generate-disk';
 import { containedPath } from './generate-write';
 import type { Finding } from './output';
 import { CATALOG_ROOT, i18nIndex, localeEntry, localeImport } from './templates';
@@ -30,6 +33,8 @@ export interface IndexSync {
   /** False for an app with no i18n package, or an index this writer refused to edit. */
   readonly registered: boolean;
   readonly findings: readonly Finding[];
+  /** The index, when this changed its bytes — a run's file list names every file it touched. */
+  readonly edited?: readonly string[];
 }
 
 const CATALOG_IMPORT = /^import (\w+) from '\.\.\/catalogs\/([^']+)\.json';$/gm;
@@ -48,31 +53,42 @@ const importedLocales = (source: string): readonly string[] =>
  * stay. A shape with no `locales: { … }` object to add to is refused with the edit named, never
  * overwritten: it was, on every `x g`, with a template hard-coding `default: 'en'`.
  */
-export async function syncI18nIndex(root: string): Promise<IndexSync> {
-  const indexAbsolute = containedPath(root, APP_CATALOGS_PATH);
-  if (!existsSync(indexAbsolute)) return { registered: false, findings: [] };
-  const current = await Bun.file(indexAbsolute).text();
-  const onDisk = await catalogLocales(root);
+export async function syncI18nIndex(
+  root: string,
+  disk: GenerateDisk = appDisk(root),
+  /** Locales whose catalog a dry run PLANS: on the real disk only once the run has written. */
+  planned: readonly string[] = [],
+): Promise<IndexSync> {
+  const current = await disk.read(APP_CATALOGS_PATH);
+  if (current === undefined) return { registered: false, findings: [] };
+  const onDisk = [...new Set([...(await catalogLocales(root)), ...planned])].sort();
   const imported = importedLocales(current);
-  if (current === i18nIndex(imported)) {
-    await Bun.write(indexAbsolute, i18nIndex(onDisk));
-    return { registered: true, findings: [] };
-  }
+  const write = async (next: string): Promise<IndexSync> => {
+    if (next === current) return { registered: true, findings: [] };
+    await disk.write(APP_CATALOGS_PATH, next);
+    return { registered: true, findings: [], edited: [APP_CATALOGS_PATH] };
+  };
+  if (current === i18nIndex(imported)) return write(i18nIndex(onDisk));
   const missing = onDisk.filter((locale) => !imported.includes(locale));
   if (missing.length === 0) return { registered: true, findings: [] };
   const edited = withLocales(current, missing);
   if (edited === undefined) return { registered: false, findings: [refusal(missing)] };
-  await Bun.write(indexAbsolute, edited);
-  return { registered: true, findings: [] };
+  return write(edited);
 }
 
 /** Each import after the last catalog import (or at the top), each entry at the object's end. */
 function withLocales(source: string, locales: readonly string[]): string | undefined {
-  const object = LOCALES_OBJECT.exec(source);
+  // Found on the comment-stripped text (same offsets): a `locales: { … }` in a comment above the
+  // call is prose, and it was the one this edited.
+  const object = LOCALES_OBJECT.exec(stripComments(source));
   if (object === null) return undefined;
-  const body = (object[2] ?? '').trim().replace(/,$/, '');
+  const [whole, head = '', inner = ''] = object;
+  // A comment INSIDE the object cannot be carried through a one-line rewrite: refused, with the
+  // edit named, rather than dropped.
+  if (source.slice(object.index, object.index + whole.length) !== whole) return undefined;
+  const body = inner.trim().replace(/,$/, '');
   const entries = [body, ...locales.map(localeEntry)].filter((part) => part !== '').join(', ');
-  const withEntries = source.replace(LOCALES_OBJECT, `$1 ${entries} $3`);
+  const withEntries = `${source.slice(0, object.index)}${head} ${entries} }${source.slice(object.index + whole.length)}`;
   const imports = locales.map(localeImport).join('\n');
   const lastImport = [...withEntries.matchAll(CATALOG_IMPORT)].at(-1);
   if (lastImport === undefined) return `${imports}\n${withEntries}`;

package/src/mcp-host.ts

@@ -105,7 +105,8 @@ export function lazyServices(input: DevHostInput): LazyServices {
   // one connection wedged every later tool call in the session with that first error, and the only
   // way out was restarting the host — `startServices` unwinds everything it started before it
   // rejects, so there is nothing left over for a second attempt to collide with.
-  const boot = retryMemo(() => startServices(services, input.env));
+  // `[]`: this host starts no role, so it only ever publishes to the bus and never waits for it.
+  const boot = retryMemo(() => startServices(services, input.env, undefined, 'apply', []));
   let closed = false;
   return {
     services,

package/src/runtime-bus.ts

@@ -0,0 +1,158 @@
+// Single responsibility: the fanout bus as ONE boot holds it — what the roles it starts do with
+// the bus, the dial that calls for, the readiness check, and the label the boot line prints.
+//
+// The rule is the role's, not the transport's. A `sync` node serves sockets from the bus and a
+// replicator feeds them: neither can work without it, so each awaits the dial and refuses its
+// boot, coded, inside a bounded wait. `web`, `worker` and `scheduler` only PUBLISH — channel
+// events and cache invalidations, both of which mean "re-read" — so for them the bus is dialled in
+// the background and a dead one is `degraded`: the pod still boots, serves and runs jobs. Until
+// 2026-10 every role awaited the dial and the JetStream bucket, so a web pod that restarted while
+// NATS was down took the app's pages, webhooks and send jobs down with a feature none of them use.
+
+import type { RealtimeConfig, Role } from '@ultimat3/core';
+import { logger, registerReadinessCheck } from '@ultimat3/core';
+import type { BusUse, SelectTransportOptions, Transport } from '@ultimat3/realtime/server';
+import { selectTransport, setChannelTransport } from '@ultimat3/realtime/server';
+import type { Env } from './runtime-bindings';
+
+/**
+ * What a process running `roles` does with the bus. `undefined` — a boot that names no roles — is
+ * held to the strictest reading, the one every boot had. `realtime.enabled: false` starts neither
+ * realtime role (`role-realtime.ts`), so nothing in such a process waits for the bus.
+ */
+export function busUseFor(
+  roles: readonly Role[] | undefined,
+  realtime: Pick<RealtimeConfig, 'enabled'>,
+): BusUse {
+  if (roles === undefined) return 'sockets';
+  if (!realtime.enabled) return 'publish';
+  if (roles.includes('sync')) return 'sockets';
+  return roles.includes('replicator') ? 'feed' : 'publish';
+}
+
+/** A transport that says whether it is connected. NATS does; the in-process bus has nothing to be. */
+interface ConnectableTransport {
+  readonly connected: boolean;
+}
+
+const saysConnected = (transport: Transport): transport is Transport & ConnectableTransport =>
+  typeof (transport as Partial<ConnectableTransport>).connected === 'boolean';
+
+/**
+ * The boot line's `bus=` value: `nats(up)`, `nats(connecting)`, or the bare name of a bus with no
+ * connection to lose. A fixed vocabulary a script may parse, never a catalog lookup.
+ */
+export function busLabel(transport: Transport): string {
+  if (!saysConnected(transport)) return transport.name;
+  return `${transport.name}(${transport.connected ? 'up' : 'connecting'})`;
+}
+
+export interface RunningBus {
+  readonly transport: Transport;
+  /** The env key that selected the bus — never the url behind it — or `runtime override`. */
+  readonly detail: string;
+  /** Everything `start()` acquired, newest first; the first failure is rethrown, every step runs. */
+  stop(): Promise<void>;
+}
+
+export interface SelectedBus {
+  readonly use: BusUse;
+  /** What the sync role must give `PresenceRegistry` (`RunningServices.presenceTtlMs`). */
+  readonly presenceTtlMs: number;
+  /**
+   * Dial as `use` calls for, install the transport as the process's channel bus, and register its
+   * readiness check. Rejects — with nothing left registered or open — only for a use that cannot
+   * work without the bus.
+   */
+  start(): Promise<RunningBus>;
+}
+
+export interface SelectBusInput {
+  readonly env: Env;
+  readonly realtime: RealtimeConfig;
+  /** The roles this process will start; `undefined` when the caller does not know. */
+  readonly roles: readonly Role[] | undefined;
+  /** `RuntimeOverrides.transport`: already connected, and its owner's to close. */
+  readonly override?: Transport | undefined;
+  /** Injected by a test: a fake dial, a short wait. */
+  readonly select?: SelectTransportOptions | undefined;
+}
+
+/**
+ * Selection is pure — it parses env and constructs, it dials nothing — so a config and an
+ * environment that disagree refuse here, before any service starts (`selectTransport`).
+ */
+export function selectBus(input: SelectBusInput): SelectedBus {
+  const use = busUseFor(input.roles, input.realtime);
+  const selection = selectTransport(input.env, input.realtime, { ...input.select, use });
+  return {
+    use,
+    presenceTtlMs: selection.presenceTtlMs,
+    async start(): Promise<RunningBus> {
+      const started: (() => void | Promise<void>)[] = [];
+      const stop = async (): Promise<void> => {
+        let failure: { readonly error: unknown } | undefined;
+        for (const step of started.splice(0).reverse()) {
+          try {
+            await step();
+          } catch (error) {
+            failure ??= { error };
+          }
+        }
+        if (failure !== undefined) throw failure.error;
+      };
+      try {
+        // A supplied transport is already connected and is NOT closed here: whoever built it owns
+        // its socket, which is why the override skips both halves rather than only the dial.
+        let transport = input.override;
+        if (transport === undefined) {
+          // Before the dial, not after: a dial refused for being late is still in flight inside
+          // the client library, and closing the transport is what releases whatever it lands as.
+          started.push(() => selection.transport.close());
+          await selection.connect();
+          transport = selection.transport;
+        }
+        // The bus an app's own code publishes a channel event on (`publishChannelEvent`), in EVERY
+        // role: the hub is the `sync` role's, so a job or an action reached none, and an
+        // events-only channel — the one kind that needs no replicator — could be fed by nothing
+        // but a socket.
+        started.push(setChannelTransport(transport));
+        // Only a transport that can be disconnected gets a check. `NatsTransport.connected` is a
+        // synchronous getter over the client's own state, so no probe is needed; the in-process
+        // bus has nothing to lose a connection to, and a check that can only answer `true` is a
+        // number in `registered` that means nothing.
+        if (saysConnected(transport)) {
+          const connectable = transport;
+          started.push(
+            registerReadinessCheck(
+              'transport',
+              () => connectable.connected,
+              // A publisher serves without the bus, so losing it must not pull the pod from the
+              // ingress — it is reported, and `/readyz?deep=1` is where a monitor reads it.
+              { onFailure: use === 'publish' ? 'degraded' : 'failing' },
+            ),
+          );
+          // Each time the bus comes (back) up, on one line: the boot line may have said
+          // `connecting`, and this is the other half of it.
+          started.push(
+            connectable.onReconnect(() => {
+              logger.info('ultimate bus', { bus: busLabel(connectable), use });
+            }),
+          );
+        }
+        return {
+          transport,
+          // The env key that selected the bus — or the honest answer that no env key did, because
+          // a boot line reading `NATS_URL` over a transport the host handed in is a lie a script
+          // parses.
+          detail: input.override === undefined ? selection.detail : 'runtime override',
+          stop,
+        };
+      } catch (error) {
+        // The refusal is the failure worth reporting, not a release on the way out.
+        await stop().catch(() => undefined);
+        throw error;
+      }
+    },
+  };
+}

package/src/runtime-cache.ts

@@ -8,6 +8,7 @@ import type { CacheTier, PurgeDriver } from '@ultimat3/cache';
 import {
   CacheDriverUnavailableError,
   cdnTier,
+  flushProcessTiers,
   isNoopPurgeDriver,
   lruTier,
   memoTier,
@@ -29,6 +30,19 @@ import type { Env } from './runtime-bindings';
  */
 export const CACHE_INVALIDATE_SUBJECT = 'x.cache.invalidate';
 
+/**
+ * "Drop everything you hold in process", on the same subject. An object, where a bust is an array
+ * of wire tags: a replica from before this marker existed parses it, finds no array and ignores
+ * it — its entries wait for their TTL, which is what a lost bust always cost it.
+ */
+export const CACHE_FLUSH_ALL = '{"flush":"all"}';
+
+/**
+ * How many refused wire tags a process keeps for the bus's return. A bound, not a queue: past it
+ * the set is dropped and ONE flush-all is owed instead, so memory does not grow with the outage.
+ */
+export const MAX_DEFERRED_TAGS = 1_024;
+
 export interface CacheTiersOptions {
   readonly env: Env;
   /** Already resolved by the boot — a `cdn` rung is built against a real edge or not at all. */
@@ -152,8 +166,87 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void>
   for (const tier of built) registerTier(tier);
   warnUnnamed(options);
 
+  const send = (payload: string): Promise<void> =>
+    options.transport.publish(CACHE_INVALIDATE_SUBJECT, payload);
+  // What the bus refused, kept for its return. A publish with no live connection is refused, not
+  // buffered (`NatsTransport`), so without this a bust made during a two-second NATS restart
+  // reached no peer at all. De-duplicated — a tag is a fact, not an event — and bounded.
+  const deferred = new Set<string>();
+  let flushOwed = false;
+  const defer = (wireTags: readonly string[]): void => {
+    if (flushOwed) return;
+    for (const wire of wireTags) deferred.add(wire);
+    if (deferred.size <= MAX_DEFERRED_TAGS) return;
+    deferred.clear();
+    flushOwed = true;
+  };
+  /**
+   * One pass over what is owed. It is TAKEN before the publish and put back if the bus refuses, so
+   * a bust refused while this publish is in flight is owed afresh rather than cleared by a success
+   * that never carried it — and a flush-all sent before that bust cannot stand in for it.
+   */
+  const settleOnce = async (): Promise<void> => {
+    if (flushOwed) {
+      flushOwed = false;
+      try {
+        await send(CACHE_FLUSH_ALL);
+      } catch (error) {
+        deferred.clear();
+        flushOwed = true;
+        throw error;
+      }
+      return;
+    }
+    if (deferred.size === 0) return;
+    const batch = [...deferred];
+    deferred.clear();
+    try {
+      await send(JSON.stringify(batch));
+    } catch (error) {
+      defer(batch);
+      throw error;
+    }
+  };
+  // ONE settle at a time. It is asked for by every reconnect and after every accepted publish,
+  // and two that overlapped both published the same batch (and the same flush-all). A call that
+  // arrives mid-run asks for one more pass instead, which finds whatever the run did not carry.
+  let settling: Promise<void> | undefined;
+  let again = false;
+  const settle = (): Promise<void> => {
+    if (settling !== undefined) {
+      again = true;
+      return settling;
+    }
+    settling = (async (): Promise<void> => {
+      try {
+        do {
+          again = false;
+          await settleOnce();
+        } while (again);
+      } finally {
+        again = false;
+        settling = undefined;
+      }
+    })();
+    return settling;
+  };
+  const settleQuietly = (): void => {
+    void settle().catch((error: unknown) => {
+      logger.warn('cache.broadcast.deferred-failed', { error: broadcastErrorText(error) });
+    });
+  };
+
   registerInvalidationBroadcast(async (wireTags) => {
-    await options.transport.publish(CACHE_INVALIDATE_SUBJECT, JSON.stringify(wireTags));
+    try {
+      await send(JSON.stringify(wireTags));
+    } catch (error) {
+      defer(wireTags);
+      // Still thrown: the report must say the peers have not been told YET.
+      throw error;
+    }
+    // The bus took this one, so it takes what an earlier publish could not — the case no
+    // reconnect announces, a refusal with the connection up.
+    if (flushOwed || deferred.size > 0) settleQuietly();
   });
   // Not awaited HERE: the boot must not block on a subscribe. The PROMISE is held rather than a
   // handle assigned inside a `.then`, because the release ran first whenever `stop()` beat the round
@@ -162,28 +255,56 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void>
   // logged once and never asked again, so the process missed every peer invalidation for its life.
   const released = Promise.withResolvers<undefined>();
   let stopped = false;
+  let subscribed = false;
+  /** Cuts the retry's wait short: the bus coming up is a better signal than a backoff. */
+  let wake: () => void = () => undefined;
   const retryMs = options.subscribeRetryMs ?? defaultSubscribeRetryMs;
+  // This process heard no peer for a window nobody measured — since boot, or since the connection
+  // dropped — so nothing it holds in its own heap is known fresh. One cold cache, never a stale one.
+  const flushDeaf = (source: string): void => {
+    void flushProcessTiers(source);
+  };
   const subscribing = (async (): Promise<TransportSubscription | undefined> => {
     for (let attempt = 1; !stopped; attempt += 1) {
       try {
-        return await options.transport.subscribe(CACHE_INVALIDATE_SUBJECT, (payload: string) => {
-          void applyBroadcast(payload);
-        });
+        const subscription = await options.transport.subscribe(
+          CACHE_INVALIDATE_SUBJECT,
+          (payload: string) => {
+            void applyBroadcast(payload);
+          },
+        );
+        subscribed = true;
+        if (attempt > 1) flushDeaf('cache.bus-subscribed');
+        return subscription;
       } catch (error) {
-        logger.warn('cache.broadcast.subscribe-failed', {
-          error: broadcastErrorText(error),
-          attempt,
-        });
-        await Promise.race([Bun.sleep(retryMs(attempt)), released.promise]);
+        // Attempts 1, 2, 4, 8, …: the dial's own thinning (`NatsTransport`), so an outage is not
+        // one line per retry per pod for as long as it lasts.
+        if ((attempt & (attempt - 1)) === 0) {
+          logger.warn('cache.broadcast.subscribe-failed', {
+            error: broadcastErrorText(error),
+            attempt,
+          });
+        }
+        const woken = Promise.withResolvers<undefined>();
+        wake = (): void => woken.resolve(undefined);
+        await Promise.race([Bun.sleep(retryMs(attempt)), released.promise, woken.promise]);
       }
     }
     return undefined;
   })();
+  // The bus is (back) up. The subscription came back with the connection, so from here this
+  // process hears again: drop what it held while deaf, and say what it could not say.
+  const offReconnect = options.transport.onReconnect(() => {
+    wake();
+    if (subscribed) flushDeaf('cache.bus-reconnect');
+    settleQuietly();
+  });
 
   // `resetTiers()` drops the registry AND the broadcast in one call: this boot is the only thing
   // that registers either, and a tier left behind would purge for a process that has stopped.
   return async () => {
     stopped = true;
+    offReconnect();
     released.resolve(undefined);
     (await subscribing)?.unsubscribe();
     resetTiers();
@@ -200,6 +321,13 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void>
  */
 export const broadcastErrorText = (error: unknown): string => renderThrowable(error);
 
+/** `CACHE_FLUSH_ALL`, parsed: a peer had more refused busts than it could keep. */
+const isFlushAll = (parsed: unknown): boolean =>
+  typeof parsed === 'object' &&
+  parsed !== null &&
+  !Array.isArray(parsed) &&
+  Reflect.get(parsed, 'flush') === 'all';
+
 /**
  * A peer's wire tags, applied here. Never throws: a malformed frame or an undeclared tag must not
  * kill the subscriber loop, because that would silently end cross-instance invalidation for the
@@ -208,6 +336,10 @@ export const broadcastErrorText = (error: unknown): string => renderThrowable(er
 async function applyBroadcast(payload: string): Promise<void> {
   try {
     const parsed: unknown = JSON.parse(payload);
+    if (isFlushAll(parsed)) {
+      await flushProcessTiers('cache.broadcast');
+      return;
+    }
     if (!Array.isArray(parsed)) return;
     const wire = parsed.filter((value): value is string => typeof value === 'string');
     if (wire.length > 0) await receiveInvalidationBroadcast(wire);

package/src/runtime-services.ts

@@ -10,6 +10,7 @@ import { isNoopPurgeDriver, selectPurgeDriver } from '@ultimat3/cache';
 import {
   isLocal,
   type RealtimeConfig,
+  type Role,
   registerReadinessCheck,
   renderThrowable,
   resolveEnvironment,
@@ -26,14 +27,14 @@ import {
   resetMailDriver,
   setMailDriver,
 } from '@ultimat3/mail';
-import type { Transport, TransportSelection } from '@ultimat3/realtime/server';
-import { selectTransport, setChannelTransport } from '@ultimat3/realtime/server';
+import type { BusUse, Transport } from '@ultimat3/realtime/server';
 import type { Storage } from '@ultimat3/storage';
 import { defineStorage, localDriver, s3Driver, usesDevStorageSecret } from '@ultimat3/storage';
 import { loadAppConfig } from './app-config-load';
 import { LocalDiskUnsafeError, StorageUnwritableError } from './errors';
 import { msg } from './messages';
 import type { DevServices, Env } from './runtime-bindings';
+import { selectBus } from './runtime-bus';
 import { cacheTiersOf, startCacheTiers } from './runtime-cache';
 import { type WorkerConfig, workerConfigOf } from './runtime-jobs';
 import { selectAppMailDriver } from './runtime-mail';
@@ -74,6 +75,11 @@ export interface RunningServices {
   readonly mailDetail: string;
   /** Same rule as `mailDetail`: the env key that selected the bus, never the url behind it. */
   readonly transportDetail: string;
+  /**
+   * What this process does with the bus, which decided whether the boot waited for it
+   * (`runtime-bus.ts`). Optional for the reason `workerConfig` is: a hand-built runtime has none.
+   */
+  readonly busUse?: BusUse;
   /**
    * What the sync role must give `PresenceRegistry`. It travels with the transport because the KV
    * bucket's age limit was derived from it — a registry given a longer TTL than the bucket honours
@@ -278,14 +284,6 @@ function probedReadinessCheck(name: string, probe: () => Promise<unknown>): () =
   });
 }
 
-/** A transport that says whether it is connected. NATS does; the in-process bus has nothing to be. */
-interface ConnectableTransport {
-  readonly connected: boolean;
-}
-
-const saysConnected = (transport: Transport): transport is Transport & ConnectableTransport =>
-  typeof (transport as Partial<ConnectableTransport>).connected === 'boolean';
-
 /**
  * Release what has already started, newest first, and return every failure instead of throwing on
  * the first: a step that rejects must not skip the ones after it, or one transport that will not
@@ -324,6 +322,11 @@ export async function startServices(
   overrides?: RuntimeOverrides,
   /** `'verify'` for a serving role on an external database — `runtime-queue.ts`'s `SchemaMode`. */
   schema: SchemaMode = 'apply',
+  /**
+   * The roles this process will start, which decide whether the boot waits for the bus: only a
+   * `sync` node or a replicator does (`runtime-bus.ts`). Unset is the strictest reading.
+   */
+  roles?: readonly Role[],
 ): Promise<RunningServices> {
   // The app's config is loaded ONCE, here, first, and every section below is read out of that one
   // validated object — mail's `retainMime` is the first reader, so it is loaded before mail.
@@ -341,13 +344,13 @@ export async function startServices(
   // service starts, rather than quietly keeping the in-process bus. Which transport, which KV
   // bucket and which presence TTL is `@ultimat3/realtime`'s decision, and it is the same call a
   // `ROLE=sync` container makes, so this process cannot resolve the bus differently from the
-  // container it stands in for.
+  // container it stands in for. What the bus is USED for is the roles' (`runtime-bus.ts`).
   const realtime = realtimeConfigOf(config);
   // Fourth: `pwa.push` and its VAPID pair (`runtime-push.ts`). Resolving the pair reads env and
   // signs one probe — a deploy with no keys, or two halves of different pairs, refuses here.
   const push = await selectWebPush(config, env);
   const workerConfig = workerConfigOf(config, env);
-  const bus: TransportSelection = selectTransport(env, realtime);
+  const bus = selectBus({ env, realtime, roles, override: overrides?.transport });
   // `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.
@@ -405,28 +408,14 @@ export async function startServices(
     // 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()));
-    // Dialled here rather than at selection: an unreachable bus must fail at `x dev`, not on the
-    // first change nobody receives, and the socket is a resource the unwind below has to release.
-    // A supplied transport is already connected and is NOT closed here: whoever built it owns its
-    // socket, which is why the override skips both halves rather than only the dial.
-    let transport = overrides?.transport;
-    if (transport === undefined) {
-      await bus.connect();
-      started.push(() => bus.transport.close());
-      transport = bus.transport;
-    }
-    // The bus an app's own code publishes a channel event on (`publishChannelEvent`), in EVERY
-    // role: the hub is the `sync` role's, so a job or an action reached none, and an events-only
-    // channel — the one kind that needs no replicator — could be fed by nothing but a socket.
-    started.push(setChannelTransport(transport));
-    // Only a transport that can be disconnected gets a check. `NatsTransport.connected` is a
-    // synchronous getter over the client's own state, so no probe is needed; the in-process bus
-    // has nothing to lose a connection to, and a check that can only answer `true` is a number in
-    // `registered` that means nothing.
-    if (saysConnected(transport)) {
-      const connectable = transport;
-      started.push(registerReadinessCheck('transport', () => connectable.connected));
-    }
+    // Dialled here rather than at selection: the socket is a resource the unwind below has to
+    // release. AWAITED only by a process that cannot work without the bus — a `sync` node, a
+    // replicator — where an unreachable one must fail the boot, not the first change nobody
+    // receives. Every other role dials in the background and boots regardless; the channel bus and
+    // the `transport` readiness check are installed either way (`runtime-bus.ts`).
+    const running = await bus.start();
+    started.push(() => running.stop());
+    const transport = running.transport;
     // Before `loadApp` for the auth limiters' reason: `pushSubscribe()` is declared when the app's
     // modules import, and reads this runtime per call.
     if (push !== undefined) started.push(await installAppWebPush(push, executor));
@@ -467,9 +456,8 @@ export async function startServices(
       // table: three readers of one executor, resolved once. `startWeb` is what an override
       // replaces it at.
       rateLimitStore,
-      // The env key that selected the bus — or the honest answer that no env key did, because a
-      // boot line reading `NATS_URL` over a transport the host handed in is a lie a script parses.
-      transportDetail: overrides?.transport === undefined ? bus.detail : 'runtime override',
+      transportDetail: running.detail,
+      busUse: bus.use,
       presenceTtlMs: bus.presenceTtlMs,
       purge,
       purgeDetail: cdn.detail,

package/src/serve-boot.ts

@@ -12,6 +12,7 @@ import { startOtlpExport } from './otlp-export';
 import { loadAppForRole, roleLoadFor } from './role-load';
 import { startRoles } from './role-start';
 import { resolveServices } from './runtime-bindings';
+import { busLabel } from './runtime-bus';
 import { warnIfIdempotencyProcessScoped } from './runtime-idempotency-scope';
 import { warnUnsealedMfaSecrets } from './runtime-mfa-warning';
 import { replicaOverrides } from './runtime-replica';
@@ -89,7 +90,8 @@ export async function bootServing(boot: {
   // tables first, and this boot only verifies the stamp it left (`framework-schema-apply.ts`).
   // The embedded database has no migrate step to have run, so it applies its own.
   const schema = services.db.mode === 'external' ? 'verify' : 'apply';
-  const runtime = await startServices(services, options.env, options.runtime, schema);
+  // The role decides whether this boot waits for the bus: only `sync` and the replicator do.
+  const runtime = await startServices(services, options.env, options.runtime, schema, [boot.role]);
   boot.acquired.push(() => runtime.stop());
   return bootRoles({ ...boot, runtime });
 }
@@ -190,6 +192,7 @@ async function bootRoles(boot: {
     role,
     url: running.url,
     buildId,
+    bus: busLabel(runtime.transport),
     running,
     runtime,
     async stop() {

package/src/serve-types.ts

@@ -39,6 +39,12 @@ export interface ServedApp {
   /** `http://…` for the web role; null for the roles that open no HTTP socket. */
   readonly url: string | null;
   readonly buildId: string;
+  /**
+   * The bus as the boot left it: `nats(up)`, `nats(connecting)` or `in-process` (`busLabel`). Only
+   * a role that publishes and serves no socket can boot `connecting`. Optional: a hand-built
+   * `ServedApp` — a test double — has no bus to report, and the boot line then carries none.
+   */
+  readonly bus?: string;
   readonly running: RunningRoles;
   readonly runtime: RunningServices;
   stop(): Promise<void>;

package/src/serve.ts

@@ -203,7 +203,14 @@ export async function runRole(input: ServeOptions): Promise<StartedApp> {
   }
   const { app, hold } = booted;
   retire?.adopt(app.running.worker);
-  logger.info('ultimate started', { role: app.role, url: app.url, buildId: app.buildId });
+  logger.info('ultimate started', {
+    role: app.role,
+    url: app.url,
+    buildId: app.buildId,
+    // `nats(connecting)` on a role that only publishes is a served pod with the bus down;
+    // `ultimate bus` is logged with `nats(up)` when the dial lands.
+    bus: app.bus,
+  });
   await hold();
   return app;
 }