@ultimat3/cli 23.0.0 → 25.0.0

package/src/runtime-bindings.ts

@@ -24,19 +24,39 @@ export interface DevServices {
   readonly storage: ServiceBinding;
   readonly stateDir: string;
   /**
-   * The app directory itself, carried rather than re-derived from `stateDir`. A boot that needs to
-   * read the app's own `app.config.ts` — `loadInboxRetention` does — otherwise has to undo the
-   * `join(root, '.x')` above, and a `dirname` that silently disagrees with this file's join is a
-   * path bug nothing would catch.
+   * The app directory itself, carried rather than re-derived from `stateDir`. A boot that needs
+   * to read the app's own `app.config.ts` — `startServices`' `loadAppConfig` does — otherwise has
+   * to undo the `join(root, '.x')` above, and a `dirname` that silently disagrees with this
+   * file's join is a path bug nothing would catch.
    */
   readonly root: string;
 }
 
 export type Env = Readonly<Record<string, string | undefined>>;
 
+/**
+ * An embedded binding's `url`: `<scheme>://` and then the HOST path, verbatim — a scheme-tagged
+ * path, NOT a URL. `pglite://D:\\app\\.x\\pgdata` is what Windows gets, and no URL parser reads it
+ * back (a `\\` is not a separator to one, a space would need encoding). Nothing parses it: db's
+ * `pgliteDataDir` and `startStorage` strip the prefix, and the report goes through `safeUrlLabel`,
+ * which answers the binding's name for anything that is not a URL. `Bun.pathToFileURL` was the
+ * other option, and would have made both readers decode as well as strip.
+ */
+export const embeddedLocation = (scheme: 'pglite' | 'file', path: string): string =>
+  `${scheme}://${path}`;
+
 const nonEmpty = (value: string | undefined): string | undefined =>
   value === undefined || value.trim().length === 0 ? undefined : value;
 
