@ultimat3/core 8.0.0 → 10.0.0

package/CLAUDE.md

@@ -12,6 +12,7 @@ is a change to every package.
 | A value a CALLER supplied | `describeValue()` — shape, never content. `renderCauseValue` is safe against throwing, not against leaking |
 | Reading a caught value | `renderThrowable()` / `isThrownError()` / `stringField()`; never `error.message`, `error instanceof Error` or `typeof error.code === 'string'` directly — the probe throws before the renderer runs |
 | New code | add to `CORE_CODE_TITLES` in `error-codes.ts`, else the title is auto-humanised |
+| Where an error points | `ERROR_DOCS_URL` — one constant, never a per-code URL. `docs:` is omitted at every construction site and resolved from the registry |
 | Time | take a `Clock`; `Date.now()` / `new Date()` only inside `clock.ts` |
 | Context | never thread `ctx` as a parameter — `useContext()` |
 | A value ambient across an `await` | `asyncContext<T>(subject)` from `async-context.ts`, in **every** package — never `new AsyncLocalStorage` |
@@ -110,6 +111,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 |
@@ -275,10 +277,17 @@ in a different trace, which is worse than no span because it looks authoritative
 including the three that open no other socket — `queue_depth` belongs to one of them.
 
 ```bash
-bun test                      # from packages/core
+bun test packages/core/src    # from the REPO ROOT, never from packages/core
 bun run typecheck
 ```
 
+**The root is not a preference.** `bunfig.toml`'s `preload = ["./scripts/test-setup.ts"]` is what
+installs `@ultimat3/testing`'s matchers, and Bun reads `bunfig.toml` from the cwd — so `bun test`
+run inside `packages/core` loads no preload and 17 tests in `secrets.test.ts` die on
+`expect(...).rejects.toBeUltimateError is not a function`, which reads as this package's failure
+and is the shell's. `.github/workflows/ci.yml`'s `package` job spawns `bun test packages/<pkg>`
+with `cwd` at the root for the same reason (`scripts/coverage-gate.ts`).
+
 `markReady()` means **bound**, and readiness means **usable** — two different facts since
 `registerReadinessCheck(name, check)`. `/readyz` is ready only when the state is `ready` AND every
 named check passes, and `HealthReport.checks` carries them by name because "alert on check
@@ -347,6 +356,18 @@ the customer's. The non-blank-reason assert is `@ultimat3/entity`'s `crossTenant
 verbatim — two escapes from the framework's default posture should not look like two things. Do
 not add a second impersonation path.
 
+**`ERROR_DOCS_URL` replaced `ERROR_DOCS_BASE` + `errorDocsUrl(code)` `As of 2026-08-23`, and it is
+a breaking change** — it lands in the next major, not in the released line. `https://ultimate.dev/errors/<code>` answered **404**, host included, on every error the
+framework has ever thrown — including the first line a new agent reads (`x --json` →
+`"docs":"https://ultimate.dev/errors/X_CLI_UNKNOWN_COMMAND"`). A dead link in every error is a
+defect under axiom 4, and it is not "not built yet": `wiki/` is the only public documentation
+surface there is. There is no per-code URL because there is no per-code ANCHOR — codes live in
+`wiki/Error-Codes.md` as TABLE ROWS, and a `#X_DB_DRIFT` fragment would be a second dead
+declaration rather than a fix for the first. So the function is gone rather than kept with an
+ignored parameter, and `descriptor()` lost its `code` parameter with it. A package constructing an
+`UltimateError` now OMITS `docs:` entirely and lets the constructor resolve the registered
+descriptor — one URL, one place, instead of the fifteen packages that each spelled the base out.
+
 Every `UltimateError` carries `retry` (`terminal | retryable | retry-after`), **defaulting to
 `terminal`** — fail closed, because a client retrying on `status >= 500` hammers `X_DB_DRIFT` and
 `X_TENANCY_UNSCOPED`, which are permanent config faults. `registerErrorRetry()` is the one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "8.0.0",
