@ultimat3/cli 7.0.0 → 9.0.0

package/src/dev-cache.ts

@@ -1,11 +1,14 @@
 // Which cache tiers this process reads through, and the hop that tells the other replicas what it
-// just dropped. `createMemoTier`, `createLruTier` and `createRedisTier` were built, exported and
-// tested with ZERO callers — `dev-runtime.ts` registered the CDN tier and nothing else — so every
-// cached read was recomputed on every replica on every request, and `registerInvalidationBroadcast`
-// had no one to register it.
+// just dropped. The ladder is exactly what `cache.tiers` names: a rung the config lists is built or
+// the boot refuses, and a rung it does not list is never built — this file used to register memo
+// 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,
@@ -16,8 +19,11 @@ import {
   registerTier,
   resetTiers,
 } from '@ultimat3/cache';
-import { logger } from '@ultimat3/core';
-import type { Transport, TransportSubscription } from '@ultimat3/realtime';
+import type { CacheTierName } from '@ultimat3/core';
+import { CACHE_TIERS, defineConfig, logger } 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 './dev-services';
 
 /**
@@ -29,24 +35,125 @@ export const CACHE_INVALIDATE_SUBJECT = 'x.cache.invalidate';
 
 export interface CacheTiersOptions {
   readonly env: Env;
-  /** Already resolved by the boot — the CDN tier is registered only for a real edge. */
+  /** Already resolved by the boot — a `cdn` rung is built against a real edge or not at all. */
   readonly purge: PurgeDriver;
   readonly transport: Transport;
+  /**
+   * `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.
+   */
+  readonly tiers: readonly CacheTierName[];
 }
 
 /**
- * The shared tier, or nothing. `REDIS_URL` is the same "an unset variable means the embedded
- * default" law the db, events, storage, mail and CDN bindings already follow — and it is the
- * variable Bun's own `Bun.redis` reads, so a tier selected here and a client built there cannot
- * point at two servers.
+ * 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
+ * literal list of rung names is a second vocabulary that `bun run render-modes` refuses (it caught
+ * exactly that here). One source, so the default cannot drift into a second ladder.
  */