+const s3EndpointOf = (env: Env): string | undefined => nonEmpty(env['S3_ENDPOINT']);
+
+/**
+ * THE storage choice: a non-empty `S3_ENDPOINT` is object storage, anything else the embedded disk
+ * — which alone mints its own signed URLs and so needs `STORAGE_SIGNING_SECRET`. Exported so the
+ * deploy contract (`framework-env.ts`) asks this function rather than restating the rule.
+ */
+export const storageIsExternal = (env: Env): boolean => s3EndpointOf(env) !== 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.
@@ -51,7 +71,7 @@ export function resolveServices(
   // (`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 s3Endpoint = nonEmpty(env['S3_ENDPOINT']);
+  const s3Endpoint = s3EndpointOf(env);
   // 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
@@ -67,7 +87,7 @@ export function resolveServices(
         ? {
             name: 'db',
             mode: 'embedded',
-            url: `pglite://${join(stateDir, 'pgdata')}`,
+            url: embeddedLocation('pglite', join(stateDir, 'pgdata')),
             detail: 'PGlite in this process — set DATABASE_URL to use a real Postgres',
           }
         : { name: 'db', mode: 'external', url: databaseUrl, detail: 'DATABASE_URL' },
@@ -77,7 +97,7 @@ export function resolveServices(
         ? {
             name: 'storage',
             mode: 'embedded',
-            url: `file://${join(stateDir, 'storage')}`,
+            url: embeddedLocation('file', join(stateDir, 'storage')),
             detail: 'local directory — set S3_ENDPOINT to use S3',
           }
         : { name: 'storage', mode: 'external', url: s3Endpoint, detail: 'S3_ENDPOINT' },

package/src/runtime-cache.ts

@@ -4,26 +4,22 @@
 // and lru unconditionally, redis on `REDIS_URL` and cdn on any real purge driver, so the key was
 // declared, validated at boot, documented, and read by nothing.
 
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
 import type { CacheTier, PurgeDriver } from '@ultimat3/cache';
 import {
   CacheDriverUnavailableError,
-  createCdnTier,
-  createLruTier,
-  createMemoTier,
-  createRedisTier,
+  cdnTier,
   isNoopPurgeDriver,
+  lruTier,
+  memoTier,
   receiveInvalidationBroadcast,
+  redisTier,
   registerInvalidationBroadcast,
   registerTier,
   resetTiers,
 } from '@ultimat3/cache';
-import type { CacheTierName } from '@ultimat3/core';
-import { CACHE_TIERS, defineConfig, logger, renderThrowable } from '@ultimat3/core';
+import type { AppConfig, CacheTierName } from '@ultimat3/core';
+import { backoffDelay, defineConfig, logger, renderThrowable } from '@ultimat3/core';
 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 './runtime-bindings';
 
 /**
@@ -41,11 +37,17 @@ export interface CacheTiersOptions {
   /**
    * `config.cache.tiers`, verbatim. REQUIRED, and that is the enforcement (axiom 3): a boot that
    * has not read the app's declaration cannot call this function at all — it is a type error, not
-   * a convention to remember. `loadCacheTiers` is what a boot holding only a root calls for it.
+   * a convention to remember. `cacheTiersOf` is what a boot holding the loaded config calls for it.
    */
   readonly tiers: readonly CacheTierName[];
+  /** The wait before re-subscribing after `attempt` failures (1-based). Injected by a test. */
+  readonly subscribeRetryMs?: ((attempt: number) => number) | undefined;
 }
 
+/** 1 s doubling to 30 s, full jitter: a bus that is down is retried without a fleet in lockstep. */
+const defaultSubscribeRetryMs = (attempt: number): number =>
+  backoffDelay({ attempt, base: 1_000, max: 30_000, jitter: 'full' });
+
 /**
  * The rungs an app that declares none gets — ASKED of `defineConfig` rather than written out, for
  * two reasons that point the same way: `defaults()` is private to `@ultimat3/core`, and a second
@@ -56,32 +58,9 @@ export const DEFAULT_CACHE_TIERS: readonly CacheTierName[] = defineConfig({
   name: 'cache-defaults',
 }).cache.tiers;
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-const isTierList = (value: unknown): value is readonly CacheTierName[] =>
-  Array.isArray(value) && value.every((entry) => CACHE_TIERS.some((name) => name === entry));
-
-/**
- * `cache.tiers` out of the app's own `app.config.ts` — the sibling of `app-auth.ts`'s
- * `loadSignInPath`, and structural for the same reason: `defineConfig` returns a plain object, and
- * a config that resolved through an older core simply has no `cache` section.
- *
- * A list this refuses cannot come from `defineConfig` — `validate()` rejects an unknown rung one
- * `await import` above this line — so the fallback is for a hand-written config object, and the
- * two rungs every app starts from are the honest answer for one.
- */
-export async function loadCacheTiers(root: string): Promise<readonly CacheTierName[]> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!existsSync(configPath)) return DEFAULT_CACHE_TIERS;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!isRecord(config)) return DEFAULT_CACHE_TIERS;
-  const cache = config['cache'];
-  if (!isRecord(cache)) return DEFAULT_CACHE_TIERS;
-  const { tiers } = cache;
-  return isTierList(tiers) ? tiers : DEFAULT_CACHE_TIERS;
-}
+/** `cache.tiers` out of the config `startServices` loads once; the defaults for a root with none. */
+export const cacheTiersOf = (config: AppConfig | undefined): readonly CacheTierName[] =>
+  config?.cache.tiers ?? DEFAULT_CACHE_TIERS;
 
 /**
  * `REDIS_URL` is the same "an unset variable means the embedded default" law the db, events,
@@ -106,9 +85,9 @@ function redisUrl(env: Env): string | undefined {
 function buildTier(name: CacheTierName, options: CacheTiersOptions): CacheTier {
   switch (name) {
     case 'request-memo':
-      return createMemoTier();
+      return memoTier();
     case 'lru':
-      return createLruTier();
+      return lruTier();
     case 'redis':
       if (redisUrl(options.env) === undefined) {
         throw new CacheDriverUnavailableError({
@@ -118,7 +97,7 @@ function buildTier(name: CacheTierName, options: CacheTiersOptions): CacheTier {
           fix: 'set REDIS_URL in .env, or drop the redis tier from cache.tiers in app.config.ts',
         });
       }
-      return createRedisTier();
+      return redisTier();
     case 'cdn':
       // A noop tier would put a `cdn` line in every invalidation report claiming keys an edge that
       // does not exist had accepted — and the `/_x` cache panel renders those reports, so the lie
@@ -131,7 +110,7 @@ function buildTier(name: CacheTierName, options: CacheTiersOptions): CacheTier {
           fix: 'set FASTLY_API_TOKEN and FASTLY_SERVICE_ID in .env, or CLOUDFLARE_API_TOKEN and CLOUDFLARE_ZONE_ID, or drop the cdn tier from cache.tiers in app.config.ts',
         });
       }
-      return createCdnTier({ purge: options.purge });
+      return cdnTier({ purge: options.purge });
   }
 }
 
@@ -176,24 +155,36 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void>
   registerInvalidationBroadcast(async (wireTags) => {
     await options.transport.publish(CACHE_INVALIDATE_SUBJECT, JSON.stringify(wireTags));
   });
-  // Not awaited HERE: the boot must not block on a subscribe, and a bus that refuses one is a
-  // process that misses peer invalidations, never a process that fails to start. The PROMISE is
-  // held rather than a handle assigned inside a `.then`, because the release ran first whenever
-  // `stop()` beat the round trip — a NATS bus plus a boot that throws in `bootRoles`, or a test
-  // that boots and stops immediately — and the subscription that landed afterwards was live with
-  // nobody left holding it. `mcp-host.ts`'s lazy `started` is the same shape.
-  const subscribing: Promise<TransportSubscription | undefined> = options.transport
-    .subscribe(CACHE_INVALIDATE_SUBJECT, (payload: string) => {
-      void applyBroadcast(payload);
-    })
-    .catch((error: unknown) => {
-      logger.warn('cache.broadcast.subscribe-failed', { error: broadcastErrorText(error) });
-      return undefined;
-    });
+  // 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
+  // trip and the subscription that landed afterwards was live with nobody left holding it.
+  // RETRIED until it lands or the release runs (s1-con #8): a refused boot subscribe used to be
+  // logged once and never asked again, so the process missed every peer invalidation for its life.
+  const released = Promise.withResolvers<undefined>();
+  let stopped = false;
+  const retryMs = options.subscribeRetryMs ?? defaultSubscribeRetryMs;
+  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);
+        });
+      } catch (error) {
+        logger.warn('cache.broadcast.subscribe-failed', {
+          error: broadcastErrorText(error),
+          attempt,
+        });
+        await Promise.race([Bun.sleep(retryMs(attempt)), released.promise]);
+      }
+    }
+    return undefined;
+  })();
 
   // `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;
+    released.resolve(undefined);
     (await subscribing)?.unsubscribe();
     resetTiers();
   };

package/src/runtime-hooks.ts

@@ -2,7 +2,8 @@
 // decides for pages only, from the SAME `Policy` object every other surface evaluates — the route
 // table's declared permission — so a denial in `x dev` is the one production produces.
 
-import { actorOf, explainActionPathMiss } from '@ultimat3/action';
+import { explainActionPathMiss } from '@ultimat3/action';
+import { actorOf } from '@ultimat3/core';
 import type { AuthzDecision, ServerHooks } from '@ultimat3/http';
 import { asCtx, configuredAuthenticator } from '@ultimat3/http';
 import type { KnownPermission, Policy } from '@ultimat3/policy';

package/src/runtime-idempotency-scope.ts

@@ -0,0 +1,23 @@
+// A container boot over an idempotency store that keeps its records per process. The boot installs
+// the shared Postgres store (`runtime-queue.ts`); an app module that swapped in a per-process one
+// after it left `idempotent: true` meaning "once per replica" — with nothing to say so, because
+// `assertIdempotencyScope` only fires on a `'shared'` DECLARATION and nothing infers a replica count.
+
+import { getIdempotencyStore, type IdempotencyStore } from '@ultimat3/action';
+import { logger } from '@ultimat3/core';
+
+/** `true` when it warned. Said, not refused: one replica is a real deployment and is correct. */
+export function warnIfIdempotencyProcessScoped(
+  store: IdempotencyStore = getIdempotencyStore(),
+): boolean {
+  if (store.scope === 'shared') return false;
+  logger.warn('X_CONFIG_INVALID', {
+    code: 'X_CONFIG_INVALID',
+    cause:
+      'the idempotency store this process ended its boot with keeps records per process, so on more than one replica a retried idempotent action that lands on another replica runs its handler again — docker/helm/values.yaml runs roles.web.replicas: 3',
+    // Declaring the scope is the enforcement: `assertIdempotencyScope` then refuses the store.
+    fix: "configureIdempotency({ scope: 'shared' })",
+    scope: store.scope ?? 'undeclared',
+  });
+  return true;
+}

