@ultimat3/core - npm Package Compare versions

Comparing version 9.0.0 to 10.0.0

CLAUDE.md

@@ -15,2 +15,3 @@ # @ultimat3/core — agent notes
 | 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` |
@@ -280,6 +281,13 @@ | Context | never thread `ctx` as a parameter — `useContext()` |
 ```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
@@ -353,2 +361,14 @@ `registerReadinessCheck(name, check)`. `/readyz` is ready only when the state is `ready` AND every
 
+**`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
@@ -355,0 +375,0 @@ `terminal`** — fail closed, because a client retrying on `status >= 500` hammers `X_DB_DRIFT` and

package.json

 {
   "name": "@ultimat3/core",
-  "version": "9.0.0",
+  "version": "10.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
@@ -5,0 +5,0 @@ "license": "MIT",

src/config.ts

@@ -18,3 +18,2 @@ // Single responsibility: `app.config.ts` — the one config file. Deeply optional with real
 export type ThemeMode = 'light' | 'dark' | 'system';
-export type RealtimeTier = 'channels' | 'live-queries' | 'local-first';
 export type RealtimeTransport = 'memory' | 'nats' | 'redis';
@@ -123,6 +122,15 @@
  * 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;
@@ -249,3 +257,3 @@ readonly urlEnv: string | undefined;
     },
-    realtime: { enabled: false, tier: 'channels', transport: 'memory', urlEnv: undefined },
+    realtime: { enabled: false, transport: 'memory', urlEnv: undefined },
     ai: { mcp: { expose: true, path: '/mcp' } },
@@ -252,0 +260,0 @@ };

src/context.ts

@@ -203,3 +203,6 @@ // Single responsibility: the ambient request context. Authz, tracing, locale, tz and the
   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) {
@@ -206,0 +209,0 @@ throw new UltimateError({

src/error-codes.ts

@@ -22,8 +22,11 @@ // Single responsibility: the framework-wide error-code registry (code -> title + docs).
 
-export const ERROR_DOCS_BASE = 'https://ultimate.dev/errors/';
+/**
+ * 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';
 
-export function errorDocsUrl(code: string): string {
-  return `${ERROR_DOCS_BASE}${code}`;
-}
-
 /** Codes owned by `@ultimat3/core`. Every other package calls `registerErrorCodes()`. */
@@ -79,4 +82,4 @@ const 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 });
 }
@@ -86,3 +89,3 @@
   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>,
@@ -111,3 +114,3 @@ );
   for (const [code, declaration] of Object.entries(codes)) {
-    registry.set(code, descriptor(code, declaration));
+    registry.set(code, descriptor(declaration));
   }
@@ -124,3 +127,3 @@ }
   if (known !== undefined) return known;
-  return descriptor(code, { title: humanize(code) });
+  return descriptor({ title: humanize(code) });
 }
@@ -127,0 +130,0 @@

src/exports/error-contract.ts

@@ -15,5 +15,4 @@ // The error-contract slice of `@ultimat3/core`'s public surface: `UltimateError` and its shipped
   describeErrorCode,
-  ERROR_DOCS_BASE,
+  ERROR_DOCS_URL,
   errorCodeSnapshot,
-  errorDocsUrl,
   hasErrorCode,
@@ -20,0 +19,0 @@ listErrorCodes,

src/index.ts

@@ -51,3 +51,2 @@ // Single responsibility: the public API of @ultimat3/core. Explicit named exports only —
   RealtimeConfig,
-  RealtimeTier,
   RealtimeTransport,
@@ -137,6 +136,5 @@ ThemeConfig,
   EnvMissingError,
-  ERROR_DOCS_BASE,
+  ERROR_DOCS_URL,
   ERROR_RETRY_KINDS,
   errorCodeSnapshot,
-  errorDocsUrl,
   errorRetry,
@@ -143,0 +141,0 @@ formatError,

src/metrics.ts

@@ -198,2 +198,27 @@ // Single responsibility: the OpenTelemetry-shaped metrics seam — counter, gauge and histogram
 
+/**
+ * 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) {
@@ -207,2 +232,3 @@ if (!METRIC_NAME_RE.test(name)) {
   }
+  assertBounds(name, options.bounds);
   const existing = instruments.get(name);
@@ -209,0 +235,0 @@ if (existing !== undefined) {

src/telemetry.ts

@@ -329,3 +329,9 @@ // Single responsibility: OpenTelemetry-shaped tracing that is always on. The default exporter
   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}`;
 }
@@ -332,0 +338,0 @@

src/type-pins.ts

@@ -9,3 +9,3 @@ // Compile-time pins for the actor-facts seam, the config surface, the request-context patch and
 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';
@@ -124,2 +124,22 @@ import type { HydrateStrategy, OfflineStrategy, RenderMode } from './route-vocabulary';
 /**
+ * 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`
@@ -126,0 +146,0 @@ * verbatim, so `{ buildId }` on the patch was an option that read as honoured and was dropped

New alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Fixed alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Improved metrics

Total package byte prevSize

486800

1.3%

Lines of code

9175

0.66%

No dependency changes