@ultimat3/cli 8.0.0 → 9.0.0

package/CLAUDE.md

@@ -535,6 +535,7 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `dev-queue.ts` | the db + queue pair alone, and the one place that takes every ambient accessor back |
 | `dev-runtime.ts` | start the rest on top of it and install the remaining accessors (storage, mail, transport) |
 | `dev-cache.ts` | which cache tiers this process reads through, and the cross-instance invalidation hop |
+| `dev-purge.ts` | the hourly retention sweep: which framework tables this boot owns, the `purge()` job over them and the `task` that fires it |
 | `dev-sync.ts` | the `sync` role: its live-query registry, who is dialling it, and the socket it owns |
 | `runtime-overrides.ts` | the one field a host hands the framework a driver through |
 | `sync-authenticator.ts` | the app's HTTP authenticator, seen as the sync node's |
@@ -602,6 +603,8 @@ relay draining it.
 | the durable scheduler | `pgSchedulerState` + `createPgLeaseLeader` in `startRoles` | a watermark forgotten on restart, and every replica its own leader |
 | the Postgres event bus | `dev-queue.ts` | `step.waitForEvent` forgot every correlation on restart |
 | the shared idempotency store | `dev-queue.ts` | a retry on another replica charged the card twice |
+| the shared auth limiter | `configureAuthLimiters` in `startServices` | account lockouts counted per POD, so N replicas granted `maxAttempts × N` guesses |
+| the retention sweep | `dev-purge.ts`, declared in `startServices` | three `purgeExpired()` with no caller — every row `x_idempotency`, `x_rate_limit` and `x_auth_*` ever took was kept |
 | the cache tiers | `dev-cache.ts` | only the CDN tier was registered; memo, LRU and Redis had zero callers |
 | WebSocket authentication | `dev-sync.ts` | `actorId: null` on every socket — realtime was single-tenant by wiring |
 | OTLP export | `otlp-export.ts` | the chart set the variable and no code read it |
@@ -769,9 +772,12 @@ Promoting it to `x verify`'s `boundaries` host check is one line in `scripts/ver
 rule over names. Two stronger rules were measured and rejected: "the read must not be a property
 initializer" reports six flags, five of which work (`x db --allow-destructive`, `x jobs --queue`);
 "the summary must match the behaviour" is undecidable. So the flag's summary now says what it does,
