@ultimat3/cli 23.0.0 → 24.0.0

package/src/runtime-cache.ts

@@ -4,8 +4,6 @@
 // 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,
@@ -19,11 +17,9 @@ import {
   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,
@@ -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-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.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 { createIsrController } 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 = createIsrController({
+    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,14 +1,9 @@
 // `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.
+// `app.config.ts` for the `worker` role, out of the config `startServices` loads once. Until 22.0.0
+// `createWorker` was called with none of them, so a `mail` queue ran nothing.
 
-// why: Bun ships no path-joining API — `Object.keys(Bun)` has `file`, `write`, `Glob`,
-// `pathToFileURL` and `fileURLToPath`, and nothing that joins a path.
-import { join } from 'node:path';
+import type { AppConfig } from '@ultimat3/core';
 import { registeredJobs, type WorkerOptions } from '@ultimat3/jobs';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
 
 /** What the worker takes from the config. An absent number keeps the worker's own default. */
 export interface WorkerConfig {
@@ -17,37 +12,17 @@ export interface WorkerConfig {
   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: [],
   concurrency: undefined,
   visibilityTimeoutMs: undefined,
 });
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-/**
- * A number is handed on AS WRITTEN, never screened here: `createWorker`'s `resolveWorkerTimings`
- * is the one refusal for a non-finite knob, and core's `defineConfig` screens both counts first.
- */
-const numberOf = (value: unknown): number | undefined =>
-  typeof value === 'number' ? value : undefined;
-
-export async function loadWorkerConfig(root: string): Promise<WorkerConfig> {
-  const path = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(path).exists())) return NO_WORKER_CONFIG;
-  const module = (await import(path)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  const jobs = isRecord(config) ? config['jobs'] : undefined;
-  if (!isRecord(jobs)) return NO_WORKER_CONFIG;
-  const queues = Array.isArray(jobs['queues'])
-    ? jobs['queues'].filter((queue): queue is string => typeof queue === 'string' && queue !== '')
-    : [];
-  return {
-    queues,
-    concurrency: numberOf(jobs['concurrency']),
-    visibilityTimeoutMs: numberOf(jobs['visibilityTimeoutMs']),
-  };
+export function workerConfigOf(config: AppConfig | undefined): WorkerConfig {
+  if (config === undefined) return NO_WORKER_CONFIG;
+  const { queues, concurrency, visibilityTimeoutMs } = config.jobs;
+  return { queues, concurrency, visibilityTimeoutMs };
 }
 
 /**

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 { BuiltinAdapter, countUnsealedMfaSecrets } 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: new BuiltinAdapter(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;
+}

package/src/runtime-notify-retention.ts

@@ -1,18 +1,8 @@
-// `notify.inboxReadRetentionMs` and `notify.inboxUnreadRetentionMs`, read out of the app's own
-// `app.config.ts`. The sibling of `app-auth.ts`'s `loadSignInPath` and `runtime-cache.ts`'s
-// `loadCacheTiers`, and structural for the same reason: `defineConfig` returns a plain object, so
-// a config that resolved through an older core simply has no `notify` section.
-//
-// WHY A LOADER AND NOT A BOOT ARGUMENT: `startServices` has no `AppConfig` — the app's modules
-// import after it, which is the same reason `configureAuthLimiters` takes a factory. A key read
-// here is a key read from the file the operator edited, per boot.
+// `notify.inboxReadRetentionMs` and `notify.inboxUnreadRetentionMs`, out of the config
+// `startServices` loads once (`app-config-load.ts`) — before the app's modules import, so the window
+// is read from the file the operator edited, per boot.
 
-// 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 { INBOX_RETENTION_KEYS } from '@ultimat3/core';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import type { AppConfig } from '@ultimat3/core';
 
 /**
  * The two windows in milliseconds, each `undefined` where the app named none.
@@ -32,38 +22,12 @@ export const NO_INBOX_RETENTION: InboxRetention = Object.freeze({
   unreadMs: undefined,
 });
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
 /**
- * Re-screened here rather than trusted from `defineConfig`. That validator runs when the app
- * IMPORTS its config, and this loader imports the module for its export — so a config object
- * assembled by hand, or one that resolved through a core too old to validate the section, reaches
- * this line unchecked. A window that is not a positive finite number reads as absent: refusing
- * would take the sweep over the other four framework tables down with it, and the whole point of
- * the key is that not sweeping is a legal state.
+ * Core's validator (through the loader) refuses a window that is not a positive finite number, so
+ * a `NaN` cutoff — every row older than it, the inbox emptied on the first pass — cannot reach here.
  */
-const windowOf = (section: Record<string, unknown>, key: string): number | undefined => {
-  const value = section[key];
-  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return undefined;
-  return value;
-};
-
-export async function loadInboxRetention(root: string): Promise<InboxRetention> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  // `Bun.file(p).exists()` rather than `existsSync`: this function is already async, so the
-  // `node:fs` import buys nothing here — and an import with nothing to say for itself is what
-  // `bun run node-imports` refuses.
-  if (!(await Bun.file(configPath).exists())) return NO_INBOX_RETENTION;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!isRecord(config)) return NO_INBOX_RETENTION;
-  const notify = config['notify'];
-  if (!isRecord(notify)) return NO_INBOX_RETENTION;
-  // Keyed off core's own list rather than two string literals here, so the two names exist in one
-  // place. What actually stops a third window being declared-and-never-read is
-  // `bun run scripts/config-readers.ts` — every leaf key of `AppConfig` needs a reader or a pinned
-  // reason, and it is the guard whose own header calls that "the framework's most repeated defect".
-  const [readKey, unreadKey] = INBOX_RETENTION_KEYS;
-  return { readMs: windowOf(notify, readKey), unreadMs: windowOf(notify, unreadKey) };
+export function inboxRetentionOf(config: AppConfig | undefined): InboxRetention {
+  const notify = config?.notify;
+  if (notify === undefined) return NO_INBOX_RETENTION;
+  return { readMs: notify.inboxReadRetentionMs, unreadMs: notify.inboxUnreadRetentionMs };
 }

package/src/runtime-overrides.ts

@@ -69,7 +69,7 @@ export interface RuntimeOverrides {
    * answers a document, and a protocol that fixes its own error shape is neither.
    */
   readonly routes?: readonly Route[];
-  /** The `/media/*` transform. Omitted, `builtinImageDriver` — core's PNG/JPEG pipeline. */
+  /** The `/media/*` transform. Omitted, `builtinImageDriver` — core's PNG/JPEG/WebP pipeline. */
   readonly images?: ImageTransformDriver;
   /**
    * Who is dialling the `sync` node. Omitted, the app's own `configureAuthenticator()` is adapted

package/src/runtime-purge.ts

@@ -1,10 +1,11 @@
 // The retention sweep this boot owns: the framework tables that grow with traffic, the `purge()`
 // job that empties them and the `task` that fires it hourly.
 //
-// FIVE TARGETS over six tables, `As of 2026-08-27` — `x_idempotency`, `x_rate_limit`, the two
-// `x_auth` tables under one target, `x_notify_deliveries` and `x_notify_inbox`. Counted nowhere in
-// prose but here: this header said "three" for two releases after the notify tables joined the
-// boot's DDL, which is how `x_notify_inbox` became the one framework table nothing swept.
+// SEVEN TARGETS over seven tables, `As of 2026-10-02` — `x_idempotency`, `x_rate_limit`, the
+// `x_auth` limiter's table, `x_notify_deliveries`, `x_notify_inbox`, `x_notify_digests` and
+// `x_job_events`. Counted nowhere in prose but here: this header said "three" for two releases
+// after the notify tables joined the boot's DDL, which is how `x_notify_inbox` became the one
+// framework table nothing swept.
 //
 // WHY here and not in the packages that own the tables: `postgresIdempotencyStore` (tier 3),
 // `postgresRateLimitStore` (tier 2) and `postgresAuthLimiter` (tier 2) cannot see each other and
@@ -20,9 +21,16 @@
 import type { PostgresIdempotencyStore } from '@ultimat3/action';
 import { purgeAuthLimits } from '@ultimat3/auth';
 import type { PostgresRateLimitStore } from '@ultimat3/http';
-import type { JobHandle, PurgeInput, PurgeTarget } from '@ultimat3/jobs';
-import { DEFAULT_PURGE_CRON, getJob, getTask, purge, task } from '@ultimat3/jobs';
-import { purgeNotifyDeliveries, purgeNotifyInbox } from '@ultimat3/notify';
+import type { EventBus, JobHandle, PurgeInput, PurgeTarget } from '@ultimat3/jobs';
+import {
+  DEFAULT_PURGE_CRON,
+  eventsPurgeTarget,
+  getJob,
+  getTask,
+  purge,
+  task,
+} from '@ultimat3/jobs';
+import { purgeNotifyDeliveries, purgeNotifyDigests, purgeNotifyInbox } from '@ultimat3/notify';
 import type { InboxRetention } from './runtime-notify-retention';
 import { NO_INBOX_RETENTION } from './runtime-notify-retention';
 
@@ -32,7 +40,7 @@ export const PURGE_JOB_NAME = 'x.purge';
 export const PURGE_TASK_NAME = 'x.purge.hourly';
 
 /**
- * The two stores this boot BUILT, handed over rather than rebuilt here. A second
+ * The stores this boot BUILT, handed over rather than rebuilt here. A second
  * `postgresIdempotencyStore({ executor })` would sweep on the default window even where the boot
  * had configured another — two answers to "how long is a record kept", and the shorter one
  * deletes reservations a retry is still entitled to.
@@ -45,15 +53,22 @@ export interface RetentionStores {
   readonly idempotency: PostgresIdempotencyStore;
   readonly rateLimit: PostgresRateLimitStore;
   /**
-   * The app's own answer to "how long is an unread message kept", loaded from `app.config.ts` by
-   * `loadInboxRetention`. Absent windows mean the inbox is never swept, which is the default and a
-   * decision rather than an oversight — see `NotifyConfig` in `@ultimat3/core`.
+   * The bus this boot installed for `step.waitForEvent`. REQUIRED: `x_job_events` takes a row per
+   * publish and `find` only filters an expired one, so a boot that left it out is the table
+   * growing for the life of the deployment — which it did until this member existed.
+   */
+  readonly events: EventBus;
+  /**
+   * The app's own answer to "how long is an unread message kept", read off the config
+   * `startServices` loads (`inboxRetentionOf`). Absent windows mean the inbox is never swept,
+   * which is the default and a decision rather than an oversight — see `NotifyConfig` in
+   * `@ultimat3/core`.
    */
   readonly inboxRetention?: InboxRetention | undefined;
 }
 
 /**
- * The two notify tables, and neither store is in `RetentionStores` — deliberately, and for the
+ * The three notify tables, and no store is in `RetentionStores` — deliberately, and for the
  * reason `authTarget` is not either. `setNotifyStores` is an APP's boot line and runs when the
  * app's modules import, which is AFTER this install; `framework-schema.ts` says so where it
  * applies the DDL "whether or not this boot calls `setNotifyStores`". So the sweep can only ask,
@@ -79,6 +94,12 @@ function notifyTargets(retention: InboxRetention): readonly PurgeTarget[] {
             retention.unreadMs === undefined ? undefined : new Date(nowMs - retention.unreadMs),
         }),
     },
+    {
+      name: 'x_notify_digests',
+      // The job's clock, and the store's own window (`createPgDigestStore({ retentionMs })`, a week
+      // by default) — a closed window only its dead-lettered flush would ever have drained.
+      purgeExpired: (nowMs: number): Promise<number> => purgeNotifyDigests(nowMs),
+    },
   ];
 }
 
@@ -94,14 +115,13 @@ let installed: readonly PurgeTarget[] = [];
 let sweep: JobHandle<PurgeInput> | undefined;
 
 /**
- * `x_auth_failures` and `x_auth_lockouts` together, under the prefix they share: one target,
- * because `purgeAuthLimits()` clears both in one statement and two targets under one pair of
- * tables would be a second delete that removes nothing.
+ * `x_auth_lockouts` — every credential bucket, one row per key. The target keeps the `x_auth`
+ * name it has always reported under: it is what a dashboard and `PurgeReport.swept` already key on.
  */
 const authTarget: PurgeTarget = {
   name: 'x_auth',
   // No `nowMs`: a limiter built through the seam holds the clock its host handed it, which is the
-  // clock every `at_ms` in those tables was written from.
+  // clock every instant in that table was written from.
   purgeExpired: () => purgeAuthLimits(),
 };
 
@@ -121,6 +141,8 @@ function retentionTargets(stores: RetentionStores): readonly PurgeTarget[] {
     },
     authTarget,
     ...notifyTargets(stores.inboxRetention ?? NO_INBOX_RETENTION),
+    // Its own clock, and so no `nowMs`: every instant in that table is the database's.
+    eventsPurgeTarget(stores.events),
   ];
 }
 

