@ultimat3/core 7.0.0 → 9.0.0

package/CLAUDE.md

@@ -79,12 +79,17 @@ escape, so a cause could repaint the screen or hide the line above it. `@ultimat
 deliberate duplicate for the tier-0 reason below, pinned behaviourally by
 `single-line-pin.test.ts` in `@ultimat3/cli`.
 
-`describeValue` in `error-render.ts` is a character-for-character duplicate of `describeValue` in
+`describeValue` in `error-render.ts` is a deliberate duplicate of `describeValue` in
 `packages/schema/src/describe-value.ts`, for the same tier-0 reason `SCHEMA_ERROR_CODE_TITLES` is
 one: schema and core are both tier 0 and `core → schema` is **not** a declared edge in
-`scripts/lib/tiers.ts`, so neither may import the other. Keep the two identical; a pin test in
+`scripts/lib/tiers.ts`, so neither may import the other. Keep the two ANSWERING identically — that
+is the contract, and the source is no longer character-for-character: schema counts characters
+through `char-count.ts`, which core copies privately. A pin test in
 `@ultimat3/cli` (which may legally import both) is the mechanical half, the same shape as
-`schema-error-codes-pin.test.ts`. The rule it enforces: a `cause` reaches the log index AND the
+`schema-error-codes-pin.test.ts`. **A string's length is CODE POINTS in both, `As of 2026-08-22`**
+— `validators.ts` rejects in that unit and `json-schema.ts` publishes `minLength` in it, so
+`.length` made `t.string.min(3).safeParse('👍a')` say "at least 3 chars, received a string of 3
+characters". The rule it enforces: a `cause` reaches the log index AND the
 HTTP problem document, redaction is by log FIELD key, and a value baked into a message string has
 no key left to redact — so `parseId`/`uuidTimestamp` describe a rejected id and never echo it.
 
@@ -105,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 |
@@ -175,6 +181,17 @@ NOT — `@ultimat3/query`, whose `OrderKey` is a name and a direction — must n
 orders a `text` column of digits lexically and a comparator guessing would trade one disagreement
 with the SQL it printed for another.
 
+`format-bytes.ts` is the same rule at its smallest, `As of 2026-08-22`: one `formatBytes(bytes)`,
+1024-base, `b|kb|mb|gb`, for the byte count an error message carries. `@ultimat3/render` (t4) and
+`@ultimat3/pwa` (t4) each had one and they had diverged — render's stopped at `kb`, so a 5 MiB route
+read `5120kb` in `X_BUDGET_EXCEEDED` and `5mb` in the precache warning about the same bytes, and
+`@ultimat3/cli`'s budget error imported render's. Deliberately NOT
+`@ultimat3/ui`'s `formatBytes(bytes, locale)`, which is a different function and stays: that one is
+`Intl`-formatted and DECIMAL (kB = 1000 B, which is what `Intl`'s unit means), for a human reading a
+file picker, where this one must line up with a bundler's own KiB figures and must not move with the
+reader's locale. **Not mechanised** — no gate refuses a third copy, unlike `render-modes.ts` for the
+route vocabulary; a `formatBytes` reappearing in `packages/*/src` is caught by review only.
+
 `mcp-exposure.ts` is the same shape for a declaration rather than an algorithm: `isMcpExposed` is
 the ONE answer to "did this primitive opt into being an MCP tool?", asked by `action`, `query`
 (t3), `mcp`, `ai`, `manifest` (t4) — five packages that cannot import each other, so core is the
@@ -207,6 +224,16 @@ which is what stops an exporter from turning 40k rps into 40k rps of spans. `con
 takes a `Sampler`; the default reads `OTEL_TRACES_SAMPLER*` **at the first span, never at module
 scope** (same call-time rule as `cursor.ts`'s secret). `resetTelemetry()` drops both.
 
+**An empty `spanId` means "no inbound decision", and every reader must honour it, `As of
+2026-08-22`.** `currentSpanContext()` synthesises `{ traceId, spanId: '', traceFlags: 1 }` from the
+request context — a trace id this process minted, plus the header it would send onward. Handing
+that to `Sampler.shouldSample` as a parent made `parentBasedRatioSampler` inherit a bit nobody sent,
+so at ratio 0 a root span outside a request exported 0 and one inside exported 1 — and
+`@ultimat3/http`'s `pipeline.ts` is `runWithContext` then `withSpan`, so **every HTTP root span was
+exported at every ratio**. `startSpan` now narrows through `inboundParent()`: the trace id is
+carried, the decision is not. It is the same discriminator `end()` already used to drop a synthetic
+`parentSpanId`.
+
 The OTLP exporters are built, not wrapped, and the case is in
 [`docs/idea/18-build-vs-wrap.md`](../../docs/idea/18-build-vs-wrap.md): OTLP/HTTP JSON is `fetch`
 plus `JSON.stringify`, while `@opentelemetry/api` would put a SECOND `Span` type in the framework
@@ -216,6 +243,15 @@ plus `JSON.stringify`, while `@opentelemetry/api` would put a SECOND `Span` type
 non-`http/json` `OTEL_EXPORTER_OTLP_PROTOCOL` throw `X_OTLP_PROTOCOL_UNSUPPORTED` naming `:4318`.
 A boot that must not throw asks `tryOtlpEndpoint(signal)` first.
 
+**Three OTLP variables, three codes, `As of 2026-08-22`** — `X_OTLP_ENDPOINT_INVALID`,
+`X_OTLP_HEADERS_INVALID`, `X_OTLP_PROTOCOL_UNSUPPORTED`, one per variable an operator sets. The
+headers one is not a duplicate of the endpoint one: `otlpHeaders` percent-decodes, so `%zz` in
+`OTEL_EXPORTER_OTLP_HEADERS` used to take the process down with a bare `URIError` at exporter
+construction, and raising the ENDPOINT code instead would send the first reader of
+`x errors explain` to inspect a variable that is fine. A title is what an agent reads first, and an
+accurate `cause:` does not rescue one that misdirects. The header **key** is in the cause, the fix
+and `meta`; the **value** is in none of them — it is the collector's credential.
+
 `error-reporter.ts` is the same shape a third time: `ErrorReporter`, a no-op default, a memory
 reporter for tests, and a transport on the wire (`error-reporter-sentry.ts`, an optional separate
 export — the DSN is the app's typed env, never a constant here). `reportError` never throws and
@@ -247,13 +283,32 @@ bun run typecheck
 `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
-failures by check name" is not writable against a boolean. Checks are **synchronous** on purpose:
+failures by check name" is not writable against a boolean. `HealthReport.registered` carries the
+COUNT beside it, `As of 2026-08-22`: `checks: {}` reads identically for "every check passed" and
+"nobody registered one", and only the second is a `/readyz` meaning no more than "the socket is
+bound". Reported, never enforced — **an empty registry is still `ready`, and `/readyz` still
+answers 200**: `Object.values({}).every(…)` is vacuously true, and that is deliberate so a role
+with no dependency does not have to invent a check to boot. `registered` is the field a caller
+reads to tell "all checks passed" from "there were none".
+
+`readinessChecks()` builds its record through `Object.fromEntries`, never by assigning
+`results[name]` — assignment to the one name `__proto__` sets the PROTOTYPE rather than adding a
+key, so a check by that name disappeared from the report and a `failing` one answered 200. Checks are **synchronous** on purpose:
 a probe that awaits a network call turns a slow dependency into a wedged endpoint and a restart
 loop, so the owner of the dependency keeps a boolean fresh and this reads it. Liveness ignores
 them — a database outage that failed `/healthz` would restart the whole fleet into the same
 outage. The registration returns its unregister, same shape and same ownership rule as
 `onShutdown`; `readinessCheckCount()` is the leak probe.
 
+**`drain()`'s memo is published BEFORE the first hook runs, `As of 2026-08-22`, and that ordering
+is the whole of the function.** A hook may call back into `drain()` and one does — `handle.stop()`
+in `@ultimat3/http` is `drain('manual')`, and an `accept` hook is exactly where a server stops
+listening — while `settleWithin` invokes a hook SYNCHRONOUSLY. `drainPromise = (async () => …)()`
+had therefore not assigned when the first hook ran: the re-entrant call read `undefined`, started a
+second whole drain and recursed **~4,700 deep** until the stack ran out, every level swallowed by
+`settleWithin` as `shutdown hook failed`. The guard and the registration are now one synchronous
+step (`jobs`' `worker.ts` states the same rule), with the phases in `runDrain`.
+
 **The drain deadline is enforced, not merely computed, and there is no unbounded state.**
 `ShutdownReason.deadlineAt` was always handed to every hook and **no hook has ever read it** —
 `jobs`' worker awaits every in-flight job and `driver.close()`, `jobs`' scheduler awaits its round,

package/README.md

@@ -322,6 +322,15 @@ nothing and still reports healthy.
   once has to keep it: a discarded one is a hook per `start()`, each retaining the resource it
   was going to drain, and the next drain runs every one of them against a torn-down copy.
   `shutdownHookCount()` is the test-only probe that makes the leak assertable.
+- `registerReadinessCheck(name, check)` is what makes `/readyz` mean **usable** rather than
+  **bound**. `ReadinessCheck` is `() => boolean` and must stay synchronous — a probe that awaits its
+  dependency turns a slow dependency into a wedged endpoint and then a restart loop; keep a boolean
+  fresh and let the check read it. It returns an unregister. `HealthReport.checks` is a map of name
+  → `'ok' | 'failing'`, so "alert on check failures by check name" is writable.
+- **`HealthReport.registered` is the third state.** `checks: {}` reads identically for "every check
+  passed" and "nobody registered one", and an **empty registry is still ready** — reported, never
+  enforced, so a role with no dependency does not have to invent a check to boot. Read `registered`
+  before trusting an empty `checks`.
 - Anything that opens a socket calls `markListening(server.url.origin)` and releases it on close.
   That is what tells the sealed test network a loopback request is this process, not egress.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "7.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';
 
@@ -22,38 +25,30 @@ export interface ThemeConfig {
 }
 
 /**
- * Where a browser that failed `auth: 'required'` is sent, and where it lands afterwards.
+ * Where a browser that failed `auth: 'required'` is sent.
  *
  * `signInPath: null` is the default and the redirect stays off until an app names its page: the
  * framework may not invent one of its app's routes, and an app that spells it `/login` would send
  * every unauthenticated visitor to a 404. Null means the visitor gets the problem document — the
  * right answer for an agent, and what a browser got in production until this existed.
+ *
+ * `afterSignInPath` was removed 2026-08 for the reason `urlEnv`, `poolSize` and `schema` were
+ * (below): accepted, defaulted and merged here, and read by NO file — `dummy/social-media-clone`
+ * set `/dashboard` and got whatever its sign-in route did on its own. The landing path belongs to
+ * the app's sign-in route, which is the only code that can honour it.
  */
 export interface AuthConfig {
   readonly signInPath: string | null;
-  /**
-   * Where sign-in lands when there is nowhere to return to, or `?next=` is not same-origin.
-   *
-   * **Consulted by nothing, `As of 2026-08.`** Accepted, defaulted and merged here and read by no
-   * file in the repo — `dummy/social-media-clone/app.config.ts` sets `/dashboard` and gets
-   * whatever the sign-in route does on its own. Same shape `urlEnv`, `poolSize` and `schema` were
-   * deleted for below; this one is not deleted yet only because its writer is a tracked app's
-   * config, so removing the key and the line that sets it is one commit across two file sets.
-   */
-  readonly afterSignInPath: string;
 }
 