-and forcing a reload stays what it always was — `@ultimat3/pwa`'s `updateSignal({ reason:
-'security' })`, which `As of 2026-08` has **no runtime caller anywhere**, in that package or
-outside it. Wiring the flag means giving that function a caller first.
+and forcing a reload is **not a thing this framework does**, `As of 2026-08`. `updateSignal`
+had no runtime caller for four majors and 9.0.0 deleted it rather than wiring it: `pwa` is tier 4
+and the two runtimes holding both build ids — `http` (2) and `sync` (3) — are below it, so no
+legal import could ever have reached the function. A deploy command has no channel to a running
+client regardless; the plan is `docker compose up` or `helm upgrade`. What ships is notification:
+`useConnection().updateAvailable` from `@ultimat3/realtime`.
 
 ## Planned commands are commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "8.0.0",
+  "version": "9.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,30 +37,31 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "8.0.0",
-    "@ultimat3/admin": "8.0.0",
-    "@ultimat3/ai": "8.0.0",
-    "@ultimat3/cache": "8.0.0",
-    "@ultimat3/core": "8.0.0",
-    "@ultimat3/db": "8.0.0",
-    "@ultimat3/entity": "8.0.0",
-    "@ultimat3/http": "8.0.0",
-    "@ultimat3/i18n": "8.0.0",
-    "@ultimat3/jobs": "8.0.0",
-    "@ultimat3/mail": "8.0.0",
-    "@ultimat3/manifest": "8.0.0",
-    "@ultimat3/mcp": "8.0.0",
-    "@ultimat3/policy": "8.0.0",
-    "@ultimat3/pwa": "8.0.0",
-    "@ultimat3/query": "8.0.0",
-    "@ultimat3/realtime": "8.0.0",
-    "@ultimat3/render": "8.0.0",
-    "@ultimat3/schema": "8.0.0",
-    "@ultimat3/scraping": "8.0.0",
-    "@ultimat3/seo": "8.0.0",
-    "@ultimat3/storage": "8.0.0",
-    "@ultimat3/testing": "8.0.0",
-    "@ultimat3/time": "8.0.0",
+    "@ultimat3/action": "9.0.0",
+    "@ultimat3/admin": "9.0.0",
+    "@ultimat3/ai": "9.0.0",
+    "@ultimat3/auth": "9.0.0",
+    "@ultimat3/cache": "9.0.0",
+    "@ultimat3/core": "9.0.0",
+    "@ultimat3/db": "9.0.0",
+    "@ultimat3/entity": "9.0.0",
+    "@ultimat3/http": "9.0.0",
+    "@ultimat3/i18n": "9.0.0",
+    "@ultimat3/jobs": "9.0.0",
+    "@ultimat3/mail": "9.0.0",
+    "@ultimat3/manifest": "9.0.0",
+    "@ultimat3/mcp": "9.0.0",
+    "@ultimat3/policy": "9.0.0",
+    "@ultimat3/pwa": "9.0.0",
+    "@ultimat3/query": "9.0.0",
+    "@ultimat3/realtime": "9.0.0",
+    "@ultimat3/render": "9.0.0",
+    "@ultimat3/schema": "9.0.0",
+    "@ultimat3/scraping": "9.0.0",
+    "@ultimat3/seo": "9.0.0",
+    "@ultimat3/storage": "9.0.0",
+    "@ultimat3/testing": "9.0.0",
+    "@ultimat3/time": "9.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-load.ts

@@ -11,6 +11,13 @@ import { localeConfig } from '@ultimat3/i18n';
 import type { ErrorCodeFact } from '@ultimat3/manifest';
 import { registerQueries } from '@ultimat3/query';
 import { isRouteConfig, pageComponentOf, registerRoute } from '@ultimat3/render';
+// For the SIDE EFFECT, and it is this module's to hold: importing `@ultimat3/render/server`
+// installs the `.tsx`/`.scss` Bun plugin, a plugin only transforms modules loaded AFTER it, and
+// every app module below is loaded by the dynamic `import()` in this file. Before the render
+// barrel split it came free with the line above; after it, the only other path to `/server` from
+// here is six hops through `error-contract` → `fix-command` → the command registry, which is an
+// accident one refactor away from compiling every app's `.tsx` to `React.createElement`.
+import '@ultimat3/render/server';
 import { collectDeclaredCodes } from './error-contract';
 import type { Finding } from './output';
 import { findingFrom } from './output';

package/src/cmd-deploy.ts

@@ -175,9 +175,12 @@ export const deployCommand: CliCommand = {
       // `critical: <bool>`, and no file in `packages/` read that field — so the flag changed
       // nothing about what `x deploy` did, on either method. `flag-reads.ts`'s
       // `X_CLI_FLAG_UNREAD` passed it, because that gate proves a flag is READ and this one was:
-      // into a field with no reader. Forcing a reload is `@ultimat3/pwa`'s
-      // `updateSignal({ reason: 'security' })`, which has no runtime caller either; a flag that
-      // triggers it is a change in that package, and this was not it.
+      // into a field with no reader. It is not coming back: `@ultimat3/pwa`'s
+      // `updateSignal({ reason: 'security' })`, the call it was to have triggered, is **deleted**
+      // as of 9.0.0 for having had no runtime caller of its own, and nothing in the framework
+      // force-navigates a client. A deploy also has no channel to one — the plan is
+      // `docker compose up` / `helm upgrade`, and the client's build id is read by `http` (tier 2)
+      // and `sync` (tier 3), neither of which may import a tier-4 package to act on it.
     ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {

package/src/dev-assets.ts

@@ -15,8 +15,8 @@ import type { IconPlan } from '@ultimat3/pwa';
 import { BuiltinImagePipeline, PwaIconMissingError, planIcons } from '@ultimat3/pwa';
 import type { ImageQuery, ImageTransformDriver } from '@ultimat3/seo';
 import { builtinImageDriver, DEFAULT_WIDTHS, parseImageQuery } from '@ultimat3/seo';
-import type { ImageFormat, ImageTransform, Storage } from '@ultimat3/storage';
-import { IMAGE_FORMATS, isTenantScoped, variantKey } from '@ultimat3/storage';
+import type { ImageTransform, Storage, VariantFormat } from '@ultimat3/storage';
+import { isTenantScoped, isVariantFormat, variantKey } from '@ultimat3/storage';
 import {
   AUTHORIZED_OBJECT_CACHE,
   assertReadableKey,
@@ -87,14 +87,11 @@ const imageResponse = (bytes: Uint8Array, contentType: string, cache: CacheHint)
 const mediaCache = (key: string): CacheHint =>
   isTenantScoped(key) ? AUTHORIZED_OBJECT_CACHE : IMMUTABLE_IMAGE;
 
-const isImageFormat = (value: string): value is ImageFormat =>
-  (IMAGE_FORMATS as readonly string[]).includes(value);
-
 /**
  * `exactOptionalPropertyTypes` makes an explicit `undefined` a different answer from an absent
  * key, and `variantKey` reads presence — so a spread, never an assignment.
  */
-function storageTransform(query: ImageQuery, format: ImageFormat | undefined): ImageTransform {
+function storageTransform(query: ImageQuery, format: VariantFormat | undefined): ImageTransform {
   return {
     ...(query.width === undefined ? {} : { width: query.width }),
     ...(format === undefined ? {} : { format }),
@@ -117,7 +114,7 @@ async function transformedVariant(
   // A format storage cannot name has no variant key, so it cannot be cached. The driver refuses
   // it with core's `X_IMAGE_UNSUPPORTED`; refusing it here too would give one bad URL two codes.
   const format =
-    query.format !== undefined && isImageFormat(query.format) ? query.format : undefined;
+    query.format !== undefined && isVariantFormat(query.format) ? query.format : undefined;
   const cacheable = query.format === undefined || format !== undefined;
   const cached = cacheable ? variantKey(key, storageTransform(query, format)) : undefined;
   // The SOURCE key decides the posture, not the variant's: `variantKey` keeps the source's prefix,

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 { 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-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,
@@ -50,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>;
 }
 
@@ -86,17 +95,25 @@ export function pgExecutorFor(client: DbClient): PgExecutor {
  * 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` and `SQL_RATE_LIMIT_TABLE` are here and not in `@ultimat3/action` or
