@ultimat3/cli 23.0.0 → 25.0.0

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

@@ -35,7 +35,7 @@ export interface RuntimeOverrides {
   readonly mail?: MailDriver;
   /**
    * Replaces the `NATS_URL` selection. Already connected when it arrives, and NOT closed by
-   * `stop()`: whoever built it owns its socket, exactly as `createServer` does not close a
+   * `stop()`: whoever built it owns its socket, exactly as `httpServer` does not close a
    * `rateLimitStore` it was handed.
    */
   readonly transport?: Transport;
@@ -53,12 +53,12 @@ export interface RuntimeOverrides {
    */
   readonly rateLimitStore?: RateLimitStore;
   /**
-   * Where regenerated ISR pages live. Omitted, `createIsrController` keeps a per-process memory
+   * Where regenerated ISR pages live. Omitted, `isrController` keeps a per-process memory
    * store — twelve replicas then hold twelve of them, and a purge tag reaches one twelfth of the
    * fleet.
    */
   readonly isrStore?: IsrStore;
-  /** Prepended to the pipeline by `createServer`, which `startRoles` never passed one. */
+  /** Prepended to the pipeline by `httpServer`, which `startRoles` never passed one. */
   readonly middleware?: readonly Middleware[];
   /**
    * Plain HTTP routes at paths no primitive projects to — `/.well-known/oauth-authorization-server`,
@@ -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 (`postgresDigestStore({ 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,32 +7,34 @@
 import {
   type PostgresIdempotencyStore,
   postgresIdempotencyStore,
+  requestDeadlineMs,
   resetIdempotency,
   setIdempotencyStore,
 } from '@ultimat3/action';
 import type { DbClient, PgliteClient, PostgresClient, SqlFragment } from '@ultimat3/db';
 import {
-  createPgliteClient,
-  createPostgresClient,
+  baseClient,
   currentTx,
+  pgliteClient,
   pgliteDataDir,
-  raw,
+  postgresClient,
   setDbClient,
 } from '@ultimat3/db';
 import type { Tx } from '@ultimat3/entity';
 import type { EventBus, JobDriver, OutboxStore, PgExecutor } from '@ultimat3/jobs';
 import {
-  createJobsFacade,
-  createPgDriver,
-  createPgEventBus,
-  createPgOutboxStore,
+  outboxJobsFacade,
+  postgresEventBus,
+  postgresJobDriver,
+  postgresOutboxStore,
+  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';
@@ -97,11 +99,11 @@ export function startDb(services: DevServices, env: ReplicaEnv): StartedDb {
         // Linked at boot, from the app's own migrations: PGlite cannot `create extension` one it
         // was not handed, and the schema dump's scratch replay already asks this same reader — an
         // app that replayed in the gate and failed in `x dev` was the two disagreeing.
-        createPgliteClient({
+        pgliteClient({
           dataDir: pgliteDataDir(binding.url),
           extensions: () => appExtensions(services.root),
         })
-      : createPostgresClient({ url: binding.url });
+      : postgresClient({ url: binding.url });
   const attached = attachReplica(client, replicaUrlFor(binding, env));
   setDbClient(attached.client);
   return { client, replica: attached.replica };
@@ -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,23 +179,31 @@ 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 });
+  const driver = overrides?.jobs ?? postgresJobDriver({ executor });
   setJobDriver(driver);
-  const outbox = createPgOutboxStore({
+  const outbox = postgresOutboxStore({
     executor,
     // The open transaction is a client on its own connection; the `Tx` token is not that object.
     txExecutor: () => pgExecutorFor(currentTx() ?? client),
   });
   setJobsFacade(
-    createJobsFacade({ store: outbox, driver }, () => currentTx() as unknown as Tx | undefined),
+    outboxJobsFacade({ store: outbox, driver }, () => currentTx() as unknown as Tx | undefined),
   );
-  const events = createPgEventBus({ executor });
+  const events = postgresEventBus({ 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

package/src/runtime-realtime.ts

@@ -1,55 +1,21 @@
-// `realtime.enabled`, `realtime.transport` and `realtime.urlEnv`, read out of the app's own
-// `app.config.ts` for the boot. The sibling of `runtime-notify-retention.ts` and `runtime-cache.ts`, and
-// structural for their reason: `startServices` holds no `AppConfig`, and `defineConfig` returns a
-// plain object. Until 22.0.0 no boot read any of the three and `NATS_URL` alone decided the bus.
+// The `realtime` section for the boot, out of the config `startServices` loads once
+// (`app-config-load.ts`). Until 22.0.0 no boot read `enabled`, `transport` or `urlEnv` and
+// `NATS_URL` alone decided the bus; the two per-actor caps are read by the `sync` role.
 
-// 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 { ConfigInvalidError, type RealtimeConfig, type RealtimeTransport } from '@ultimat3/core';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import type { AppConfig, RealtimeConfig } from '@ultimat3/core';
 
-/** Core's `defaults()` for the section, restated as the answer for a config that names none. */
+/** Core's `defaults()` for the section — the answer for a root with no `app.config.ts`. */
 export const REALTIME_DEFAULTS: RealtimeConfig = Object.freeze({
   enabled: true,
   transport: 'memory',
   urlEnv: undefined,
+  maxSubscriptionsPerActor: undefined,
+  maxSocketsPerActor: undefined,
 });
 
-const TRANSPORTS: readonly RealtimeTransport[] = ['memory', 'nats'];
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-/** A transport this boot can build, or a refusal — never a guess at a bus. */
-function transportOf(section: Record<string, unknown>): RealtimeTransport {
-  const value = section['transport'];
-  if (value === undefined) return REALTIME_DEFAULTS.transport;
-  const known = TRANSPORTS.find((transport) => transport === value);
-  if (known !== undefined) return known;
-  throw new ConfigInvalidError({
-    cause: `realtime.transport in ${APP_CONFIG_FILE} is not one of ${TRANSPORTS.join(', ')}`,
-    fix: `set realtime: { transport: 'memory' } in ${APP_CONFIG_FILE}, or { transport: 'nats', urlEnv: 'NATS_URL' } for more than one node`,
-    meta: { key: 'realtime.transport' },
-  });
-}
-
 /**
- * The section as the boot obeys it. A key the file does not name keeps core's default, the same
- * per-key merge `defineConfig` performs, so the boot and the app's own config object agree.
+ * The section as the boot obeys it — `defineConfig`'s per-key merge, so the boot and the app's own
+ * config object agree, and a transport nothing builds is core's `X_CONFIG_INVALID`.
  */
-export async function loadRealtimeConfig(root: string): Promise<RealtimeConfig> {
-  const path = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(path).exists())) return REALTIME_DEFAULTS;
-  const module = (await import(path)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  const section = isRecord(config) ? config['realtime'] : undefined;
-  if (!isRecord(section)) return REALTIME_DEFAULTS;
-  const { enabled, urlEnv } = section;
-  return {
-    enabled: typeof enabled === 'boolean' ? enabled : REALTIME_DEFAULTS.enabled,
-    transport: transportOf(section),
-    urlEnv: typeof urlEnv === 'string' && urlEnv.trim() !== '' ? urlEnv.trim() : undefined,
-  };
-}
+export const realtimeConfigOf = (config: AppConfig | undefined): RealtimeConfig =>
+  config?.realtime ?? REALTIME_DEFAULTS;