+/**
+ * `installPrompt` was removed 2026-08, same rule: `@ultimat3/pwa`'s `createInstallController` is
+ * real and complete, nothing ever threaded the flag into it, and both tracked apps plus every
+ * scaffolded app set a switch with no wire. Call the controller from your own affordance instead.
+ */
 export interface PwaConfig {
   readonly enabled: boolean;
   readonly offline: OfflineStrategy;
-  /**
-   * **Consulted by nothing, `As of 2026-08.`** `wiki/Configuration.md` describes it as "render
-   * your own install affordance from the deferred event", both tracked apps set it, and
-   * `x new`'s scaffold writes it into every generated app — and no file reads it.
-   * `@ultimat3/pwa`'s `install.ts` is real and complete; nothing threads this flag into it.
-   * Delete the key or thread it; leaving it is a switch with no wire.
-   */
-  readonly installPrompt: boolean;
   readonly backgroundSync: boolean;
   readonly push: boolean;
 }
@@ -78,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 {
@@ -123,18 +132,16 @@ export interface McpConfig {
   readonly path: string;
 }
 
+/**
+ * No `modelEnv`. It named the env KEY holding the model id, "so no model string is baked into the
+ * image" — and its only reader was this file's own merge, copying input to output. Nothing
+ * consumed the merged value, so `modelEnv: 'ANTHROPIC_MODEL'` selected no model: `@ultimat3/ai`
+ * reads env for API KEYS only, and the model is `request.model ?? DEFAULT_MODEL`, a compile-time
+ * constant in `models.ts`. The exact thing the key existed to prevent is what it delivered.
+ * Deleted 2026-08 — pass `model` on the request, or read your own env key and pass it.
+ */
 export interface AiConfig {
   readonly mcp: McpConfig;
-  /**
-   * Env key for the model id, so no model string is baked into the image — **an intention, not a
-   * behaviour, `As of 2026-08`.** The only read of it in the repo is the merge two hundred lines
-   * below, which copies it from input to output; nothing consumes the merged value, so
-   * `examples/dummy`'s `modelEnv: 'ANTHROPIC_MODEL'` selects no model. `@ultimat3/ai` reads env
-   * for API KEYS only (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`); the model is
-   * `request.model ?? DEFAULT_MODEL`, a compile-time constant in `models.ts`. So the exact thing
-   * this key exists to prevent — a model string baked into the image — is what actually happens.
-   */
-  readonly modelEnv: string | undefined;
 }
 
 export interface AppConfig {
@@ -156,7 +163,8 @@ export interface AppConfig {
 
 type Input<T> = { readonly [K in keyof T]?: T[K] | undefined };
 
-export interface AiConfigInput extends Input<Omit<AiConfig, 'mcp'>> {
+/** `mcp` is the only member, and it is NESTED — `Input<AiConfig>` would make it all-or-nothing. */
+export interface AiConfigInput {
   readonly mcp?: Input<McpConfig> | undefined;
 }
 
@@ -224,17 +232,11 @@ function defaults(name: string): Omit<AppConfig, 'name'> {
     defaultTimeZone: 'UTC',
     defaultCurrency: 'USD',
     theme: { defaultMode: 'system', tokens: {} },
-    auth: { signInPath: null, afterSignInPath: '/' },
-    pwa: {
-      enabled: false,
-      offline: 'network-only',
-      installPrompt: false,
-      backgroundSync: false,
-      push: false,
-    },
+    auth: { signInPath: null },
+    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,
@@ -243,7 +245,7 @@ function defaults(name: string): Omit<AppConfig, 'name'> {
       visibilityTimeoutMs: 30_000,
     },
     realtime: { enabled: false, tier: 'channels', transport: 'memory', urlEnv: undefined },
-    ai: { mcp: { expose: true, path: '/mcp' }, modelEnv: undefined },
+    ai: { mcp: { expose: true, path: '/mcp' } },
   };
 }
 
@@ -259,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)}`);
@@ -292,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) {
@@ -301,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 },
     });
   }
@@ -337,10 +355,7 @@ export function defineConfig(
     cache: section(base.cache, merged.cache),
     jobs: section(base.jobs, merged.jobs),
     realtime: section(base.realtime, merged.realtime),
-    ai: {
-      mcp: section(base.ai.mcp, merged.ai?.mcp),
-      modelEnv: merged.ai?.modelEnv ?? base.ai.modelEnv,
-    },
+    ai: { mcp: section(base.ai.mcp, merged.ai?.mcp) },
   };
 
   validate(config);

package/src/context.ts

@@ -70,7 +70,13 @@ export interface CtxInit {
   readonly services?: ServiceBag | undefined;
 }
 
-export type CtxPatch = Omit<CtxInit, 'requestId'>;
+/**
+ * Neither id a child may change. `requestId` because one request is one request however many
+ * scopes it opens; `buildId` because a child context is the same DEPLOY — `withChildContext`
+ * has always forwarded the parent's, so accepting the key was an option that read as honoured and
+ * was dropped in silence. Pinned in `type-pins.ts`.
+ */
+export type CtxPatch = Omit<CtxInit, 'requestId' | 'buildId'>;
 
 /**
  * `async-context.ts` owns why this is a lazily-opened seam rather than a module-scope

package/src/decimal-order.ts

@@ -48,12 +48,16 @@ function decimalOf(value: unknown): Decimal | undefined {
  * a 38-digit `numeric` orders by its digits rather than by whatever a `Number` rounded it to.
  */
 function compare(left: Decimal, right: Decimal): number {
-  if (left.negative !== right.negative) return left.negative ? -1 : 1;
   const width = Math.max(left.fraction.length, right.fraction.length);
   const scaled = (value: Decimal): bigint =>
     BigInt(`${value.whole}${value.fraction.padEnd(width, '0')}`);
   const first = scaled(left);
   const second = scaled(right);
+  // Magnitude BEFORE sign, because a `numeric` has exactly one zero: `select '-0'::numeric =
+  // '0'::numeric` is true, and so is `'-0.00' = '0'`. Comparing the sign first answered `-1` for
+  // that pair and cut a keyset page boundary between two rows the database calls equal.
+  if (first === 0n && second === 0n) return 0;
+  if (left.negative !== right.negative) return left.negative ? -1 : 1;
   // Never a subtraction: the difference between two `bigint`s is exact and the return type is a
   // `number`, which cannot hold it.
   const order = first < second ? -1 : first > second ? 1 : 0;

package/src/error-codes.ts

@@ -53,6 +53,9 @@ const CORE_CODE_TITLES = {
   X_NO_CONTEXT: 'no request context is active',
   X_NOT_IMPLEMENTED: 'this driver does not implement the requested feature',
   X_OTLP_ENDPOINT_INVALID: 'the OTLP collector endpoint is missing or malformed',
+  // Its own code rather than the endpoint's, because a title is what an agent reads first:
+  // `x errors explain X_OTLP_ENDPOINT_INVALID` would send it to inspect a variable that is fine.
+  X_OTLP_HEADERS_INVALID: 'OTEL_EXPORTER_OTLP_HEADERS is malformed',
   X_OTLP_PROTOCOL_UNSUPPORTED: 'the OTLP protocol requested is not OTLP/HTTP JSON',
   X_READINESS_CHECK_DUPLICATE: 'a readiness check name is registered twice',
   X_REGISTRAR_CONFLICT: 'two different registrars are loaded for one primitive kind',

package/src/error-render.ts

@@ -252,17 +252,17 @@ export function renderMetaRecord(
  * There is no dev-only escape hatch on purpose — a flag is one misconfigured environment away
  * from being the same breach.
  *
- * A deliberate, character-for-character duplicate of `describeValue` in
- * `packages/schema/src/describe-value.ts`, for the reason `SCHEMA_ERROR_CODE_TITLES` is one:
- * `@ultimat3/schema` is tier 0 alongside this package, so neither may import the other. Keep the
- * two identical; changing one alone is the bug.
+ * A deliberate duplicate of `describeValue` in `packages/schema/src/describe-value.ts`, for the
+ * reason `SCHEMA_ERROR_CODE_TITLES` is one: `@ultimat3/schema` is tier 0 alongside this package,
+ * so neither may import the other. Keep the two answering IDENTICALLY — that is what
+ * `packages/cli/src/describe-value-pin.test.ts` holds — and changing one alone is the bug.
  */
 export function describeValue(value: unknown): string {
   if (value === undefined) return 'undefined';
   if (value === null) return 'null';
   switch (typeof value) {
     case 'string':
-      return countOf(value.length, 'string', 'character');
+      return countOf(charCount(value), 'string', 'character');
     case 'number':
       return describeNumber(value);
     case 'boolean':
@@ -294,3 +294,15 @@ function countOf(size: number, noun: string, unit: string): string {
   const article = noun === 'array' ? 'an' : 'a';
   return `${article} ${noun} of ${size} ${unit}${size === 1 ? '' : 's'}`;
 }
+
+/**
+ * The twin of `@ultimat3/schema`'s `char-count.ts`, duplicated for the same reason `describeValue`
+ * is: both packages are tier 0 and neither may import the other. Code points, because the rules
+ * that reject a string count in them and the message must quote the same unit — `'👍'.length` is 2.
+ * Only a surrogate makes the two counts differ, so every ASCII value keeps the O(1) read.
+ */
+const HAS_SURROGATE = /[\uD800-\uDBFF]/;
+
+function charCount(value: string): number {
+  return HAS_SURROGATE.test(value) ? [...value].length : value.length;
+}

package/src/exports/observability.ts

@@ -42,6 +42,7 @@ export {
   REDACTED,
   redactKeys,
   setLoggerContextFields,
+  setLogStream,
 } from '../logger';
 export type {
   Counter,
@@ -88,6 +89,7 @@ export {
   OTLP_PROTOCOL_KEY,
   OTLP_SCOPE,
   OtlpEndpointInvalidError,
+  OtlpHeadersInvalidError,
   OtlpProtocolUnsupportedError,
   otlpAttributes,
   otlpEndpoint,

package/src/format-bytes.ts

@@ -0,0 +1,47 @@
+// Single responsibility: a byte count as the short, machine-ish string an error message carries.
+//
+// Tier 0 because two tier-4 packages need exactly this and neither may import the other:
+// `@ultimat3/render`'s `X_BUDGET_EXCEEDED` cause and `@ultimat3/pwa`'s precache warning. Each kept
+// its own copy and they had diverged — render's stopped at `kb`, so one 5 MiB route read `5120kb`
+// in the budget error and `5mb` in the warning about the same bytes.
+
+/** 1024-based, because every producer here counts bundle bytes, which tooling reports in KiB. */
+const STEP = 1024;
+
+/**
+ * Ascending, so the index into it IS the power of `STEP`. `gb` is the last rung on purpose: a
+ * precache or a route bundle past a terabyte is a bug in the caller, not a unit this should grow.
+ */
+const UNITS = ['b', 'kb', 'mb', 'gb'] as const;
+
+const round1 = (value: number): number => Math.round(value * 10) / 10;
+
+/**
+ * A size a message can state — `1023b`, `4.5kb`, `5mb`, `1.2gb`.
+ *
+ * Not `@ultimat3/ui`'s `formatBytes(bytes, locale)`, which is `Intl`-formatted, DECIMAL (kB = 1000
+ * B, because that is what `Intl`'s unit means) and for a human reading a file picker. This one is
+ * for an error's `cause:`, where the number has to line up with a bundler's own KiB figures and
+ * must not change with the reader's locale.
+ *
+ * A negative or non-finite input answers `0b` rather than `-5b` or `NaNb`: axiom 4 says an error is
+ * an instruction, and `NaNb` instructs nobody. A size is never negative, so the input was already
+ * wrong by the time it arrived.
+ */
+export const formatBytes = (bytes: number): string => {
+  if (!Number.isFinite(bytes) || bytes <= 0) return `0${UNITS[0]}`;
+  let value = bytes;
+  let index = 0;
+  while (index < UNITS.length - 1 && value >= STEP) {
+    value /= STEP;
+    index += 1;
+  }
+  // One more rung when ROUNDING crosses the boundary the raw value did not: 1048575 is under a
+  // mebibyte, but one decimal place renders it `1024kb` — a number that disagrees with its own
+  // unit, the same class of bug as render's missing `mb` branch.
+  if (index < UNITS.length - 1 && round1(value) >= STEP) {
+    value /= STEP;
+    index += 1;
+  }
+  return `${round1(value)}${UNITS[index] ?? 'b'}`;
+};

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,
@@ -268,6 +268,7 @@ export {
   OTLP_PROTOCOL_KEY,
   OTLP_SCOPE,
   OtlpEndpointInvalidError,
+  OtlpHeadersInvalidError,
   OtlpProtocolUnsupportedError,
   OVERFLOW_ATTRIBUTE,
   otlpAttributes,
@@ -303,6 +304,7 @@ export {
   sentryErrorReporter,
   serviceResource,
   setLoggerContextFields,
+  setLogStream,
   startMetricExport,
   startSpan,
   traceparent,
@@ -369,6 +371,7 @@ export {
   writeMasterKeyFile,
   writeSecretsFile,
 } from './exports/secrets';
+export { formatBytes } from './format-bytes';
 export type { Brand, Id } from './ids';
 export {
   isSpanId,
@@ -459,17 +462,19 @@ export {
   SHUTDOWN_PHASES,
   shutdownHookCount,
 } from './lifecycle';
-export {
-  isSelfOrigin,
-  listeningOrigins,
-  markListening,
-  resetListeners,
-} from './listeners';
+export { isSelfOrigin, listeningOrigins, markListening, resetListeners } from './listeners';
 export { isMcpExposed, type McpExposureDeclaration } from './mcp-exposure';
+export { nearestName } from './nearest-name';
 export { type CappedBody, readWithinLimit } from './read-capped';
-export type { ModuleRegistrar, PrimitiveKind, RegisteredPrimitive } from './registrar';
+export type {
+  ModuleRegistrar,
+  PrimitiveFactory,
+  PrimitiveKind,
+  RegisteredPrimitive,
+} from './registrar';
 export {
   hasPrimitiveRegistrar,
+  PRIMITIVE_FACTORIES,
   PRIMITIVE_KINDS,
   primitiveRegistrar,
   registerPrimitiveRegistrar,

package/src/lifecycle.ts

@@ -82,6 +82,14 @@ export interface HealthReport {
   readonly buildId: string;
   /** Named, because "alert on check failures BY CHECK NAME" is not writable against a boolean. */
   readonly checks: Readonly<Record<string, ReadinessStatus>>;
+  /**
+   * How many checks are registered. `checks: {}` reads identically for "every check passed" and
+   * "nobody registered one", and only the second is a `/readyz` that means no more than "the
+   * socket is bound" — which is what the chart's and compose's healthchecks route traffic on.
+   * Reported rather than enforced: an empty registry is still ready, so a role that genuinely has
+   * no dependency does not have to invent a check to boot.
+   */
+  readonly registered: number;
 }
 
 export interface HealthPayload {
@@ -192,18 +200,25 @@ function report(level: 'info' | 'warn' | 'error', message: string, fields: LogFi
   }
 }
 
-/** Every check, run now, by name. A check that throws is `failing` — never an unhandled error. */
+/**
+ * Every check, run now, by name. A check that throws is `failing` — never an unhandled error.
+ *
+ * Built through `Object.fromEntries`, never by assigning `results[name]`: assignment to the one
+ * name `__proto__` sets the PROTOTYPE instead of adding a key, so that check vanished from the
+ * report, `ready` was computed over an empty object — vacuously true — and a failing check
+ * answered 200. `fromEntries` defines own properties and has no such name.
+ */
 export function readinessChecks(): Readonly<Record<string, ReadinessStatus>> {
-  const results: Record<string, ReadinessStatus> = {};
+  const results: [string, ReadinessStatus][] = [];
   for (const [name, check] of readiness) {
     try {
-      results[name] = check() ? 'ok' : 'failing';
+      results.push([name, check() ? 'ok' : 'failing']);
     } catch (thrown) {
-      results[name] = 'failing';
+      results.push([name, 'failing']);
       report('warn', 'readiness check threw', { check: name, error: thrown });
     }
   }
-  return results;
+  return Object.fromEntries(results);
 }
 
 export function inflightCount(): number {
@@ -328,43 +343,62 @@ async function runPhase(phase: ShutdownPhase, reason: ShutdownReason): Promise<v
   }
 }
 
-/** Idempotent: concurrent signals join the same drain. */
+/** The three phases, in order, under one budget. Never rejects — `drain()` depends on that. */
+async function runDrain(signal: string, reason: ShutdownReason): Promise<void> {
+  try {
+    report('info', 'draining', { signal, deadlineMs, inflight });
+    await runPhase('accept', reason);
+
+    // Real monotonic, like `deadlineAt` itself: `waitForIdle` sleeps on a real `setTimeout`, and
+    // a budget read off an injected clock is a number that timer will never honour.
+    const remaining = Math.max(0, reason.deadlineAt - systemClock.monotonic());
+    const idle = await waitForIdle(remaining);
+    if (!idle) {
+      report('warn', 'X_SHUTDOWN_TIMEOUT', {
+        code: 'X_SHUTDOWN_TIMEOUT',
+        cause: `${inflight} in-flight operations still running after ${deadlineMs}ms`,
+        fix: 'raise the budget past the slowest handler — configureLifecycle({ deadlineMs: 600_000 }) for a 10-minute one — and set terminationGracePeriodSeconds to at least as many seconds, or shorten the handler',
+      });
+    }
+
+    await runPhase('inflight', reason);
+    await runPhase('close', reason);
+  } catch (thrown) {
+    // Nothing above should reach here — every hook is caught by `settleWithin` and every line
+    // goes through `report`. If something does, the drain still ENDS: a rejected `drainPromise`
+    // is a memo that re-rejects for every later caller and an unhandled rejection that kills the
+    // process mid-drain, which is strictly worse than a drain that finished badly and said so.
+    report('error', 'drain failed', { signal, error: thrown });
+  } finally {
+    state = 'stopped';
+  }
+  report('info', 'stopped', { signal });
+}
+
+/**
+ * Idempotent: concurrent signals join the same drain, and so does a RE-ENTRANT one.
+ *
+ * The memo is published before `runDrain` is called, and that ordering is the whole of this
+ * function. A hook may call back in here — `handle.stop()` in `@ultimat3/http` is `drain('manual')`
+ * and an `accept` hook is exactly where a server stops listening — and `settleWithin` invokes a
+ * hook SYNCHRONOUSLY, so the old `drainPromise = (async () => …)()` had not assigned yet when the
+ * first hook ran: the re-entrant call saw `undefined`, started a second whole drain, and recursed
+ * ~4,700 deep until the stack ran out, every level swallowed by `settleWithin` as
+ * `shutdown hook failed`. Same rule as `packages/jobs/src/worker.ts` — guard and registration in
+ * one synchronous step.
+ */
 export function drain(signal = 'manual'): Promise<void> {
   if (drainPromise !== undefined) return drainPromise;
   state = 'draining';
   const reason: ShutdownReason = { signal, deadlineAt: systemClock.monotonic() + deadlineMs };
-
-  drainPromise = (async () => {
-    try {
-      report('info', 'draining', { signal, deadlineMs, inflight });
-      await runPhase('accept', reason);
-
-      // Real monotonic, like `deadlineAt` itself: `waitForIdle` sleeps on a real `setTimeout`, and
-      // a budget read off an injected clock is a number that timer will never honour.
-      const remaining = Math.max(0, reason.deadlineAt - systemClock.monotonic());
-      const idle = await waitForIdle(remaining);
-      if (!idle) {
-        report('warn', 'X_SHUTDOWN_TIMEOUT', {
-          code: 'X_SHUTDOWN_TIMEOUT',
-          cause: `${inflight} in-flight operations still running after ${deadlineMs}ms`,
-          fix: 'raise the budget past the slowest handler — configureLifecycle({ deadlineMs: 600_000 }) for a 10-minute one — and set terminationGracePeriodSeconds to at least as many seconds, or shorten the handler',
-        });
-      }
-
-      await runPhase('inflight', reason);
-      await runPhase('close', reason);
-    } catch (thrown) {
-      // Nothing above should reach here — every hook is caught by `settleWithin` and every line
-      // goes through `report`. If something does, the drain still ENDS: a rejected `drainPromise`
-      // is a memo that re-rejects for every later caller and an unhandled rejection that kills the
-      // process mid-drain, which is strictly worse than a drain that finished badly and said so.
-      report('error', 'drain failed', { signal, error: thrown });
-    } finally {
-      state = 'stopped';
-    }
-    report('info', 'stopped', { signal });
-  })();
-
+  let published!: () => void;
+  drainPromise = new Promise<void>((resolve) => {
+    published = resolve;
+  });
+  // Both settle paths, for the reason `installSignalHandlers` gives below: `runDrain` cannot
+  // reject today — that is its `try/finally`, not luck — and a rejected memo would re-reject for
+  // every later caller and end the process the drain was trying to end cleanly.
+  void runDrain(signal, reason).then(published, published);
   return drainPromise;
 }
 
@@ -410,6 +444,7 @@ export function healthReport(): HealthReport {
     inflight,
     buildId: process.env['BUILD_ID'] ?? 'dev',
     checks,
+    registered: readiness.size,
   };
 }
 

package/src/logger.ts

@@ -101,8 +101,28 @@ export function setLoggerContextFields(provider: () => LogFields | undefined): v
   contextFields = provider;
 }
 
+/**
+ * Where a line with no explicit writer lands, for everything below `error`. A fact about the
+ * PROCESS and not about the line: a container's stdout IS its log stream (12-factor), while a
+ * CLI's stdout is the answer it was asked for. `x db migrate --json` printed the boot logger's
+ * `ultimate migrate applied` and then the command's own JSON to fd 1, so a caller doing what
+ * `--json` exists for — parsing the output — raised on the second object.
+ */
+let logStream: 'stdout' | 'stderr' = 'stdout';
+
+/**
+ * Send everything below `error` to stderr, or back to stdout. The process's own call, made once at
+ * entry: a per-line choice would be the second logging path axiom 1 refuses, and a per-logger one
+ * already exists as `LoggerOptions.writer` — what had no seam is the module-scope `logger`, which
+ * is the one `serve.ts` and every boot path write through.
+ */
+export function setLogStream(stream: 'stdout' | 'stderr'): void {
+  logStream = stream;
+}
+
 function defaultWriter(line: string, level: LogLevel): void {
-  const stream = LEVEL_WEIGHT[level] >= LEVEL_WEIGHT.error ? process.stderr : process.stdout;
+  const toStderr = logStream === 'stderr' || LEVEL_WEIGHT[level] >= LEVEL_WEIGHT.error;
+  const stream = toStderr ? process.stderr : process.stdout;
   stream.write(`${line}\n`);
 }
 

package/src/nearest-name.ts

@@ -0,0 +1,45 @@
+// Single responsibility: the declared name a mistyped one most likely meant, so any error can lead
+// with the real one. It lives in core because three packages need the same answer — `@ultimat3/cli`
+// for an unknown command, flag or positional, `@ultimat3/policy` for an unknown permission — and
+// two copies of one cutoff are two suggestions for one typo.
+
+/**
+ * Levenshtein distance. A grid rather than two rolling rows because `noUncheckedIndexedAccess`
+ * makes every read an `?? 0`, and one `at()` reads better than four of them.
+ */
+const distance = (a: string, b: string): number => {
+  const rows = a.length + 1;
+  const cols = b.length + 1;
+  const grid: number[] = new Array<number>(rows * cols).fill(0);
+  const at = (r: number, c: number): number => grid[r * cols + c] ?? 0;
+  for (let r = 0; r < rows; r += 1) grid[r * cols] = r;
+  for (let c = 0; c < cols; c += 1) grid[c] = c;
+  for (let r = 1; r < rows; r += 1) {
+    for (let c = 1; c < cols; c += 1) {
+      const cost = a[r - 1] === b[c - 1] ? 0 : 1;
+      grid[r * cols + c] = Math.min(at(r - 1, c) + 1, at(r, c - 1) + 1, at(r - 1, c - 1) + cost);
+    }
+  }
+  return at(rows - 1, cols - 1);
+};
+
+/** Past this many edits the "suggestion" is a different word, and a wrong lead is worse than none. */
+const MAX_EDITS = 3;
+
+/**
+ * The nearest candidate within `MAX_EDITS`, or `undefined` when nothing is close enough. Ties keep
+ * the FIRST candidate, which is the order the caller declared them in — `definePermissions([...])`
+ * and a `CommandSpec` list are both authored orders, and a stable answer is what lets a test pin one.
+ */
+export const nearestName = (input: string, candidates: readonly string[]): string | undefined => {
+  let best: string | undefined;
+  let bestScore = MAX_EDITS + 1;
+  for (const candidate of candidates) {
+    const score = distance(input, candidate);
+    if (score < bestScore) {
+      best = candidate;
+      bestScore = score;
+    }
+  }
+  return best;
+};

package/src/otlp.ts

@@ -15,6 +15,20 @@ export class OtlpEndpointInvalidError extends UltimateError {
   }
 }
 
+/**
+ * Separate from `OtlpEndpointInvalidError` on purpose. The endpoint code's title says the ENDPOINT
+ * is missing or malformed, so raising it for a bad header escape sends the first reader of
+ * `x errors explain` to inspect `OTEL_EXPORTER_OTLP_ENDPOINT` — a variable that is fine. An
+ * accurate `cause:` does not rescue a title that misdirects.
+ */
+export class OtlpHeadersInvalidError extends UltimateError {
+  static readonly code = 'X_OTLP_HEADERS_INVALID';
+  override readonly name = 'OtlpHeadersInvalidError';
+  constructor(init: CodedErrorInit) {
+    super({ ...init, code: OtlpHeadersInvalidError.code });
+  }
+}
+
 export class OtlpProtocolUnsupportedError extends UltimateError {
   static readonly code = 'X_OTLP_PROTOCOL_UNSUPPORTED';
   override readonly name = 'OtlpProtocolUnsupportedError';
@@ -112,6 +126,25 @@ export function otlpEndpoint(
   });
 }
 
+/**
+ * One header value, percent-decoded. `decodeURIComponent` throws a bare `URIError` on a malformed
+ * escape (`%zz`, a lone `%`), and the whole of `otlpHeaders` runs at exporter construction — so a
+ * typo in an operator-set variable took the process down with an error carrying no code, no cause
+ * and no fix. Refused instead, naming the variable and the header KEY: the value is the
+ * collector's credential and a `cause:` is folded into a log line.
+ */
+function decodeHeaderValue(key: string, raw: string): string {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    throw new OtlpHeadersInvalidError({
+      cause: `${OTLP_HEADERS_KEY} carries a malformed percent-escape in the "${key}" value, so the header cannot be decoded`,
+      fix: `set ${OTLP_HEADERS_KEY}=${key}=<encoded>, where <encoded> is what bun -e 'console.log(encodeURIComponent(process.argv[1]))' <value> prints — or drop the stray % from the "${key}" value if it was meant literally`,
+      meta: { header: key },
+    });
+  }
+}
+
 /** `key=value,key2=value2`, percent-decoded — the spec's format for collector auth headers. */
 export function otlpHeaders(
   explicit?: Readonly<Record<string, string>> | undefined,
@@ -125,7 +158,7 @@ export function otlpHeaders(
       if (index <= 0) continue;
       const key = pair.slice(0, index).trim().toLowerCase();
       if (key === '') continue;
-      headers[key] = decodeURIComponent(pair.slice(index + 1).trim());
+      headers[key] = decodeHeaderValue(key, pair.slice(index + 1).trim());
     }
   }
   for (const [key, value] of Object.entries(explicit ?? {})) headers[key.toLowerCase()] = value;

package/src/registrar.ts

@@ -27,6 +27,44 @@ export const PRIMITIVE_KINDS = [
 
 export type PrimitiveKind = (typeof PRIMITIVE_KINDS)[number];
 
+/** One factory over one primitive: the export's name, the package that ships it, what it returns. */
+export interface PrimitiveFactory {
+  readonly factory: string;
+  /** The package specifier the factory is imported from, so a `fix:` can be pasted. */
+  readonly pkg: string;
+  readonly kind: PrimitiveKind;
+}
+
+/**
+ * The other half of "never invent a ninth": the factories that already exist, in one table.
+ *
+ * Prose counted them — "the fourth instance of the framework's factory rule" — in three files that
+ * cannot see each other, so every ordinal was wrong the moment a fifth landed and none of them
+ * could be checked. A list here can be: `@ultimat3/cli` is tier 5, may import `ai`, `jobs` and
+ * `scraping`, and pins that every exported function returning an `Action`/`JobHandle` from outside
+ * their owning packages has a row. Adding a factory means adding a row, not editing a sentence.
+ *
+ * Sorted by package then name so the diff of a new row is one line.
+ *
+ * Every ROW is frozen, not just the list. `readonly` fields are a compile-time claim and this is a
+ * public export: freezing the array alone left `PRIMITIVE_FACTORIES[0].kind = 'entity'` a silent
+ * write from any untyped caller, which is the same defect `@ultimat3/money`'s currency rows
+ * carried — a table the framework hands out is a constant at RUNTIME or it is not a constant.
+ */
+export const PRIMITIVE_FACTORIES = Object.freeze<readonly PrimitiveFactory[]>(
+  (
+    [
+      { factory: 'agent', pkg: '@ultimat3/ai', kind: 'action' },
+      { factory: 'agentJob', pkg: '@ultimat3/ai', kind: 'job' },
+      { 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)),
+);
+
 /**
  * What a registrar hands back: the primitives it actually took, each carrying the name
  * registration stamped on it. Returning the registered set — rather than nothing — is what lets

package/src/telemetry.ts

@@ -167,7 +167,13 @@ export function currentSpan(): Span | undefined {
   return activeSpan.get();
 }
 
-/** The trace the caller is inside: active span, else the request context, else a fresh trace. */
+/**
+ * The trace the caller is inside: active span, else the request context, else a fresh trace.
+ *
+ * The context branch carries an EMPTY `spanId` on purpose, and that emptiness is the discriminator
+ * every reader must honour: it is a trace id this process minted, not a span an upstream reported.
+ * `traceFlags: 1` here is the header this process would send onward, never a decision it received.
+ */
 export function currentSpanContext(): SpanContext | undefined {
   const span = activeSpan.get();
   if (span !== undefined) return span.context;
@@ -176,8 +182,20 @@ export function currentSpanContext(): SpanContext | undefined {
   return { traceId: ctx.traceId, spanId: '', traceFlags: 1 };
 }
 
+/**
+ * A parent an upstream actually reported, as opposed to the synthetic one `currentSpanContext()`
+ * builds from a request context. Only the first carries a sampling decision: reading the synthetic
+ * one as inbound made `parentBasedRatioSampler` inherit a bit nobody sent, so every HTTP root span
+ * was exported at every ratio — `pipeline.ts` is `runWithContext` then `withSpan`, which is that
+ * exact pair — and the one lever between "tracing is on" and "the collector melts" did nothing.
+ */
+function inboundParent(parent: SpanContext | undefined): SpanContext | undefined {
+  return parent === undefined || parent.spanId === '' ? undefined : parent;
+}
+
 export function startSpan(name: string, options?: StartSpanOptions): Span {
   const parent = options?.parent ?? currentSpanContext();
+  const inbound = inboundParent(parent);
   const attributes: Record<string, AttributeValue> = { ...(options?.attributes ?? {}) };
   // The bit is decided ONCE, here, and every child of this span inherits it through `parent` —
   // so one trace is sampled or not sampled as a whole. Before this, `traceFlags` was hardcoded to
@@ -186,7 +204,7 @@ export function startSpan(name: string, options?: StartSpanOptions): Span {
   const context: SpanContext = {
     traceId: parent?.traceId ?? newTraceId(),
     spanId: newSpanId(),
-    traceFlags: currentSampler().shouldSample(name, parent, attributes) ? 1 : 0,
+    traceFlags: currentSampler().shouldSample(name, inbound, attributes) ? 1 : 0,
   };
   const events: SpanEvent[] = [];
   const startedAt = clock.now().getTime();
@@ -245,7 +263,7 @@ export function startSpan(name: string, options?: StartSpanOptions): Span {
       // `traceparent`; it is simply not exported.
       if ((context.traceFlags & 1) === 0) return;
       const endedAt = clock.now().getTime();
-      const parentSpanId = parent === undefined || parent.spanId === '' ? undefined : parent.spanId;
+      const parentSpanId = inbound?.spanId;
       exporter.export({
         name,
         kind: options?.kind ?? 'internal',

package/src/type-pins.ts

@@ -1,10 +1,13 @@
-// Compile-time pins for the actor-facts seam, the config surface and the route vocabulary.
+// Compile-time pins for the actor-facts seam, the config surface, the request-context patch and
+// 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';
 
 /** Fails to compile when `T` is anything but `true`. The whole mechanism. */
@@ -99,6 +102,40 @@ 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
+ * without a word — the same silent-no-op class as the three `database` fields above, one tier
+ * lower. `requestId` is here beside it because the two are refused for the same reason.
+ */
+type UnpatchableCtxKey = 'requestId' | 'buildId';
+
+type _CtxPatchRefusesTheIds = Assert<
+  Extract<keyof CtxPatch, UnpatchableCtxKey> extends never ? true : false
+>;
+
+/** And the keys a child MAY change are still there — a pin that empties the type is not a pin. */
+type _CtxPatchStillPatchesTheRest = Assert<
+  'actor' | 'locale' | 'tz' extends keyof CtxPatch ? true : false
+>;
+
 /**
  * Mutual assignability, not one-way. The tuples are load-bearing: a bare `A extends B` distributes
  * over a union and answers `true` for every member separately, so it cannot see a widening — which
@@ -123,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>
+>;