package/src/runtime-isr-outcome.ts

@@ -0,0 +1,100 @@
+// What one `isr` request is answered with: a page from the store, or the redirect ITS OWN `load`
+// decided. A returned discriminated outcome, never a throw: the controller's regeneration treats
+// anything thrown as a failure and logs it, and a redirect is an ordinary answer, not a failure.
+
+import type { RedirectIntent, RequestContext, RouteParams } from '@ultimat3/http';
+import { asCtx, takeRedirect } from '@ultimat3/http';
+import type { RenderResult, RouteData, RouteEntry } from '@ultimat3/render';
+import { routeDataFor, routeStatusOf } from '@ultimat3/render';
+import type { IsrController, IsrEntry } from '@ultimat3/render/server';
+import { isrKey } from '@ultimat3/render/server';
+
+export type IsrOutcome =
+  | { readonly kind: 'page'; readonly result: RenderResult }
+  | { readonly kind: 'redirect'; readonly to: RedirectIntent };
+
+export interface IsrRequest {
+  readonly entry: RouteEntry;
+  /** What `load` and `meta` are given; `url` is a string because that is what `ld.*` embeds. */
+  readonly data: { readonly url: string; readonly params: RouteParams } & Record<string, unknown>;
+  readonly ctx: RequestContext;
+  readonly isr: IsrController;
+  /** The route's whole document for what `load` returned (`runtime-render.ts`'s `documentFrom`). */
+  readonly document: (loaded: RouteData) => Promise<string>;
+}
+
+/**
+ * The producer's answer when `load` redirected. A 3xx status is never a page — `withStatus` refuses
+ * one by name, because a document has no `Location` — so a 3xx entry can only be this marker, and a
+ * request that JOINED the flight reads it as "the leader's load redirected for the leader".
+ */
+const isRedirectMarker = (entry: IsrEntry): boolean => {
+  // An entry stored before statuses were (`status` absent) is a 200, and never this marker.
+  const { status } = entry;
+  return status !== undefined && status >= 300 && status < 400;
+};
+
+/**
+ * A redirect means the key holds no page. Deleting drops the stale copy, so the next request is a
+ * miss and decides again. `markStale` records an invalidation of the key AFTER the regeneration's
+ * fence was sampled, and the controller refuses to store a render its fence no longer covers — so
+ * the marker this producer returns is never published, and never served from the store.
+ */
+function dropPage(isr: IsrController, key: string): void {
+  isr.store().delete(key);
+  isr.markStale(key);
+}
+
+/**
+ * `isr`: a store hit is answered WITHOUT `load` — resolving it before the mode choice, as every
+ * other mode does, made each hit cost a full SSR's database work. So `load` and its redirect live
+ * inside the producer, which runs on a miss and on a stale page's regeneration.
+ *
+ * Concurrent misses on one key share ONE producer run, and only a PAGE may be shared. A redirect is
+ * the request's own (its `load` may have read a cookie), so a request that joined a run whose load
+ * redirected decides for itself, exactly as the static single-flight in `appRoutes` does.
+ */
+export async function isrOutcome(request: IsrRequest): Promise<IsrOutcome> {
+  const { entry, data, ctx, isr } = request;
+  // `isrKey(url, locale)`, never `url.pathname`: the query is part of what was rendered — `meta`
+  // reads `data.url` — so two URLs differing only in their query are two documents (#171). The
+  // locale is `ctx.locale`, the one the `locale` stage negotiated for THIS request.
+  const key = isrKey(new URL(data.url), asCtx(ctx).locale);
+  let decided: RedirectIntent | undefined;
+  // `{ html, status }`, never the bare string: the entry stores the status beside the HTML and
+  // serves it on every hit, so a 404 under `isr` is a 404 for its whole TTL.
+  const served = await isr.serve(key, async () => {
+    const loaded = await routeDataFor(entry.config, data);
+    const to = takeRedirect(ctx);
+    if (to === undefined)
+      return { html: await request.document(loaded), status: routeStatusOf(loaded) };
+    // Set by THIS request's producer only. On a stale page it runs behind the answer, and when it
+    // has already decided by the time `serve` returns, the redirect is still this request's own.
+    decided = to;
+    dropPage(isr, key);
+    return { html: '', status: to.status };
+  });
+  if (decided !== undefined) return { kind: 'redirect', to: decided };
+  if (!isRedirectMarker(served.entry)) return { kind: 'page', result: served.result };
+  return ownOutcome(request);
+}
+
+/**
+ * A joiner whose leader's load redirected: its own `load`, answered for this request alone. A page
+ * here is NOT stored — the store was just told the key has none — so it is `private, no-store`;
+ * the next request to miss stores one.
+ */
+async function ownOutcome(request: IsrRequest): Promise<IsrOutcome> {
+  const loaded = await routeDataFor(request.entry.config, request.data);
+  const to = takeRedirect(request.ctx);
+  if (to !== undefined) return { kind: 'redirect', to };
+  const body = await request.document(loaded);
+  return {
+    kind: 'page',
+    result: {
+      status: routeStatusOf(loaded),
+      headers: { 'cache-control': 'private, no-store' },
+      body,
+    },
+  };
+}

