@ultimat3/cli 24.0.0 → 25.0.0

package/src/role-realtime.ts

@@ -14,10 +14,14 @@ const REALTIME_ROLES: readonly Role[] = ['sync', 'replicator'];
  * what `x dev`'s default set needs on an app that opted out (`enabled: false`; the default is on).
  * A selection that was NOTHING but realtime roles is refused instead: that is `ROLE=sync` on an app
  * that turned realtime off, a container that would bind nothing and restart behind its probe.
+ *
+ * `dev` is the boot's `WebBinding.dev`, and picks the invocation the fix names: `x dev --role` for
+ * `x dev`, a `ROLE=` for a container — neither reads the other's selector.
  */
 export function rolesUnderRealtime(
   selected: readonly Role[],
   realtime: Pick<RealtimeConfig, 'enabled'>,
+  dev: boolean,
 ): readonly Role[] {
   // The key is read only when a realtime role was asked for, so a selection without one never
   // depends on it — a hand-built runtime in a test that starts `web` alone included.
@@ -27,7 +31,9 @@ export function rolesUnderRealtime(
   if (kept.length === 0) {
     throw new ConfigInvalidError({
       cause: `role ${dropped.join(',')} was asked for and realtime.enabled is false in app.config.ts, so this process would serve nothing`,
-      fix: `set realtime: { enabled: true } in app.config.ts, or run a role that is not realtime: x dev --role web,worker,scheduler`,
+      fix: dev
+        ? 'set realtime: { enabled: true } in app.config.ts, or run a role that is not realtime: x dev --role web,worker,scheduler'
+        : 'ROLE=web bun apps/web/server.ts — a role that is not realtime; or set realtime: { enabled: true } in app.config.ts and rebuild the image, or drop the role from the deploy (the chart: roles.<role>.enabled: false in values.yaml)',
       meta: { key: 'realtime.enabled', roles: dropped },
     });
   }

package/src/role-replicator.ts

@@ -1,13 +1,22 @@
-// Single responsibility: the `replicator` role under `x dev` — the one place the Postgres logical
-// replication feed is selected, locked and pumped into the transport. Everything it starts is what
-// a `ROLE=replicator` container starts; the only difference is that this process also runs the
-// roles reading the other end of that transport.
+// Single responsibility: the `replicator` role — the one place the Postgres logical replication
+// feed is selected, locked and pumped into the transport, for `x dev --role replicator` and a
+// `ROLE=replicator` container alike. The two differ in what losing the lock means: terminal under
+// `x dev`, a standby that keeps asking in a container.
 
-import { registerReadinessCheck } from '@ultimat3/core';
+import {
+  ConfigInvalidError,
+  logger,
+  registerReadinessCheck,
+  renderThrowable,
+} from '@ultimat3/core';
 import { describeEntities } from '@ultimat3/entity';
 import { ReplicatorSlotHeldError } from '@ultimat3/realtime';
-import type { Replicator, Transport } from '@ultimat3/realtime/server';
-import { createReplicator, replicatorLockKey, selectChangeFeed } from '@ultimat3/realtime/server';
+import type { Replicator, ReplicatorOptions, Transport } from '@ultimat3/realtime/server';
+import {
+  changeFeedReplicator,
+  replicatorLockKey,
+  selectChangeFeed,
+} from '@ultimat3/realtime/server';
 import { BadFlagError } from './errors';
 import type { DevServices, Env } from './runtime-bindings';
 
@@ -15,6 +24,14 @@ export interface StartReplicatorOptions {
   readonly services: DevServices;
   readonly env: Env;
   readonly transport: Transport;
+  /**
+   * `x dev` (true) or a container (false) — the boot's `WebBinding.dev`. It decides what a lost
+   * lock race means and which invocation a refusal names: `x dev --role` is not a command a pod
+   * can run, and `ROLE=` is not a flag `x dev` reads.
+   */
+  readonly dev: boolean;
+  /** The replicator's constructor. A seam for the role's own tests; the boot never passes it. */
+  readonly create?: (options: ReplicatorOptions) => Replicator;
 }
 
 export interface RunningReplicator {
@@ -32,15 +49,23 @@ export interface RunningReplicator {
  * "not a dev role", which is what this used to say and sent an agent looking for a flag instead of
  * a database. Same code as before (`X_CLI_BAD_FLAG`) because it is the same invocation.
  */
-const embeddedRefusal = (): BadFlagError =>
-  new BadFlagError({
-    flag: 'role',
-    command: 'dev',
-    reason:
-      'the replicator decodes a write-ahead log, and the embedded database is PGlite — it has ' +
-      'no walsender to decode',
-    fix: 'DATABASE_URL=postgres://user:password@localhost:5432/app x dev --role replicator',
-  });
+const NO_WALSENDER =
+  'the replicator decodes a write-ahead log, and the embedded database is PGlite — it has no ' +
+  'walsender to decode';
+
+const embeddedRefusal = (dev: boolean): BadFlagError | ConfigInvalidError =>
+  dev
+    ? new BadFlagError({
+        flag: 'role',
+        command: 'dev',
+        reason: NO_WALSENDER,
+        fix: 'DATABASE_URL=postgres://user:password@localhost:5432/app x dev --role replicator',
+      })
+    : new ConfigInvalidError({
+        cause: `ROLE=replicator booted with no DATABASE_URL: ${NO_WALSENDER}`,
+        fix: 'DATABASE_URL=postgres://user:password@host:5432/app ROLE=replicator bun apps/web/server.ts — in the chart, DATABASE_URL comes from the Secret named by existingSecret in docker/helm/values.yaml',
+        meta: { key: 'DATABASE_URL', role: 'replicator' },
+      });
 
 /**
  * The relations the feed decodes: every registered entity's PHYSICAL TABLE, never its name.
@@ -65,13 +90,22 @@ export function replicatedRelations(): readonly string[] {
  * and forwards none. Refused here rather than inside the feed: this is the layer that knows the
  * list came from the app's own registry, so it can name the command that adds to it.
  */
-const noEntitiesRefusal = (): BadFlagError =>
-  new BadFlagError({
-    flag: 'role',
-    command: 'dev',
-    reason: 'no entities are registered, so the replicator would decode changes nothing matches',
-    fix: 'x g entity Post title:text — then x dev --role replicator',
-  });
+const NO_ENTITIES =
+  'no entities are registered, so the replicator would decode changes nothing matches';
+
+const noEntitiesRefusal = (dev: boolean): BadFlagError | ConfigInvalidError =>
+  dev
+    ? new BadFlagError({
+        flag: 'role',
+        command: 'dev',
+        reason: NO_ENTITIES,
+        fix: 'x g entity Post title:text — then x dev --role replicator',
+      })
+    : new ConfigInvalidError({
+        cause: `ROLE=replicator: ${NO_ENTITIES}`,
+        fix: 'x g entity Post title:text — then rebuild the image and roll the ROLE=replicator Deployment',
+        meta: { role: 'replicator' },
+      });
 
 /** The name `/readyz` reports the replicator under. */
 export const REPLICATOR_READINESS_CHECK = 'replicator';
@@ -85,28 +119,71 @@ export function watchReplicatorReadiness(replicator: Pick<Replicator, 'running'>
   return registerReadinessCheck(REPLICATOR_READINESS_CHECK, () => replicator.running);
 }
 
+/**
+ * The standby: ask for the slot again on the replicator's own jittered backoff until it is granted
+ * or the role is stopped. `start()` answering `false` arms no retry of its own — the replicator's
+ * takeover loop covers a run it LOST, not one it never had — so a container that lost the race at
+ * boot would otherwise stand by forever, and a holder that died would leave the slot unreplicated.
+ *
+ * Unref'd: a pending ask must never be what keeps a draining process alive. Returns the cancel.
+ */
+function standBy(replicator: Replicator, key: string): () => void {
+  let cancelled = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const ask = (attempt: number): void => {
+    timer = setTimeout(() => {
+      timer = undefined;
+      if (cancelled) return;
+      // Voided: both outcomes are handled here, and a timer has nobody to hand a promise to.
+      void replicator.start().then(
+        (held) => {
+          if (held) logger.info('replicator.slot_taken_over', { key });
+          else if (!cancelled) ask(attempt + 1);
+        },
+        (thrown: unknown) => {
+          logger.warn('replicator.standby_failed', { key, error: renderThrowable(thrown) });
+          if (!cancelled) ask(attempt + 1);
+        },
+      );
+    }, replicator.retryDelayMs(attempt));
+    timer.unref?.();
+  };
+  ask(0);
+  return () => {
+    cancelled = true;
+    if (timer !== undefined) clearTimeout(timer);
+  };
+}
+
 /**
  * Lock first, feed second. A replicator that opened its slot before losing the lock race would
  * have already consumed WAL the holder is responsible for, and `pg_try_advisory_lock` is the only
  * thing standing between two containers and every change delivered twice.
  */
 export async function startReplicator(options: StartReplicatorOptions): Promise<RunningReplicator> {
-  if (options.services.db.mode === 'embedded') throw embeddedRefusal();
+  if (options.services.db.mode === 'embedded') throw embeddedRefusal(options.dev);
   const entities = replicatedRelations();
-  if (entities.length === 0) throw noEntitiesRefusal();
+  if (entities.length === 0) throw noEntitiesRefusal(options.dev);
 
   const selection = selectChangeFeed(options.env, { entities });
   const slot = selection.slot ?? '';
-  const replicator = createReplicator({
+  const key = replicatorLockKey(slot);
+  const replicator = (options.create ?? changeFeedReplicator)({
     feed: selection.feed,
     transport: options.transport,
     lock: selection.lock,
   });
-  // `start()` answers `false` for the one condition that is not this process's fault. A dev boot
-  // has nothing to fail over to — the standby loop belongs to a container an orchestrator
-  // restarts — so it is terminal here, with the code the topology docs already promised.
+  // `start()` answers `false` for the one condition that is not this process's fault: another
+  // process holds the lock. A dev boot has nothing to fail over to, so it is terminal there, with
+  // the code the topology docs promised. A container stays up, `/readyz` false, and stands by —
+  // a pod that threw here crash-looped, and a rolling update waiting on its readiness never
+  // terminated the old holder, so every rollout stalled (`replicator.ts`'s header: the loser stays
+  // up, unready).
+  let cancelStandby = (): void => undefined;
   if (!(await replicator.start())) {
-    throw new ReplicatorSlotHeldError({ key: replicatorLockKey(slot) });
+    if (options.dev) throw new ReplicatorSlotHeldError({ key });
+    logger.warn('replicator.standby', { key, detail: 'another process holds the slot' });
+    cancelStandby = standBy(replicator, key);
   }
   const unregister = watchReplicatorReadiness(replicator);
   return {
@@ -114,7 +191,9 @@ export async function startReplicator(options: StartReplicatorOptions): Promise<
     slot,
     detail: selection.detail,
     async stop() {
-      // First: a replicator being stopped on purpose is not a failing one.
+      // First: a replicator being stopped on purpose is not a failing one, and a standby must not
+      // ask for a slot after the role that wanted it has gone.
+      cancelStandby();
       unregister();
       await replicator.stop();
     },

package/src/role-start.ts

@@ -7,24 +7,24 @@
 // something every `x dev` in a team should do to the same server by simply starting.
 
 import type { Role } from '@ultimat3/core';
-import { createContext, isRole, logger, markReady, ROLES } from '@ultimat3/core';
+import { ctxOf, isRole, logger, markReady, ROLES } from '@ultimat3/core';
 import type { RateLimitStore, Route, ServerHandle, WebSocketMount } from '@ultimat3/http';
 import {
+  adoptRateLimitStore,
   configuredAuthenticator,
   configuredHttp,
-  createServer,
   defineHttpConfig,
-  MAX_PROXY_HOPS,
+  httpServer,
   mergeHttpConfig,
 } from '@ultimat3/http';
 import type { OutboxRelay } from '@ultimat3/jobs';
 import {
-  createOutboxRelay,
-  createPgLeaseLeader,
-  createScheduler,
-  createWorker,
   jobDriver,
-  pgSchedulerState,
+  jobScheduler,
+  jobWorker,
+  outboxRelay,
+  postgresLeaseLeader,
+  postgresSchedulerState,
 } from '@ultimat3/jobs';
 import type { SyncWs } from '@ultimat3/realtime/server';
 import { errorPageHook } from './error-pages';
@@ -40,16 +40,15 @@ import type { RunningRoles, StartRolesOptions } from './role-start-types';
 import { DEV_ROLES } from './role-start-types';
 import { prepareSync, type RunningSync } from './role-sync';
 import { startWorkerWake } from './role-wake';
-import type { Env } from './runtime-bindings';
 import { devHooks } from './runtime-hooks';
 import { workerOptionsFor } from './runtime-jobs';
 import { startLiveFeed } from './runtime-live-feed';
 import { pgExecutorFor } from './runtime-queue';
-import type { RunningServices } from './runtime-services';
+import { type RunningServices, releaseOrThrow } from './runtime-services';
 import { inlineScriptSources } from './script-csp';
 import { inlineStyleSources } from './style-csp';
 import { syncConnectSources } from './sync-url';
-import { TrustedProxyHopsInvalidError } from './trusted-hops-error';
+import { trustedHopsFromEnv } from './trusted-hops';
 import { DEV_BINDING } from './web-binding';
 
 // Declared beside the option types so `x dev`'s spec reads it without loading this module.
@@ -125,47 +124,8 @@ function warnIfUnauthenticatable(routes: readonly Route[]): void {
   );
 }
 
-/**
- * How many proxies is too many, and the number is **`@ultimat3/http`'s**, not this file's.
- *
- * `defineHttpConfig` screens the same setting — `assertFiniteCount('trustedProxyHops', …,
- * MAX_PROXY_HOPS)` — and this screen used to say 16 where that one says 64, so one setting had two
- * ceilings and a deployment behind 20 hops was accepted by the library and refused by the boot.
- * Widened rather than narrowed: tightening the library would break a shipped public API, while
- * this end only ever refused topologies http already supports.
- *
- * It was a duplicated literal until 2026-08-26, because `@ultimat3/http` did not export the
- * constant. It does now, so this file IMPORTS it — a downward edge, tier 5 to tier 2 — and there is
- * no second number left to drift. `runtime-overrides.test.ts` still probes both screens for the
- * highest count each accepts, and it is kept rather than deleted: it compares BEHAVIOUR, so it also
- * catches the two disagreeing for a reason a shared constant cannot fix, such as one side gaining a
- * range check the other does not have.
- */
-
-/**
- * How many proxies append to `x-forwarded-for` between the client and this process, or `null`
- * when nothing in front of it is trusted.
- *
- * Read from the environment and not from `app.config.ts`, for the reason `PORT` and `ROLE` are: it
- * is a fact about the DEPLOYMENT — one image runs behind an ingress in one cluster and behind
- * nothing on a laptop — and an app that hardcoded it would be wrong in one of the two. `x dev`
- * sets neither and gets `trustProxy: false`, which is correct: there is no proxy.
- *
- * Without this seam a container behind an ingress reads `ctx.ip` as the ingress's own socket
- * address on every request, so the rate limiter keys the entire fleet's anonymous traffic into ONE
- * bucket and a single scanner 429s every real signup.
- */
-export function trustedHopsFromEnv(env: Env): number | null {
-  const raw = env['TRUSTED_PROXY_HOPS']?.trim();
-  if (raw === undefined || raw === '') return null;
-  const hops = Number(raw);
-  // A malformed count is refused rather than defaulted: reading the header at the wrong index is
-  // trusting a value the client typed, which is the failure trusting a proxy exists to avoid.
-  if (!/^\d+$/.test(raw) || !Number.isInteger(hops) || hops < 1 || hops > MAX_PROXY_HOPS) {
-    throw new TrustedProxyHopsInvalidError({ value: raw });
-  }
-  return hops;
-}
+// `trusted-hops.ts` owns the read; re-exported because callers and tests already name it here.
+export { trustedHopsFromEnv } from './trusted-hops';
 
 /**
  * A deployment that substituted a PER-PROCESS store is enforcing every declared number once per
@@ -190,7 +150,7 @@ function warnIfProcessScoped(store: RateLimitStore): void {
  *
  * One expression, one answer, in the order `RuntimeOverrides` documents — an override REPLACES the
  * resolved default rather than sitting beside it. `undefined` is reachable only from a hand-built
- * runtime, which is `createServer`'s per-process memory store and `scope: 'process'` below.
+ * runtime, which is `httpServer`'s per-process memory store and `scope: 'process'` below.
  */
 function rateLimitStoreFor(options: StartRolesOptions): RateLimitStore | undefined {
   const supplied = options.overrides?.rateLimitStore;
@@ -206,7 +166,7 @@ function startWeb(options: StartRolesOptions, mount?: WebSocketMount<SyncWs>): S
   const binding = options.http ?? DEV_BINDING;
   const hops = trustedHopsFromEnv(options.env);
   const store = rateLimitStoreFor(options);
-  return createServer({
+  return httpServer({
     routes: options.routes,
     role: 'web',
     ...(mount === undefined ? {} : { websocket: mount }),
@@ -217,7 +177,7 @@ function startWeb(options: StartRolesOptions, mount?: WebSocketMount<SyncWs>): S
         ? {}
         : { errorPage: errorPageHook(options.root, { perRequest: binding.dev }) }),
     }),
-    // Both seams `createServer` already had and `startRoles` passed neither of, so an app's own
+    // Both seams `httpServer` 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.
     ...(options.overrides?.middleware === undefined
       ? {}
@@ -272,7 +232,7 @@ function startWeb(options: StartRolesOptions, mount?: WebSocketMount<SyncWs>): S
  * `startServices` captures the drivers it built; `loadApp` imports the app's modules after it, and
  * a module calling `setJobDriver()` at import time moves the ambient slot and leaves the capture
  * alone. From here on the two are indistinguishable at every call site: `handle.enqueue()` reads
- * the ambient one, `createWorker` claims from the captured one, and `/_x` reads the ambient one —
+ * the ambient one, `jobWorker` claims from the captured one, and `/_x` reads the ambient one —
  * so the dashboard agrees with the enqueue side and disagrees with reality.
  *
  * Refused, not reconciled. Reading through the accessor would make the split invisible instead of
@@ -291,12 +251,26 @@ function assertOneJobDriver(runtime: RunningServices): void {
 
 export async function startRoles(options: StartRolesOptions): Promise<RunningRoles> {
   // `realtime.enabled` read here, before anything binds: a refusal leaves nothing to unwind.
-  const selected = rolesUnderRealtime(options.roles, options.runtime.realtime);
+  const selected = rolesUnderRealtime(
+    options.roles,
+    options.runtime.realtime,
+    (options.http ?? DEV_BINDING).dev,
+  );
   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.
   const started: (() => Promise<void>)[] = [];
   try {
+    // Every role, before any can serve: an action's or a query's declared `rateLimit:` is spent
+    // inside the primitive (`invoke`, the read path) on every surface — a `worker` running
+    // `.job()`s as much as `web` — and counted in the installed store. The SAME instance the web
+    // role's limiter gets below (`rateLimitStoreFor` is the one decision), so one replica's MCP
+    // call and another's HTTP call spend one bucket in one table.
+    // A frame of its own over what `startServices` adopted, popped by its own undo — so stopping
+    // these roles takes back exactly this install, whatever else stacked over or under it.
+    const limits = rateLimitStoreFor(options);
+    const restoreLimits = limits === undefined ? () => undefined : adoptRateLimitStore(limits);
+    started.push(async () => restoreLimits());
     // First, and for every role rather than only the two that open an HTTP socket: `worker` and
     // `sync` are precisely the roles whose HPAs read a series the process itself has to publish,
     // and a `worker` container with no listener is an HPA pinned at `<unknown>` forever.
@@ -320,21 +294,32 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
     // own port and a listening server cannot be handed one, while the neighbouring-port refusals
     // are only the right answer once the web port's own has been given.
     const prepared = selected.includes('sync') ? await prepareSync(options) : null;
-    // One rollback entry, kept current — two would stop the node twice out of a failed boot.
+    // One rollback entry, kept current — two would stop the node twice out of a failed boot. It
+    // goes on the list AFTER the server's, because the list is also the stop order (newest
+    // first): the node's listener closes before the web server drains, as it always has. The
+    // window between — `startWeb` refusing — releases the prepared node itself.
     let releaseSync = prepared?.stop ?? null;
+    let server: ServerHandle | null;
+    try {
+      server = selected.includes('web') ? startWeb(options, prepared?.mount) : null;
+    } catch (error) {
+      await releaseSync?.().catch(() => undefined);
+      throw error;
+    }
+    if (server !== null) {
+      const web = server;
+      started.push(() => web.stop());
+    }
     if (prepared !== null) started.push(async () => await releaseSync?.());
 
-    const server = selected.includes('web') ? startWeb(options, prepared?.mount) : null;
-    if (server !== null) started.push(() => server.stop());
-
     const sync: RunningSync | null =
       prepared === null ? null : await prepared.listen(server === null ? null : server.url());
     if (sync !== null) releaseSync = sync.stop;
 
     const worker = selected.includes('worker')
-      ? createWorker({
+      ? jobWorker({
           driver: options.runtime.jobs,
-          context: () => createContext({ role: 'worker', buildId: options.buildId }),
+          context: () => ctxOf({ role: 'worker', buildId: options.buildId }),
           ...workerOptionsFor(options.runtime.workerConfig),
         })
       : null;
@@ -352,7 +337,7 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
     // collapses a repeat only while the first job is still live. A deployment with no `worker` has
     // no one to run the jobs either way.
     const relay: OutboxRelay | null = selected.includes('worker')
-      ? createOutboxRelay({ store: options.runtime.outbox, driver: options.runtime.jobs })
+      ? outboxRelay({ store: options.runtime.outbox, driver: options.runtime.jobs })
       : null;
     relay?.start();
     // Returned, not called-and-discarded: `stop()` waits out the pass in flight, and an unawaited
@@ -366,20 +351,20 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
     const wake = selected.includes('worker') ? startWorkerWake(options.runtime.db) : null;
     if (wake !== null) started.push(() => wake.stop());
 
-    // `state` and `leader`, not the defaults. `createMemorySchedulerState` forgets every watermark
+    // `state` and `leader`, not the defaults. `memorySchedulerState` forgets every watermark
     // on restart, so a rolling deploy re-fires or skips whatever was due across it, and
     // `soleLeader()` makes every replica the leader — three `scheduler` pods, three of every task.
     //
-    // `createPgLeaseLeader` and NOT `createPgLeader`: the latter's `pg_try_advisory_lock` is
+    // `postgresLeaseLeader` and NOT `postgresLeader`: the latter's `pg_try_advisory_lock` is
     // SESSION-scoped, and the session ends the moment the connection goes back to the pool, so
     // every node reads itself as leader anyway. An expiring row is correct on the executor this
     // package is actually handed.
     const executor = pgExecutorFor(options.runtime.db);
     const scheduler = selected.includes('scheduler')
-      ? createScheduler({
+      ? jobScheduler({
           driver: options.runtime.jobs,
-          state: pgSchedulerState(executor),
-          leader: createPgLeaseLeader({ executor }),
+          state: postgresSchedulerState(executor),
+          leader: postgresLeaseLeader({ executor }),
         })
       : null;
     scheduler?.start();
@@ -393,6 +378,7 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
           services: options.runtime.services,
           env: options.env,
           transport: options.runtime.transport,
+          dev: binding.dev,
         })
       : null;
     if (replicator !== null) started.push(() => replicator.stop());
@@ -425,22 +411,15 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
       liveBridge: live.bridge,
       liveRegistry: sync?.registry ?? null,
       async stop() {
-        // Reverse boot order, so the slot is released before the bus it published to closes.
-        live.stop();
-        await replicator?.stop();
-        await scheduler?.stop();
-        // Before the worker, so nothing publishes into a queue whose consumer has already gone —
-        // and AWAITED, because a pass is a `driver.enqueue` followed by a `markPublished`. Dropped,
-        // this returns between the two and the lines below close the pool under the row it was
-        // about to mark: re-published next boot at best, a rejection against a closed pool at worst.
-        // The session first: a notification arriving after this wakes a loop that is about to stop.
-        await wake?.stop();
-        await relay?.stop();
-        await worker?.stop('x dev stopped');
-        await sync?.stop();
-        await server?.stop();
-        // Last: a scrape taken while the roles above drain is the one that explains the drain.
-        metrics.stop();
+        // `started` IS the stop list, in boot order: released newest first — the live feed, the
+        // replicator (so the slot is released before the bus it published to closes), the
+        // scheduler, the wake session, the relay (awaited: a pass is an enqueue then a
+        // `markPublished`, and a pool closed between the two re-publishes next boot), the worker,
+        // the sync node, the server, the metrics listener (a scrape taken mid-drain explains the
+        // drain) and, after every role that could spend from it, the rate-limit store. EVERY step
+        // runs: one rejection used to skip the rest. One list, so the rollback and the stop cannot
+        // drift apart.
+        await releaseOrThrow(started);
       },
     };
   } catch (error) {

package/src/role-sync.ts

@@ -2,25 +2,35 @@
 // 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';
-import { configuredHttp, type WebSocketMount } from '@ultimat3/http';
+import { ctxOf, logger, type RealtimeConfig, UltimateError } from '@ultimat3/core';
+import {
+  clientAddress,
+  configuredHttp,
+  defineHttpConfig,
+  mergeHttpConfig,
+  type WebSocketMount,
+} from '@ultimat3/http';
 import { listQueries } from '@ultimat3/query';
 import type { SyncNode, SyncWs } from '@ultimat3/realtime/server';
 import {
   ChannelHub,
-  createSyncNode,
   LiveQueryRegistry,
   listenSyncNode,
   liveQueryDefinition,
   PresenceRegistry,
   RingChangeBuffer,
   SocketRegistry,
+  syncNode,
 } from '@ultimat3/realtime/server';
 import { neighbouringPort, PORT_RANGE, portPairAfter } from './flag-number';
 import { portFree } from './port-probe';
 import type { StartRolesOptions } from './role-start';
+import type { Env } from './runtime-bindings';
 import { syncAuthenticator } from './sync-authenticator';
 import { syncOriginsFrom } from './sync-url';
+// A value edge back into `role-start.ts`, read only inside a call: the one parser of
+// `TRUSTED_PROXY_HOPS`, never a second copy of it.
+import { trustedHopsFromEnv } from './trusted-hops';
 import { DEV_BINDING } from './web-binding';
 
 /**
@@ -154,18 +164,26 @@ export interface RunningSync {
  * close. And no default is defensible: one tenant is a single person and the next is five
  * thousand seats, so any number here is either unreachable or an outage on a Monday morning. The
  * per-socket 128 stands because a socket is one browser tab, which is a bound the framework can
- * actually know. A deployment that wants the tenant cap passes both:
+ * actually know, and so does the per-ACTOR 1,000 (`realtime.maxSubscriptionsPerActor`): one
+ * principal's share is knowable where a tenant's is not. A deployment that wants the tenant cap
+ * passes both:
  *
  *   new LiveQueryRegistry({ …, maxPerTenant: 5_000, tenantOf: (actor) => actor?.orgId ?? null })
  */
 export function registerLiveQueries(options: StartRolesOptions): LiveQueryRegistry {
+  // `?.` because a caller that builds only the registry (`role-sync-resume.test.ts`) hands no
+  // runtime; unset is the registry's own `DEFAULT_MAX_PER_ACTOR`, which is what core leaves it.
+  const maxPerActor = options.runtime?.realtime?.maxSubscriptionsPerActor;
   const registry = new LiveQueryRegistry({
     source: new RingChangeBuffer(),
+    // One actor's — or one anonymous address's — share of this node's live queries, from the app's
+    // `realtime.maxSubscriptionsPerActor`. Without it 79 sockets of one actor filled the node.
+    ...(maxPerActor === undefined ? {} : { maxPerActor }),
     // A withheld row is a metric, never a frame and never an error: telling a client "there is a
     // row you may not see" is the leak the gate exists to prevent.
     onRowDenied: (event) => logger.debug('live.rows_denied', { ...event }),
   });
-  const ctx = createContext({ role: 'sync', buildId: options.buildId });
+  const ctx = ctxOf({ 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
@@ -177,6 +195,45 @@ export function registerLiveQueries(options: StartRolesOptions): LiveQueryRegist
   return registry;
 }
 
+/**
+ * Who dialled the socket, resolved by `@ultimat3/http`'s `clientAddress()` — the rule the web role's
+ * `ctx.ip` follows, at the same `TRUSTED_PROXY_HOPS`. It keys an anonymous live reader's rate
+ * limit: read off the socket alone, a node behind an ingress put every anonymous viewer of the
+ * fleet in the ingress's one bucket, and one visitor looping subscribes locked out the rest.
+ *
+ * The config is built only to carry the hops — `rateLimit.scope` is declared because
+ * `defineHttpConfig` requires it, and this node runs no HTTP limiter that would read it.
+ */
+export function syncClientAddressOf(
+  env: Env,
+): (request: Request, socketAddress: string | null) => string | null {
+  const hops = trustedHopsFromEnv(env);
+  const config = defineHttpConfig(
+    mergeHttpConfig(configuredHttp(), {
+      rateLimit: { scope: 'process' },
+      ...(hops === null ? {} : { trustProxy: true, trustedProxyHops: hops }),
+    }),
+  );
+  return (request, socketAddress) =>
+    clientAddress({
+      headers: request.headers,
+      config,
+      socketAddress,
+      urlProtocol: new URL(request.url).protocol,
+    });
+}
+
+/**
+ * The node's half of the app's per-actor caps: `realtime.maxSocketsPerActor`, the sockets one
+ * principal may hold here. Absent, the node keeps its own default (16) — which is core's too.
+ */
+export function syncNodeCaps(realtime: RealtimeConfig | undefined): {
+  readonly maxSocketsPerActor?: number;
+} {
+  const max = realtime?.maxSocketsPerActor;
+  return max === undefined ? {} : { maxSocketsPerActor: max };
+}
+
 const healthDetailPeersOf = (
   peers: readonly string[] | undefined,
 ): { readonly healthDetailPeers?: readonly string[] } =>
@@ -226,7 +283,7 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
   const authenticate = options.overrides?.syncAuthenticate ?? syncAuthenticator(options.buildId);
   const registry = registerLiveQueries(options);
   const origins = syncOriginsFrom(options.env);
-  const node = createSyncNode({
+  const node = syncNode({
     hub,
     registry,
     transport: options.runtime.transport,
@@ -244,6 +301,8 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
     // Who this node's OWN `/healthz` and `/readyz` tell the detail to: the app's one declaration,
     // the same list the web role reads. Unset, the node keeps its default (the box itself).
     ...healthDetailPeersOf(configuredHttp()?.healthDetailPeers),
+    clientAddressOf: syncClientAddressOf(options.env),
+    ...syncNodeCaps(options.runtime.realtime),
     // Tier 1 is presence, and without a registry the node answers a topic subscribe with no member
     // list at all — the KV bucket the transport just created would hold nothing and every `sync`
     // container would run a presence-less protocol. It reads and writes `transport.shared`, so it