- * `@ultimat3/http` because a package that holds no database dependency cannot apply its own schema
+ * `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.
+ * 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, SQL_RATE_LIMIT_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));
     }
@@ -146,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.

package/src/dev-runtime.ts

@@ -4,6 +4,8 @@
 // boot installs, only backed by embedded drivers.
 
 import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { configureAuthLimiters, postgresAuthLimiter, resetAuthLimiters } from '@ultimat3/auth';
 import type { PurgeDriver } from '@ultimat3/cache';
 import { isNoopPurgeDriver, selectPurgeDriver } from '@ultimat3/cache';
 import {
@@ -11,6 +13,7 @@ import {
   registerReadinessCheck,
   renderThrowable,
   resolveEnvironment,
+  systemClock,
 } from '@ultimat3/core';
 import type { RateLimitStore } from '@ultimat3/http';
 import { postgresRateLimitStore } from '@ultimat3/http';
@@ -27,7 +30,8 @@ import type { Transport, TransportSelection } from '@ultimat3/realtime/server';
 import { selectTransport } from '@ultimat3/realtime/server';
 import type { Storage } from '@ultimat3/storage';
 import { defineStorage, localDriver, s3Driver, usesDevStorageSecret } from '@ultimat3/storage';
-import { startCacheTiers } from './dev-cache';
+import { loadCacheTiers, startCacheTiers } from './dev-cache';
+import { installRetentionSweep } from './dev-purge';
 import type { DevDbClient } from './dev-queue';
 import { pgExecutorFor, startQueue } from './dev-queue';
 import type { DevServices, Env } from './dev-services';
@@ -288,16 +292,45 @@ export async function startServices(
   const bus: TransportSelection = selectTransport(env);
   const queue = await startQueue(services, overrides);
   const { db, jobs, outbox, events } = queue;
+  // The same executor the jobs driver, the outbox, the event bus and the idempotency store run
+  // on — one pool, one `Bun.sql` that does NOT satisfy `PgExecutor` (`Bun.sql.query` is
+  // `undefined`), one wrapper.
+  const executor = pgExecutorFor(db);
+  const rateLimitStore = postgresRateLimitStore({ executor });
   // Boot is a sequence of external resources, and every step after the first can reject — the
   // queue is already up, so from here an unwind must release it exactly like everything after it.
+  // Which is why the `try` opens on the NEXT line and not eight steps further down: it did, and
+  // the steps above it registered process-wide state (`configureAuthLimiters`, the `purge()` job
+  // and its `task`) that throws on a name a previous boot in this process left in the registry —
+  // `X_JOB_NAME_TAKEN`, outside the unwind, so `x dev` exited holding the PGlite lock, the pool
+  // and the ambient accessors. Nothing may be pushed onto `started` from outside this block.
   const started: (() => void | Promise<void>)[] = [() => queue.stop()];
-  // One readiness check per resource this boot OWNS, released with it. Nothing in the tree
-  // registered one, so `/readyz` was `markReady()` alone — "this process bound a socket" — and
-  // `packages/http/src/server.ts` calls that BEFORE `Bun.serve`, while `dev-roles.ts` calls it
-  // before `sync`, `worker` and `scheduler` start. The chart's `readinessProbe` and the container
-  // healthcheck both route on it, so a replica whose pool was gone kept taking traffic.
-  started.push(probedReadinessCheck('database', () => db.ping()));
   try {
+    // Where failed sign-ins are counted, installed BEFORE `loadApp` for the reason the idempotency
+    // store is: `defineAuth` is the app's call and it runs when the app's modules import, so a seam
+    // filled afterwards is one every app would have to fill itself. A FACTORY and not a limiter —
+    // the app declares `maxAttempts`/`windowMs`/`lockoutMs` and this boot has not read them yet, so
+    // a limiter built here would be refused by `assertAuthLimiterPolicy` on any app that tuned one.
+    //
+    // Until this line every deployment the framework produces counted lockouts per POD, while
+    // `x new` scaffolds `replicas: 2` and `docker/helm` runs three — `maxAttempts × N` guesses per
+    // account, and a lockout one replica established invisible to the rest.
+    configureAuthLimiters((policy) =>
+      postgresAuthLimiter({ executor, clock: systemClock, policy }),
+    );
+    started.push(() => resetAuthLimiters());
+    // The hourly sweep over the three framework tables this boot is responsible for. Every one of
+    // them ships a `purgeExpired()` that nothing called, so every row written was a row kept —
+    // `x_rate_limit` takes one upsert per request the web role serves, assets included.
+    started.push(
+      installRetentionSweep({ idempotency: queue.idempotency, rateLimit: rateLimitStore }),
+    );
+    // One readiness check per resource this boot OWNS, released with it. Nothing in the tree
+    // registered one, so `/readyz` was `markReady()` alone — "this process bound a socket" — and
+    // `packages/http/src/server.ts` calls that BEFORE `Bun.serve`, while `dev-roles.ts` calls it
+    // before `sync`, `worker` and `scheduler` start. The chart's `readinessProbe` and the container
+    // healthcheck both route on it, so a replica whose pool was gone kept taking traffic.
+    started.push(probedReadinessCheck('database', () => db.ping()));
     // Dialled here rather than at selection: an unreachable bus must fail at `x dev`, not on the
     // first change nobody receives, and the socket is a resource the unwind below has to release.
     // A supplied transport is already connected and is NOT closed here: whoever built it owns its
@@ -331,7 +364,13 @@ export async function startServices(
     // recomputed every cached read. Released with `resetTiers()`, which drops the whole registry:
     // this boot is the only thing that registers one, and a tier left behind would purge for a
     // process that has stopped.
-    started.push(startCacheTiers({ env, purge, transport }));
+    // The ladder is the app's declaration, never the environment's. `cache.tiers` was declared,
+    // validated and documented while NOTHING read it — so an app asking for one rung got four,
+    // and one asking for a shared tier got whatever `REDIS_URL` happened to say. `.x` is
+    // `resolveServices`' own join, so its parent is the app root: the one fact this function needs
+    // and does not already carry.
+    const tiers = await loadCacheTiers(dirname(services.stateDir));
+    started.push(startCacheTiers({ env, purge, transport, tiers }));
 
     return {
       services,
@@ -343,12 +382,12 @@ export async function startServices(
       storage,
       mail,
       mailDetail: selection.detail,
+      // Built above, beside the auth limiter factory and the retention sweep that purges its
+      // table: three readers of one executor, resolved once. `startWeb` is what an override
+      // replaces it at.
+      rateLimitStore,
       // The env key that selected the bus — or the honest answer that no env key did, because a
       // boot line reading `NATS_URL` over a transport the host handed in is a lie a script parses.
-      // The same executor the jobs driver, the outbox, the event bus and the idempotency store
-      // run on — one pool, one `Bun.sql` that does NOT satisfy `PgExecutor` (`Bun.sql.query` is
-      // `undefined`), one wrapper. `startWeb` is what an override replaces it at.
-      rateLimitStore: postgresRateLimitStore({ executor: pgExecutorFor(db) }),
       transportDetail: overrides?.transport === undefined ? bus.detail : 'runtime override',
       presenceTtlMs: bus.presenceTtlMs,
       purge,

package/src/document-styles.ts

@@ -5,7 +5,8 @@
 // apart from the styling nobody sees missing. A silent failure is exactly what axiom 3 exists for.
 
 import type { Surface } from '@ultimat3/render';
-import { routeEntries, stylesFor } from '@ultimat3/render';
+import { routeEntries } from '@ultimat3/render';
+import { stylesFor } from '@ultimat3/render/server';
 import type { Finding } from './output';
 
 /** The stylesheet an app is expected to own, named in the fix so it is one edit, not a hunt. */

package/src/island-bundle.ts

@@ -6,12 +6,8 @@
 // Bun ships no path API. `posix` does the specifier arithmetic (an app-relative route file is
 // POSIX by construction), `join`/`basename` the filesystem side.
 import { basename, join, posix, relative, sep } from 'node:path';
-import {
-  contentHash,
-  ISLAND_EXTENSION,
-  IslandInvalidError,
-  islandModuleId,
-} from '@ultimat3/render';
+import { ISLAND_EXTENSION, IslandInvalidError, islandModuleId } from '@ultimat3/render';
+import { contentHash } from '@ultimat3/render/server';
 import { IslandBuildFailedError } from './errors';
 import { solidProductionPlugin } from './island-solid-production';
 import { islandStylesPlugin } from './island-styles';

package/src/island-styles.ts

@@ -4,7 +4,7 @@
 // element renders unclassed, and `Bun.build` reports `success: true` with no log.
 
 import { renderThrowable, UltimateError } from '@ultimat3/core';
-import { loadStylesheet } from '@ultimat3/render';
+import { loadStylesheet } from '@ultimat3/render/server';
 import type { BunPlugin } from 'bun';
 import { IslandBuildFailedError } from './errors';
 

package/src/prerender.ts

@@ -6,7 +6,8 @@
 import { join } from 'node:path';
 import { renderThrowable } from '@ultimat3/core';
 import type { RouteEntry } from '@ultimat3/render';
-import { renderStatic, routeEntries } from '@ultimat3/render';
+import { routeEntries } from '@ultimat3/render';
+import { renderStatic } from '@ultimat3/render/server';
 import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
 import type { RouteStats } from './budgets';

package/src/runtime-overrides.ts

@@ -9,7 +9,7 @@ import type { Middleware, RateLimitStore } from '@ultimat3/http';
 import type { JobDriver } from '@ultimat3/jobs';
 import type { MailDriver } from '@ultimat3/mail';
 import type { SyncAuthenticator, Transport } from '@ultimat3/realtime/server';
-import type { IsrStore } from '@ultimat3/render';
+import type { IsrStore } from '@ultimat3/render/server';
 import type { ImageTransformDriver } from '@ultimat3/seo';
 import type { Storage } from '@ultimat3/storage';
 

package/src/serve.ts

@@ -20,7 +20,7 @@ import {
   migrate,
 } from '@ultimat3/db';
 import type { Route } from '@ultimat3/http';
-import { createIsrController } from '@ultimat3/render';
+import { createIsrController } from '@ultimat3/render/server';
 import { apiRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
 import { loadApp } from './app-load';

package/src/solid-loader.ts

@@ -7,7 +7,7 @@
 // `tsc` compiles this file inside ITS program, where a `.d.ts` sitting in this directory is
 // not included and its `declare module` never applies. `tsc -b` proves it in this repo.
 import { transformAsync } from '@babel/core';
-import { contentHash } from '@ultimat3/render';
+import { contentHash } from '@ultimat3/render/server';
 import solidPreset from 'babel-preset-solid';
 import type { BunPlugin } from 'bun';
 import { IslandBuildFailedError } from './errors';

package/src/style-csp.ts

@@ -4,7 +4,8 @@
 // stylesheet the document no longer carries — and the CSP would block the framework's own CSS.
 
 import { cspHashSource } from '@ultimat3/http';
-import { SURFACES, stylesFor } from '@ultimat3/render';
+import { SURFACES } from '@ultimat3/render';
+import { stylesFor } from '@ultimat3/render/server';
 
 /**
  * Call AFTER `loadApp`. One hash per distinct body: `stylesFor` is what `dev-render.ts` puts in

package/src/templates/scaffold-docs.ts

@@ -137,27 +137,34 @@ exec bunx x verify "$@"
 const composeDev = (
   app: NameSet,
 ): string => `# Optional: x dev needs none of this. Use it when you want the real Postgres/NATS/MinIO locally.