-function sharedTier(env: Env): CacheTier | undefined {
+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;
+}
+
+/**
+ * `REDIS_URL` is the same "an unset variable means the embedded default" law the db, events,
+ * storage, mail and CDN bindings follow — and it is the variable Bun's own `Bun.redis` reads, so a
+ * tier selected here and a client built there cannot point at two servers.
+ */
+function redisUrl(env: Env): string | undefined {
   const url = env['REDIS_URL']?.trim();
-  return url === undefined || url === '' ? undefined : createRedisTier();
+  return url === undefined || url === '' ? undefined : url;
 }
 
 /**
- * Register the tiers, wire both halves of cross-instance invalidation, and return the release.
+ * One rung, or a refusal. A process that cannot build what it was configured to build must not
+ * start — `assertRateLimitScope`'s rule (`@ultimat3/http`), applied to the ladder: a fleet reading
+ * a per-process cache while `cache.tiers` declares a shared one is a stale-and-slow deployment
+ * that looks like a performance problem for a week.
+ *
+ * `X_CACHE_DRIVER_UNAVAILABLE` is BORROWED from `@ultimat3/cache` rather than twinned: "this tier
+ * cannot be built here" is what that code already means, and its shipped `fix:` is this one. The
+ * precedent is `dev-assets.ts` throwing `@ultimat3/pwa`'s `PwaIconMissingError`.
+ */
+function buildTier(name: CacheTierName, options: CacheTiersOptions): CacheTier {
+  switch (name) {
+    case 'request-memo':
+      return createMemoTier();
+    case 'lru':
+      return createLruTier();
+    case 'redis':
+      if (redisUrl(options.env) === undefined) {
+        throw new CacheDriverUnavailableError({
+          driver: 'redis',
+          cause:
+            'cache.tiers names it and REDIS_URL is unset, so this process would read a per-process ladder while the config declares a shared one',
+          fix: 'set REDIS_URL in .env, or drop the redis tier from cache.tiers in app.config.ts',
+        });
+      }
+      return createRedisTier();
+    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
+      // would be the thing an agent reads.
+      if (isNoopPurgeDriver(options.purge)) {
+        throw new CacheDriverUnavailableError({
+          driver: 'cdn',
+          cause:
+            'cache.tiers names it and no CDN credential is set, so every invalidation report would claim keys an edge that does not exist had accepted',
+          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 });
+  }
+}
+
+/**
+ * The one case where the declaration and the environment disagree and the boot still proceeds: a
+ * credential is set for a rung `cache.tiers` does not name. The config wins — it is the
+ * declaration, an env var is deployment detail — but silently paying for a Redis or an edge
+ * nothing reads is the same class of surprise the refusals above exist for, so it is said out loud.
+ */
+function warnUnnamed(options: CacheTiersOptions): void {
+  const named = new Set(options.tiers);
+  if (!named.has('redis') && redisUrl(options.env) !== undefined) {
+    logger.warn('cache.tier.unnamed', { tier: 'redis', source: 'REDIS_URL' });
+  }
+  if (!named.has('cdn') && !isNoopPurgeDriver(options.purge)) {
+    logger.warn('cache.tier.unnamed', { tier: 'cdn', source: options.purge.name });
+  }
+}
+
+/**
+ * Register the tiers the app declared, wire both halves of cross-instance invalidation, and return
+ * the release.
  *
  * The outbound half publishes the wire tags this process just dropped; the inbound half applies
  * another instance's. A message this process published is delivered back to it on every real bus
@@ -56,25 +163,15 @@ function sharedTier(env: Env): CacheTier | undefined {
  * suppresses it, and `emit` is not a public parameter.
  */
 export function startCacheTiers(options: CacheTiersOptions): () => Promise<void> {
-  // Request-scoped memo first, then the process-local LRU: both are free of external state, so
-  // they are the "embedded default" that needs no variable to switch on. Registration order does
-  // not decide read order — `sortTiers` does — but it is written in read order anyway.
-  registerTier(createMemoTier());
-  registerTier(createLruTier());
-  const shared = sharedTier(options.env);
-  if (shared !== undefined) registerTier(shared);
-  // Nothing installs a read tier here, and that is the point. `@ultimat3/query` used to own a
-  // private `ReadCache` this boot had to hand-wire over one of the objects above, because
-  // `invalidateTags` fans out to registered tiers and to nothing else — so a read cache holding
-  // entries of its own was a `cache:` query an action's `invalidates` could never bust. The seam
-  // is gone: a `cache:` read fills the ladder registered here, so there is one registry and one
-  // fan-out and no wiring to get wrong.
-  // Registered only when a credential named a real edge. 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 would be the thing an agent reads.
-  if (!isNoopPurgeDriver(options.purge)) {
-    registerTier(createCdnTier({ purge: options.purge }));
-  }
+  // Built before ANY of them is registered: a refusal halfway through a list would leave the
+  // process-global registry holding the rungs that came first, with no release returned to drop
+  // them. Registration order does not decide read order — `sortTiers` does, by `CACHE_TIERS`.
+  // Nothing installs a read tier beyond these, and that is the point: `invalidateTags` fans out to
+  // registered tiers and to nothing else, so a read cache holding entries of its own was a
+  // `cache:` query an action's `invalidates` could never bust.
+  const built = options.tiers.map((name) => buildTier(name, options));
+  for (const tier of built) registerTier(tier);
+  warnUnnamed(options);
 
   registerInvalidationBroadcast(async (wireTags) => {
     await options.transport.publish(CACHE_INVALIDATE_SUBJECT, JSON.stringify(wireTags));

package/src/dev-lock.ts

@@ -14,11 +14,12 @@
 // The lock file is what makes the second one nameable at all: nothing else in the process can tell
 // "another dev server owns this directory" from "the database is broken".
 
-import { unlinkSync } from 'node:fs';
+import { closeSync, mkdirSync, openSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { UltimateError } from '@ultimat3/core';
 import { docsFor } from './error-codes';
 import { exec, type Runner } from './exec';
+import { quoteArg } from './shell-quote';
 
 /** Where the running dev server records itself, inside the state directory it already owns. */
 export const DEV_LOCK_FILE = 'dev.lock';
@@ -101,6 +102,28 @@ export class DevAlreadyRunningError extends UltimateError {
   }
 }
 
+/**
+ * The lock file exists, this process could not read it and could not remove it — which is not
+ * "another x dev is running", and was reported as exactly that.
+ *
+ * `DevAlreadyRunningError` needs a `DevLock`, and the only one in hand on that path was `mine`:
+ * the refusal then read `pid <this process> is already running x dev` with `fix: … kill <this
+ * process>`, a remedy that kills the reader and a cause naming the wrong holder. Axiom 4 wants a
+ * runnable fix and an honest cause, so the honest answer is its own code — the file is the
+ * problem, and removing it is what a reader can actually do.
+ */
+export class DevLockUnreadableError extends UltimateError {
+  constructor(input: { readonly path: string; readonly stateDir: string }) {
+    super({
+      code: 'X_DEV_LOCK_UNREADABLE',
+      cause: `${input.path} could not be parsed as a dev lock and could not be removed, so x dev cannot tell whether another process owns ${input.stateDir}`,
+      fix: `rm ${quoteArg(input.path)}   # then re-run x dev`,
+      docs: docsFor('X_DEV_LOCK_UNREADABLE'),
+      meta: { path: input.path, stateDir: input.stateDir },
+    });
+  }
+}
+
 /** Whatever is listening, as far as the OS will say. Both fields absent when it will not say. */
 export interface PortHolder {
   readonly pid?: number;
@@ -207,6 +230,41 @@ export const isPortBound = (port: number, hostname: string): boolean => {
   }
 };
 
+/**
+ * Take the lock, or answer `false` because someone else holds it.
+ *
+ * `wx` is the whole mechanism: the create and the exclusivity are ONE syscall, so two boots racing
+ * this cannot both come back `true`. A check followed by a write is what this replaces, and the
+ * window between those two was seconds wide — `startDev` boots embedded Postgres, the queue, the
+ * transport and the app's modules before anything was written down.
+ *
+ * Only `EEXIST` is "someone else has it". Anything else — a read-only checkout, a `.x/` nobody may
+ * write — is rethrown as it arrives: it is the same failure `writeLock` would have raised seconds
+ * later, and inventing a code for it here would be a second answer to one condition.
+ */
+function claimExclusive(path: string, lock: DevLock): boolean {
+  let fd: number;
+  try {
+    fd = openSync(path, 'wx');
+  } catch (error) {
+    if ((error as { code?: string }).code === 'EEXIST') return false;
+    throw error;
+  }
+  try {
+    writeFileSync(fd, `${JSON.stringify(lock, null, 2)}\n`);
+  } finally {
+    closeSync(fd);
+  }
+  return true;
+}
+
+/** Whatever is on disk right now, or `null` if it is absent or half-written. */
+const readLock = async (path: string): Promise<DevLock | null> => {
+  const file = Bun.file(path);
+  if (!(await file.exists())) return null;
+  return parseLock(await file.text());
+};
+
 export interface PreflightInput {
   readonly stateDir: string;
   readonly port: number;
@@ -220,22 +278,53 @@ export interface PreflightInput {
   readonly holder?: (port: number) => Promise<PortHolder>;
 }
 
+export interface PreflightResult {
+  readonly clearedStale: boolean;
+  /**
+   * Give the directory back. The caller runs it when the boot it was preflighting FAILED —
+   * `serve.ts`'s `releaseBoot` shape — because a claim held by a process that gave up refuses
+   * every later boot in that shell for a pid that is gone.
+   */
+  release(): void;
+}
+
 /**
- * Run before anything boots. Throws the coded refusal, or returns the stale lock it cleared so the
- * caller can say so — a lock left by a hard kill is normal and worth one line, not a failure.
+ * Run before anything boots, and it CLAIMS: it returns holding the directory, never having merely
+ * looked at it.
+ *
+ * That is the fix, not a detail. `preflight` read the lock, `startDev` booted for seconds, and
+ * `writeLock` ran last — so two `x dev` in one checkout both passed the check and both opened
+ * `.x/pgdata`, `X_DEV_ALREADY_RUNNING` was unreachable, and what the operator actually got was
+ * `X_DB_UNAVAILABLE` whose `fix:` reads "run `x dev`" — the incident this file's own header
+ * records. The claim closes the window it names.
+ *
+ * The stale path still exists and is still normal (a hard kill leaves a lock behind): the file is
+ * removed and the claim retried once. A retry that ALSO loses is another boot that claimed the
+ * cleared slot in that instant, which is a refusal and not a third boot.
  */
-export const preflight = async (input: PreflightInput): Promise<{ clearedStale: boolean }> => {
+export const preflight = async (input: PreflightInput): Promise<PreflightResult> => {
   const alive = input.alive ?? isProcessAlive;
   const bound = input.portBound ?? isPortBound;
   const path = lockPath(input.stateDir);
-  const file = Bun.file(path);
+  const release = (): void => clearLock(input.stateDir);
+  // The lock lives inside the state directory, which the database has not created yet — this runs
+  // before anything boots, which is the whole point of it.
+  mkdirSync(input.stateDir, { recursive: true });
+  const mine: DevLock = {
+    pid: process.pid,
+    port: input.port,
+    // Refined by `writeLock` once the server reports the address it really bound; until then this
+    // is what the refusal prints, and it is the address the boot is about to ask for.
+    url: `http://${input.hostname}:${input.port}`,
+    startedAt: new Date().toISOString(),
+  };
   let clearedStale = false;
 
-  if (await file.exists()) {
-    const lock = parseLock(await file.text());
-    if (lock !== null && alive(lock.pid)) {
+  if (!claimExclusive(path, mine)) {
+    const held = await readLock(path);
+    if (held !== null && alive(held.pid)) {
       throw new DevAlreadyRunningError({
-        lock,
+        lock: held,
         stateDir: input.stateDir,
         ...(input.embeddedDb === undefined ? {} : { embeddedDb: input.embeddedDb }),
       });
@@ -245,22 +334,45 @@ export const preflight = async (input: PreflightInput): Promise<{ clearedStale:
     try {
       unlinkSync(path);
     } catch {
-      // Already gone, or not ours to remove. Either way the boot below is what decides.
+      // Already gone, or not ours to remove. The claim below is what decides.
     }
     clearedStale = true;
+    if (!claimExclusive(path, mine)) {
+      // Lost the race for the slot we just cleared. `held` is the best identity available — a
+      // half-written file parses as `null` for microseconds — and refusing on a stale pid beats
+      // the alternative, which is two processes writing one single-writer data directory.
+      //
+      // NEVER `mine`, which is what it fell back to: with an unparseable lock and a failed
+      // `unlinkSync`, both reads answer `null` and the refusal named THIS pid as the holder —
+      // `kill <self>` as the remedy for a file nobody could read.
+      const holder = (await readLock(path)) ?? held;
+      if (holder === null) throw new DevLockUnreadableError({ path, stateDir: input.stateDir });
+      throw new DevAlreadyRunningError({
+        lock: holder,
+        stateDir: input.stateDir,
+        ...(input.embeddedDb === undefined ? {} : { embeddedDb: input.embeddedDb }),
+      });
+    }
   }
 
   if (bound(input.port, input.hostname)) {
+    // Released before the throw: the remedy this refusal prints is `x dev --port <n>`, and a claim
+    // left behind would answer that command with X_DEV_ALREADY_RUNNING naming the process that
+    // just exited on it.
+    release();
     throw new DevPortInUseError({
       port: input.port,
       suggestion: suggestPort(input.port),
       holder: await (input.holder ?? portHolder)(input.port),
     });
   }
-  return { clearedStale };
+  return { clearedStale, release };
 };
 
-/** Record this process. Written after the preflight passes and before the roles start. */
+/**
+ * Record this process. The claim is already on disk — `preflight` took it — so this REFINES it
+ * with the address the server actually bound, which is the one field the preflight could not know.
+ */
 export const writeLock = async (stateDir: string, lock: DevLock): Promise<void> => {
   await Bun.write(lockPath(stateDir), `${JSON.stringify(lock, null, 2)}\n`);
 };

package/src/dev-purge.ts

@@ -0,0 +1,120 @@
+// The retention sweep this boot owns: the three framework tables that grow with traffic, the
+// `purge()` job that empties them and the `task` that fires it hourly.
+//
+// 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
+// none of them may import `@ultimat3/jobs`. Boot is the one place that holds all three, which is
+// the same reason it is boot that applies their DDL and installs them.
+//
+// WHY they had no caller at all until now: each store shipped a `purgeExpired()` documented as
+// "an app runs this from a `task`" — and a task only ENQUEUES, so there was no job for one to
+// enqueue and no app wrote either half. `x_rate_limit` takes one upsert per HTTP request the web
+// role serves, assets included, so every deployment the framework produces was accumulating a row
+// per source address forever.
+
+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';
+
+/** The durable queue key. Pinned, like every framework-owned job name — rows carry it. */
+export const PURGE_JOB_NAME = 'x.purge';
+/** The scheduler's key for the same sweep: `lastFiredAt` and the occurrence lock read it. */
+export const PURGE_TASK_NAME = 'x.purge.hourly';
+
+/**
+ * The two 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.
+ *
+ * The auth limiter is absent on purpose: it does not exist yet at boot. `defineAuth` builds it
+ * through the factory `configureAuthLimiters` installed, and that happens when the app's modules
+ * import — after this. `purgeAuthLimits()` is the seam that reads whatever was built.
+ */
+export interface RetentionStores {
+  readonly idempotency: PostgresIdempotencyStore;
+  readonly rateLimit: PostgresRateLimitStore;
+}
+
+/**
+ * Read per attempt by the job, and emptied by the disposer `installRetentionSweep` returns: a
+ * sweep left declared after its boot has stopped must not reach through a closed pool. Module
+ * scope for the reason `setJobDriver` and `configureKdfGate` are — a process has one boot at a
+ * time, and the registry the job lives in is process-wide too.
+ */
+let installed: readonly PurgeTarget[] = [];
+
+/** Declared once per process and re-declared only if a `resetJobs()` took it out of the registry. */
+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.
+ */
+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.
+  purgeExpired: () => purgeAuthLimits(),
+};
+
+function retentionTargets(stores: RetentionStores): readonly PurgeTarget[] {
+  return [
+    {
+      name: 'x_idempotency',
+      purgeExpired: (): Promise<number> => stores.idempotency.purgeExpired(),
+    },
+    {
+      name: 'x_rate_limit',
+      // The job's clock, not the server's. `last_ms` is written by whichever process took the
+      // token, so a purge measured against `now()` in Postgres computes a refill from the offset
+      // between two clocks — and against a frozen one it read 20,000,000 seconds of refill and
+      // deleted a bucket holding 0 of 4 tokens, which is a free limit reset from the cleanup.
+      purgeExpired: (nowMs: number): Promise<number> => stores.rateLimit.purgeExpired(nowMs),
+    },
+    authTarget,
+  ];
+}
+
+/**
+ * Declared lazily and guarded on the registry rather than on a module flag alone: `resetJobs()` /
+ * `resetTasks()` empty the registries a test shares with the next boot, and a memoised handle that
+ * is no longer seated is one the worker's `getJob` can never find.
+ */
+function declareSweep(): void {
+  if (getJob(PURGE_JOB_NAME) === undefined) {
+    sweep = purge({ name: PURGE_JOB_NAME, targets: () => installed });
+  }
+  const handle = sweep;
+  if (handle !== undefined && getTask(PURGE_TASK_NAME) === undefined) {
+    task({
+      name: PURGE_TASK_NAME,
+      cron: DEFAULT_PURGE_CRON,
+      // The one zone a framework-shipped schedule may name: an app's business hours are the app's,
+      // and a retention sweep has none. `tz` is required by `task()` and never inferred.
+      tz: 'UTC',
+      // `skip`, the default: a scheduler that was down across four occurrences has four sweeps'
+      // worth of expired rows in one table, and one pass removes all of them. Replaying the missed
+      // occurrences would be three passes that each delete nothing.
+      enqueue: () => [[handle, {}]],
+    });
+  }
+}
+
+/**
+ * Put the sweep on the queue's registry and its schedule, and answer the release.
+ *
+ * IF NOTHING EVER RUNS IT the tables grow exactly as they did before — the sweep is a `job`, so it
+ * needs a `worker` to claim it and a `scheduler` to enqueue it. A deployment with neither has no
+ * background work at all, and this is one more thing it does not do.
+ */
+export function installRetentionSweep(stores: RetentionStores): () => void {
+  installed = retentionTargets(stores);
+  declareSweep();
+  return () => {
+    installed = [];
+  };
+}

package/src/dev-queue.ts

@@ -5,11 +5,13 @@
 // a driver over a closed socket.
 
 import {
+  type PostgresIdempotencyStore,
   postgresIdempotencyStore,
   resetIdempotency,
   SQL_IDEMPOTENCY_TABLE,
   setIdempotencyStore,
 } from '@ultimat3/action';
+import { SQL_AUTH_LIMIT_TABLES } from '@ultimat3/auth';
 import type { DbClient, PgliteClient, PostgresClient, SqlFragment } from '@ultimat3/db';
 import {
   createPgliteClient,
@@ -20,6 +22,7 @@ import {
   setDbClient,
 } from '@ultimat3/db';
 import type { Tx } from '@ultimat3/entity';
+import { SQL_RATE_LIMIT_TABLE } from '@ultimat3/http';
 import type { EventBus, JobDriver, OutboxStore, PgExecutor } from '@ultimat3/jobs';
 import {
   createJobsFacade,
@@ -49,6 +52,13 @@ export interface RunningQueue {
   readonly outbox: OutboxStore;
   /** The `x_job_events` bus a `step.waitForEvent` resumes from. Durable, not per-process. */
   readonly events: EventBus;
+  /**
+   * The `x_idempotency` store this boot installed behind `idempotent: true`. Returned for the
+   * reason `outbox` is: the retention sweep over that table is a ROLE's work, not the queue's,
+   * and it has to sweep the store that was INSTALLED — a second one built beside it would purge
+   * on the default window even where this boot had configured another.
+   */
+  readonly idempotency: PostgresIdempotencyStore;
   stop(): Promise<void>;
 }
 
@@ -82,16 +92,28 @@ export function pgExecutorFor(client: DbClient): PgExecutor {
  * Every table this process's framework packages own, applied before anything reads one.
  *
  * PGlite speaks the extended protocol, which carries one statement per round trip, so the DDL is
- * applied statement by statement. Safe to split on `;`: both constants are fixed, with no
- * semicolon inside a literal, and each package's own SQL test is where that stays true.
+ * applied statement by statement. Safe to split on `;`: every constant is fixed, with no semicolon
+ * inside a literal, and each package's own SQL test is where that stays true.
  *
- * `SQL_IDEMPOTENCY_TABLE` is here and not in `@ultimat3/action` because a package that holds no
- * database dependency cannot apply its own schema — the same reason `SQL_JOBS_TABLE` is applied
- * here. Without it `postgresIdempotencyStore` is a store whose first reservation fails on a
- * missing relation, which is how a retried `POST /api/payments/charge` charges a card twice.
+ * `SQL_IDEMPOTENCY_TABLE`, `SQL_RATE_LIMIT_TABLE` and `SQL_AUTH_LIMIT_TABLES` are here and not in
+ * `@ultimat3/action`, `@ultimat3/http` or `@ultimat3/auth` because a package that holds no
+ * database dependency cannot apply its own schema
+ * — the same reason `SQL_JOBS_TABLE` is applied here. Each one absent is the same failure at a
+ * different door: a retried `POST /api/payments/charge` charges the card twice, and the FIRST
+ * request a `rateLimitStore` deployment serves dies on a missing `x_rate_limit` relation. The
+ * table is installed whether or not this boot passes `runtime.rateLimitStore` — `create table if
+ * not exists` on an unused table costs one round trip at boot, and a store installed later must
+ * not be the thing that discovers the schema was never applied. The auth pair is the strongest
+ * case for that rule: `defineAuth` builds its limiter when the APP's modules import, which is
+ * after this, so the first failed sign-in would otherwise be what discovers the missing relation.
  */
 async function applySchema(client: DevDbClient): Promise<void> {
-  for (const ddl of [SQL_JOBS_TABLE, SQL_IDEMPOTENCY_TABLE]) {
+  for (const ddl of [
+    SQL_JOBS_TABLE,
+    SQL_IDEMPOTENCY_TABLE,
+    SQL_RATE_LIMIT_TABLE,
+    SQL_AUTH_LIMIT_TABLES,
+  ]) {
     for (const statement of ddl.split(';')) {
       if (statement.trim().length > 0) await client.execute(raw(statement));
     }
@@ -141,8 +163,16 @@ async function startJobs(client: DevDbClient, overrides?: RuntimeOverrides): Pro
   );
   const events = createPgEventBus({ executor });
   setEventBus(events);
-  setIdempotencyStore(postgresIdempotencyStore({ executor }));
-  return { db: client, jobs: driver, outbox, events, stop: () => releaseQueue(client, driver) };
+  const idempotency = postgresIdempotencyStore({ executor });
+  setIdempotencyStore(idempotency);
+  return {
+    db: client,
+    jobs: driver,
+    outbox,
+    events,
+    idempotency,
+    stop: () => releaseQueue(client, driver),
+  };
 }
 
 /**

package/src/dev-render.ts

@@ -11,32 +11,29 @@ import type { Ctx } from '@ultimat3/core';
 import type { RouteMeta as HttpRouteMeta, Route, RouteParams } from '@ultimat3/http';
 import { asCtx, html, stream } from '@ultimat3/http';
 import { currentLocale } from '@ultimat3/i18n';
-import type {
-  IslandCollector,
-  IsrController,
-  RenderResult,
-  RouteData,
-  RouteEntry,
-} from '@ultimat3/render';
+import type { IslandCollector, RenderResult, RouteData, RouteEntry } from '@ultimat3/render';
 import {
-  contentHash,
   createIslandCollector,
-  createIsrController,
   headFromMeta,
   hydrateRuntime,
-  isrKey,
   metaContextFor,
-  ROOT_ELEMENT_ID,
-  renderComponent,
   renderHead,
-  renderSsr,
   routeDataFor,
   routeEntries,
   seoRenderers,
+} from '@ultimat3/render';
+import type { IsrController } from '@ultimat3/render/server';
+import {
+  contentHash,
+  createIsrController,
+  isrKey,
+  ROOT_ELEMENT_ID,
+  renderComponent,
+  renderSsr,
   staticHeaders,
   streamResult,
   stylesFor,
-} from '@ultimat3/render';
+} from '@ultimat3/render/server';
 
 /**
  * Specifier → built chunk URL, bound to the route file the specifier is written relative to.