@ultimat3/core 9.0.0 → 11.0.0

package/CLAUDE.md

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

package/package.json

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

package/src/config.ts

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

package/src/context.ts

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

package/src/error-codes.ts

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

package/src/exports/error-contract.ts

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

package/src/index.ts

@@ -48,7 +48,6 @@ export type {
   McpConfig,
   PwaConfig,
   RealtimeConfig,
-  RealtimeTier,
   RealtimeTransport,
   ThemeConfig,
   ThemeMode,
@@ -133,10 +132,9 @@ export {
   describeErrorCode,
   describeValue,
   EnvMissingError,
-  ERROR_DOCS_BASE,
+  ERROR_DOCS_URL,
   ERROR_RETRY_KINDS,
   errorCodeSnapshot,
-  errorDocsUrl,
   errorRetry,
   formatError,
   hasErrorCode,

package/src/logger.ts

@@ -1,6 +1,7 @@
 // Single responsibility: structured JSON logging. One line per event, machine-readable by
 // default because the primary reader is an agent tailing `x logs --json`.
 
+import { assert } from './assert';
 import { type Clock, systemClock } from './clock';
 import { renderCauseValue } from './error-render';
 import { isUltimateError } from './errors';
@@ -244,8 +245,29 @@ function envLevel(): LogLevel {
     : 'info';
 }
 
+/**
+ * The level this logger enforces, refused when it is not one.
+ *
+ * `LEVEL_WEIGHT[level]` on anything else is `undefined`, and every `weight < undefined` is false —
+ * so the threshold failed OPEN and the logger emitted every line at every level. That is a `trace`
+ * stream out of a production process from one typo, which is the direction this read must never
+ * fail in. `LOG_LEVELS`, the same list `envLevel()` filters `LOG_LEVEL` through, because a level
+ * is typed here and arrives untyped: an `app.config.ts` value, a JSON file, a CLI flag.
+ */
+function resolveLevel(declared: LogLevel): LogLevel {
+  assert(
+    (LOG_LEVELS as readonly unknown[]).includes(declared),
+    // `renderCauseValue`, never `JSON.stringify`: it raises on a bigint and on a cycle, and a
+    // level that arrived from a config file can be either — the refusal must not be replaced by
+    // a `TypeError` from building its own message.
+    `${renderCauseValue(declared)} is not a log level`,
+    `pass one of ${LOG_LEVELS.join(', ')} to createLogger({ level })`,
+  );
+  return declared;
+}
+
 export function createLogger(options?: LoggerOptions): Logger {
-  const level = options?.level ?? envLevel();
+  const level = options?.level === undefined ? envLevel() : resolveLevel(options.level);
   const bound = options?.fields ?? {};
   const clock = options?.clock ?? systemClock;
   const writer = options?.writer ?? defaultWriter;

package/src/metrics.ts

@@ -174,14 +174,24 @@ export function resetMetrics(): void {
   }
 }
 
-/** Stable series key: attribute order must not create a second series for one label set. */
+/**
+ * Stable series key: attribute order must not create a second series for one label set, and no
+ * label set may spell another one's key.
+ *
+ * `JSON.stringify` over the sorted pairs, because a DELIMITER cannot carry the second property:
+ * the key was the pairs joined by control characters (U+0000 inside a pair, U+0001 between them),
+ * and a value holding those bytes IS another set's key — `{ a: 'b\u0001c\u0000d' }` was
+ * `{ a: 'b', c: 'd' }`, so the point landed on whichever series arrived first and was exported
+ * under labels the caller never passed. Attribute values are app data. Quoting is the only total
+ * answer and is not slower: 644 ns/op against the join's 709, on a 3-label set. `String(value)`
+ * stays, so `1` and `'1'` are still one series rather than two rows an exporter renders alike.
+ */
 function seriesKey(attributes: MetricAttributes): string {
   const entries = Object.entries(attributes);
   if (entries.length === 0) return '';
-  return entries
-    .sort(([a], [b]) => (a < b ? -1 : 1))
-    .map(([key, value]) => `${key}\u0000${String(value)}`)
-    .join('
');
+  return JSON.stringify(
+    entries.sort(([a], [b]) => (a < b ? -1 : 1)).map(([key, value]) => [key, String(value)]),
+  );
 }
 
 function finite(name: string, value: number): number {
@@ -195,6 +205,31 @@ function finite(name: string, value: number): number {
   return value;
 }
 
+/**
+ * Bounds are strictly ascending finite numbers, refused at DECLARATION like `maxSeries` beside it.
+ * `record` takes the first bound an observation fits, and the exposition format emits one
+ * cumulative `le` series per bound in array order — so `[1, 0.5, 5]` both counted observations
+ * into a bucket that was not theirs and rendered a non-monotonic `le` series that Prometheus and
+ * OpenMetrics each reject. Two wrong numbers, neither visible from the other, and nothing at the
+ * call site to notice: the observations themselves were all valid.
+ */
+function assertBounds(name: string, bounds: readonly number[] | undefined): void {
+  if (bounds === undefined) return;
+  const bad = bounds.findIndex((bound, index) => {
+    const previous = index === 0 ? Number.NEGATIVE_INFINITY : (bounds[index - 1] as number);
+    return !Number.isFinite(bound) || bound <= previous;
+  });
+  if (bad === -1) return;
+  const repaired = [...new Set(bounds.filter((bound) => Number.isFinite(bound)))].sort(
+    (left, right) => left - right,
+  );
+  throw new MetricNameInvalidError({
+    cause: `${name} declared bounds [${bounds.map((bound) => String(bound)).join(', ')}], which are not strictly ascending finite numbers — [${String(bad)}] is ${String(bounds[bad])}`,
+    fix: `sort the bounds and drop the duplicates: histogram('${name}', { bounds: [${repaired.join(', ')}] })`,
+    meta: { metric: name, bounds: bounds.map((bound) => String(bound)), at: bad },
+  });
+}
+
 function declare(name: string, kind: MetricKind, options: GaugeOptions & HistogramOptions) {
   if (!METRIC_NAME_RE.test(name)) {
     throw new MetricNameInvalidError({
@@ -203,6 +238,7 @@ function declare(name: string, kind: MetricKind, options: GaugeOptions & Histogr
       meta: { name },
     });
   }
+  assertBounds(name, options.bounds);
   const existing = instruments.get(name);
   if (existing !== undefined) {
     if (existing.descriptor.kind !== kind) {

package/src/telemetry.ts

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

package/src/type-pins.ts

@@ -6,7 +6,7 @@
 
 import type { Actor, ActorFactMap, FactKeysOf, FactMapOf } from './actor';
 import type { CacheTierName } from './cache-vocabulary';
-import type { AppConfigInput, CacheConfig, DatabaseConfig } from './config';
+import type { AppConfigInput, CacheConfig, DatabaseConfig, RealtimeConfig } from './config';
 import type { CtxPatch } from './context';
 import type { HydrateStrategy, OfflineStrategy, RenderMode } from './route-vocabulary';
 
@@ -119,6 +119,26 @@ type _CacheInputCarriesNoDeadField = Assert<
   Extract<keyof NonNullable<AppConfigInput['cache']>, DeadCacheField> extends never ? true : false
 >;
 
+/**
+ * The two `config.realtime` fields deleted for the same rule — `heartbeatMs` (2026-08-19) and
+ * `tier` (2026-08-23). `tier` is the worse of the two and the reason this pin exists: it accepted
+ * three values with three documented meanings, and `transport`/`urlEnv` are the only fields of
+ * this section any code reads, so all three meanings were one behaviour. Re-adding it restores a
+ * knob whose `'local-first'` setting promises a durable local store the framework does not build.
+ */
+type DeadRealtimeField = 'tier' | 'heartbeatMs';
+
+type _RealtimeConfigCarriesNoDeadField = Assert<
+  Extract<keyof RealtimeConfig, DeadRealtimeField> extends never ? true : false
+>;
+
+/** And the input side with it — `Input<RealtimeConfig>` is what an `app.config.ts` writes. */
+type _RealtimeInputCarriesNoDeadField = Assert<
+  Extract<keyof NonNullable<AppConfigInput['realtime']>, DeadRealtimeField> extends never
+    ? true
+    : false
+>;
+
 /**
  * Neither id a child context may patch. `withChildContext` forwards the parent's `buildId`
  * verbatim, so `{ buildId }` on the patch was an option that read as honoured and was dropped