@ultimat3/core 1.2.0 → 2.0.0

package/src/actor.ts

@@ -1,11 +1,75 @@
 // Single responsibility: who is making the request. `agent` is a first-class kind because
 // every action is also an MCP tool, and MCP callers go through the same authz as humans.
+//
+// `ActorFacts` is the extension seam: an app declares its own authz facts once, by module
+// augmentation, and they ride on the SAME actor every surface already hands the policy layer —
+// so a relational rule ("a friend of the author") never needs a second authz path.
 
 /** `agent` = an MCP/LLM caller acting on behalf of a user or a service. */
 export type ActorKind = 'user' | 'service' | 'agent' | 'anonymous';
 
 export const ACTOR_KINDS = ['user', 'service', 'agent', 'anonymous'] as const;
 
+/**
+ * **The channel for every app-specific fact about who is calling.** `Actor` itself carries only
+ * what every app has — `kind`, `id`, `orgId`, `roles`, `scopes` — and it never grows a field for
+ * one app's vocabulary. A `memberId`, a `tz`, a plan tier, the friend set, the block set, the org
+ * row: each is declared here, by module augmentation, and resolved ONCE per request, because a
+ * policy predicate is synchronous and may not query.
+ *
+ * ```ts
+ * declare module '@ultimat3/core' {
+ *   interface ActorFacts {
+ *     readonly memberId: string;
+ *     readonly tz: string;
+ *     readonly viewer: Viewer;
+ *   }
+ * }
+ * ```
+ *
+ * Then `withFacts(actor, { memberId, tz })` at the request boundary and `actorFact(actor,
+ * 'memberId')` everywhere else. Do not thread a second identity object beside the actor and do
+ * not ask for a field on `Actor`/`ActorInit`: a fact declared here rides the SAME actor every
+ * surface already hands the policy layer, so a relational rule never needs a second authz path.
+ *
+ * Same shape as `CtxServices` and `PermissionRegistry`, for the same reason: the app declares
+ * once and every reader — predicate, action handler, component — is typed from that declaration
+ * without a single surface package learning the app's vocabulary.
+ */
+export interface ActorFacts {
+  /** Phantom member; never augment or read this key. */
+  readonly __ultimate?: never;
+}
+
+/**
+ * Generic over the interface so `type-pins.ts` can instantiate the machinery against a sample
+ * fact set. Augmenting `ActorFacts` inside the framework would declare that fact for every app.
+ */
+export type FactKeysOf<F> = Exclude<keyof F, '__ultimate'>;
+
+export type FactMapOf<F> = { readonly [K in FactKeysOf<F>]?: F[K] | undefined };
+
+export type ActorFactKey = FactKeysOf<ActorFacts>;
+
+/**
+ * Every declared fact, each independently absent.
+ *
+ * Optional per key, and that is the load-bearing decision: nothing can prove a fact was
+ * resolved — an actor is also minted by a test, a job runner and an MCP token exchange — so an
+ * unresolved fact reads as `undefined` and a predicate must branch on it. An absent fact is not
+ * a satisfied one, and here that is a type error rather than a convention.
+ */
+export type ActorFactMap = FactMapOf<ActorFacts>;
+
+/**
+ * Who is REALLY acting, when the effective actor is someone else. Two fields, both bounded and
+ * both already log-safe — a support engineer's id and kind, never their email or name.
+ */
+export interface ActorOrigin {
+  readonly actorId: string;
+  readonly actorKind: ActorKind;
+}
+
 export interface Actor {
   readonly kind: ActorKind;
   readonly id: string;
@@ -14,6 +78,14 @@ export interface Actor {
   readonly roles: readonly string[];
   /** Capability strings a policy can require (`post:publish`). */
   readonly scopes: readonly string[];
+  /** App-declared facts. Read it through `actorFact()`; never logged — `actorLabel` is id-only. */
+  readonly facts?: ActorFactMap | undefined;
+  /**
+   * Set by `impersonate()`. Its absence is a positive statement — this actor is acting for
+   * themselves — which is what makes a refund issued during impersonation distinguishable from
+   * one the customer issued. Every surface that renders an actor renders this with it.
+   */
+  readonly onBehalfOf?: ActorOrigin | undefined;
 }
 
 export interface ActorInit {
@@ -21,13 +93,19 @@ export interface ActorInit {
   readonly orgId?: string | undefined;
   readonly roles?: readonly string[] | undefined;
   readonly scopes?: readonly string[] | undefined;
+  readonly facts?: ActorFactMap | undefined;
+  /** For a session that already recorded an impersonation; `impersonate()` sets it otherwise. */
+  readonly onBehalfOf?: ActorOrigin | undefined;
 }
 
+const NO_FACTS: ActorFactMap = Object.freeze({});
+
 const ANONYMOUS: Actor = Object.freeze({
   kind: 'anonymous',
   id: 'anonymous',
   roles: Object.freeze([]),
   scopes: Object.freeze([]),
+  facts: NO_FACTS,
 });
 
 function build(kind: ActorKind, init: ActorInit): Actor {
@@ -37,6 +115,8 @@ function build(kind: ActorKind, init: ActorInit): Actor {
     orgId: init.orgId,
     roles: Object.freeze([...(init.roles ?? [])]),
     scopes: Object.freeze([...(init.scopes ?? [])]),
+    facts: Object.freeze({ ...init.facts }),
+    onBehalfOf: init.onBehalfOf === undefined ? undefined : Object.freeze({ ...init.onBehalfOf }),
   });
 }
 
@@ -73,9 +153,43 @@ export function hasScope(actor: Actor, scope: string): boolean {
   return actor.scopes.includes(scope);
 }
 
-/** Log/trace-safe identity — no email, no token, stable across surfaces. */
+/**
+ * Attach resolved facts to an actor, once, at the request boundary — the one place that already
+ * awaited the database. Returns a new frozen actor, so the actor a predicate reads later cannot
+ * be edited under it; later facts win over earlier ones for the same key.
+ */
+export function withFacts(actor: Actor, facts: ActorFactMap): Actor {
+  return Object.freeze({ ...actor, facts: Object.freeze({ ...actor.facts, ...facts }) });
+}
+
+/**
+ * The one way to read a declared fact. Takes `Actor | null` because that is exactly what a policy
+ * predicate is handed, and returns `undefined` for an anonymous, absent or unresolved actor —
+ * which is what makes "absent fact" a denial by construction rather than by review.
+ */
+export function actorFact<K extends ActorFactKey>(
+  actor: Actor | null | undefined,
+  key: K,
+): ActorFacts[K] | undefined {
+  return actor?.facts?.[key];
+}
+
+/** The origin tuple for an actor, for stamping onto whoever they go on to impersonate. */
+export function actorOrigin(actor: Actor): ActorOrigin {
+  return Object.freeze({ actorId: actor.id, actorKind: actor.kind });
+}
+
+/**
+ * Log/trace-safe identity — no email, no token, stable across surfaces. Under impersonation it
+ * renders `service:eng-7→user:cust-99@org-3`: the real actor, an arrow, the effective one. One
+ * string, so no reader of a log line, a span or an audit row can see the second half alone.
+ */
 export function actorLabel(actor: Actor): string {
-  return actor.orgId === undefined
-    ? `${actor.kind}:${actor.id}`
-    : `${actor.kind}:${actor.id}@${actor.orgId}`;
+  const base =
+    actor.orgId === undefined
+      ? `${actor.kind}:${actor.id}`
+      : `${actor.kind}:${actor.id}@${actor.orgId}`;
+  return actor.onBehalfOf === undefined
+    ? base
+    : `${actor.onBehalfOf.actorKind}:${actor.onBehalfOf.actorId}→${base}`;
 }

package/src/app-version.ts

@@ -0,0 +1,32 @@
+// Single responsibility: which build of the APP this process is running. The third key in the
+// same family as `environment.ts` (`ULTIMATE_ENV` — which deploy) and `roles.ts` (`ROLE` — what
+// this process does): one key, one spelling, one default.
+//
+// Deliberately NOT `version.ts`. That answers what version of the FRAMEWORK shipped, read from
+// `@ultimat3/core`'s own manifest; this answers what the deploy calls itself, and on every release
+// that does not bump both they are different strings.
+
+export const APP_VERSION_KEY = 'APP_VERSION';
+
+/** An unset key is a local process, never a build nobody can name. */
+export const DEFAULT_APP_VERSION = 'dev';
+
+/**
+ * `APP_VERSION`, else `dev`.
+ *
+ * One reader rather than one per caller because the value is DURABLE: it is written into
+ * `x_migrations` rows by `@ultimat3/db` and `x_backfills` rows by `@ultimat3/jobs`, both of which
+ * outlive the process that wrote them. Two packages defaulting it differently would put two names
+ * on one build, in two tables an operator reads side by side. `jobs` cannot reach `db` for it —
+ * `db` is tier 1 and off that package's import list — so the shared answer lives here, at tier 0.
+ */
+export function appVersion(
+  env: Readonly<Record<string, string | undefined>> = process.env as Record<
+    string,
+    string | undefined
+  >,
+): string {
+  const declared = env[APP_VERSION_KEY];
+  // Empty is unset: a platform that exports the key with no value has named no build.
+  return declared === undefined || declared === '' ? DEFAULT_APP_VERSION : declared;
+}

package/src/assert.ts

@@ -1,6 +1,7 @@
 // Single responsibility: compile-time-backed runtime assertions. Exhaustive switches and
 // invariants both fail with a real error code, never a bare Error.
 
+import { renderCauseValue } from './error-render';
 import { UltimateError } from './errors';
 
 export interface InvariantOptions {
@@ -15,7 +16,10 @@ export interface InvariantOptions {
 export function assertNever(value: never, fix?: string): never {
   throw new UltimateError({
     code: 'X_UNREACHABLE',
-    cause: `unhandled variant: ${JSON.stringify(value) ?? String(value)}`,
+    // `JSON.stringify` raises on a bigint and on a cycle, and `String()` raises on a symbol, so
+    // the cause threw BEFORE `X_UNREACHABLE` existed: the caller caught a TypeError where a coded
+    // refusal belongs, and catching by code found nothing.
+    cause: `unhandled variant: ${renderCauseValue(value)}`,
     fix: fix ?? 'add a case for the variant named in cause',
     meta: { value },
   });

package/src/config.ts

@@ -18,6 +18,20 @@ export interface ThemeConfig {
   readonly tokens: Readonly<Record<string, string>>;
 }
 
+/**
+ * Where a browser that failed `auth: 'required'` is sent, and where it lands afterwards.
+ *
+ * `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.
+ */
+export interface AuthConfig {
+  readonly signInPath: string | null;
+  /** Where sign-in lands when there is nowhere to return to, or `?next=` is not same-origin. */
+  readonly afterSignInPath: string;
+}
+
 export interface PwaConfig {
   readonly enabled: boolean;
   readonly offline: OfflineStrategy;
@@ -26,13 +40,24 @@ export interface PwaConfig {
   readonly push: boolean;
 }
 
+/**
+ * Deliberately thin. `urlEnv`, `poolSize` and `schema` were removed 2026-08 because **nothing
+ * read them** — the only reader of any `config.database.*` field in the repo was this file's own
+ * validator, and each of the three was unfixable where it sat:
+ *
+ * - `poolSize` — `@ultimat3/db`'s `baseClient()` layers `DATABASE_POOL_MAX` over the role profile,
+ *   so the knob works; this was a second, non-functioning spelling of it.
+ * - `urlEnv` — `client.ts` reads `process.env['DATABASE_URL']` as a hardcoded literal, so a
+ *   different key here could not be honoured.
+ * - `schema` — nothing emits `SET search_path`.
+ *
+ * Wiring them instead would need a tier-0 → tier-1 read the tier table forbids. Deleting is axiom
+ * 3 applied to configuration: a value that produces neither a build error nor a runtime effect is
+ * worse than no field, because an SRE sets `poolSize: 3`, redeploys, and nothing changes.
+ */
 export interface DatabaseConfig {
   readonly driver: 'postgres';
-  /** Env key holding the connection string — never the string itself. */
-  readonly urlEnv: string;
-  readonly poolSize: number;
   readonly ssl: boolean;
-  readonly schema: string;
 }
 
 export interface CacheConfig {
@@ -77,6 +102,7 @@ export interface AppConfig {
   readonly defaultTimeZone: string;
   readonly defaultCurrency: string;
   readonly theme: ThemeConfig;
+  readonly auth: AuthConfig;
   readonly pwa: PwaConfig;
   readonly roles: readonly Role[];
   readonly database: DatabaseConfig;
@@ -99,6 +125,7 @@ export interface AppConfigInput {
   readonly defaultTimeZone?: string | undefined;
   readonly defaultCurrency?: string | undefined;
   readonly theme?: Input<ThemeConfig> | undefined;
+  readonly auth?: Input<AuthConfig> | undefined;
   readonly pwa?: Input<PwaConfig> | undefined;
   readonly roles?: readonly Role[] | undefined;
   readonly database?: Input<DatabaseConfig> | undefined;
@@ -125,6 +152,19 @@ function section<T extends object>(base: T, patch: Input<T> | undefined): T {
 }
 
 const NAME_RE = /^[a-z][a-z0-9-]{1,63}$/;
+
+/**
+ * A deliberate duplicate of `CURRENCY_CODE_PATTERN` in `packages/schema/src/money-value.ts`, which
+ * is the framework's ONE declaration of what an ISO 4217 code looks like and the source
+ * `isCurrencyCode`, the published OpenAPI `pattern` and `@ultimat3/entity`'s Postgres CHECK all
+ * derive from. This file cannot import it: `core` and `schema` are both tier 0 and `core → schema`
+ * is not in `SIDEWAYS_ALLOW` (`scripts/lib/tiers.ts`), the same wall that makes `describeValue` a
+ * character-for-character copy in `error-render.ts`.
+ *
+ * So keep the two identical, and keep the pattern inside the syntax ECMAScript, JSON Schema and
+ * POSIX ERE spell identically — a `defaultCurrency` this accepts and `t.money` refuses is an app
+ * whose configured currency cannot be written to a row.
+ */
 const CURRENCY_RE = /^[A-Z]{3}$/;
 
 function isTimeZone(value: string): boolean {
@@ -151,6 +191,7 @@ 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',
@@ -159,13 +200,7 @@ function defaults(name: string): Omit<AppConfig, 'name'> {
       push: false,
     },
     roles: [...ROLES],
-    database: {
-      driver: 'postgres',
-      urlEnv: 'DATABASE_URL',
-      poolSize: 10,
-      ssl: false,
-      schema: 'public',
-    },
+    database: { driver: 'postgres', ssl: false },
     cache: { driver: 'memory', urlEnv: undefined, defaultTtlMs: 60_000, tiers: ['memo', 'lru'] },
     jobs: {
       driver: 'postgres',
@@ -206,7 +241,6 @@ 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.database.poolSize < 1) issues.push('database.poolSize must be >= 1');
   if (config.jobs.concurrency < 1) issues.push('jobs.concurrency must be >= 1');
   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) {
@@ -248,6 +282,7 @@ export function defineConfig(
     defaultTimeZone: merged.defaultTimeZone ?? base.defaultTimeZone,
     defaultCurrency: merged.defaultCurrency ?? base.defaultCurrency,
     theme: section(base.theme, merged.theme),
+    auth: section(base.auth, merged.auth),
     pwa: section(base.pwa, merged.pwa),
     roles: merged.roles ?? base.roles,
     database: section(base.database, merged.database),

package/src/context.ts

@@ -19,6 +19,15 @@ import { installedServices, isManagedService } from './service';
  *   interface CtxServices { readonly posts: PostRepo }
  * }
  * ```
+ *
+ * KNOWN GAP, and the one place in this file that axiom 3 does not hold: the index signature
+ * below makes `ctx.<anything>` a legal expression typed `unknown`, so a service nobody declared
+ * and nobody installed is not a compile error — it is a `TS18046` at its first use, or nothing
+ * at all where the value is only passed on. The reference app shipped `ctx.storage.ensureBucket()`
+ * against a method that exists in no package for exactly this reason. Closing it means deleting
+ * the index signature, which is a breaking change for every app that reaches a service through
+ * `ctx` without declaring it, and it makes `ServiceBag`'s late-bound half (`ctx.services['mail']`)
+ * the only untyped path — which is what it is for.
  */
 export interface CtxServices {
   readonly [service: string]: unknown;
@@ -198,13 +207,31 @@ export function throwIfAborted(ctx: Ctx = useContext()): void {
   throw new UltimateError({
     code: 'X_ABORTED',
     cause: `request ${ctx.requestId} was aborted by the caller`,
-    fix: 'no action needed — stop work and return',
+    fix: 'add throwIfAborted(ctx) before expensive work, or pass fetch(url, { signal: ctx.signal }) — the caller is gone, so unwind instead of finishing',
     meta: { requestId: ctx.requestId },
   });
 }
 
-// Every log line inside a request gets the ids for free.
+/**
+ * Every log line inside a request gets the ids for free.
+ *
+ * Deliberately bounded and deliberately non-PII: ids, kinds and the runtime role, never an email,
+ * a name or a token — a log store is not a place to discover you shipped one. What is here is
+ * exactly what an incident query needs: `orgId` to scope to a tenant, `actorId` to scope to a
+ * user, `role` to scope to a fleet, and `onBehalfOfId` so a line written under impersonation is
+ * never mistaken for the customer's own.
+ */
 setLoggerContextFields(() => {
   const ctx = storage.getStore();
-  return ctx === undefined ? undefined : { requestId: ctx.requestId, traceId: ctx.traceId };
+  if (ctx === undefined) return undefined;
+  const { actor } = ctx;
+  return {
+    requestId: ctx.requestId,
+    traceId: ctx.traceId,
+    role: ctx.role,
+    actorKind: actor.kind,
+    actorId: actor.id,
+    ...(actor.orgId === undefined ? {} : { orgId: actor.orgId }),
+    ...(actor.onBehalfOf === undefined ? {} : { onBehalfOfId: actor.onBehalfOf.actorId }),
+  };
 });

package/src/cursor.ts

@@ -38,16 +38,37 @@ export class CursorInvalidError extends UltimateError {
  */
 const DEV_SECRET = 'ultimate-dev-cursor-secret';
 
-let secret = Bun.env['ULTIMATE_CURSOR_SECRET'] ?? DEV_SECRET;
+/** `configureCursorSigning`'s value, when an app has called it. `undefined` means "read the env". */
+let configured: string | undefined;
+
+/**
+ * Read at CALL time, never at module scope — the same rule `@ultimat3/auth`'s `oauth-cookie.ts`
+ * and `oauth-exchange.ts` follow, and for the same reason: an app that loads secrets through
+ * `openSecrets()` during boot sets `ULTIMATE_CURSOR_SECRET` *after* this module was imported, so a
+ * module-scope read signed every cursor of that process with the shipped dev key. `x doctor`
+ * warned and nothing failed.
+ */
+function currentSecret(): string {
+  return configured ?? Bun.env['ULTIMATE_CURSOR_SECRET'] ?? DEV_SECRET;
+}
 
 /** Set once at boot from the app secret. Rotating it invalidates every open cursor. */
 export function configureCursorSigning(next: string): void {
-  secret = next;
+  configured = next;
+}
+
+/**
+ * Test seam: forget `configureCursorSigning`, so signing falls back to the environment.
+ * The counterpart to `resetIdCounter` — a suite that configured a secret has a way back to
+ * "unconfigured", which restoring a literal cannot express.
+ */
+export function resetCursorSigning(): void {
+  configured = undefined;
 }
 
 /** True while cursors are signed with the shipped dev key — `x doctor` reports it. */
 export function usesDevCursorSecret(): boolean {
-  return secret === DEV_SECRET;
+  return currentSecret() === DEV_SECRET;
 }
 
 /** `base64url(payload).signature`. Opaque by contract: callers must never parse it. */
@@ -82,7 +103,7 @@ export function decodeCursor(cursor: string, scope: string): CursorPayload {
 
 /** Truncated HMAC-SHA256. 128 bits is far past forging a page position. */
 function sign(body: string): string {
-  return new Bun.CryptoHasher('sha256', secret).update(body).digest('hex').slice(0, 32);
+  return new Bun.CryptoHasher('sha256', currentSecret()).update(body).digest('hex').slice(0, 32);
 }
 
 /** Constant time: the comparison must not leak how much of a forged signature was right. */

package/src/env-example.ts

@@ -64,7 +64,8 @@ export interface EnvExampleOptions {
 /** Deterministic: declaration order in, declaration order out, so a rewrite diffs to nothing. */
 export function renderEnvExample(schema: EnvSchema, options?: EnvExampleOptions): string {
   const lines = [
-    '# Generated from defineEnv() — regenerate with renderEnvExample() from @ultimat3/core.',
+    '# Generated from defineEnv() — regenerate with `x env example`. Never hand-edited: drift',
+    '# fails `x verify`.',
     '# Commit this file. Never commit .env: Bun loads .env, .env.<mode> and .env.local for you.',
   ];
   for (const [key, decl] of Object.entries(schema)) {

package/src/env.ts

@@ -2,6 +2,7 @@
 // is reported in ONE error — an agent should never have to restart the process six times to
 // discover six missing variables.
 
+import { describeValue } from './error-render';
 import { EnvMissingError } from './errors';
 import { REDACTED, redactKeys } from './logger';
 import { type Role, resolveRole } from './roles';
@@ -213,18 +214,28 @@ export function defineEnv<const S extends EnvSchema>(schema: S, options?: EnvOpt
   }
 
   if (!report.ok) {
-    const cause = report.issues
+    // The SHAPE of a rejected value, never its content. `secret: true` masks by declaration
+    // (`:193`), but the leak is the variable nobody declared secret: the scaffold's own
+    // `DATABASE_URL` is not marked, so a malformed `postgres://user:pw@host/db` wrote its
+    // password into this `cause` — which is the boot log line AND the `--json` field, where no
+    // key is left to redact it by. The value itself still has a printer: `x env check`, through
+    // `maskedEnvValues`. `checkEnv().values` and `EnvCheckReport.issues` are untouched.
+    const described = report.issues.map((issue) => ({
+      ...issue,
+      received: issue.received === undefined ? undefined : describeValue(issue.received),
+    }));
+    const cause = described
       .map((issue) =>
         issue.reason === 'missing'
           ? `${issue.key} is missing (expected ${issue.expected})`
-          : `${issue.key}="${issue.received ?? ''}" is not ${issue.expected}`,
+          : `${issue.key} is not ${issue.expected} (received ${issue.received ?? 'undefined'})`,
       )
       .join('; ');
     const keys = report.issues.map((issue) => issue.key).join(' ');
     throw new EnvMissingError({
       cause,
       fix: `add ${keys} to .env (copy .env.example), then run: x env check`,
-      meta: { issues: report.issues },
+      meta: { issues: described },
     });
   }
 

package/src/environment.ts

@@ -35,6 +35,22 @@ export interface ResolveEnvironmentOptions {
   readonly fallback?: Environment | undefined;
 }
 
+/** One read of the two keys, so the throwing and the non-throwing entry point cannot disagree. */
+type EnvironmentRead =
+  | { readonly ok: true; readonly environment: Environment }
+  | { readonly ok: false; readonly declared: string };
+
+function readEnvironment(options?: ResolveEnvironmentOptions): EnvironmentRead {
+  const source = options?.env ?? (process.env as Record<string, string | undefined>);
+  const declared = source[ENVIRONMENT_KEY];
+  if (declared !== undefined && declared !== '') {
+    return isEnvironment(declared) ? { ok: true, environment: declared } : { ok: false, declared };
+  }
+  const inherited = source['NODE_ENV'];
+  if (isEnvironment(inherited)) return { ok: true, environment: inherited };
+  return { ok: true, environment: options?.fallback ?? DEFAULT_ENVIRONMENT };
+}
+
 /**
  * `ULTIMATE_ENV`, else `NODE_ENV`, else `development`.
  *
@@ -43,19 +59,29 @@ export interface ResolveEnvironmentOptions {
  * it is not ours to police, and CI images set it to values ("ci", "qa") that must not stop a boot.
  */
 export function resolveEnvironment(options?: ResolveEnvironmentOptions): Environment {
-  const source = options?.env ?? (process.env as Record<string, string | undefined>);
-  const declared = source[ENVIRONMENT_KEY];
-  if (declared !== undefined && declared !== '') {
-    if (isEnvironment(declared)) return declared;
-    throw new EnvironmentInvalidError({
-      cause: `${ENVIRONMENT_KEY}="${declared}" is not one of ${ENVIRONMENTS.join(' | ')}`,
-      fix: `export ${ENVIRONMENT_KEY}=${ENVIRONMENTS.join('|')} — one of those exact values`,
-      meta: { key: ENVIRONMENT_KEY, received: declared, allowed: ENVIRONMENTS },
-    });
-  }
-  const inherited = source['NODE_ENV'];
-  if (isEnvironment(inherited)) return inherited;
-  return options?.fallback ?? DEFAULT_ENVIRONMENT;
+  const read = readEnvironment(options);
+  if (read.ok) return read.environment;
+  throw new EnvironmentInvalidError({
+    cause: `${ENVIRONMENT_KEY}="${read.declared}" is not one of ${ENVIRONMENTS.join(' | ')}`,
+    fix: `export ${ENVIRONMENT_KEY}=${ENVIRONMENTS.join('|')} — one of those exact values`,
+    meta: { key: ENVIRONMENT_KEY, received: read.declared, allowed: ENVIRONMENTS },
+  });
+}
+
+/**
+ * The same resolution for a caller that must answer rather than fail — a response being rendered,
+ * a report being tagged. `undefined` means exactly one thing: `ULTIMATE_ENV` is set to something
+ * that is not an environment, the one case `resolveEnvironment` throws on. Every other input
+ * answers identically, so the key still has one reader and only the failure policy differs.
+ *
+ * The caller names its own fallback (`?? DEFAULT_ENVIRONMENT`) rather than getting one here: a
+ * process that cannot say which deploy it is has a policy about that, and it is never this file's.
+ */
+export function tryResolveEnvironment(
+  options?: ResolveEnvironmentOptions,
+): Environment | undefined {
+  const read = readEnvironment(options);
+  return read.ok ? read.environment : undefined;
 }
 
 /** The one production test. Anything that is not literally `production` is not production. */

package/src/error-codes.ts

@@ -36,22 +36,35 @@ const CORE_CODE_TITLES = {
   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',
   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',
+  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 already declared with another kind',
   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',
+  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_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;