@ultimat3/core 1.2.0 → 3.0.0

package/src/impersonate.ts

@@ -0,0 +1,62 @@
+// Single responsibility: acting as another actor, on the record. `withChildContext({ actor })` is
+// the mechanism; this is the ONE door through it, because a swap with no reason and no origin is
+// indistinguishable in an audit trail from the customer doing it themselves.
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { type Actor, actorLabel, actorOrigin } from './actor';
+import { assert } from './assert';
+import { useContext, withChildContext } from './context';
+import { currentSpan } from './telemetry';
+
+const storage = new AsyncLocalStorage<string>();
+
+/**
+ * Run `fn` as `actor`, recording who asked and why.
+ *
+ * ```ts
+ * await impersonate(customer, 'ticket 4821: reproduce the failed refund', async () => { … });
+ * ```
+ *
+ * Three properties, none optional. **The original actor is preserved** — stamped onto the child as
+ * `onBehalfOf`, so every log line, span and `actorLabel()` inside renders `support:eng-7→user:…`
+ * and a refund issued here can never read as the customer's. **The reason is required and
+ * non-blank** because it *is* the mechanism: a swap with no argument is a pragma, and the next
+ * reader cannot tell a support session from a bug. **There must be a context** — outside one there
+ * is no original actor to preserve, so there is nothing to impersonate *from*, and
+ * `withChildContext` says so with `X_NO_CONTEXT`.
+ *
+ * Same template as `@ultimat3/entity`'s `crossTenant()`, deliberately: two escapes from the
+ * framework's default posture should not be two different-looking things.
+ */
+export function impersonate<T>(actor: Actor, reason: string, fn: () => T): T {
+  assert(
+    reason.trim() !== '',
+    'impersonate() was given a blank reason, so the identity swap it performs carries no argument',
+    "pass why one actor is acting as another: impersonate(customer, 'ticket 4821: reproduce the failed refund', fn)",
+  );
+  const parent = useContext();
+  const impersonated: Actor = Object.freeze({ ...actor, onBehalfOf: actorOrigin(parent.actor) });
+  const label = actorLabel(impersonated);
+  // The PARENT's logger, because the parent is who is performing this — and `warn`, not `info`,
+  // because this is rare, always interesting, and an audit query that has to read info-level to
+  // find it will be run at the wrong level during the one incident where it matters.
+  parent.logger.warn('impersonation', { event: 'impersonation', actor: label, reason });
+  currentSpan()?.addEvent('impersonation', {
+    'actor.label': label,
+    'impersonation.reason': reason,
+  });
+  return withChildContext({ actor: impersonated }, () => storage.run(reason, fn));
+}
+
+/**
+ * The innermost enclosing reason, or `undefined` outside every scope — which is every request in
+ * an app where nobody is impersonating. Read by an audit sink, and by nothing else.
+ */
+export function impersonationReason(): string | undefined {
+  return storage.getStore();
+}
+
+/** Is the caller acting as somebody else right now? */
+export function isImpersonating(): boolean {
+  return storage.getStore() !== undefined;
+}

package/src/index.ts

@@ -1,10 +1,24 @@
 // Single responsibility: the public API of @ultimat3/core. Explicit named exports only —
 // every other package imports from here, so this list is the tier-0 contract.
+//
+// Three slices arrive through a barrel in `exports/` — observability, the error contract and
+// secrets — because each is one subject spread over a dozen modules. Every name they carry is
+// still written out below: `export *` would make the contract something a reader has to resolve.
 
