@ultimat3/cli 22.15.0 → 24.0.0

package/src/runtime-assets.ts

@@ -9,7 +9,7 @@ import { probeImage } from '@ultimat3/core';
 import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
 import type { ImageQuery, ImageTransformDriver } from '@ultimat3/seo';
-import { builtinImageDriver, DEFAULT_WIDTHS, parseImageQuery } from '@ultimat3/seo';
+import { builtinImageDriver, DEFAULT_WIDTHS, parseImageQuery, usableWidths } from '@ultimat3/seo';
 import type { ImageTransform, Storage, VariantFormat } from '@ultimat3/storage';
 import { isTenantScoped, isVariantFormat, variantKey } from '@ultimat3/storage';
 import { faviconRoute } from './favicon';
@@ -29,6 +29,7 @@ import {
 } from './runtime-storage';
 import { siteAssetRoutes } from './site-asset-routes';
 import { siteAssetTable } from './site-assets';
+import { storedObjectHeaders } from './stored-object-headers';
 
 /**
  * Storage-backed images. `responsiveImage({ src: '/media/<key>' })` mints its variants under it.
@@ -58,21 +59,24 @@ const IMMUTABLE_IMAGE: CacheHint = { mode: 'immutable' };
  * blast radius and does not close it: 8192 stored objects per source, per format, is amplification
  * a tenant drives with a `for` loop.
  *
- * The set is `DEFAULT_WIDTHS` **plus the source's intrinsic width**, which is exactly what
- * `usableWidths` puts in a `srcset` — clamping to the constant alone would refuse the widest entry
- * of every image whose intrinsic width is not one of the eight, a URL the framework mints itself.
+ * The set is `usableWidths(intrinsic, DEFAULT_WIDTHS)` — the function that writes the `srcset`,
+ * asked rather than restated. A restatement (`DEFAULT_WIDTHS` plus the intrinsic width) disagreed
+ * with it for a source wider than `MAX_IMAGE_WIDTH`, whose widest candidate is the ceiling: that
+ * URL, minted by the framework itself, was decoded on every request and never stored.
  * Anything outside it is still SERVED: this decides what is written, not what is answered, so no
  * caller gains a new 4xx and the disk stops growing on a stranger's key.
  */
 const isMintableWidth = (width: number | undefined, intrinsic: number): boolean =>
-  width === undefined || width === intrinsic || DEFAULT_WIDTHS.includes(width);
+  width === undefined || usableWidths(intrinsic, DEFAULT_WIDTHS).includes(width);
 
 const imageResponse = (bytes: Uint8Array, contentType: string, cache: CacheHint): Response =>
   applyCacheHeaders(
     // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
     // `SharedArrayBuffer`, which `Response` does not accept, and copying is what makes that true
     // by construction rather than by a cast that would only silence it.
-    new Response(new Uint8Array(bytes), { headers: { 'content-type': contentType } }),
+    new Response(new Uint8Array(bytes), {
+      headers: { 'content-type': contentType, ...storedObjectHeaders(contentType) },
+    }),
     cache,
   );
 
@@ -174,7 +178,7 @@ export interface AssetRoutesOptions {
   /** App root. The source icon is resolved against it; storage keys never are. */
   readonly root: string;
   readonly storage: Storage;
-  /** Replaces `builtinImageDriver` for `/media/*`. Omitted, core's PNG/JPEG pipeline. */
+  /** Replaces `builtinImageDriver` for `/media/*`. Omitted, core's PNG/JPEG/WebP pipeline. */
   readonly images?: ImageTransformDriver;
   /**
    * `manifest.webmanifest`, resolved at boot by `pwa-artifacts.ts`. Absent when the app declares

package/src/runtime-bindings.ts

@@ -24,10 +24,10 @@ 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;
 }

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-hooks.ts

@@ -1,8 +1,8 @@
-// The two seams `@ultimat3/http` leaves open, bound to the packages that own them. `authorize`
+// The seams `@ultimat3/http` leaves open, bound to the packages that own them. `authorize`
 // 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 } from '@ultimat3/action';
+import { actorOf, explainActionPathMiss } from '@ultimat3/action';
 import type { AuthzDecision, ServerHooks } from '@ultimat3/http';
 import { asCtx, configuredAuthenticator } from '@ultimat3/http';
 import type { KnownPermission, Policy } from '@ultimat3/policy';
@@ -57,6 +57,9 @@ export function devHooks(options: DevHookOptions = {}): ServerHooks {
     ...(authenticate === undefined ? {} : { authenticate }),
     ...(devNotices === undefined ? {} : { devNotices }),
     ...(errorPage === undefined ? {} : { errorPage }),
+    // Every web role, `x dev` and the container alike: a caller that derived an action's URL under
+    // the wrong `pathStyle` is told which one this app serves, not that no route exists.
+    explainMiss: explainActionPathMiss,
     authorize: (route, _request, ctx): AuthzDecision => {
       // An action route never arrives here: it carries `enforcedBy: 'handler'`, so the pipeline
       // never asks. `invoke` is its one evaluation, and the only one holding the row a row-level

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),
   ];
 }