@ultimat3/core 20.2.1 → 22.0.0

package/src/config.ts

@@ -7,15 +7,24 @@ import { CURRENCY_CODE_PATTERN } from '@ultimat3/schema';
 // them. Declaring them here is what let `cache.tiers` and the ladder `@ultimat3/cache` orders by
 // drift into two vocabularies with no map between them (issue #293).
 import { CACHE_TIERS, type CacheTierName } from './cache-vocabulary';
+import { countIssue } from './config-count';
+import { BASE_FIX, CACHE_TIER_FIX, TIMEZONE_FIX } from './config-fixes';
+import { type Input, lastSaid, layered } from './config-merge';
 import type { PwaConfig, PwaOfflineConfig } from './config-pwa';
 import { PWA_FIX, pwaIssues } from './config-pwa';
 import { describeValue } from './error-render';
 import { ConfigInvalidError } from './errors';
+import { defaultReadinessGraceMs, readinessGraceIssue } from './lifecycle-grace';
 import { ROLES, type Role } from './roles';
 import { isIanaZoneName } from './time-zone-name';
 
 export type ThemeMode = 'light' | 'dark' | 'system';
-export type RealtimeTransport = 'memory' | 'nats' | 'redis';
+/**
+ * The buses `@ultimat3/realtime`'s `selectTransport` builds, and nothing else. `'redis'` was in
+ * this union until 22.0.0 with no Redis transport anywhere: it booted whatever `NATS_URL` chose.
+ */
+export const REALTIME_TRANSPORTS = ['memory', 'nats'] as const;
+export type RealtimeTransport = (typeof REALTIME_TRANSPORTS)[number];
 
 export interface ThemeConfig {
   readonly defaultMode: ThemeMode;
@@ -172,6 +181,20 @@ export interface AiConfig {
   readonly mcp: McpConfig;
 }
 
+/**
+ * How a SIGTERM'd process leaves the load balancer. Read by `@ultimat3/http`'s `createServer`
+ * (`ServerOptions.drain`), which hands it to core's `configureLifecycle`.
+ */
+export interface DrainConfig {
+  /**
+   * `/readyz` answers 503 for this long before the listener closes, so endpoints stop routing here
+   * first. Default 0 in development/test and 5000 everywhere else — a process naming NO environment
+   * included. A whole number, 0–60000. The chart's `terminationGracePeriodSeconds` must exceed it
+   * plus the drain budget.
+   */
+  readonly readinessGraceMs: number;
+}
+
 export interface AppConfig {
   readonly name: string;
   readonly locales: readonly string[];
@@ -188,10 +211,9 @@ export interface AppConfig {
   readonly realtime: RealtimeConfig;
   readonly notify: NotifyConfig;
   readonly ai: AiConfig;
+  readonly drain: DrainConfig;
 }
 
-type Input<T> = { readonly [K in keyof T]?: T[K] | undefined };
-
 /** `mcp` is the only member, and it is NESTED — `Input<AiConfig>` would make it all-or-nothing. */
 export interface AiConfigInput {
   readonly mcp?: Input<McpConfig> | undefined;
@@ -224,24 +246,12 @@ export interface AppConfigInput {
   readonly realtime?: Input<RealtimeConfig> | undefined;
   readonly notify?: Input<NotifyConfig> | undefined;
   readonly ai?: AiConfigInput | undefined;
+  readonly drain?: Input<DrainConfig> | undefined;
 }
 
 /** An overlay from `config/<concern>.ts`. No `name` — the base owns it. */
 export type AppConfigOverlay = Omit<AppConfigInput, 'name'> & { readonly name?: string };
 
-/**
- * Apply a partial section over its defaults. Explicit `undefined` never wins — that is what
- * makes every config field deeply optional without `exactOptionalPropertyTypes` fighting back.
- */
-function section<T extends object>(base: T, patch: Input<T> | undefined): T {
-  if (patch === undefined) return base;
-  const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
-  for (const [key, value] of Object.entries(patch)) {
-    if (value !== undefined) out[key] = value;
-  }
-  return out as T;
-}
-
 const NAME_RE = /^[a-z][a-z0-9-]{1,63}$/;
 
 /**
@@ -287,32 +297,16 @@ function defaults(name: string): Omit<AppConfig, 'name'> {
       backoff: 'exponential',
       visibilityTimeoutMs: 30_000,
     },
-    realtime: { enabled: false, transport: 'memory', urlEnv: undefined },
+    // ON by default since 22.0.0, when the boot began obeying the key: an app with no section
+    // keeps the `sync` node it always got, and `enabled: false` is the explicit opt-out.
+    realtime: { enabled: true, transport: 'memory', urlEnv: undefined },
     notify: { inboxReadRetentionMs: undefined, inboxUnreadRetentionMs: undefined },
     ai: { mcp: { expose: true, path: '/mcp' } },
+    // Read from the process env when the config is DEFINED — the same env the drain will run in.
+    drain: { readinessGraceMs: defaultReadinessGraceMs() },
   };
 }
 
-const BASE_FIX = 'edit app.config.ts to fix the fields named in cause, then run: x verify';
-
-/**
- * Appended only when the zone is what failed. Axiom 4: an operator holding `'CET'` needs the
- * spelling to write, and the two refused classes have different remedies — a single-label legacy
- * name swaps mechanically, an abbreviation or an offset has no replacement at all because it names
- * no jurisdiction. Deliberately parallel to `@ultimat3/time`'s `X_TIMEZONE_INVALID` fix, since the
- * two refuse the same strings and an operator may meet either first.
- */
-const TIMEZONE_FIX =
-  "set defaultTimeZone to an Area/Location name, or UTC — list every accepted one with bun -e \"console.log(Intl.supportedValuesOf('timeZone').join('\\n'))\" — where a legacy single-label name swaps mechanically (Japan → Asia/Tokyo, GB → Europe/London, Universal → UTC), while an abbreviation or numeric offset (CET, EST5EDT, +01:00) carries no DST rule and has no replacement, so name the city whose clock you mean (Europe/Paris, America/New_York)";
-
-/**
- * Appended only when a tier name is what failed, and it names the rename rather than the rule: the
- * three refused spellings are the ones 8.0.0 accepted, and two of them have a mechanical
- * replacement while `isr` has none — it is a `RenderMode`, and no cache tier ever served it.
- */
-const CACHE_TIER_FIX =
-  "in app.config.ts, rewrite cache.tiers with the rung names the ladder serves — request-memo, lru, redis, cdn — where memo becomes request-memo and shared becomes redis, and isr is dropped: it is a render mode, so move it to render: 'isr' on the routes that want it";
-
 function validate(config: AppConfig): void {
   const issues: string[] = [];
   // Zero or one entry: the zone's own remedy, carried only when the zone is what failed.
@@ -346,10 +340,25 @@ function validate(config: AppConfig): void {
     issues.push(`defaultCurrency "${config.defaultCurrency}" is not a 3-letter ISO 4217 code`);
   }
   if (config.roles.length === 0) issues.push('roles must list at least one runtime role');
-  if (config.jobs.concurrency < 1) issues.push('jobs.concurrency must be >= 1');
+  // A domain per numeric key, never a bare `< 1`: every comparison with `NaN` is false, so the old
+  // `concurrency < 1` passed `NaN`, `2.5` and `Infinity`, and nothing screened the other three.
+  const counts: readonly (string | undefined)[] = [
+    countIssue('jobs.concurrency', config.jobs.concurrency, 1),
+    countIssue('jobs.maxAttempts', config.jobs.maxAttempts, 1),
+    countIssue('jobs.visibilityTimeoutMs', config.jobs.visibilityTimeoutMs, 1),
+    countIssue('cache.defaultTtlMs', config.cache.defaultTtlMs, 0),
+    readinessGraceIssue(config.drain.readinessGraceMs),
+  ];
+  for (const issue of counts) if (issue !== undefined) issues.push(issue);
   if (config.jobs.queues.length === 0) issues.push('jobs.queues must list at least one queue');
-  if (config.realtime.transport !== 'memory' && config.realtime.urlEnv === undefined) {
-    issues.push(`realtime.transport "${config.realtime.transport}" requires realtime.urlEnv`);
+  // An untyped config reaches here with whatever it wrote: a string is a name worth echoing, and
+  // anything else goes through `describeValue` rather than `${…}`.
+  const transport: unknown = config.realtime.transport;
+  if (!REALTIME_TRANSPORTS.some((known) => known === transport)) {
+    const said = typeof transport === 'string' ? `"${transport}"` : describeValue(transport);
+    issues.push(`realtime.transport ${said} is not one of ${REALTIME_TRANSPORTS.join(', ')}`);
+  } else if (transport === 'nats' && config.realtime.urlEnv === undefined) {
+    issues.push(`realtime.transport "nats" requires realtime.urlEnv`);
   }
   // BOTH RETENTION WINDOWS OR NEITHER — `undefined` is a real value here (never swept) and the
   // only other legal one is a positive, finite count of milliseconds. Zero is refused rather than
@@ -401,35 +410,83 @@ export function defineConfig(
   ...overlays: readonly AppConfigOverlay[]
 ): AppConfig {
   const base = defaults(input.name);
-  // One `Object.assign` over all overlays rather than a spread per overlay: `reduce` with a
-  // spread copies every key again on each step, and config is merged at boot on every start.
-  // `name` is applied last because it identifies the app — an overlay may not rename it.
-  const merged: AppConfigInput = Object.assign({}, input, ...overlays, {
-    name: input.name,
-  }) as AppConfigInput;
+  // Every layer, in order, merged per section and KEY BY KEY — see `layered`. `name` comes from
+  // the input alone because it identifies the app: an overlay may not rename it.
+  const layers: readonly AppConfigOverlay[] = [input, ...overlays];
 
   const config: AppConfig = {
-    name: merged.name,
-    locales: merged.locales ?? base.locales,
-    defaultLocale: merged.defaultLocale ?? base.defaultLocale,
-    defaultTimeZone: merged.defaultTimeZone ?? base.defaultTimeZone,
-    defaultCurrency: merged.defaultCurrency ?? base.defaultCurrency,
-    theme: section(base.theme, merged.theme),
-    auth: section(base.auth, merged.auth),
-    // Two `section` calls, one per level: the outer one may not see `offline` at all, or it would
-    // drop the nested defaults `PwaConfigInput` exists to keep. Hence the cast — the outer patch is
-    // this block minus the key the inner call owns.
+    name: input.name,
+    locales: lastSaid(
+      base.locales,
+      layers.map((layer) => layer.locales),
+    ),
+    defaultLocale: lastSaid(
+      base.defaultLocale,
+      layers.map((layer) => layer.defaultLocale),
+    ),
+    defaultTimeZone: lastSaid(
+      base.defaultTimeZone,
+      layers.map((layer) => layer.defaultTimeZone),
+    ),
+    defaultCurrency: lastSaid(
+      base.defaultCurrency,
+      layers.map((layer) => layer.defaultCurrency),
+    ),
+    theme: layered(
+      base.theme,
+      layers.map((layer) => layer.theme),
+    ),
+    auth: layered(
+      base.auth,
+      layers.map((layer) => layer.auth),
+    ),
+    // Two merges, one per level: the outer one may not see `offline` at all, or it would drop the
+    // nested defaults `PwaConfigInput` exists to keep. Hence the cast — the outer patch is this
+    // block minus the key the inner merge owns.
     pwa: {
-      ...section(base.pwa, { ...merged.pwa, offline: undefined } as Input<PwaConfig>),
-      offline: section(base.pwa.offline, merged.pwa?.offline),
+      ...layered(
+        base.pwa,
+        layers.map((layer) => ({ ...layer.pwa, offline: undefined }) as Input<PwaConfig>),
+      ),
+      offline: layered(
+        base.pwa.offline,
+        layers.map((layer) => layer.pwa?.offline),
+      ),
+    },
+    roles: lastSaid(
+      base.roles,
+      layers.map((layer) => layer.roles),
+    ),
+    database: layered(
+      base.database,
+      layers.map((layer) => layer.database),
+    ),
+    cache: layered(
+      base.cache,
+      layers.map((layer) => layer.cache),
+    ),
+    jobs: layered(
+      base.jobs,
+      layers.map((layer) => layer.jobs),
+    ),
+    realtime: layered(
+      base.realtime,
+      layers.map((layer) => layer.realtime),
+    ),
+    notify: layered(
+      base.notify,
+      layers.map((layer) => layer.notify),
+    ),
+    ai: {
+      mcp: layered(
+        base.ai.mcp,
+        layers.map((layer) => layer.ai?.mcp),
+      ),
     },
-    roles: merged.roles ?? base.roles,
-    database: section(base.database, merged.database),
-    cache: section(base.cache, merged.cache),
-    jobs: section(base.jobs, merged.jobs),
-    realtime: section(base.realtime, merged.realtime),
-    notify: section(base.notify, merged.notify),
-    ai: { mcp: section(base.ai.mcp, merged.ai?.mcp) },
+    drain: layered(
+      base.drain,
+      layers.map((layer) => layer.drain),
+    ),
   };
 
   validate(config);

package/src/conflict-policy.ts

@@ -0,0 +1,48 @@
+/**
+ * The ONE conflict vocabulary: which row survives when an optimistic local write and the server's
+ * answer disagree. Row-shaped because the client store is — a merge over a mutator's OUTPUT had
+ * nowhere to land, and realtime's rebase silently dropped it. Tier 0 so `action` and `realtime`
+ * (both tier 3) name the same type.
+ */
+
+/** One record as the client store holds it: a JSON object, keyed by field name. */
+export type Row = Readonly<Record<string, unknown>>;
+
+export type ConflictPolicy =
+  | 'server-wins'
+  | 'last-write-wins'
+  | { readonly kind: 'custom'; readonly merge: (local: Row, server: Row) => Row };
+
+export interface ResolveConflictOptions {
+  /**
+   * The field `last-write-wins` compares — a finite number (epoch ms) the SERVER wrote. Default
+   * `updatedAt`, the name realtime's rebase has always read.
+   */
+  readonly clockField?: string | undefined;
+}
+
+/**
+ * The surviving row. `last-write-wins` keeps the local row only when its clock is provably newer
+ * by the server's own field; a missing or non-numeric clock on either side is no proof, so the
+ * server's row stands — the store must never keep a guess over an answer.
+ */
+export function resolveConflict(
+  policy: ConflictPolicy,
+  local: Row,
+  server: Row,
+  options: ResolveConflictOptions = {},
+): Row {
+  if (typeof policy !== 'string') return policy.merge(local, server);
+  if (policy === 'server-wins') return server;
+  const field = options.clockField ?? 'updatedAt';
+  const localAt = clockOf(local, field);
+  const serverAt = clockOf(server, field);
+  return localAt !== undefined && serverAt !== undefined && localAt > serverAt ? local : server;
+}
+
+function clockOf(row: Row, field: string): number | undefined {
+  // Own keys only: a field named `constructor` must not read `Object.prototype`'s.
+  if (!Object.hasOwn(row, field)) return undefined;
+  const value = row[field];
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}

package/src/context.ts

@@ -37,6 +37,7 @@ import { UltimateError } from './errors';
 import { finiteOption } from './finite-option';
 import { traceId as newTraceId, uuid } from './ids';
 import { type Logger, logger as rootLogger, setLoggerContextFields } from './logger';
+import { installTraceHeaders } from './outbound-headers';
 import { type Role, resolveRole } from './roles';
 import { installedServices, isManagedService } from './service';
 
@@ -130,6 +131,13 @@ export interface CtxInit {
   /** Epoch ms. `@ultimat3/http`'s `startDeadline` is the one production writer. */
   readonly deadlineAt?: number | undefined;
   readonly services?: ServiceBag | undefined;
+  /**
+   * `false` installs no `defineService` factory — only `services` — and leaves the registered
+   * ones to the caller. `@ultimat3/http` is that caller: its context exists before the `auth`
+   * stage names the actor, and a service built here would act as anonymous for the whole request.
+   * Default `true`.
+   */
+  readonly installServices?: boolean | undefined;
 }
 
 /**
@@ -184,7 +192,8 @@ export function createContext(init: CtxInit = {}): Ctx {
   // wins over an auto-installed one of the same name — a test's hand-built mock overrides the
   // real thing on purpose.
   const preview: CtxFacts = Object.freeze({ ...explicit, ...fields, services: explicit });
-  const services: ServiceBag = Object.freeze({ ...installedServices(preview), ...explicit });
+  const installed = init.installServices === false ? {} : installedServices(preview);
+  const services: ServiceBag = Object.freeze({ ...installed, ...explicit });
   const ctx = {
     // Services ride ON the context, not only under `ctx.services`: `CtxServices` exists to be
     // augmented, so `ctx.posts` has to BE the service. Spread first, so a service that collides
@@ -208,6 +217,8 @@ export function createContext(init: CtxInit = {}): Ctx {
 }
 
 export function runWithContext<T>(ctx: Ctx, fn: () => T): T {
+  // A request scope is what gives an outbound typed call a budget to forward; see the module.
+  installTraceHeaders();
   return requestContext.run(ctx, fn);
 }
 

package/src/core-error-codes.ts

@@ -0,0 +1,78 @@
+// Single responsibility: core's OWN error-code titles, registered at import. A side-effect
+// anchor, bare-imported by the barrel — the same shape as `schema-error-codes.ts` — so the table
+// rides every barrel import and none of the light paths: `UltimateError` alone no longer carries
+// 40 titles into a browser island that throws one code. Listed in `SIDE_EFFECTS_ANCHORS`.
+
+import type { ErrorCodeDescriptor } from './error-codes';
+import { descriptor, registerCoreErrorCodes } from './error-codes';
+
+/** Codes owned by `@ultimat3/core`. Every other package calls `registerErrorCodes()`. */
+const CORE_CODE_TITLES = {
+  X_ABORTED: 'operation aborted',
+  X_ASYNC_CONTEXT_UNAVAILABLE: 'async context unavailable',
+  // The browser seam's three (`client-transport.ts`, `record-envelope.ts`, `client-scope.ts`).
+  X_CLIENT_RECORD_ENVELOPE_INVALID: 'a response marked as a records envelope has the wrong shape',
+  X_CLIENT_SCOPE_CHANGED: 'the page changed principal while this request was in flight',
+  X_CLIENT_TRANSPORT_FAILED: 'a browser request got no answer from the app',
+  X_CONFIG_INVALID: 'app.config.ts is invalid',
+  X_CURSOR_INVALID: 'pagination cursor is malformed, tampered with or from another query',
+  // `x doctor` reports it; `assertNoDevSecretsOutsideLocal()` throws it at boot.
+  X_CURSOR_SECRET_DEV: 'cursors are signed with the shipped development key',
+  X_DRAINING: 'process is draining and refuses new work',
+  X_ENV_EXAMPLE_DRIFT: '.env.example does not declare every variable the schema requires',
+  X_ENV_MISSING: 'required environment variables are missing or invalid',
+  X_ENVIRONMENT_INVALID: 'ULTIMATE_ENV is not a known environment',
+  X_ERROR_CODE_DUPLICATE: 'error code registered twice',
+  X_ERROR_REPORTER_DSN_INVALID: 'the error monitor DSN is malformed',
+  X_ERROR_RETRY_INVALID: 'error retry classification is unknown or already claimed',
+  // Core's own, and deliberately NOT `@ultimat3/http`'s `X_OVERLOADED`: that code is owned by a
+  // tier-2 package, and a tier-0 gate borrowing it upward is an import core may not make. The two
+  // read alike to an operator and the fix lines say which ceiling to widen.
+  X_FLIGHT_GATE_OVERLOADED: 'a concurrency gate is at its ceiling and its queue is full',
+  X_ID_INVALID: 'value is not a valid id',
+  X_IMAGE_DECODE_FAILED: 'image bytes are malformed, truncated or internally inconsistent',
+  X_IMAGE_TOO_LARGE: 'image exceeds the pipeline pixel ceiling',
+  X_IMAGE_UNSUPPORTED: 'the built-in image pipeline cannot read or write this format',
+  X_INTERNAL: 'unexpected internal framework error',
+  X_INVARIANT: 'invariant violated',
+  // Owned here rather than by `@ultimat3/time`, which declared it until 16.x: `@ultimat3/money`
+  // needs the same screen and tier 1 may not import sideways. One code, one declaration.
+  X_LOCALE_INVALID: 'not a well-formed BCP 47 tag',
+  X_METRIC_CARDINALITY:
+    'a metric exceeded its series ceiling and is folding into one overflow series',
+  X_METRIC_NAME_INVALID:
+    'metric name is malformed, or redeclared with a different kind, bounds or observer',
+  X_METRIC_VALUE_INVALID: 'metric value is not recordable',
+  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',
+  X_REGISTRAR_MISSING: 'no registrar is loaded for a primitive kind',
+  X_ROLE_INVALID: 'ROLE is not a known runtime role',
+  X_SERVICE_DUPLICATE: 'a service name is registered twice',
+  X_SERVICE_MISSING: 'service is not registered on the request context',
+  X_SHUTDOWN_TIMEOUT: 'graceful shutdown exceeded its deadline',
+  X_SUPERSEDED: 'a later generation superseded this work',
+  X_TELEMETRY_SAMPLER_ARG_INVALID: 'the trace sampling ratio is not a number between 0 and 1',
+  // Core's, though core does not throw it — the twin of `X_ABORTED`, and `@ultimat3/http` already
+  // calls it "borrowed (core's concept)" in `HTTP_BORROWED_ERROR_CODES`. A deadline that expired
+  // and a caller that went away are one pair of facts, so they are titled and classified in one
+  // place rather than by whichever package happened to raise one first.
+  X_TIMEOUT: 'operation exceeded its deadline',
+  X_UNREACHABLE: 'unreachable branch was reached',
+} as const;
+
+export type CoreErrorCode = keyof typeof CORE_CODE_TITLES;
+
+export const CORE_ERROR_CODES: Readonly<Record<CoreErrorCode, ErrorCodeDescriptor>> = Object.freeze(
+  Object.fromEntries(
+    Object.entries(CORE_CODE_TITLES).map(([code, title]) => [code, descriptor({ title })]),
+  ) as Record<CoreErrorCode, ErrorCodeDescriptor>,
+);
+
+registerCoreErrorCodes(CORE_ERROR_CODES);

package/src/dev-secrets.ts

@@ -0,0 +1,45 @@
+// Single responsibility: the boot refusal of a shipped development signing secret outside a local
+// environment. `x doctor` reported it; nothing failed — so a production pod that forgot
+// ULTIMATE_CURSOR_SECRET signed every cursor with a key published in this package.
+
+import { usesDevCursorSecret } from './cursor';
+import { isLocal } from './environment';
+import { UltimateError } from './errors';
+
+/**
+ * `X_CURSOR_SECRET_DEV`, the code `x doctor` already reports for this key — one condition, one code.
+ * Doctor warns; this refuses the boot.
+ */
+export class CursorSecretDevError extends UltimateError {
+  static readonly code = 'X_CURSOR_SECRET_DEV';
+  override readonly name = 'CursorSecretDevError';
+
+  // One secret today, so the fix is a literal: a spliced name would be a value in a pasted command.
+  constructor() {
+    super({
+      code: CursorSecretDevError.code,
+      cause:
+        'ULTIMATE_CURSOR_SECRET is unset, so this process signs cursors with the development key the framework ships — anyone can forge a page position',
+      fix: "x secrets set ULTIMATE_CURSOR_SECRET — or export ULTIMATE_CURSOR_SECRET from the platform's secret store",
+      meta: { variable: 'ULTIMATE_CURSOR_SECRET' },
+    });
+  }
+}
+
+export interface DevSecretsOptions {
+  /** Which environment the boot is — defaults to `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+}
+
+/**
+ * Throws when a shipped dev secret is in use and the environment is not `development`/`test`.
+ *
+ * FAILS CLOSED: a process with neither `ULTIMATE_ENV` nor `NODE_ENV` resolves as `production`
+ * here, the answer `templates/scaffold-auth.ts` already gives — `isLocal()`'s own fallback is
+ * `development`, which is exactly the process that forgot to say. The secret itself is read where
+ * signing reads it, so this refuses what the process WILL sign with, not what `env` claims.
+ */
+export function assertNoDevSecretsOutsideLocal(options: DevSecretsOptions = {}): void {
+  if (isLocal({ env: options.env, fallback: 'production' })) return;
+  if (usesDevCursorSecret()) throw new CursorSecretDevError();
+}

package/src/error-codes.ts

@@ -28,75 +28,26 @@ export interface ErrorCodeEntry extends ErrorCodeDescriptor {
  */
 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 = {
-  X_ABORTED: 'operation aborted',
-  X_ASYNC_CONTEXT_UNAVAILABLE: 'async context unavailable',
-  X_CONFIG_INVALID: 'app.config.ts is invalid',
-  X_CURSOR_INVALID: 'pagination cursor is malformed, tampered with or from another query',
-  X_CURSOR_SECRET_DEV: 'cursors are signed with the shipped development key',
-  X_DRAINING: 'process is draining and refuses new work',
-  X_ENV_EXAMPLE_DRIFT: '.env.example does not declare every variable the schema requires',
-  X_ENV_MISSING: 'required environment variables are missing or invalid',
-  X_ENVIRONMENT_INVALID: 'ULTIMATE_ENV is not a known environment',
-  X_ERROR_CODE_DUPLICATE: 'error code registered twice',
-  X_ERROR_REPORTER_DSN_INVALID: 'the error monitor DSN is malformed',
-  X_ERROR_RETRY_INVALID: 'error retry classification is unknown or already claimed',
-  // Core's own, and deliberately NOT `@ultimat3/http`'s `X_OVERLOADED`: that code is owned by a
-  // tier-2 package, and a tier-0 gate borrowing it upward is an import core may not make. The two
-  // read alike to an operator and the fix lines say which ceiling to widen.
-  X_FLIGHT_GATE_OVERLOADED: 'a concurrency gate is at its ceiling and its queue is full',
-  X_ID_INVALID: 'value is not a valid id',
-  X_IMAGE_DECODE_FAILED: 'image bytes are malformed, truncated or internally inconsistent',
-  X_IMAGE_TOO_LARGE: 'image exceeds the pipeline pixel ceiling',
-  X_IMAGE_UNSUPPORTED: 'the built-in image pipeline cannot read or write this format',
-  X_INTERNAL: 'unexpected internal framework error',
-  X_INVARIANT: 'invariant violated',
-  // Owned here rather than by `@ultimat3/time`, which declared it until 16.x: `@ultimat3/money`
-  // needs the same screen and tier 1 may not import sideways. One code, one declaration.
-  X_LOCALE_INVALID: 'not a well-formed BCP 47 tag',
-  X_METRIC_CARDINALITY:
-    'a metric exceeded its series ceiling and is folding into one overflow series',
-  X_METRIC_NAME_INVALID:
-    'metric name is malformed, or redeclared with a different kind, bounds or observer',
-  X_METRIC_VALUE_INVALID: 'metric value is not recordable',
-  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',
-  X_REGISTRAR_MISSING: 'no registrar is loaded for a primitive kind',
-  X_ROLE_INVALID: 'ROLE is not a known runtime role',
-  X_SERVICE_DUPLICATE: 'a service name is registered twice',
-  X_SERVICE_MISSING: 'service is not registered on the request context',
-  X_SHUTDOWN_TIMEOUT: 'graceful shutdown exceeded its deadline',
-  X_SUPERSEDED: 'a later generation superseded this work',
-  X_TELEMETRY_SAMPLER_ARG_INVALID: 'the trace sampling ratio is not a number between 0 and 1',
-  // Core's, though core does not throw it — the twin of `X_ABORTED`, and `@ultimat3/http` already
-  // calls it "borrowed (core's concept)" in `HTTP_BORROWED_ERROR_CODES`. A deadline that expired
-  // and a caller that went away are one pair of facts, so they are titled and classified in one
-  // place rather than by whichever package happened to raise one first.
-  X_TIMEOUT: 'operation exceeded its deadline',
-  X_UNREACHABLE: 'unreachable branch was reached',
-} as const;
-
-export type CoreErrorCode = keyof typeof CORE_CODE_TITLES;
-
-function descriptor(declaration: ErrorCodeDeclaration): ErrorCodeDescriptor {
+export 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({ title })]),
-  ) as Record<CoreErrorCode, ErrorCodeDescriptor>,
-);
+/**
+ * Empty at load, on purpose: core's own titles live in `core-error-codes.ts`, which the barrel
+ * bare-imports as a side-effect anchor. A browser module that constructs an `UltimateError` from a
+ * light path pays for the class and this lookup, not a 40-row table — an untitled code renders
+ * through `humanize`, the trade `@ultimat3/realtime` already made for its own titles.
+ */
+const registry = new Map<string, ErrorCodeDescriptor>();
 
-const registry = new Map<string, ErrorCodeDescriptor>(Object.entries(CORE_ERROR_CODES));
+/** What `resetErrorCodes` restores: the codes `registerCoreErrorCodes` installed. */
+const coreCodes = new Map<string, ErrorCodeDescriptor>();
+
+/** `core-error-codes.ts`'s one call. Registered like any package's, and remembered for a reset. */
+export function registerCoreErrorCodes(codes: Readonly<Record<string, ErrorCodeDescriptor>>): void {
+  registerErrorCodes(codes);
+  for (const [code, value] of Object.entries(codes)) coreCodes.set(code, value);
+}
 
 /**
  * Register a package's codes. Throws `X_ERROR_CODE_DUPLICATE` on collision so two packages
@@ -145,7 +96,7 @@ export function listErrorCodes(): readonly ErrorCodeEntry[] {
 /** Test-only: drop everything a package registered, keeping core's codes. */
 export function resetErrorCodes(): void {
   registry.clear();
-  for (const [code, value] of Object.entries(CORE_ERROR_CODES)) registry.set(code, value);
+  for (const [code, value] of coreCodes) registry.set(code, value);
 }
 
 /**

package/src/error-retry.ts

@@ -58,6 +58,9 @@ const CORE_ERROR_RETRY: ReadonlyMap<string, ErrorRetry> = new Map(
     // re-run produces the same refusal by construction, so an UNCLASSIFIED reading would spend a
     // job's whole retry policy proving that the world has still moved on.
     X_SUPERSEDED: 'terminal',
+    // The principal fence's twin of `X_SUPERSEDED`, listed for the same reason: re-sending a read
+    // from the previous principal's scope is refused identically every time.
+    X_CLIENT_SCOPE_CHANGED: 'terminal',
   } as const),
 );
 

package/src/exports/error-contract.ts

@@ -3,14 +3,14 @@
 // built with, and the retry classification a code carries. One group because a code, its title,
 // its rendering and its retry class are one contract; `index.ts` re-exports every name explicitly.
 
+export type { CoreErrorCode } from '../core-error-codes';
+export { CORE_ERROR_CODES } from '../core-error-codes';
 export type {
-  CoreErrorCode,
   ErrorCodeDeclaration,
   ErrorCodeDescriptor,
   ErrorCodeEntry,
 } from '../error-codes';
 export {
-  CORE_ERROR_CODES,
   describeErrorCode,
   ERROR_DOCS_URL,
   errorCodeSnapshot,

package/src/exports/secrets.ts

@@ -66,6 +66,7 @@ export {
   SECRETS_KEY_MODE,
   secretsFileExists,
   secretsPath,
+  stagedMasterKeyPath,
   writeMasterKeyFile,
   writeSecretsFile,
 } from '../secrets-store';

package/src/generation-fence.ts

@@ -51,7 +51,14 @@ function superseded(subject: string, issued: number, current: number): UltimateE
   });
 }
 
-/** Whether a caught value is this refusal. The one reader a caller needs; never `error.code`. */
+/**
+ * Whether a caught value is a supersession — this fence's refusal, or `X_CLIENT_SCOPE_CHANGED`,
+ * the principal fence's (`client-scope.ts`). One reader for both, because a caller does the same
+ * thing with either: drop the answer and render nothing. Never `error.code`.
+ */
 export function isSuperseded(error: unknown): boolean {
-  return isUltimateError(error) && error.code === 'X_SUPERSEDED';
+  return (
+    isUltimateError(error) &&
+    (error.code === 'X_SUPERSEDED' || error.code === 'X_CLIENT_SCOPE_CHANGED')
+  );
 }