-export type { Actor, ActorInit, ActorKind } from './actor';
+export type {
+  Actor,
+  ActorFactKey,
+  ActorFactMap,
+  ActorFacts,
+  ActorInit,
+  ActorKind,
+  ActorOrigin,
+} from './actor';
 export {
   ACTOR_KINDS,
+  actorFact,
   actorLabel,
+  actorOrigin,
   agentActor,
   anonymousActor,
   hasRole,
@@ -13,7 +27,9 @@ export {
   isAnonymous,
   serviceActor,
   userActor,
+  withFacts,
 } from './actor';
+export { APP_VERSION_KEY, appVersion, DEFAULT_APP_VERSION } from './app-version';
 export type { InvariantOptions } from './assert';
 export { assert, assertNever, invariant } from './assert';
 export type { Clock, FrozenClock } from './clock';
@@ -24,6 +40,7 @@ export type {
   AppConfig,
   AppConfigInput,
   AppConfigOverlay,
+  AuthConfig,
   CacheConfig,
   CacheTier,
   DatabaseConfig,
@@ -58,6 +75,7 @@ export {
   configureCursorSigning,
   decodeCursor,
   encodeCursor,
+  resetCursorSigning,
   usesDevCursorSecret,
 } from './cursor';
 export type {
@@ -95,44 +113,266 @@ export {
   isLocal,
   isProduction,
   resolveEnvironment,
+  tryResolveEnvironment,
 } from './environment';
 export type {
+  CodedErrorInit,
   CoreErrorCode,
   ErrorCodeDeclaration,
   ErrorCodeDescriptor,
   ErrorCodeEntry,
-} from './error-codes';
-export {
-  CORE_ERROR_CODES,
-  describeErrorCode,
-  ERROR_DOCS_BASE,
-  errorCodeSnapshot,
-  errorDocsUrl,
-  hasErrorCode,
-  listErrorCodes,
-  registerErrorCodes,
-  resetErrorCodes,
-} from './error-codes';
-export type {
-  CodedErrorInit,
+  ErrorRetry,
   FormatErrorOptions,
   UltimateErrorInit,
   UltimateErrorJSON,
-} from './errors';
+} from './exports/error-contract';
 export {
+  CORE_ERROR_CODES,
   ConfigInvalidError,
+  DEFAULT_ERROR_RETRY,
+  declaredErrorRetry,
+  describeErrorCode,
+  describeValue,
   EnvMissingError,
+  ERROR_DOCS_BASE,
+  ERROR_RETRY_KINDS,
+  errorCodeSnapshot,
+  errorDocsUrl,
+  errorRetry,
   formatError,
+  hasErrorCode,
   InternalError,
+  isErrorRetry,
+  isThrownError,
   isUltimateError,
+  listErrorCodes,
+  MAX_RENDERED_LENGTH,
   NotImplementedError,
   notImplemented,
+  registerErrorCodes,
+  registerErrorRetry,
+  registeredErrorRetry,
+  renderCauseValue,
+  renderFixLiteral,
+  renderThrowable,
+  resetErrorCodes,
+  resetErrorRetry,
+  retryFor,
+  SCHEMA_ERROR_CODE_TITLES,
+  stringField,
   toUltimateError,
   ULTIMATE_ERROR_BRAND,
   UltimateError,
-} from './errors';
+} from './exports/error-contract';
+export type {
+  AttributeValue,
+  Counter,
+  ErrorReport,
+  ErrorReporter,
+  ErrorReportingOptions,
+  ErrorScope,
+  ErrorSeverity,
+  ErrorSource,
+  Gauge,
+  GaugeOptions,
+  Histogram,
+  HistogramOptions,
+  HistogramPoint,
+  InstrumentOptions,
+  LogFields,
+  Logger,
+  LoggerOptions,
+  LogLevel,
+  MemoryErrorReporter,
+  MemoryExporter,
+  MemoryMetricExporter,
+  MetricAttributes,
+  MetricAttributeValue,
+  MetricCollection,
+  MetricDescriptor,
+  MetricExporter,
+  MetricKind,
+  MetricPoint,
+  MetricsOptions,
+  OtlpAnyValue,
+  OtlpKeyValue,
+  OtlpMetricExporter,
+  OtlpMetricExporterOptions,
+  OtlpSignal,
+  OtlpSpanExporter,
+  OtlpSpanExporterOptions,
+  ReadableMetric,
+  ReadableSpan,
+  ReportErrorOptions,
+  RequestSample,
+  Sampler,
+  SentryDsn,
+  SentryEnvelopeOptions,
+  SentryReporterOptions,
+  Span,
+  SpanAttributes,
+  SpanContext,
+  SpanEvent,
+  SpanExporter,
+  SpanKind,
+  SpanResource,
+  SpanStatus,
+  SpanStatusCode,
+  StartSpanOptions,
+  TelemetryOptions,
+} from './exports/observability';
+export {
+  alwaysOffSampler,
+  alwaysOnSampler,
+  collectMetrics,
+  configureErrorReporting,
+  configureMetrics,
+  configureTelemetry,
+  connections,
+  counter,
+  createLogger,
+  currentSampler,
+  currentSpan,
+  currentSpanContext,
+  DEFAULT_HISTOGRAM_BOUNDS,
+  DEFAULT_MAX_SERIES,
+  DEFAULT_SAMPLE_RATIO,
+  defaultSampler,
+  ERROR_SOURCES,
+  ErrorReporterDsnInvalidError,
+  errorReport,
+  exportMetrics,
+  gauge,
+  histogram,
+  isRedactedKey,
+  jobs,
+  LOG_LEVELS,
+  leasesLost,
+  logger,
+  METRICS_CONTENT_TYPE,
+  METRICS_PATH,
+  MetricCardinalityError,
+  MetricNameInvalidError,
+  MetricValueInvalidError,
+  memoryErrorReporter,
+  memoryExporter,
+  memoryMetricExporter,
+  metricsText,
+  noopErrorReporter,
+  noopExporter,
+  noopMetricExporter,
+  OTEL_SAMPLER_ARG_KEY,
+  OTEL_SAMPLER_KEY,
+  OTLP_ENDPOINT_KEY,
+  OTLP_HEADERS_KEY,
+  OTLP_PROTOCOL_KEY,
+  OTLP_SCOPE,
+  OtlpEndpointInvalidError,
+  OtlpProtocolUnsupportedError,
+  OVERFLOW_ATTRIBUTE,
+  otlpAttributes,
+  otlpEndpoint,
+  otlpHeaders,
+  otlpMetricExporter,
+  otlpMetricsRequest,
+  otlpResource,
+  otlpSpanExporter,
+  otlpTraceRequest,
+  parentBasedRatioSampler,
+  parseSentryDsn,
+  parseTraceparent,
+  queueDepth,
+  REDACTED,
+  ratioSampler,
+  recordConnection,
+  recordJob,
+  recordLeaseLost,
+  recordQueueDepth,
+  recordRequest,
+  redactKeys,
+  reportError,
+  requestDuration,
+  requests,
+  resetDefaultSampler,
+  resetErrorReporting,
+  resetMetrics,
+  resetTelemetry,
+  SCALING_METRICS,
+  samplerFromEnv,
+  sentryEnvelope,
+  sentryErrorReporter,
+  serviceResource,
+  setLoggerContextFields,
+  startMetricExport,
+  startSpan,
+  traceparent,
+  tryOtlpEndpoint,
+  unixNano,
+  withSpan,
+  withSpanContext,
+} from './exports/observability';
+export type {
+  MasterKeyRef,
+  MasterKeySource,
+  Secret,
+  SecretSummary,
+  SecretsEnvelope,
+  SecretsErrorCode,
+  SecretsInstallOptions,
+  SecretsInstallReport,
+  SecretsLocation,
+  SecretValues,
+} from './exports/secrets';
+export {
+  assertSecretValues,
+  describeSecrets,
+  findMasterKey,
+  generateMasterKey,
+  installSecrets,
+  isSecret,
+  masterKeyId,
+  masterKeyIdOf,
+  masterKeyPath,
+  openSecrets,
+  parseMasterKey,
+  parseSecretsEnvelope,
+  readSecretsFile,
+  requireMasterKey,
+  revealOptionalSecret,
+  revealSecret,
+  SECRET_BRAND,
+  SECRET_NAME,
+  SECRETS_ALG,
+  SECRETS_ERROR_CODES,
+  SECRETS_FILE,
+  SECRETS_IV_BYTES,
+  SECRETS_KEY_BYTES,
+  SECRETS_KEY_ENV,
+  SECRETS_KEY_FILE,
+  SECRETS_KEY_HEX_LENGTH,
+  SECRETS_KEY_ID_LENGTH,
+  SECRETS_KEY_MODE,
+  SECRETS_TAG_BYTES,
+  SECRETS_VERSION,
+  SecretsFileInvalidError,
+  SecretsFileMissingError,
+  SecretsKeyInvalidError,
+  SecretsKeyMismatchError,
+  SecretsKeyMissingError,
+  SecretsPlaintextInvalidError,
+  SecretsTamperedError,
+  sealSecrets,
+  secret,
+  secretsFileExists,
+  secretsPath,
+  serializeSecretValues,
+  writeMasterKeyFile,
+  writeSecretsFile,
+} from './exports/secrets';
 export type { Brand, Id } from './ids';
 export {
+  isSpanId,
+  isTraceId,
   isUuid,
   nanoid,
   parseId,
@@ -187,6 +427,8 @@ export {
 } from './image/raster';
 export type { ImageFit, ResizeSpec } from './image/resize';
 export { fitBox, resizeRaster, scaledToFit } from './image/resize';
+export { impersonate, impersonationReason, isImpersonating } from './impersonate';
+export { cachedFormatter, canonicalLocale, MAX_CACHED_FORMATTERS } from './intl-cache';
 export type {
   HealthPayload,
   HealthReport,
@@ -194,6 +436,8 @@ export type {
   LifecycleOptions,
   OnShutdownOptions,
   ProcessSignal,
+  ReadinessCheck,
+  ReadinessStatus,
   ShutdownHook,
   ShutdownPhase,
   ShutdownReason,
@@ -203,17 +447,23 @@ export {
   beginWork,
   configureLifecycle,
   drain,
+  drainDeadlineMs,
   healthReport,
   healthzPayload,
+  idleWaiterCount,
   inflightCount,
   installSignalHandlers,
   isDraining,
   lifecycleState,
   markReady,
   onShutdown,
+  readinessCheckCount,
+  readinessChecks,
   readyzPayload,
+  registerReadinessCheck,
   resetLifecycle,
   SHUTDOWN_PHASES,
+  shutdownHookCount,
 } from './lifecycle';
 export {
   isSelfOrigin,
@@ -221,51 +471,10 @@ export {
   markListening,
   resetListeners,
 } from './listeners';
-export type { LogFields, Logger, LoggerOptions, LogLevel } from './logger';
-export {
-  createLogger,
-  isRedactedKey,
-  LOG_LEVELS,
-  logger,
-  REDACTED,
-  redactKeys,
-  setLoggerContextFields,
-} from './logger';
-export type {
-  Counter,
-  Gauge,
-  GaugeOptions,
-  Histogram,
-  HistogramOptions,
-  HistogramPoint,
-  InstrumentOptions,
-  MemoryMetricExporter,
-  MetricAttributes,
-  MetricAttributeValue,
-  MetricCollection,
-  MetricDescriptor,
-  MetricExporter,
-  MetricKind,
-  MetricPoint,
-  MetricsOptions,
-  ReadableMetric,
-} from './metrics';
-export {
-  collectMetrics,
-  configureMetrics,
-  counter,
-  DEFAULT_HISTOGRAM_BOUNDS,
-  exportMetrics,
-  gauge,
-  histogram,
-  MetricNameInvalidError,
-  MetricValueInvalidError,
-  memoryMetricExporter,
-  noopMetricExporter,
-  resetMetrics,
-  startMetricExport,
-} from './metrics';
-export { METRICS_CONTENT_TYPE, METRICS_PATH, metricsText } from './metrics-text';
+export type { McpExposureDeclaration } from './mcp-exposure';
+export { isMcpExposed } from './mcp-exposure';
+export type { CappedBody } from './read-capped';
+export { readWithinLimit } from './read-capped';
 export type { ModuleRegistrar, PrimitiveKind, RegisteredPrimitive } from './registrar';
 export {
   hasPrimitiveRegistrar,
@@ -278,57 +487,14 @@ 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 { RequestSample } from './runtime-metrics';
-export {
-  connections,
-  jobs,
-  queueDepth,
-  recordConnection,
-  recordJob,
-  recordQueueDepth,
-  recordRequest,
-  requestDuration,
-  requests,
-  SCALING_METRICS,
-} from './runtime-metrics';
-export type { Secret } from './secret';
-export {
-  isSecret,
-  revealOptionalSecret,
-  revealSecret,
-  SECRET_BRAND,
-  secret,
-} from './secret';
+export { safeUrl, URL_ATTRIBUTES } from './safe-url';
 export type { ServiceFactory } from './service';
 export { defineService, resetServices } from './service';
-export type {
-  AttributeValue,
-  MemoryExporter,
-  ReadableSpan,
-  Span,
-  SpanAttributes,
-  SpanContext,
-  SpanEvent,
-  SpanExporter,
-  SpanKind,
-  SpanResource,
-  SpanStatus,
-  SpanStatusCode,
-  StartSpanOptions,
-  TelemetryOptions,
-} from './telemetry';
+export { timingSafeEqual } from './timing-safe-equal';
 export {
-  configureTelemetry,
-  currentSpan,
-  currentSpanContext,
-  memoryExporter,
-  noopExporter,
-  parseTraceparent,
-  resetTelemetry,
-  serviceResource,
-  startSpan,
-  traceparent,
-  withSpan,
-  withSpanContext,
-} from './telemetry';
-export { FRAMEWORK_VERSION, readPackageVersion, VERSION_MANIFEST } from './version';
+  frameworkVersion,
+  readPackageVersion,
+  resolveVersion,
+  VERSION_DEFINE,
+  VERSION_MANIFEST,
+} from './version';

package/src/intl-cache.ts

@@ -0,0 +1,43 @@
+// One bounded cache, on one canonical key, for every `Intl` formatter the framework builds.
+// A locale and a zone both arrive from a request header, so an unbounded `Map` keyed on the
+// caller's spelling is memory the client chooses — 31 MB and 55.1 MB, measured `As of 2026-08` and
+// written up in the README. The bound and the canonical key are two halves of ONE rule.
+
+/**
+ * Above the full canonical IANA set (445 zones as of tzdata 2025) so a correct app never evicts,
+ * and small enough that the worst case is a few megabytes rather than a leak. A miss costs one
+ * `Intl` construction, never a wrong answer — which is what makes a bound safe here at all.
+ */
+export const MAX_CACHED_FORMATTERS = 512;
+
+/** FIFO — a `Map` iterates in insertion order, so the first key inserted is the first evicted. */
+export function cachedFormatter<T>(cache: Map<string, T>, key: string, build: () => T): T {
+  // Membership decides, never truthiness: `T` is the caller's, so a stored `undefined` is a hit.
+  // The cast is sound because `has` just proved the key is present, which `get`'s signature cannot.
+  if (cache.has(key)) return cache.get(key) as T;
+  const formatter = build();
+  if (cache.size >= MAX_CACHED_FORMATTERS) {
+    const oldest = cache.keys().next().value;
+    if (oldest !== undefined) cache.delete(oldest);
+  }
+  cache.set(key, formatter);
+  return formatter;
+}
+
+/**
+ * The canonical BCP 47 spelling, or `undefined` when the tag is not structurally valid at all
+ * (`en_US`, `''`, `not a locale`). Well-formed but unknown to ICU (`zz`) is a locale — `Intl`
+ * falls back for it, and refusing here would be stricter than the formatters this feeds.
+ *
+ * Deliberately **not** memoised: this is string work, and a `Map` keyed on a header value is the
+ * unbounded cache the bound above exists to prevent.
+ */
+export function canonicalLocale(locale: string): string | undefined {
+  try {
+    // `getCanonicalLocales` runs the same IsStructurallyValidLanguageTag check that
+    // `supportedLocalesOf` throws on, and unlike it, hands back the canonical spelling.
+    return Intl.getCanonicalLocales(locale)[0];
+  } catch {
+    return undefined;
+  }
+}

package/src/lifecycle-deadline.ts

@@ -0,0 +1,73 @@
+// Single responsibility: run one shutdown hook under the drain's remaining budget. A hook that
+// overruns is ABANDONED — still running, no longer awaited — because a deadline that only logged
+// leaves the kubelet to SIGKILL the process, which is the failure the budget exists to prevent.
+// Split out of `lifecycle.ts` so the race has no access to the drain's module state.
+
+/**
+ * What became of one hook. `abandoned` is the only outcome the caller must report: the hook is
+ * still running, nothing will ever read its result, and whatever it had in flight may be
+ * incomplete — which is the price of a deadline and has to be visible in the log line.
+ */
+export type HookOutcome =
+  | { readonly kind: 'settled' }
+  | { readonly kind: 'failed'; readonly error: unknown }
+  | { readonly kind: 'abandoned' };
+
+const SETTLED: HookOutcome = Object.freeze({ kind: 'settled' });
+const ABANDONED: HookOutcome = Object.freeze({ kind: 'abandoned' });
+
+const failed = (error: unknown): HookOutcome => ({ kind: 'failed', error });
+
+/**
+ * `work()` raced against `budgetMs` of REAL elapsed time. `budgetMs` is required and is a `number`:
+ * every drain has a budget, so "no budget" is not a case this has to answer for, and the signature
+ * is what stops it from becoming one.
+ *
+ * A synchronous throw and a rejection are one outcome (`failed`); the caller logs both the same
+ * way. Nothing here throws: a drain that rejects never reaches `process.exit(0)`.
+ */
+export function settleWithin(
+  work: () => void | Promise<void>,
+  budgetMs: number,
+): Promise<HookOutcome> {
+  let started: void | Promise<void>;
+  try {
+    started = work();
+  } catch (error) {
+    return Promise.resolve(failed(error));
+  }
+  const pending = Promise.resolve(started);
+  return new Promise<HookOutcome>((resolve) => {
+    let decided = false;
+    const timer = setTimeout(
+      () => {
+        if (decided) return;
+        decided = true;
+        resolve(ABANDONED);
+      },
+      Math.max(0, budgetMs),
+    );
+    // A budget already spent still gives a synchronous hook its turn — a resolved promise settles
+    // on a microtask and this timer on a macrotask — so closing a pool costs nothing it does not
+    // already have. It must also never be the thing keeping a drained process alive.
+    timer.unref?.();
+    // Attached unconditionally, on both settle paths: an abandoned hook that rejects later has
+    // nobody left awaiting it, and an unhandled rejection would kill the process this drain is
+    // trying to end cleanly. After the decision the outcome is dropped on purpose — the overrun
+    // was already reported, and a second line about a hook nobody is waiting for is noise.
+    pending.then(
+      () => {
+        if (decided) return;
+        decided = true;
+        clearTimeout(timer);
+        resolve(SETTLED);
+      },
+      (error: unknown) => {
+        if (decided) return;
+        decided = true;
+        clearTimeout(timer);
+        resolve(failed(error));
+      },
+    );
+  });
+}

package/src/lifecycle-errors.ts

@@ -0,0 +1,33 @@
+// Single responsibility: the one condition a lifecycle that has already drained raises, and the
+// error that carries it. Split from `lifecycle.ts` so the state machine reads as a state machine,
+// and registered here rather than in `error-codes.ts` for the reason `secrets-errors.ts` gives:
+// the code and the module that throws it ship together.
+
+import { registerErrorCodes } from './error-codes';
+import { UltimateError } from './errors';
+
+registerErrorCodes({
+  X_LIFECYCLE_DRAINED: { title: 'a drained process cannot become ready again' },
+});
+
+/**
+ * A role tried to become ready in a process whose lifecycle has already drained.
+ *
+ * Loud rather than tolerant, because the silent version was measured and is worse than a failed
+ * boot: `state` never leaves `stopped` and `drain()` has memoized its promise, so a second
+ * `createServer().start()` bound a real port, answered `X_DRAINING` (503) to every request, and was
+ * still accepting connections after its own `stop()` returned — a dead listener holding a port,
+ * with no log line naming what happened.
+ *
+ * The `fix` has to answer two readers, because there are exactly two ways here: a boot that starts
+ * a role after SIGTERM has already arrived, and a test that drained in one case and built a server
+ * in the next.
+ */
+export function lifecycleDrained(state: 'draining' | 'stopped'): UltimateError {
+  return new UltimateError({
+    code: 'X_LIFECYCLE_DRAINED',
+    cause: `this process is ${state} — its lifecycle has already drained, and a drain is terminal: one process, one lifecycle. A role marked ready now would bind a socket that answers 503 to every request, and drain() memoizes, so nothing would ever close it`,
+    fix: 'start every role BEFORE the first drain — a drained process is on its way out and is replaced, never reused. In a test, call resetLifecycle() from @ultimat3/core between the drain and the next start()',
+    meta: { state },
+  });
+}