+  "version": "10.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,8 +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';
 
 export interface ThemeConfig {
@@ -70,11 +72,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 {
@@ -102,10 +118,19 @@ export interface JobsConfig {
  * server config, and the presence beat is DERIVED (`PresenceRegistry.heartbeatMs` is
  * `max(1000, floor(ttlMs / 3))`). A second knob is a second number that can disagree with the one
  * it is a fraction of, and a knob nothing reads is a knob nothing enforces — axioms 1 and 3.
+ *
+ * No `tier` either, and no `RealtimeTier` — deleted 2026-08-23, the thirteenth instance of the
+ * same defect and the dangerous shape of it. It accepted
+ * `'channels' | 'live-queries' | 'local-first'`, defaulted to `'channels'`, was documented with
+ * per-value semantics, was set by both tracked apps — and no file anywhere compared it, branched
+ * on it or dereferenced it. `transport` and `urlEnv` are the only two fields of this section any
+ * code reads. So `tier: 'local-first'` bought the durable client store that does not exist
+ * (`createOpfsLocalStore` still throws `X_NOT_IMPLEMENTED`), exactly as `jobs: { driver: 'redis' }`
+ * bought Postgres. Which realtime tier an app is on is decided by what it DECLARES — a `channel()`
+ * topic, a `live: true` query, a local store — never by a config key.
  */
 export interface RealtimeConfig {
   readonly enabled: boolean;
-  readonly tier: RealtimeTier;
   readonly transport: RealtimeTransport;
   readonly urlEnv: string | undefined;
 }
@@ -219,7 +244,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,
@@ -227,7 +252,7 @@ function defaults(name: string): Omit<AppConfig, 'name'> {
       backoff: 'exponential',
       visibilityTimeoutMs: 30_000,
     },
-    realtime: { enabled: false, tier: 'channels', transport: 'memory', urlEnv: undefined },
+    realtime: { enabled: false, transport: 'memory', urlEnv: undefined },
     ai: { mcp: { expose: true, path: '/mcp' } },
   };
 }
@@ -244,10 +269,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 +313,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 +327,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/context.ts

@@ -200,7 +200,10 @@ export function withChildContext<T>(patch: CtxPatch, fn: () => T): T {
 /** Resolve a late-bound service. Throws `X_SERVICE_MISSING` rather than returning undefined. */
 export function useService<T>(name: string): T {
   const ctx = useContext();
-  const service = ctx.services[name];
+  // Own keys only, and the SAME read the cause below lists. A raw index walks the prototype, so
+  // `useService('constructor')` answered with the `Object` function and the caller's first method
+  // call was a bare `TypeError` frames away — which is the failure this function exists to name.
+  const service = Object.hasOwn(ctx.services, name) ? ctx.services[name] : undefined;
   if (service === undefined) {
     throw new UltimateError({
       code: 'X_SERVICE_MISSING',

package/src/error-codes.ts

@@ -19,11 +19,14 @@ export interface ErrorCodeEntry extends ErrorCodeDescriptor {
   readonly code: string;
 }
 
-export const ERROR_DOCS_BASE = 'https://ultimate.dev/errors/';
-
-export function errorDocsUrl(code: string): string {
-  return `${ERROR_DOCS_BASE}${code}`;
-}
+/**
+ * Where an error sends its reader. One URL for every code, and deliberately not one per code:
+ * `wiki/` is the framework's only public documentation surface, codes live there in TABLE ROWS,
+ * and a table row has no anchor — so a `#X_DB_DRIFT` fragment would land on the page top while
+ * declaring a target that does not exist. The `https://ultimate.dev/errors/<code>` links this
+ * shipped until 9.x answered 404, host included, on every error the framework has ever thrown.
+ */
+export const ERROR_DOCS_URL = 'https://github.com/developerz-ai/ultimate/wiki/Error-Codes';
 
 /** Codes owned by `@ultimat3/core`. Every other package calls `registerErrorCodes()`. */
 const CORE_CODE_TITLES = {
@@ -75,13 +78,13 @@ const CORE_CODE_TITLES = {
 
 export type CoreErrorCode = keyof typeof CORE_CODE_TITLES;
 
-function descriptor(code: string, declaration: ErrorCodeDeclaration): ErrorCodeDescriptor {
-  return Object.freeze({ title: declaration.title, docs: declaration.docs ?? errorDocsUrl(code) });
+function descriptor(declaration: ErrorCodeDeclaration): ErrorCodeDescriptor {
+  return Object.freeze({ title: declaration.title, docs: declaration.docs ?? ERROR_DOCS_URL });
 }
 
 export const CORE_ERROR_CODES: Readonly<Record<CoreErrorCode, ErrorCodeDescriptor>> = Object.freeze(
   Object.fromEntries(
-    Object.entries(CORE_CODE_TITLES).map(([code, title]) => [code, descriptor(code, { title })]),
+    Object.entries(CORE_CODE_TITLES).map(([code, title]) => [code, descriptor({ title })]),
   ) as Record<CoreErrorCode, ErrorCodeDescriptor>,
 );
 
@@ -105,7 +108,7 @@ export function registerErrorCodes(codes: Readonly<Record<string, ErrorCodeDecla
     });
   }
   for (const [code, declaration] of Object.entries(codes)) {
-    registry.set(code, descriptor(code, declaration));
+    registry.set(code, descriptor(declaration));
   }
 }
 
@@ -117,7 +120,7 @@ function humanize(code: string): string {
 export function describeErrorCode(code: string): ErrorCodeDescriptor {
   const known = registry.get(code);
   if (known !== undefined) return known;
-  return descriptor(code, { title: humanize(code) });
+  return descriptor({ title: humanize(code) });
 }
 
 export function hasErrorCode(code: string): boolean {

package/src/exports/error-contract.ts

@@ -12,9 +12,8 @@ export type {
 export {
   CORE_ERROR_CODES,
   describeErrorCode,
-  ERROR_DOCS_BASE,
+  ERROR_DOCS_URL,
   errorCodeSnapshot,
-  errorDocsUrl,
   hasErrorCode,
   listErrorCodes,
   registerErrorCodes,

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,13 +43,11 @@ export type {
   AppConfigOverlay,
   AuthConfig,
   CacheConfig,
-  CacheTier,
   DatabaseConfig,
   JobsConfig,
   McpConfig,
   PwaConfig,
   RealtimeConfig,
-  RealtimeTier,
   RealtimeTransport,
   ThemeConfig,
   ThemeMode,
@@ -133,10 +132,9 @@ export {
   describeErrorCode,
   describeValue,
   EnvMissingError,
-  ERROR_DOCS_BASE,
+  ERROR_DOCS_URL,
   ERROR_RETRY_KINDS,
   errorCodeSnapshot,
-  errorDocsUrl,
   errorRetry,
   formatError,
   hasErrorCode,

package/src/metrics.ts

@@ -195,6 +195,31 @@ function finite(name: string, value: number): number {
   return value;
 }
 
+/**
+ * Bounds are strictly ascending finite numbers, refused at DECLARATION like `maxSeries` beside it.
+ * `record` takes the first bound an observation fits, and the exposition format emits one
+ * cumulative `le` series per bound in array order — so `[1, 0.5, 5]` both counted observations
+ * into a bucket that was not theirs and rendered a non-monotonic `le` series that Prometheus and
+ * OpenMetrics each reject. Two wrong numbers, neither visible from the other, and nothing at the
+ * call site to notice: the observations themselves were all valid.
+ */
+function assertBounds(name: string, bounds: readonly number[] | undefined): void {
+  if (bounds === undefined) return;
+  const bad = bounds.findIndex((bound, index) => {
+    const previous = index === 0 ? Number.NEGATIVE_INFINITY : (bounds[index - 1] as number);
+    return !Number.isFinite(bound) || bound <= previous;
+  });
+  if (bad === -1) return;
+  const repaired = [...new Set(bounds.filter((bound) => Number.isFinite(bound)))].sort(
+    (left, right) => left - right,
+  );
+  throw new MetricNameInvalidError({
+    cause: `${name} declared bounds [${bounds.map((bound) => String(bound)).join(', ')}], which are not strictly ascending finite numbers — [${String(bad)}] is ${String(bounds[bad])}`,
+    fix: `sort the bounds and drop the duplicates: histogram('${name}', { bounds: [${repaired.join(', ')}] })`,
+    meta: { metric: name, bounds: bounds.map((bound) => String(bound)), at: bad },
+  });
+}
+
 function declare(name: string, kind: MetricKind, options: GaugeOptions & HistogramOptions) {
   if (!METRIC_NAME_RE.test(name)) {
     throw new MetricNameInvalidError({
@@ -203,6 +228,7 @@ function declare(name: string, kind: MetricKind, options: GaugeOptions & Histogr
       meta: { name },
     });
   }
+  assertBounds(name, options.bounds);
   const existing = instruments.get(name);
   if (existing !== undefined) {
     if (existing.descriptor.kind !== kind) {

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/telemetry.ts

@@ -326,7 +326,13 @@ const TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
  */
 export function traceparent(context: SpanContext): string {
   const flags = (context.traceFlags & 0xff).toString(16).padStart(2, '0');
-  return `00-${context.traceId}-${context.spanId}-${flags}`;
+  // The empty `spanId` `currentSpanContext()` synthesises is the one value this function cannot
+  // interpolate bare: `00-<trace>--01` is 39 characters and `TRACEPARENT_RE` — like every
+  // collector — rejects it, so the trace the header exists to continue is lost either way. A
+  // freshly minted id is what a propagator with no reported parent sends, and it keeps the trace
+  // id joinable. Deliberately not all-zero: `parseTraceparent` refuses that, as the spec requires.
+  const parentId = context.spanId === '' ? newSpanId() : context.spanId;
+  return `00-${context.traceId}-${parentId}-${flags}`;
 }
 
 export function parseTraceparent(header: string | null | undefined): SpanContext | undefined {

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, RealtimeConfig } from './config';
 import type { CtxPatch } from './context';
 import type { HydrateStrategy, OfflineStrategy, RenderMode } from './route-vocabulary';
 
@@ -101,6 +102,43 @@ 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
+>;
+
+/**
+ * The two `config.realtime` fields deleted for the same rule — `heartbeatMs` (2026-08-19) and
+ * `tier` (2026-08-23). `tier` is the worse of the two and the reason this pin exists: it accepted
+ * three values with three documented meanings, and `transport`/`urlEnv` are the only fields of
+ * this section any code reads, so all three meanings were one behaviour. Re-adding it restores a
+ * knob whose `'local-first'` setting promises a durable local store the framework does not build.
+ */
+type DeadRealtimeField = 'tier' | 'heartbeatMs';
+
+type _RealtimeConfigCarriesNoDeadField = Assert<
+  Extract<keyof RealtimeConfig, DeadRealtimeField> extends never ? true : false
+>;
+
+/** And the input side with it — `Input<RealtimeConfig>` is what an `app.config.ts` writes. */
+type _RealtimeInputCarriesNoDeadField = Assert<
+  Extract<keyof NonNullable<AppConfigInput['realtime']>, DeadRealtimeField> 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 +180,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>
+>;