@ultimat3/core 6.0.0 → 7.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
@@ -85,6 +104,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 |

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` |

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@ultimat3/core",
-  "version": "6.0.0",
+  "version": "7.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';

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/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,
@@ -479,6 +479,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/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,

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/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/type-pins.ts

@@ -1,11 +1,11 @@
-// 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 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 { 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 +98,28 @@ type _DatabaseInputCarriesNoDeadField = Assert<
     ? 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'>
+>;