package/src/runtime-isr.ts

@@ -0,0 +1,36 @@
+// The ISR controller a boot serves pages through: built, ATTACHED as the framework's revalidator,
+// and handed back with the detach the boot puts on its stop list. One function for `x dev` and the
+// container, so neither can build a controller `invalidateTags` never reaches (plan 101, s2-con #1).
+
+import type { IsrController, IsrStore } from '@ultimat3/render/server';
+import { isrController } from '@ultimat3/render/server';
+
+export interface AttachedIsr {
+  readonly isr: IsrController;
+  /** Detaches the revalidator and drops this controller's graph edges; idempotent. */
+  readonly release: () => void;
+}
+
+/**
+ * Unattached, a `revalidate: { tags }` page (no TTL) is fresh until invalidated — and nothing
+ * invalidates it: `invalidateTags` calls the registered revalidator, which was nobody.
+ */
+export function attachedIsr(options: {
+  readonly buildId: string;
+  readonly store?: IsrStore;
+}): AttachedIsr {
+  const isr = isrController({
+    buildId: options.buildId,
+    ...(options.store === undefined ? {} : { store: options.store }),
+  });
+  const detach = isr.attach();
+  let released = false;
+  return {
+    isr,
+    release: () => {
+      if (released) return;
+      released = true;
+      detach();
+    },
+  };
+}