+#
+# Every published port binds 127.0.0.1, not 0.0.0.0. This stack ships its credentials in the file,
+# as a dev stack reasonably does — so the short form \`'5432:5432'\` would put an authenticated
+# database and an open object store on every interface this machine has, including the café wifi.
+# Docker publishes a port by writing DNAT rules, so a host firewall does not stop it. To reach this
+# stack from another machine, put a tunnel in front of it (\`ssh -L\`) rather than widening the bind;
+# production topology is docker-compose.prod.yml, and it is a different file for a reason.
 services:
   db:
     image: postgres:17-alpine
     environment:
       POSTGRES_PASSWORD: ${app.kebab}
       POSTGRES_DB: ${app.kebab}
-    ports: ['5432:5432']
+    ports: ['127.0.0.1:5432:5432']
     healthcheck:
       test: ['CMD-SHELL', 'pg_isready -U postgres']
       interval: 5s
   nats:
     image: nats:2-alpine
     command: ['-js']
-    ports: ['4222:4222']
+    ports: ['127.0.0.1:4222:4222']
   s3:
     image: minio/minio
     command: ['server', '/data']
     environment:
       MINIO_ROOT_USER: ${app.kebab}
       MINIO_ROOT_PASSWORD: ${app.kebab}-dev
-    ports: ['9000:9000']
+    ports: ['127.0.0.1:9000:9000']
 `;
 
 /** Docs, shims and container files for a new app, in the order a reader meets them. */

package/src/templates/scaffold-repo.ts

@@ -149,7 +149,9 @@ export const config = defineConfig({
   defaultCurrency: 'USD',
   // Env KEYS, never the value: the same image deploys to every environment. The database is
   // configured entirely from the environment — \`DATABASE_URL\` and \`DATABASE_POOL_MAX\`.
-  cache: { driver: 'memory', tiers: ['memo', 'lru'] },
+  // The tiers ARE the cache selection: add 'redis' to build the shared rung, which reads
+  // \`REDIS_URL\` and refuses the boot when it is unset.
+  cache: { tiers: ['request-memo', 'lru'] },
   jobs: { queues: ['${app.kebab}-default'], concurrency: 4 },
   // In-process transport by default; set urlEnv and transport: 'nats' to scale past one node.
   realtime: { enabled: true, tier: 'live-queries', transport: 'memory' },