package/src/runtime-queue.ts

@@ -7,16 +7,17 @@
 import {
   type PostgresIdempotencyStore,
   postgresIdempotencyStore,
+  requestDeadlineMs,
   resetIdempotency,
   setIdempotencyStore,
 } from '@ultimat3/action';
 import type { DbClient, PgliteClient, PostgresClient, SqlFragment } from '@ultimat3/db';
 import {
+  baseClient,
   createPgliteClient,
   createPostgresClient,
   currentTx,
   pgliteDataDir,
-  raw,
   setDbClient,
 } from '@ultimat3/db';
 import type { Tx } from '@ultimat3/entity';
@@ -26,13 +27,14 @@ import {
   createPgDriver,
   createPgEventBus,
   createPgOutboxStore,
+  resetEventBus,
   resetJobDriver,
   resetJobsFacade,
   setEventBus,
   setJobDriver,
   setJobsFacade,
 } from '@ultimat3/jobs';
-import { applyFrameworkSchema } from './framework-schema';
+import { applyLockedSchema, verifySchema } from './framework-schema-apply';
 import { appExtensions } from './migration-extensions';
 import type { DevServices } from './runtime-bindings';
 import type { RuntimeOverrides } from './runtime-overrides';
@@ -134,10 +136,18 @@ export function pgExecutorFor(client: DbClient): PgExecutor {
  * `@ultimat3/notify` because a package that holds no database dependency cannot apply its own
  * schema — the same reason `SQL_JOBS_TABLE` is applied by the boot.
  */
-async function applySchema(client: DevDbClient): Promise<void> {
-  await applyFrameworkSchema((statement) => client.execute(raw(statement)));
-}
+/**
+ * `'apply'` — `ROLE=migrate`, `x dev` and every CLI command — runs the DDL under the migration
+ * lock with a bounded `lock_timeout` and stamps the build. `'verify'` — a serving role on an
+ * external database — runs none: an `alter table` queued behind one open transaction stalled every
+ * enqueue in the fleet on each pod start, and racing `create table`s were a first-deploy `23505`.
+ */
+export type SchemaMode = 'apply' | 'verify';
 
+async function applySchema(client: DevDbClient, mode: SchemaMode): Promise<void> {
+  if (mode === 'verify') await verifySchema(client);
+  else await applyLockedSchema(client);
+}
 /**
  * The dev queue is the real Postgres queue on the embedded Postgres — claiming, leases and the
  * one-live-job-per-key index all behave here exactly as in production. A memory queue in dev
@@ -169,9 +179,10 @@ async function applySchema(client: DevDbClient): Promise<void> {
 async function startJobs(
   client: DevDbClient,
   replica: PostgresClient | undefined,
-  overrides?: RuntimeOverrides,
+  overrides: RuntimeOverrides | undefined,
+  schema: SchemaMode,
 ): Promise<RunningQueue> {
-  await applySchema(client);
+  await applySchema(client, schema);
   const executor = pgExecutorFor(client);
   const driver = overrides?.jobs ?? createPgDriver({ executor });
   setJobDriver(driver);
@@ -185,7 +196,14 @@ async function startJobs(
   );
   const events = createPgEventBus({ executor });
   setEventBus(events);
-  const idempotency = postgresIdempotencyStore({ executor });
+  const idempotency = postgresIdempotencyStore({
+    executor,
+    // `baseClient`, read per call and never `client`: a transaction's origin is the AMBIENT client
+    // `startDb` installed, which is the replicated pair when a standby is configured.
+    origin: baseClient,
+    // The app's own `requestTimeoutMs`, read per reservation — it is declared after this boot.
+    reclaimAfterMs: requestDeadlineMs,
+  });
   setIdempotencyStore(idempotency);
   return {
     db: client,
@@ -204,7 +222,8 @@ async function startJobs(
  * startup entirely, so every query it makes fails on a connection this process already dropped.
  *
  * The facade goes with the driver for the same reason: an enqueue routed through a store bound to
- * a closed client is a staged row nothing will ever publish.
+ * a closed client is a staged row nothing will ever publish — and the event bus with both, or a
+ * `publishEvent` after `stop()` runs over the closed pool.
  */
 async function releaseQueue(
   db: DevDbClient,
@@ -215,6 +234,7 @@ async function releaseQueue(
   // holds this client, and the next command in this process would reserve keys over a closed one.
   resetIdempotency();
   resetJobsFacade();
+  resetEventBus();
   resetJobDriver();
   setDbClient(undefined);
   await jobs?.close?.();
@@ -239,13 +259,14 @@ export async function startQueue(
    * this file reads it: see `startDb` for what two readers of one question cost.
    */
   env: ReplicaEnv = process.env,
+  schema: SchemaMode = 'apply',
 ): Promise<RunningQueue> {
   const { client: db, replica } = startDb(services, env);
   try {
     // Pay the Postgres boot here, so the first request is not the slow one and a broken database
     // fails at boot rather than on some later query.
     await db.ping();
-    return await startJobs(db, replica, overrides);
+    return await startJobs(db, replica, overrides, schema);
   } catch (error) {
     // `db.ping()` or `startJobs` is where a broken database is supposed to fail. Without this,
     // the caller exits holding the PGlite lock and the ambient accessors, and nothing is left to