package/src/runtime-jobs.ts

@@ -1,85 +1,120 @@
-// `jobs.queues`, `jobs.concurrency` and `jobs.visibilityTimeoutMs`, read out of the app's own
-// `app.config.ts` for the `worker` role — the sibling of `runtime-realtime.ts`, and structural
-// for its reason. Until 22.0.0 `createWorker` was called with none of them: every worker served
-// `default` at its own concurrency whatever the config said, so a `mail` queue ran nothing.
+// The queues a `worker` serves and the slots each gets: `jobs.queues`, `jobs.concurrency` and
+// `jobs.visibilityTimeoutMs` off the app's own `app.config.ts`, and `WORKER_QUEUES` off the
+// Deployment's env — the one per-Deployment answer, since every Deployment runs the same image and
+// the same config (issues #673, #676).
 
-// why: Bun ships no path-joining API — `Object.keys(Bun)` has `file`, `write`, `Glob`,
-// `pathToFileURL` and `fileURLToPath`, and nothing that joins a path.
-import { join } from 'node:path';
+import type { AppConfig, JobsConcurrency } from '@ultimat3/core';
+import { ConfigInvalidError, logger, renderCauseValue, renderFixShellArg } from '@ultimat3/core';
 import { registeredJobs, type WorkerOptions } from '@ultimat3/jobs';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import type { Env } from './runtime-bindings';
