@ultimat3/cli 8.0.0 → 10.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 { CacheTierName } from '@ultimat3/core';
+import { CACHE_TIERS, defineConfig, logger, renderThrowable } from '@ultimat3/core';
 import type { Transport, TransportSubscription } from '@ultimat3/realtime/server';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
 import type { Env } from './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));
@@ -90,7 +187,7 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void>
       void applyBroadcast(payload);
     })
     .catch((error: unknown) => {
-      logger.warn('cache.broadcast.subscribe-failed', { error: messageOf(error) });
+      logger.warn('cache.broadcast.subscribe-failed', { error: broadcastErrorText(error) });
       return undefined;
     });
 
@@ -102,8 +199,15 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void>
   };
 }
 
-const messageOf = (error: unknown): string =>
-  error instanceof Error ? error.message : 'unknown error';
+/**
+ * `renderThrowable`, never `instanceof Error` + `.message`. Both run on a value this process did
+ * not build — a `Proxy` traps `getPrototypeOf` and a `message` getter can raise — and a throw here
+ * is inside the handler whose whole job is to keep the subscriber loop alive: losing it ends
+ * cross-instance cache invalidation for the process, quietly, which is the failure the loop's own
+ * `try` exists to prevent. The old form also answered `'unknown error'` for every non-`Error`
+ * throw, so a driver rejecting with a string reported nothing at all.
+ */
+export const broadcastErrorText = (error: unknown): string => renderThrowable(error);
 
 /**
  * A peer's wire tags, applied here. Never throws: a malformed frame or an undeclared tag must not
@@ -117,6 +221,6 @@ async function applyBroadcast(payload: string): Promise<void> {
     const wire = parsed.filter((value): value is string => typeof value === 'string');
     if (wire.length > 0) await receiveInvalidationBroadcast(wire);
   } catch (error) {
-    logger.warn('cache.broadcast.apply-failed', { error: messageOf(error) });
+    logger.warn('cache.broadcast.apply-failed', { error: broadcastErrorText(error) });
   }
 }

package/src/dev-lock.ts

@@ -16,8 +16,7 @@
 
 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 { stringField, UltimateError } from '@ultimat3/core';
 import { exec, type Runner } from './exec';
 import { quoteArg } from './shell-quote';
 
@@ -68,7 +67,11 @@ export const isProcessAlive = (pid: number): boolean => {
     return true;
   } catch (error) {
     // EPERM means it exists and belongs to another user. Alive, and not ours to signal.
-    return (error as { code?: string }).code === 'EPERM';
+    // `stringField`, never a cast plus a property read: the rule `metrics-endpoint.ts` states and
+    // `caught-value-reads.test.ts` enforces — a getter that throws would take this path down one
+    // line before the guard meant to make it safe, and this guard decides whether a second `x dev`
+    // is allowed to open a single-writer data directory.
+    return stringField(error, 'code') === 'EPERM';
   }
 };
 
@@ -96,7 +99,6 @@ export class DevAlreadyRunningError extends UltimateError {
       code: 'X_DEV_ALREADY_RUNNING',
       cause: `pid ${input.lock.pid} is already running x dev on ${input.lock.url} and holds ${input.stateDir}${single}`,
       fix: `use the one already running at ${input.lock.url}, or stop it: kill ${input.lock.pid}`,
-      docs: docsFor('X_DEV_ALREADY_RUNNING'),
       meta: { pid: input.lock.pid, port: input.lock.port, stateDir: input.stateDir },
     });
   }
@@ -118,7 +120,6 @@ export class DevLockUnreadableError extends UltimateError {
       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 },
     });
   }
@@ -198,7 +199,6 @@ export class DevPortInUseError extends UltimateError {
         holder.pid === undefined
           ? `x dev --port ${input.suggestion}`
           : `x dev --port ${input.suggestion}   # or free it, if that pid is yours: kill ${holder.pid}`,
-      docs: docsFor('X_PORT_IN_USE'),
       meta: { port: input.port, ...holder },
     });
   }
@@ -247,7 +247,8 @@ function claimExclusive(path: string, lock: DevLock): boolean {
   try {
     fd = openSync(path, 'wx');
   } catch (error) {
-    if ((error as { code?: string }).code === 'EEXIST') return false;
+    // Same rule as `isProcessAlive` above: read the field, never cast and dereference.
+    if (stringField(error, 'code') === 'EEXIST') return false;
     throw error;
   }
   try {

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.