@ultimat3/core 6.0.0 → 8.0.0

package/CLAUDE.md

@@ -14,6 +14,7 @@ is a change to every package.
 | New code | add to `CORE_CODE_TITLES` in `error-codes.ts`, else the title is auto-humanised |
 | 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` |
 | Exports | add to `src/index.ts` explicitly; no `export *`. Three subjects that each span a dozen modules arrive through `src/exports/` — every name is still written out in `index.ts`, so the public surface is one file to read |
 | Files | < 200 LOC, 500 hard ceiling, one responsibility, `kebab-case.ts`, test beside source |
 | Type claims | `type-pins.ts`, never a `.test.ts` — `tsconfig.json` excludes tests, so `tsc` never reads one |
@@ -22,6 +23,24 @@ Deliberate cycles (safe — nothing is referenced at module-evaluation time):
 `errors.ts ⇄ error-codes.ts`. Keep it that way: no top-level `UltimateError` use in
 `error-codes.ts`.
 
+**`async-context.ts` is the framework's ONE `AsyncLocalStorage`, and that is a framework rule
+rather than a core one, `As of 2026-08-20`.** `asyncContext` is exported from `src/index.ts` and
+six modules outside this package opened their own before they adopted it — `@ultimat3/db`'s
+transaction, statement attribution and expected-loop scopes, `@ultimat3/entity`'s `crossTenant`,
+`@ultimat3/ai`'s budget ledger and LLM stream sink. Each was a module-scope `new` a browser bundler
+turns into `TypeError: undefined is not a constructor` at module EVALUATION, so importing any of
+those packages from a client bundle failed before a line of app code ran. Reads degrade to
+`undefined`, writes throw `X_ASYNC_CONTEXT_UNAVAILABLE`; deferring the construction changes nothing
+a server can observe — the storage is built on the first `get()` or `run()` rather than at module
+evaluation, and `getStore()` outside a scope answers `undefined` either way.
+
+The mechanical half is `scripts/async-context-guard.ts`, collected by `x verify`'s `unit` step
+through `scripts/async-context-guard.test.ts` — it refuses a `new AsyncLocalStorage` **and** the
+import that binds the class, aliased or namespaced, anywhere but this one file. The browser-barrel
+test in `async-context.test.ts` covers the same defect for core alone and cannot see another
+package; the guard cannot see a runtime `await import('node:async_hooks')`. Neither is the other's
+duplicate.
+
 `error-render.ts` imports nothing, including from this package — an error factory that dies
 formatting its own message is the failure it exists to prevent, so it cannot depend on anything
 that could itself throw. The same defect shipped three times (`entity`, `flags`, `cli`) before
@@ -60,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.
 
@@ -85,6 +109,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 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 |
@@ -155,6 +180,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
@@ -187,6 +223,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
@@ -196,6 +242,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
@@ -227,13 +282,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

@@ -9,7 +9,8 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | rendering an app's value into a `cause` / `fix` without throwing | `error-render.ts` |
 | code → `{ title, docs }` registry, `registerErrorCodes()` | `error-codes.ts` |
 | `Result<T, E>` for boundaries where throwing is wrong | `result.ts` |
-| request context on `AsyncLocalStorage` | `context.ts` |
+| the one lazy `AsyncLocalStorage`, every ambient scope in the framework | `async-context.ts` |
+| request context on that seam | `context.ts` |
 | `Actor` (`user \| service \| agent \| anonymous`) | `actor.ts` |
 | acting as another actor, with an origin and a reason | `impersonate.ts` |
 | is an error worth retrying? one classification per code | `error-retry.ts` |
@@ -20,6 +21,7 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | the committed encrypted secrets envelope, AES-256-GCM | `secrets.ts` |
 | the two secrets files, and decrypted values → `defineEnv` | `secrets-store.ts` |
 | `defineConfig()` for `app.config.ts` | `config.ts` |
+| the closed route vocabulary every renderer names | `route-vocabulary.ts` |
 | runtime roles + `ROLE` resolution | `roles.ts` |
 | `Clock` — the only source of "now" | `clock.ts` |
 | UUIDv7, nanoid, branded ids | `ids.ts` |
@@ -320,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,9 +1,15 @@
 {
   "name": "@ultimat3/core",
-  "version": "6.0.0",
+  "version": "8.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
+  "sideEffects": [
+    "./src/context.ts",
+    "./src/lifecycle-errors.ts",
+    "./src/schema-error-codes.ts",
+    "./src/secrets-errors.ts"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/developerz-ai/ultimate.git",

package/src/async-context.ts

@@ -16,16 +16,18 @@ export interface AsyncContext<T> {
 }
 
 /**
- * The storage is constructed on first `run()`, never at module scope. That is the whole point of
- * this file: a browser bundler stubs `node:async_hooks` to `{}` — Bun's `target: 'browser'` emits
- * `var { AsyncLocalStorage } = (() => ({}))` — so a module-scope `new` threw
+ * The storage is constructed on the first `get()` or `run()`, never at module scope. That is the
+ * whole point of this file: a browser bundler stubs `node:async_hooks` to `{}` — Bun's
+ * `target: 'browser'` emits `var { AsyncLocalStorage } = (() => ({}))` — so a module-scope `new` threw
  * `TypeError: undefined is not a constructor` at module EVALUATION, and every package that
  * transitively imports core was dead on arrival in a client bundle. `@ultimat3/ui` calls itself a
  * SolidJS design system and could not be put on a client by the only client bundler the framework
  * has, for this reason and no other.
  *
- * The server pays nothing: `getStore()` before any `run()` answers `undefined` whether the storage
- * was ever constructed or not, so deferring the construction changes no observable behaviour.
+ * The laziness buys the browser bundle, not a server allocation. `open()` runs on a READ as well as
+ * a write, so a server whose first call is `get()` constructs the storage there — it is deferred,
+ * never skipped. What deferring changes is nothing observable: `getStore()` outside a scope answers
+ * `undefined` whether the storage was ever constructed or not, which is what makes it safe.
  *
  * **Reads degrade, writes throw**, and that split is the doctrine rather than a convenience.
  * `get()` answers `undefined` in a browser because that is TRUE — nothing is in flight there, so

package/src/config.ts

@@ -4,10 +4,13 @@
 
 import { ConfigInvalidError } from './errors';
 import { ROLES, type Role } from './roles';
+// `app.config.ts` CONSUMES the route vocabulary; it does not own it. Declaring `OfflineStrategy`
+// here is what made it copyable — `render`, `manifest` and `pwa` each wrote their own rather than
+// import a name that reads like a config key.
+import type { OfflineStrategy } from './route-vocabulary';
 import { isIanaZoneName } from './time-zone-name';
 
 export type ThemeMode = 'light' | 'dark' | 'system';
-export type OfflineStrategy = 'precache' | 'runtime' | 'network-only';
 export type CacheTier = 'memo' | 'lru' | 'shared' | 'isr' | 'cdn';
 export type RealtimeTier = 'channels' | 'live-queries' | 'local-first';
 export type RealtimeTransport = 'memory' | 'nats' | 'redis';
@@ -19,38 +22,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;
 }
@@ -120,18 +115,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 {
@@ -153,7 +146,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;
 }
 
@@ -221,14 +215,8 @@ 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'] },
@@ -240,7 +228,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' } },
   };
 }
 
@@ -334,10 +322,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/error-reporter-sentry.ts

@@ -64,7 +64,7 @@ export function parseSentryDsn(dsn: string): SentryDsn {
 }
 
 /** The protocol's own level names. `warning`/`error`/`fatal` happen to be the same three words. */
-const LEVELS: Readonly<Record<ErrorSeverity, string>> = Object.freeze({
+const LEVELS = Object.freeze<Record<ErrorSeverity, string>>({
   warning: 'warning',
   error: 'error',
   fatal: 'fatal',

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

@@ -31,6 +31,7 @@ export {
 } from './actor';
 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 { canonicalJson, fingerprint } from './canonical-json';
 export { type Clock, type FrozenClock, frozenClock, systemClock } from './clock';
 export type {
@@ -45,7 +46,6 @@ export type {
   DatabaseConfig,
   JobsConfig,
   McpConfig,
-  OfflineStrategy,
   PwaConfig,
   RealtimeConfig,
   RealtimeTier,
@@ -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,
@@ -479,6 +484,8 @@ export type { Err, Ok, Result } from './result';
 export { err, isErr, isOk, map, mapErr, ok, tryCatch, unwrap, unwrapOr } from './result';
 export type { ResolveRoleOptions, Role, RoleInfo, ScalingSignal } from './roles';
 export { DEFAULT_ROLE, isRole, ROLE_INFO, ROLES, resolveRole } from './roles';
+export type { HydrateStrategy, OfflineStrategy, RenderMode } from './route-vocabulary';
+export { HYDRATE_STRATEGIES, OFFLINE_STRATEGIES, RENDER_MODES } from './route-vocabulary';
 export { safeUrl, URL_ATTRIBUTES } from './safe-url';
 export { defineService, resetServices, type ServiceFactory } from './service';
 export { timingSafeEqual } from './timing-safe-equal';

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

@@ -17,7 +17,7 @@ export const LOG_LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal', '
 
 export type LogLevel = (typeof LOG_LEVELS)[number];
 
-const LEVEL_WEIGHT: Readonly<Record<LogLevel, number>> = Object.freeze({
+const LEVEL_WEIGHT = Object.freeze<Record<LogLevel, number>>({
   trace: 10,
   debug: 20,
   info: 30,
@@ -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-span-exporter.ts

@@ -23,7 +23,7 @@ import type {
 } from './telemetry';
 
 /** OTLP's `SpanKind` enum; `UNSPECIFIED` is 0 and Ultimate never emits it. */
-const SPAN_KIND: Readonly<Record<SpanKind, number>> = Object.freeze({
+const SPAN_KIND = Object.freeze<Record<SpanKind, number>>({
   internal: 1,
   server: 2,
   client: 3,
@@ -31,7 +31,7 @@ const SPAN_KIND: Readonly<Record<SpanKind, number>> = Object.freeze({
   consumer: 5,
 });
 
-const STATUS_CODE: Readonly<Record<SpanStatusCode, number>> = Object.freeze({
+const STATUS_CODE = Object.freeze<Record<SpanStatusCode, number>>({
   unset: 0,
   ok: 1,
   error: 2,

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,43 @@ 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: '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/roles.ts

@@ -26,7 +26,7 @@ export interface RoleInfo {
   readonly stateful: boolean;
 }
 
-export const ROLE_INFO: Readonly<Record<Role, RoleInfo>> = Object.freeze({
+export const ROLE_INFO = Object.freeze<Record<Role, RoleInfo>>({
   web: { role: 'web', scalesOn: 'rps', maxReplicas: null, stateful: false },
   sync: { role: 'sync', scalesOn: 'ws-connections', maxReplicas: null, stateful: false },
   worker: { role: 'worker', scalesOn: 'queue-depth', maxReplicas: null, stateful: false },

package/src/route-vocabulary.ts

@@ -0,0 +1,23 @@
+// Single responsibility: the three closed vocabularies a route is declared in — how it renders,
+// how it survives offline, when it hydrates. Tier 0 so every package that names one imports it.
+// Deliberately not `config.ts`: `app.config.ts` CONSUMES `OfflineStrategy`, it does not own it.
+
+/**
+ * Each union is DERIVED from its array rather than written twice, so the pair cannot disagree:
+ * the array is the one place a member is added or removed and the type follows.
+ *
+ * This module exists because the alternative was measured. Twelve declarations of these three sets
+ * lived across six packages — `render` alone spelled `RenderMode` and `RENDER_MODES` separately —
+ * and `'spa'` was deleted from one of them while five others went on admitting it under a green
+ * project-wide typecheck. `@ultimat3/pwa`'s copy mapped `spa` to `cache-first`, the one strategy
+ * that gives an `app/` route a SHARED cache entry: one member's authed HTML served to the next.
+ * A copy is not a style question. `scripts/render-modes.test.ts` refuses a second declaration.
+ */
+export const RENDER_MODES = ['static', 'isr', 'ssr', 'stream'] as const;
+export type RenderMode = (typeof RENDER_MODES)[number];
+
+export const OFFLINE_STRATEGIES = ['precache', 'runtime', 'network-only'] as const;
+export type OfflineStrategy = (typeof OFFLINE_STRATEGIES)[number];
+
+export const HYDRATE_STRATEGIES = ['idle', 'visible', 'interaction', 'never'] as const;
+export type HydrateStrategy = (typeof HYDRATE_STRATEGIES)[number];

package/src/runtime-metrics.ts

@@ -14,7 +14,7 @@ import type { ScalingSignal } from './roles';
  * own comment ("via the ingress metric adapter") already assumes. The other two are instantaneous
  * values a scrape can read directly, so their series names are the chart's words verbatim.
  */
-export const SCALING_METRICS: Readonly<Record<ScalingSignal, string | null>> = Object.freeze({
+export const SCALING_METRICS = Object.freeze<Record<ScalingSignal, string | null>>({
   rps: 'http_requests_total',
   'ws-connections': 'connections',
   'queue-depth': 'queue_depth',

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,11 +1,13 @@
-// Compile-time pins for the actor-facts seam and the config surface. 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, the only enforcement that counts.
+// Compile-time pins for the actor-facts seam, the config surface, the request-context patch and
+// the route vocabulary.
+// 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 { CtxPatch } from './context';
+import type { HydrateStrategy, OfflineStrategy, RenderMode } from './route-vocabulary';
 
 /** Fails to compile when `T` is anything but `true`. The whole mechanism. */
 type Assert<T extends true> = T;
@@ -98,3 +100,45 @@ type _DatabaseInputCarriesNoDeadField = Assert<
     ? 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
+ * is the only thing these three pins are looking for.
+ */
+type Exact<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+
+/**
+ * Each route vocabulary's union must stay DERIVED from its array. `(typeof ARRAY)[number]` is what
+ * makes the pair unable to disagree, and it is one careless edit from being a hand-written union
+ * again — which is the shape six packages shipped until `route-vocabulary.ts` existed. Restating
+ * the members here is a pin, not a copy: nothing imports these, and a member added to the array
+ * without a word in the changelog is a build error rather than a silent widening five packages
+ * inherit through a re-export.
+ */
+type _RenderModeIsItsArray = Assert<Exact<RenderMode, 'static' | 'isr' | 'ssr' | 'stream'>>;
+
+type _OfflineStrategyIsItsArray = Assert<
+  Exact<OfflineStrategy, 'precache' | 'runtime' | 'network-only'>
+>;
+
+type _HydrateStrategyIsItsArray = Assert<
+  Exact<HydrateStrategy, 'idle' | 'visible' | 'interaction' | 'never'>
+>;