+
+/** The env key a worker Deployment names its queues with: `WORKER_QUEUES=banks,banks-long`. */
+export const WORKER_QUEUES_ENV = 'WORKER_QUEUES';
 
 /** What the worker takes from the config. An absent number keeps the worker's own default. */
 export interface WorkerConfig {
   readonly queues: readonly string[];
-  readonly concurrency: number | undefined;
+  /**
+   * `true` when `WORKER_QUEUES` named `queues`: they are served EXACTLY, never widened by the
+   * queues registered jobs are enqueued on. `false` is the union `workerQueuesFor` explains.
+   */
+  readonly exact: boolean;
+  readonly concurrency: JobsConcurrency | undefined;
   readonly visibilityTimeoutMs: number | undefined;
 }
 
+/** A root with no `app.config.ts`: no queue of its own, and the worker's own timings. */
 const NO_WORKER_CONFIG: WorkerConfig = Object.freeze({
   queues: [],
+  exact: false,
   concurrency: undefined,
   visibilityTimeoutMs: undefined,
 });
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
 /**
- * A number is handed on AS WRITTEN, never screened here: `createWorker`'s `resolveWorkerTimings`
- * is the one refusal for a non-finite knob, and core's `defineConfig` screens both counts first.
+ * `WORKER_QUEUES`, read: `undefined` when unset or blank (`ROLE`'s rule — an empty value is a
+ * template that said nothing), else its names trimmed and deduplicated in the order written. An
+ * empty entry (`banks,,long`) is REFUSED, not skipped: it is a queue somebody meant to name, and
+ * the worker that dropped it would leave that queue's jobs waiting with nothing in the log.
  */
-const numberOf = (value: unknown): number | undefined =>
-  typeof value === 'number' ? value : undefined;
+export function workerQueuesFromEnv(env: Env): readonly string[] | undefined {
+  const raw = env[WORKER_QUEUES_ENV];
+  if (raw === undefined || raw.trim() === '') return undefined;
+  const names = raw.split(',').map((name) => name.trim());
+  const named = [...new Set(names.filter((name) => name !== ''))];
+  if (!names.includes('')) return named;
+  throw new ConfigInvalidError({
+    cause: `${WORKER_QUEUES_ENV} ${renderCauseValue(raw)} contains an empty queue name — every comma-separated entry must name a queue`,
+    fix: `WORKER_QUEUES=${renderFixShellArg(named.join(','), '<queue>,<queue>')} on this Deployment — or unset WORKER_QUEUES to serve jobs.queues and every registered job's queue`,
+    meta: { key: WORKER_QUEUES_ENV },
+  });
+}
 
