@ultimat3/core 8.0.0 → 9.0.0

package/CLAUDE.md

@@ -110,6 +110,7 @@ shape against a locally declared sample interface for exactly that reason.
 | which deploy this is | `environment.ts` (`ULTIMATE_ENV`) | the twin of `ROLE`; never declare a second env var for it |
 | what this process does | `roles.ts` (`ROLE`) | |
 | how a route renders, caches offline and hydrates | `route-vocabulary.ts` (`RENDER_MODES`, `OFFLINE_STRATEGIES`, `HYDRATE_STRATEGIES`) | tier 0 because SIX packages name them and imports only go down — `render`, `http`, `seo`, `manifest` and `pwa` each kept a hand-copy until 2026-08, and `'spa'` was deleted from one while five went on admitting it under a green typecheck. Every union is `(typeof ARRAY)[number]`, pinned in `type-pins.ts`; `scripts/render-modes.test.ts` refuses a second declaration anywhere in `packages/*/src`. Re-export it, never restate it |
+| which rungs a cache ladder has | `cache-vocabulary.ts` (`CACHE_TIERS`) | tier 0 for the same reason, one tier lower down the stack: `app.config.ts` picks tiers by name and `@ultimat3/cache` builds them by name, and until 2026-08-22 those were two different vocabularies — config accepted `memo \| lru \| shared \| isr \| cdn`, the ladder ordered `request-memo \| lru \| redis \| cdn`, nothing mapped one onto the other, and `cache: { tiers: ['isr'] }` typechecked and selected nothing (issue #293). `TIER_ORDER` IS this array, so read order and the config vocabulary cannot disagree. `isr` is a `RenderMode`, never a tier. Pinned in `type-pins.ts` and by `scripts/render-modes.ts` |
 | which build of the APP this is | `app-version.ts` (`APP_VERSION`) | one reader, `dev` by default: `db` writes it into `x_migrations` and `jobs` into `x_backfills`, and `jobs` cannot reach `db` for the answer |
 | the values | `env.ts` | `checkEnv().values` holds REAL secrets — anything that prints goes through `maskedEnvValues()` |
 | `.env.example` | `env-example.ts` | a projection of the schema, never hand-maintained |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "8.0.0",
+  "version": "9.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",

package/src/cache-vocabulary.ts

@@ -0,0 +1,25 @@
+// Single responsibility: the cache tiers' NAMES, in read order — the ladder itself is
+// `@ultimat3/cache`'s. Tier 0 because that is the one place a tier-0 config declaration and a
+// tier-1 implementation can both see; not `config.ts`, because `app.config.ts` consumes these
+// names rather than owning them.
+
+/**
+ * The rungs, near to far. **Order is load-bearing**: `sortTiers` in `@ultimat3/cache` orders a
+ * stack by index in this array, so a name's position here IS its distance from the request, and a
+ * name missing from it sorts to `-1` — ahead of the request memo.
+ *
+ * Spelled once because it was spelled twice and the two disagreed (issue #293): `app.config.ts`
+ * accepted `memo | lru | shared | isr | cdn` while the stack ordered `request-memo | lru | redis |
+ * cdn`, so `cache: { tiers: ['isr'] }` typechecked and selected nothing. `memo`/`request-memo` and
+ * `shared`/`redis` were one rung spelled twice; the ladder's spelling wins, because it is the one
+ * a `TierInvalidation`, a `TierFailure` and the `/_x` panel already report.
+ *
+ * **`isr` is not here and is not a cache tier.** It is a `RenderMode` (`route-vocabulary.ts`) — a
+ * per-route rendering decision, revalidated by a tag bust — and `@ultimat3/cache` has no ISR store
+ * to build: `'isr'` appears nowhere in `packages/cache/src` except one invalidation label. Serving
+ * ISR is `render: 'isr'` on the route, never a rung of this ladder.
+ */
+export const CACHE_TIERS = ['request-memo', 'lru', 'redis', 'cdn'] as const;
+
+/** Derived from the array rather than written twice, so the pair cannot disagree. */
+export type CacheTierName = (typeof CACHE_TIERS)[number];

package/src/config.ts

@@ -2,6 +2,10 @@
 // defaults, validated eagerly, and composable so a big app can split it across `config/*.ts`
 // without inventing a second config mechanism.
 
+// Same rule for the same reason: `app.config.ts` CONSUMES the cache tier names, it does not own
+// them. Declaring them here is what let `cache.tiers` and the ladder `@ultimat3/cache` orders by
+// drift into two vocabularies with no map between them (issue #293).
+import { CACHE_TIERS, type CacheTierName } from './cache-vocabulary';
 import { ConfigInvalidError } from './errors';
 import { ROLES, type Role } from './roles';
 // `app.config.ts` CONSUMES the route vocabulary; it does not own it. Declaring `OfflineStrategy`
@@ -11,7 +15,6 @@ import type { OfflineStrategy } from './route-vocabulary';
 import { isIanaZoneName } from './time-zone-name';
 
 export type ThemeMode = 'light' | 'dark' | 'system';
-export type CacheTier = 'memo' | 'lru' | 'shared' | 'isr' | 'cdn';
 export type RealtimeTier = 'channels' | 'live-queries' | 'local-first';
 export type RealtimeTransport = 'memory' | 'nats' | 'redis';
 
@@ -70,11 +73,25 @@ export interface DatabaseConfig {
   readonly ssl: boolean;
 }
 
+/**
+ * No `CacheTier`. It was a SECOND spelling of the ladder — `memo | lru | shared | isr | cdn`
+ * against `@ultimat3/cache`'s `request-memo | lru | redis | cdn` — with nothing mapping one onto
+ * the other, so `cache: { tiers: ['isr'] }` typechecked and selected nothing. Deleted 2026-08-22
+ * in favour of `CacheTierName`, which is the ladder's own names and the only ones `sortTiers` can
+ * place. It was also the second exported type called `CacheTier` in the tree; the other is
+ * `@ultimat3/cache`'s tier INTERFACE, which is the one every implementation names.
+ *
+ * No `driver` and no `urlEnv` either, deleted 2026-08-22 and for the same reason one rung further
+ * up: `tiers` is what BUILDS the ladder (`packages/cli/src/dev-cache.ts`), so `driver: 'redis'`
+ * beside `tiers: ['request-memo', 'lru']` was a second selector that selected nothing — the shape
+ * `examples/dummy/app.config.ts` shipped. `urlEnv` was `database.urlEnv` verbatim: the Redis tier
+ * reads the literal `REDIS_URL`, so `urlEnv: 'MY_REDIS'` made nothing read `MY_REDIS`. Which rungs
+ * exist is `cache.tiers` and only that; a rung the environment cannot supply refuses the boot.
+ */
 export interface CacheConfig {
-  readonly driver: 'memory' | 'redis';
-  readonly urlEnv: string | undefined;
   readonly defaultTtlMs: number;
-  readonly tiers: readonly CacheTier[];
+  /** Order is fixed by `TIER_ORDER`; listing order here selects rungs, it does not rank them. */
+  readonly tiers: readonly CacheTierName[];
 }
 
 export interface JobsConfig {
@@ -219,7 +236,7 @@ function defaults(name: string): Omit<AppConfig, 'name'> {
     pwa: { enabled: false, offline: 'network-only', backgroundSync: false, push: false },
     roles: [...ROLES],
     database: { driver: 'postgres', ssl: false },
-    cache: { driver: 'memory', urlEnv: undefined, defaultTtlMs: 60_000, tiers: ['memo', 'lru'] },
+    cache: { defaultTtlMs: 60_000, tiers: ['request-memo', 'lru'] },
     jobs: {
       queues: [`${name}-default`],
       concurrency: 8,
@@ -244,10 +261,21 @@ const BASE_FIX = 'edit app.config.ts to fix the fields named in cause, then run:
 const TIMEZONE_FIX =
   "set defaultTimeZone to an Area/Location name, or UTC — list every accepted one with bun -e \"console.log(Intl.supportedValuesOf('timeZone').join('\\n'))\" — where a legacy single-label name swaps mechanically (Japan → Asia/Tokyo, GB → Europe/London, Universal → UTC), while an abbreviation or numeric offset (CET, EST5EDT, +01:00) carries no DST rule and has no replacement, so name the city whose clock you mean (Europe/Paris, America/New_York)";
 
+/**
+ * Appended only when a tier name is what failed, and it names the rename rather than the rule: the
+ * three refused spellings are the ones 8.0.0 accepted, and two of them have a mechanical
+ * replacement while `isr` has none — it is a `RenderMode`, and no cache tier ever served it.
+ */
+const CACHE_TIER_FIX =
+  "in app.config.ts, rewrite cache.tiers with the rung names the ladder serves — request-memo, lru, redis, cdn — where memo becomes request-memo and shared becomes redis, and isr is dropped: it is a render mode, so move it to render: 'isr' on the routes that want it";
+
 function validate(config: AppConfig): void {
   const issues: string[] = [];
   // Zero or one entry: the zone's own remedy, carried only when the zone is what failed.
   const zoneFix: string[] = [];
+  // Same shape, and it exists for the upgrade: an 8.0.0 app carrying `['memo', 'shared']` in an
+  // untyped config file reaches here rather than the compiler, and needs the new spelling.
+  const tierFix: string[] = [];
 
   if (!NAME_RE.test(config.name)) {
     issues.push(`name "${config.name}" must match ${String(NAME_RE)}`);
@@ -277,8 +305,13 @@ function validate(config: AppConfig): void {
   if (config.realtime.transport !== 'memory' && config.realtime.urlEnv === undefined) {
     issues.push(`realtime.transport "${config.realtime.transport}" requires realtime.urlEnv`);
   }
-  if (config.cache.driver === 'redis' && config.cache.urlEnv === undefined) {
-    issues.push('cache.driver "redis" requires cache.urlEnv');
+  // A rung the ladder cannot build is the defect this key had: `sortTiers` places a name by its
+  // index in `CACHE_TIERS`, and a name missing from it sorts to `-1` — AHEAD of the request memo.
+  // So an unknown tier is refused at boot rather than silently ignored or silently placed first.
+  for (const tier of config.cache.tiers) {
+    if (CACHE_TIERS.includes(tier)) continue;
+    issues.push(`cache.tiers contains "${tier}", which is not one of ${CACHE_TIERS.join(', ')}`);
+    if (tierFix.length === 0) tierFix.push(CACHE_TIER_FIX);
   }
 
   if (issues.length > 0) {
@@ -286,7 +319,7 @@ function validate(config: AppConfig): void {
       cause: issues.join('; '),
       // The generic instruction goes LAST so the fix line still ends in a command that can be
       // pasted — a trailing `.` after `x verify` is a command nobody can run.
-      fix: [...zoneFix, BASE_FIX].join('. '),
+      fix: [...zoneFix, ...tierFix, BASE_FIX].join('. '),
       meta: { issues },
     });
   }

package/src/index.ts

@@ -32,6 +32,7 @@ export {
 export { APP_VERSION_KEY, appVersion, DEFAULT_APP_VERSION } from './app-version';
 export { assert, assertNever, type InvariantOptions, invariant } from './assert';
 export { type AsyncContext, asyncContext } from './async-context';
+export { CACHE_TIERS, type CacheTierName } from './cache-vocabulary';
 export { canonicalJson, fingerprint } from './canonical-json';
 export { type Clock, type FrozenClock, frozenClock, systemClock } from './clock';
 export type {
@@ -42,7 +43,6 @@ export type {
   AppConfigOverlay,
   AuthConfig,
   CacheConfig,
-  CacheTier,
   DatabaseConfig,
   JobsConfig,
   McpConfig,

package/src/registrar.ts

@@ -59,6 +59,7 @@ export const PRIMITIVE_FACTORIES = Object.freeze<readonly PrimitiveFactory[]>(
       { factory: 'hive', pkg: '@ultimat3/ai', kind: 'action' },
       { factory: 'llm', pkg: '@ultimat3/ai', kind: 'action' },
       { factory: 'backfill', pkg: '@ultimat3/jobs', kind: 'job' },
+      { factory: 'purge', pkg: '@ultimat3/jobs', kind: 'job' },
       { factory: 'scrape', pkg: '@ultimat3/scraping', kind: 'job' },
     ] satisfies readonly PrimitiveFactory[]
   ).map((entry) => Object.freeze(entry)),

package/src/type-pins.ts

@@ -1,11 +1,12 @@
 // Compile-time pins for the actor-facts seam, the config surface, the request-context patch and
-// the route vocabulary.
+// the route and cache-tier vocabularies.
 // Source, not a `.test.ts`, on purpose: `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b`
 // never reads a test file and a type-level assertion written there can never fail. This module
 // emits nothing and exports nothing anybody imports — a regression is a build error.
 
 import type { Actor, ActorFactMap, FactKeysOf, FactMapOf } from './actor';
-import type { AppConfigInput, DatabaseConfig } from './config';
+import type { CacheTierName } from './cache-vocabulary';
+import type { AppConfigInput, CacheConfig, DatabaseConfig } from './config';
 import type { CtxPatch } from './context';
 import type { HydrateStrategy, OfflineStrategy, RenderMode } from './route-vocabulary';
 
@@ -101,6 +102,23 @@ type _DatabaseInputCarriesNoDeadField = Assert<
     : false
 >;
 
+/**
+ * The two `config.cache` fields deleted 2026-08-22, held down for the reason the `database` three
+ * are: `cache.tiers` is what BUILDS the ladder, so `driver: 'redis'` was a second selector that
+ * selected nothing and `urlEnv` named an env key the Redis tier never reads — it reads the literal
+ * `REDIS_URL`. Re-adding either restores a knob an SRE sets, redeploys, and sees no effect from.
+ */
+type DeadCacheField = 'driver' | 'urlEnv';
+
+type _CacheConfigCarriesNoDeadField = Assert<
+  Extract<keyof CacheConfig, DeadCacheField> extends never ? true : false
+>;
+
+/** And the input side with it — `Input<CacheConfig>` is what an `app.config.ts` writes. */
+type _CacheInputCarriesNoDeadField = Assert<
+  Extract<keyof NonNullable<AppConfigInput['cache']>, DeadCacheField> extends never ? true : false
+>;
+
 /**
  * Neither id a child context may patch. `withChildContext` forwards the parent's `buildId`
  * verbatim, so `{ buildId }` on the patch was an option that read as honoured and was dropped
@@ -142,3 +160,33 @@ type _OfflineStrategyIsItsArray = Assert<
 type _HydrateStrategyIsItsArray = Assert<
   Exact<HydrateStrategy, 'idle' | 'visible' | 'interaction' | 'never'>
 >;
+
+/**
+ * The cache ladder's rungs, same rule as the three above and for a defect that shipped: 8.0.0's
+ * `CacheTier` was a hand-written union in `config.ts` — `memo | lru | shared | isr | cdn` — while
+ * `@ultimat3/cache` ordered `request-memo | lru | redis | cdn`, so `cache: { tiers: ['isr'] }`
+ * typechecked and selected nothing (issue #293). Derived from `CACHE_TIERS` now, and pinned here
+ * because a `@ts-expect-error` in an excluded test file asserts nothing.
+ */
+type _CacheTierNameIsItsArray = Assert<
+  Exact<CacheTierName, 'request-memo' | 'lru' | 'redis' | 'cdn'>
+>;
+
+/**
+ * The three spellings deleted in 9.0.0 must stay deleted. `memo` and `shared` were the ladder's
+ * near and shared rungs under a second name; `isr` was never a tier at all — it is a `RenderMode`,
+ * and re-admitting it would put a rung `sortTiers` places at `-1` (AHEAD of the request memo)
+ * back within reach of `app.config.ts`.
+ */
+type DeadCacheTier = 'memo' | 'shared' | 'isr';
+
+type _CacheTiersRefuseTheOldSpellings = Assert<
+  Extract<CacheTierName, DeadCacheTier> extends never ? true : false
+>;
+
+/** And `cache.tiers` is that vocabulary, not a second one — the whole of the fix. */
+type _CacheConfigNamesTheLadder = Assert<Exact<CacheConfig['tiers'], readonly CacheTierName[]>>;
+
+type _CacheInputNamesTheLadder = Assert<
+  Exact<NonNullable<AppConfigInput['cache']>['tiers'], readonly CacheTierName[] | undefined>
+>;