-export async function loadWorkerConfig(root: string): Promise<WorkerConfig> {
-  const path = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(path).exists())) return NO_WORKER_CONFIG;
-  const module = (await import(path)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  const jobs = isRecord(config) ? config['jobs'] : undefined;
-  if (!isRecord(jobs)) return NO_WORKER_CONFIG;
-  const queues = Array.isArray(jobs['queues'])
-    ? jobs['queues'].filter((queue): queue is string => typeof queue === 'string' && queue !== '')
-    : [];
-  return {
-    queues,
-    concurrency: numberOf(jobs['concurrency']),
-    visibilityTimeoutMs: numberOf(jobs['visibilityTimeoutMs']),
-  };
+export function workerConfigOf(config: AppConfig | undefined, env: Env = {}): WorkerConfig {
+  const fromEnv = workerQueuesFromEnv(env);
+  const base =
+    config === undefined
+      ? NO_WORKER_CONFIG
+      : {
+          queues: config.jobs.queues,
+          exact: false,
+          concurrency: config.jobs.concurrency,
+          visibilityTimeoutMs: config.jobs.visibilityTimeoutMs,
+        };
+  return fromEnv === undefined ? base : { ...base, queues: fromEnv, exact: true };
 }
 
 /**
  * The queues a worker serves: the configured ones, then every queue a registered job is enqueued
  * on. The union and not the list, decided 2026-09-23: `x new` and the deployed demo configure
  * `['<app>-default']` while a `job()` naming no queue lands on `default`, so obeying the list alone
- * would leave every such job queued for ever — the silent direction. `undefined` when both are
- * empty, which is `createWorker`'s own `['default']`.
+ * would leave every such job queued for ever — the silent direction. `exact` (a Deployment that
+ * set `WORKER_QUEUES`) is the list alone: that operator split the queues across Deployments on
+ * purpose, and widening one to the rest is what made their grace periods mean nothing (#673).
+ * `undefined` when nothing is served, which is `jobWorker`'s own `['default']`.
  */
 export function workerQueuesFor(
   configured: readonly string[],
   registered: readonly string[],
+  exact = false,
 ): readonly string[] | undefined {
-  const served = [...new Set([...configured, ...registered])];
+  const served = [...new Set(exact ? configured : [...configured, ...registered])];
   return served.length === 0 ? undefined : served;
 }
 
+/**
+ * An exact worker's one boot line about what it leaves: the queues registered jobs are enqueued
+ * on that it will never claim. A warning and not a refusal — another Deployment serving them is
+ * the whole point of the split — but this process cannot see that one, so it says what to check.
+ */
+function reportUnserved(served: readonly string[], registered: readonly string[]): void {
+  const queues = [...new Set(registered)].filter((queue) => !served.includes(queue)).sort();
+  if (queues.length === 0) return;
+  logger.warn('jobs.worker.queue-unserved', {
+    queues,
+    served,
+    fix: `x jobs ls --json — every queue listed with no worker needs one: WORKER_QUEUES=<queue>,<queue> on another worker Deployment, or add it to this one's`,
+  });
+}
+
 type WorkerConfigOptions = Pick<WorkerOptions, 'queues' | 'concurrency' | 'visibilityTimeoutMs'>;
 
 /**
- * The `createWorker` options the config supplies, read at START so every job the app registered
+ * The `jobWorker` options the config supplies, read at START so every job the app registered
  * on import is counted. A key the config leaves unset is omitted, never passed as `undefined`, so
  * the worker's own default applies (`exactOptionalPropertyTypes`).
  */
 export function workerOptionsFor(config: WorkerConfig | undefined): WorkerConfigOptions {
-  const queues = workerQueuesFor(
-    config?.queues ?? [],
-    registeredJobs().map((handle) => handle.queue),
-  );
+  const registered = registeredJobs().map((handle) => handle.queue);
+  const exact = config?.exact === true;
+  const queues = workerQueuesFor(config?.queues ?? [], registered, exact);
+  if (exact) reportUnserved(queues ?? [], registered);
+  // Passed as written: `jobWorker` reads a table by own key and runs a queue it does not name at
+  // core's `JOBS_CONCURRENCY_DEFAULT` — the one slot default, so no second table is built here.
+  const concurrency = config?.concurrency;
   return {
     ...(queues === undefined ? {} : { queues }),
-    ...(config?.concurrency === undefined ? {} : { concurrency: config.concurrency }),
+    ...(concurrency === undefined ? {} : { concurrency }),
     ...(config?.visibilityTimeoutMs === undefined
       ? {}
       : { visibilityTimeoutMs: config.visibilityTimeoutMs }),

package/src/runtime-live-feed.ts

@@ -1,5 +1,5 @@
 // Where a `sync` node's changes come from when this process boots one. Production decodes the
-// write-ahead log (`x dev --role replicator`, `PgLogicalReplicationFeed`, a real `DATABASE_URL`).
+// write-ahead log (`x dev --role replicator`, `postgresChangeFeed()`, a real `DATABASE_URL`).
 // The embedded database has no walsender, and until 2026-09-05 nothing stood in for it: a live
 // subscription under `x dev` took its snapshot and then heard nothing, so every `--live` query in
 // every scaffolded app was dead in development — which is where an author first tries one.

package/src/runtime-mail.ts

@@ -0,0 +1,26 @@
+// The `mail` section of `app.config.ts` the boot obeys: `mail.retainMime`, handed to
+// `@ultimat3/mail`'s `selectMailDriver` — the one option an environment cannot carry. Selection
+// still reads env for WHICH transport; the config only says what the chosen one keeps.
+
+import type { AppConfig } from '@ultimat3/core';
+import type { MailEnvironment, MailSelection, MailSelectOptions } from '@ultimat3/mail';
+import { selectMailDriver } from '@ultimat3/mail';
+
+/** No config file, or `retainMime: false`, is no option at all — never `retainMime: undefined`. */
+export function mailSelectOptionsOf(config: AppConfig | undefined): MailSelectOptions {
+  const retain = config?.mail.retainMime ?? false;
+  if (retain === false) return {};
+  return { retainMime: retain.maxBytes === undefined ? {} : { maxBytes: retain.maxBytes } };
+}
+
+/**
+ * The boot's mail selection. Pure, as `selectMailDriver` is: it builds a transport and dials
+ * nothing, so a cap above mail's ceiling or retention asked of Resend refuses the boot here.
+ */
+export const selectAppMailDriver = (
+  env: MailEnvironment,
+  config: AppConfig | undefined,
+): MailSelection =>
+  // `retainMimeKey`: mail judges the cap before it picks a transport — the ceiling is its number —
+  // and names the `app.config.ts` key in the refusal, so the boot restates no check of its own.
+  selectMailDriver(env, { ...mailSelectOptionsOf(config), retainMimeKey: 'mail.retainMime' });

package/src/runtime-mfa-warning.ts

@@ -0,0 +1,29 @@
+// The web role's boot asks once whether `x auth seal-mfa` still has work to do (wiki/Upgrading.md,
+// the operator step for sealed MFA secrets). `x doctor` asks the same question only when someone
+// runs it; an unsealed secret is a user refused at the second factor, so the boot says so too.
+
+import { countUnsealedMfaSecrets, postgresAuthAdapter } from '@ultimat3/auth';
+import { logger } from '@ultimat3/core';
+import type { DbClient } from '@ultimat3/db';
+
+/**
+ * Answers the count it logged, `0` when there was nothing to say or nothing could be asked. Never
+ * throws: a database that cannot answer this is the readiness check's to report, not a reason for
+ * a pod to refuse traffic its other users can be served.
+ */
+export async function warnUnsealedMfaSecrets(client: DbClient): Promise<number> {
+  let unsealed = 0;
+  try {
+    unsealed = await countUnsealedMfaSecrets({ adapter: postgresAuthAdapter(client) });
+  } catch {
+    return 0;
+  }
+  if (unsealed === 0) return 0;
+  logger.warn('X_MFA_SECRET_UNSEALED', {
+    code: 'X_MFA_SECRET_UNSEALED',
+    cause: `${unsealed} user(s) hold a second-factor secret that is not sealed; the framework never reads a plaintext secret, so each of them is refused at the second factor until it is sealed`,
+    fix: 'x auth seal-mfa --json',
+    unsealed,
+  });
+  return unsealed;
+}