@ultimat3/core 1.0.0 → 1.2.0

package/README.md

@@ -11,12 +11,18 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | request context on `AsyncLocalStorage` | `context.ts` |
 | `Actor` (`user \| service \| agent \| anonymous`) | `actor.ts` |
 | typed env validated at boot | `env.ts` |
+| `.env.example` rendered from that schema, and its drift check | `env-example.ts` |
+| named environments + `ULTIMATE_ENV` resolution | `environment.ts` |
+| a value that cannot be printed by accident | `secret.ts` |
 | `defineConfig()` for `app.config.ts` | `config.ts` |
 | runtime roles + `ROLE` resolution | `roles.ts` |
 | `Clock` — the only source of "now" | `clock.ts` |
 | UUIDv7, nanoid, branded ids | `ids.ts` |
 | structured JSON logging + redaction | `logger.ts` |
 | OTel-shaped spans, always on, no-op by default | `telemetry.ts` |
+| OTel-shaped counter / gauge / histogram, same seam | `metrics.ts` |
+| the `/metrics` scrape body | `metrics-text.ts` |
+| the series every process emits, incl. what the chart scales on | `runtime-metrics.ts` |
 | graceful drain, `/healthz`, `/readyz` | `lifecycle.ts` |
 | the sockets this process opened, so a self-request is not egress | `listeners.ts` |
 | `defineService('orgs', …)` → `ctx.orgs`, rebuilt per actor | `service.ts` |
@@ -90,7 +96,7 @@ registered survives an actor swap unrebuilt.
 export const env = defineEnv({
   DATABASE_URL: { type: 'url', secret: true },
   PORT:         { type: 'port', default: 3000 },
-  STAGE:        { type: 'enum', values: ['dev', 'staging', 'prod'] },
+  REGION:       { type: 'enum', values: ['us', 'eu'] },
   SENTRY_DSN:   { type: 'url', required: false },
   NATS_URL:     { type: 'url', role: 'sync' },   // only required for ROLE=sync
 });
@@ -99,7 +105,46 @@ export const env = defineEnv({
 Every missing or malformed key is listed in one `X_ENV_MISSING`. `secret: true` keys are
 redacted in logs and masked in `checkEnv()` output; `describeEnv()` emits declarations only,
 safe for `x.manifest.json`. Omit `required` for required — `required: false` is the only
-loosening.
+loosening. Never declare an env var for *which deploy this is* — that is `ULTIMATE_ENV`, below.
+
+`.env.example` is a **projection** of that schema, never a second list:
+`renderEnvExample(schema)` writes it, `assertEnvExample(schema, text)` fails with
+`X_ENV_EXAMPLE_DRIFT` when a declared key has no line — the failure that otherwise arrives as
+somebody else's `X_ENV_MISSING` on a variable nobody documented.
+
+Loading `.env` is **Bun's**, not ours. `envFileCandidates()` states what it does, measured:
+`.env` → `.env.<mode>` → `.env.local`, with `.env.local` skipped under test, and the mode being
+`production`, `test` or **`development` for everything else — `staging` included**. There is no
+`.env.staging`; a staging deploy carries real environment variables.
+
+## One environment, one key
+
+```ts
+resolveEnvironment();   // 'development' | 'test' | 'staging' | 'production'
+isProduction();         // exact; nothing else counts
+isLocal();              // development or test — never staging
+```
+
+`ULTIMATE_ENV` is the key, `NODE_ENV` the fallback (platforms already set it). Values are
+`NODE_ENV`'s spellings plus `staging` — `prod` and `dev` are typos, not aliases, and
+`ULTIMATE_ENV=prod` is `X_ENVIRONMENT_INVALID`. An unrecognised `NODE_ENV` is *not* an error: it
+is not our key. This is the twin of `roles.ts` — `ROLE` says what the process does,
+`ULTIMATE_ENV` says which deploy it belongs to.
+
+## A secret is redacted by value, not by name
+
+```ts
+const dsn = secret(process.env.DATABASE_URL ?? '', 'DATABASE_URL');
+logger.info('boot', { dsn });        // {"dsn":"[redacted]"}
+connect(revealSecret(dsn));          // the one greppable way out
+```
+
+`redactKeys()` catches a secret travelling under a name someone remembered to list. A `Secret`
+box catches the other case: `String()`, template literals, `+`, `JSON.stringify`, `console.log`,
+the logger and an error's `meta` all render `[redacted]`, whatever key it sits under. It is
+frozen and everything but `label` is non-enumerable, so `{ ...dsn }` cannot spread the value back
+out. There is no vault integration and there will not be one — that is a platform primitive
+(axiom 7); a `Secret` plus the platform's own secret store is the whole design.
 
 ## Time, ids, telemetry, drain
 
@@ -109,12 +154,53 @@ loosening.
 - `withSpan('action.publishPost', fn)` is free until `configureTelemetry({ exporter })`.
   Traces cross process boundaries via `traceparent()` / `parseTraceparent()` — Sentry, Honeycomb
   and OTLP all plug in as a `SpanExporter`.
+- Metrics are the same shape one signal over: `counter()`, `gauge()`, `histogram()`, aggregated
+  in process, free until `configureMetrics({ exporter })`. See below.
 - `onShutdown(name, hook, { phase })` with phases `accept → inflight → close` under one
   deadline; `readyzPayload()` flips to 503 the moment draining starts, `healthzPayload()` stays
   200 until stopped.
 - Anything that opens a socket calls `markListening(server.url.origin)` and releases it on close.
   That is what tells the sealed test network a loopback request is this process, not egress.
 
+## Metrics: same seam as tracing, one signal over
+
+```ts
+const published = counter('posts_published_total', { description: 'posts published' });
+published.add(1, { plan: 'pro' });
+
+gauge('queue_depth', { observe: () => pending() });   // read at scrape time, never stale
+histogram('render_duration_seconds').record(ms / 1000);
+
+metricsText();          // the /metrics body, at METRICS_PATH, METRICS_CONTENT_TYPE
+collectMetrics();       // the same numbers as data, for a MetricExporter
+```
+
+| | |
+|---|---|
+| Kinds | `counter` (monotonic sum), `gauge` (`record` / `add`, or an async `observe`), `histogram` (explicit bounds, OTel's default latency set) |
+| Temporality | cumulative, as OTel defines it — a read never resets a counter, so two scrapers cannot steal each other's samples |
+| Names | lowercase `snake_case`, the intersection every exposition format accepts. Dotted OTel names survive OTLP and die at a Prometheus scrape |
+| Attributes | `string \| number \| boolean` only — each distinct set is a stored series, so a user id here is an outage |
+| Driver seam | `MetricExporter`, defaulting to a no-op. `memoryMetricExporter()` for tests, `startMetricExport(ms)` for a periodic push |
+| Not shipped | an OTLP client. It is bytes on a wire and a dependency; the seam is here, the driver is yours — or scrape `/metrics` with an agent that already speaks it |
+
+`runtime-metrics.ts` holds the series every process emits, and `SCALING_METRICS` maps each
+`ScalingSignal` from `roles.ts` to the one that carries it — so the role table, the chart and the
+process cannot drift apart:
+
+| Role scales on | Series | Instrument |
+|---|---|---|
+| `rps` | `http_requests_total` | counter; `rps` is a **rate** the adapter derives (`rate(http_requests_total[1m])`), never a stored number |
+| `ws-connections` | `connections` | gauge, `+1`/`-1` |
+| `queue-depth` | `queue_depth` | gauge, by `queue` label |
+
+`As of 2026-08` all three are emitted and scraped. One call site per package — `recordRequest`
+from `@ultimat3/http`'s pipeline, `recordConnection` from `@ultimat3/realtime`'s socket table,
+`recordQueueDepth` from `@ultimat3/jobs`' worker loop — and `@ultimat3/cli` serves `metricsText()`
+at `METRICS_PATH` on `METRICS_PORT` (9090), for every role rather than only the ones that open an
+HTTP socket. Labels are route **patterns**, status **classes** and queue names: nothing
+per-user, per-id or attacker-chosen ever becomes a series.
+
 ## One cursor, everywhere
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",

package/src/env-example.ts

@@ -0,0 +1,123 @@
+// Single responsibility: `.env.example` is a PROJECTION of the `defineEnv()` schema, never a
+// second hand-maintained list. Render it from the declarations, and report drift when the file on
+// disk has fallen behind. Loading `.env` itself is Bun's job — see `envFileCandidates()`.
+
+import type { EnvSchema, EnvVarDecl } from './env';
+import { type CodedErrorInit, UltimateError } from './errors';
+
+export class EnvExampleDriftError extends UltimateError {
+  static readonly code = 'X_ENV_EXAMPLE_DRIFT';
+  override readonly name = 'EnvExampleDriftError';
+  constructor(init: CodedErrorInit) {
+    super({ ...init, code: EnvExampleDriftError.code });
+  }
+}
+
+const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export const ENV_EXAMPLE_PATH = '.env.example';
+
+/**
+ * What Bun loads by itself, lowest precedence first — measured against Bun 1.3, not assumed.
+ *
+ * The mode is NOT `ULTIMATE_ENV` and not even `NODE_ENV` verbatim: Bun reads `.env.production`
+ * for `NODE_ENV=production`, `.env.test` for `test`, and `.env.development` for **everything
+ * else, `staging` included**. So a `.env.staging` file is never read, which is why a named
+ * environment is carried by real environment variables (`ULTIMATE_ENV` plus the platform's own
+ * config) and never by a per-environment dotenv file.
+ */
+export function envFileCandidates(nodeEnv?: string | undefined): readonly string[] {
+  const mode = nodeEnv === 'production' || nodeEnv === 'test' ? nodeEnv : 'development';
+  const files = ['.env', `.env.${mode}`];
+  // Bun deliberately skips `.env.local` under test so a personal override cannot change a suite.
+  return mode === 'test' ? files : [...files, '.env.local'];
+}
+
+function typeLabel(decl: EnvVarDecl): string {
+  return decl.type === 'enum' ? decl.values.join(' | ') : decl.type;
+}
+
+function annotation(decl: EnvVarDecl): string {
+  const parts = [decl.required === false ? 'optional' : 'required', typeLabel(decl)];
+  if (decl.secret === true) parts.push('secret');
+  if (decl.role !== undefined) {
+    parts.push(`role ${(typeof decl.role === 'string' ? [decl.role] : decl.role).join('/')}`);
+  }
+  return parts.join(' · ');
+}
+
+/**
+ * A secret never carries a value here even when the declaration has a default: this file is
+ * committed, and a placeholder that happens to work is a credential nobody rotates.
+ */
+function exampleValue(decl: EnvVarDecl): string {
+  if (decl.secret === true) return '';
+  if (decl.default !== undefined) return String(decl.default);
+  return decl.type === 'enum' ? (decl.values[0] ?? '') : '';
+}
+
+export interface EnvExampleOptions {
+  /** Extra keys the app sets outside the schema (`ROLE`, `ULTIMATE_ENV`), rendered commented. */
+  readonly extras?: readonly string[] | undefined;
+}
+
+/** 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.',
+    '# Commit this file. Never commit .env: Bun loads .env, .env.<mode> and .env.local for you.',
+  ];
+  for (const [key, decl] of Object.entries(schema)) {
+    lines.push('');
+    if (decl.description !== undefined) lines.push(`# ${decl.description}`);
+    lines.push(`# ${annotation(decl)}`);
+    lines.push(`${key}=${exampleValue(decl)}`);
+  }
+  for (const extra of options?.extras ?? []) lines.push('', `# ${extra}=`);
+  return `${lines.join('\n')}\n`;
+}
+
+/** Keys only — values in a dotenv file are Bun's to parse, and half of them are placeholders. */
+export function parseEnvKeys(text: string): readonly string[] {
+  const keys: string[] = [];
+  for (const raw of text.split('\n')) {
+    const line = raw.trim().replace(/^export\s+/, '');
+    if (line === '' || line.startsWith('#')) continue;
+    const separator = line.indexOf('=');
+    if (separator <= 0) continue;
+    const key = line.slice(0, separator).trim();
+    if (ENV_KEY_RE.test(key)) keys.push(key);
+  }
+  return keys;
+}
+
+export interface EnvExampleReport {
+  readonly ok: boolean;
+  /** Declared in the schema, absent from the file. Always a defect. */
+  readonly missing: readonly string[];
+  /** In the file, not in the schema. Reported, never fatal — apps set keys nothing declares. */
+  readonly extra: readonly string[];
+}
+
+export function checkEnvExample(schema: EnvSchema, text: string): EnvExampleReport {
+  const declared = Object.keys(schema);
+  const present = new Set(parseEnvKeys(text));
+  const missing = declared.filter((key) => !present.has(key));
+  const extra = [...present].filter((key) => !declared.includes(key));
+  return { ok: missing.length === 0, missing, extra };
+}
+
+/**
+ * Throws `X_ENV_EXAMPLE_DRIFT` when the committed example has fallen behind the schema — the
+ * failure an agent hits *before* a teammate hits `X_ENV_MISSING` on a variable nobody told them
+ * about.
+ */
+export function assertEnvExample(schema: EnvSchema, text: string, path = ENV_EXAMPLE_PATH): void {
+  const report = checkEnvExample(schema, text);
+  if (report.ok) return;
+  throw new EnvExampleDriftError({
+    cause: `${path} does not declare ${report.missing.join(', ')}, declared by defineEnv()`,
+    fix: `Bun.write('${path}', renderEnvExample(schema)) — regenerate it from the declarations`,
+    meta: { path, missing: report.missing, extra: report.extra },
+  });
+}

package/src/env.ts

@@ -3,7 +3,7 @@
 // discover six missing variables.
 
 import { EnvMissingError } from './errors';
-import { redactKeys } from './logger';
+import { REDACTED, redactKeys } from './logger';
 import { type Role, resolveRole } from './roles';
 
 export type EnvVarType = 'string' | 'url' | 'number' | 'integer' | 'port' | 'boolean' | 'enum';
@@ -231,6 +231,23 @@ export function defineEnv<const S extends EnvSchema>(schema: S, options?: EnvOpt
   return Object.freeze(report.values) as Env<S>;
 }
 
+/**
+ * The resolved values with every `secret: true` key replaced. `checkEnv().values` carries the REAL
+ * values because `defineEnv()` has to return them — so anything that PRINTS a report (`x env check
+ * --json`, a doctor line, a log field) renders this instead, and the masking lives in one place
+ * rather than at each printer.
+ */
+export function maskedEnvValues(
+  schema: EnvSchema,
+  values: Readonly<Record<string, unknown>>,
+): Readonly<Record<string, unknown>> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(values)) {
+    out[key] = schema[key]?.secret === true && value !== undefined ? REDACTED : value;
+  }
+  return Object.freeze(out);
+}
+
 export interface EnvVarSummary {
   readonly key: string;
   readonly type: EnvVarType;

package/src/environment.ts

@@ -0,0 +1,74 @@
+// Single responsibility: which named environment this process is running as. ONE concept, one
+// key (`ULTIMATE_ENV`), one spelling per value — the twin of `roles.ts`: `ROLE` says what the
+// process does, `ULTIMATE_ENV` says which deploy it belongs to.
+
+import { type CodedErrorInit, UltimateError } from './errors';
+
+export class EnvironmentInvalidError extends UltimateError {
+  static readonly code = 'X_ENVIRONMENT_INVALID';
+  override readonly name = 'EnvironmentInvalidError';
+  constructor(init: CodedErrorInit) {
+    super({ ...init, code: EnvironmentInvalidError.code });
+  }
+}
+
+/**
+ * The spellings are `NODE_ENV`'s, plus `staging`. Inventing `dev`/`prod` aliases would mean two
+ * ways to write one environment, and `NODE_ENV=production` — which every container image and
+ * platform already sets — would have to be translated at every read.
+ */
+export const ENVIRONMENTS = ['development', 'test', 'staging', 'production'] as const;
+
+export type Environment = (typeof ENVIRONMENTS)[number];
+
+export const DEFAULT_ENVIRONMENT: Environment = 'development';
+
+/** The one key. `NODE_ENV` is read only as a fallback, because platforms set it for us. */
+export const ENVIRONMENT_KEY = 'ULTIMATE_ENV';
+
+export function isEnvironment(value: unknown): value is Environment {
+  return typeof value === 'string' && (ENVIRONMENTS as readonly string[]).includes(value);
+}
+
+export interface ResolveEnvironmentOptions {
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  readonly fallback?: Environment | undefined;
+}
+
+/**
+ * `ULTIMATE_ENV`, else `NODE_ENV`, else `development`.
+ *
+ * A set-but-unknown `ULTIMATE_ENV` throws: it is the framework's key, so a typo in it is always a
+ * mistake, exactly as `resolveRole()` treats `ROLE`. A set-but-unknown `NODE_ENV` does not throw —
+ * 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;
+}
+
+/** The one production test. Anything that is not literally `production` is not production. */
+export function isProduction(options?: ResolveEnvironmentOptions): boolean {
+  return resolveEnvironment(options) === 'production';
+}
+
+/**
+ * True where a shipped development default (a signing key, a stub driver, an open CORS rule) is
+ * still acceptable. `staging` is deliberately NOT included: staging exists to fail the way
+ * production fails.
+ */
+export function isLocal(options?: ResolveEnvironmentOptions): boolean {
+  const environment = resolveEnvironment(options);
+  return environment === 'development' || environment === 'test';
+}

package/src/error-codes.ts

@@ -32,7 +32,9 @@ const CORE_CODE_TITLES = {
   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_ID_INVALID: 'value is not a valid id',
   X_IMAGE_DECODE_FAILED: 'image bytes are malformed, truncated or internally inconsistent',
@@ -40,6 +42,8 @@ const CORE_CODE_TITLES = {
   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_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_REGISTRAR_CONFLICT: 'two different registrars are loaded for one primitive kind',

package/src/index.ts

@@ -74,7 +74,28 @@ export type {
   EnvVarSummary,
   EnvVarType,
 } from './env';
-export { checkEnv, defineEnv, describeEnv } from './env';
+export { checkEnv, defineEnv, describeEnv, maskedEnvValues } from './env';
+export type { EnvExampleOptions, EnvExampleReport } from './env-example';
+export {
+  assertEnvExample,
+  checkEnvExample,
+  ENV_EXAMPLE_PATH,
+  EnvExampleDriftError,
+  envFileCandidates,
+  parseEnvKeys,
+  renderEnvExample,
+} from './env-example';
+export type { Environment, ResolveEnvironmentOptions } from './environment';
+export {
+  DEFAULT_ENVIRONMENT,
+  ENVIRONMENT_KEY,
+  ENVIRONMENTS,
+  EnvironmentInvalidError,
+  isEnvironment,
+  isLocal,
+  isProduction,
+  resolveEnvironment,
+} from './environment';
 export type {
   CoreErrorCode,
   ErrorCodeDeclaration,
@@ -210,6 +231,41 @@ export {
   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 { ModuleRegistrar, PrimitiveKind, RegisteredPrimitive } from './registrar';
 export {
   hasPrimitiveRegistrar,
@@ -222,6 +278,27 @@ 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 type { ServiceFactory } from './service';
 export { defineService, resetServices } from './service';
 export type {
@@ -248,6 +325,7 @@ export {
   noopExporter,
   parseTraceparent,
   resetTelemetry,
+  serviceResource,
   startSpan,
   traceparent,
   withSpan,

package/src/logger.ts

@@ -3,6 +3,11 @@
 
 import { type Clock, systemClock } from './clock';
 import { isUltimateError } from './errors';
+import { isSecret, REDACTED } from './secret';
+
+// Re-exported, not redefined: `secret.ts` owns the placeholder because a `Secret` has to render
+// it without importing the logger, and two constants spelled the same is one rename from a leak.
+export { REDACTED } from './secret';
 
 export const LOG_LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal', 'silent'] as const;
 
@@ -43,8 +48,6 @@ export interface LoggerOptions {
   readonly writer?: ((line: string, level: LogLevel) => void) | undefined;
 }
 
-export const REDACTED = '[redacted]';
-
 const redactedKeys = new Set<string>([
   'password',
   'token',
@@ -82,6 +85,9 @@ function defaultWriter(line: string, level: LogLevel): void {
 
 function serialiseValue(value: unknown, depth: number): unknown {
   if (value === null || typeof value !== 'object') return value;
+  // Before every other branch: a `Secret` is redacted by VALUE, so it stays redacted under a key
+  // nobody listed — `{ dsn: secret(url) }` is the leak key-name redaction cannot see.
+  if (isSecret(value)) return REDACTED;
   if (value instanceof Date) return value.toISOString();
   if (isUltimateError(value)) return value.toJSON();
   if (value instanceof Error) return { name: value.name, message: value.message };

package/src/metrics-text.ts

@@ -0,0 +1,81 @@
+// Single responsibility: render a `MetricCollection` as the Prometheus/OpenMetrics text format —
+// the payload behind `/metrics`. A serialisation, not a vendor: it is what a Kubernetes metric
+// adapter, a Grafana Agent, a Datadog agent and an OTel collector all already read (axiom 7).
+
+import type { MetricAttributes, MetricPoint, ReadableMetric } from './metrics';
+import { collectMetrics, type HistogramPoint, type MetricCollection } from './metrics';
+
+export const METRICS_PATH = '/metrics';
+
+export const METRICS_CONTENT_TYPE = 'text/plain; version=0.0.4; charset=utf-8';
+
+/** The exposition format escapes exactly these three, and nothing else. */
+function escapeLabel(value: string): string {
+  return value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\n', '\\n');
+}
+
+function labels(attributes: MetricAttributes, extra?: readonly [string, string]): string {
+  const pairs = Object.entries(attributes)
+    .sort(([a], [b]) => (a < b ? -1 : 1))
+    .map(([key, value]) => `${key}="${escapeLabel(String(value))}"`);
+  if (extra !== undefined) pairs.push(`${extra[0]}="${escapeLabel(extra[1])}"`);
+  return pairs.length === 0 ? '' : `{${pairs.join(',')}}`;
+}
+
+/** `+Inf` and `NaN` are spelled out; everything else is plain decimal. */
+function number(value: number): string {
+  if (value === Number.POSITIVE_INFINITY) return '+Inf';
+  if (value === Number.NEGATIVE_INFINITY) return '-Inf';
+  return Number.isNaN(value) ? 'NaN' : String(value);
+}
+
+function isHistogramPoint(point: MetricPoint): point is HistogramPoint {
+  return 'buckets' in point;
+}
+
+/**
+ * A histogram renders as three families — `_bucket`, `_sum`, `_count` — with CUMULATIVE bucket
+ * counts. Storing them cumulatively instead would make every record a loop over the bounds.
+ */
+function histogramLines(name: string, point: HistogramPoint): readonly string[] {
+  const lines: string[] = [];
+  let running = 0;
+  point.bounds.forEach((bound, index) => {
+    running += point.buckets[index] ?? 0;
+    lines.push(`${name}_bucket${labels(point.attributes, ['le', number(bound)])} ${running}`);
+  });
+  running += point.buckets[point.bounds.length] ?? 0;
+  lines.push(`${name}_bucket${labels(point.attributes, ['le', '+Inf'])} ${running}`);
+  lines.push(`${name}_sum${labels(point.attributes)} ${number(point.value)}`);
+  lines.push(`${name}_count${labels(point.attributes)} ${point.count}`);
+  return lines;
+}
+
+function metricLines(metric: ReadableMetric): readonly string[] {
+  const { name, kind, description, unit } = metric.descriptor;
+  const help = unit === '1' || unit === '' ? description : `${description} (${unit})`;
+  const lines = [`# HELP ${name} ${escapeLabel(help)}`, `# TYPE ${name} ${kind}`];
+  for (const point of metric.points) {
+    if (kind === 'histogram' && isHistogramPoint(point)) {
+      lines.push(...histogramLines(name, point));
+      continue;
+    }
+    lines.push(`${name}${labels(point.attributes)} ${number(point.value)}`);
+  }
+  return lines;
+}
+
+/**
+ * The scrape body. `target_info` carries the service identity as labels, which is how OTel's own
+ * Prometheus mapping does it — the alternative is stamping every series with the same two labels.
+ */
+export function metricsText(collection: MetricCollection = collectMetrics()): string {
+  const { serviceName, serviceVersion } = collection.resource;
+  const lines = [
+    '# HELP target_info the service these metrics describe',
+    '# TYPE target_info gauge',
+    `target_info{service_name="${escapeLabel(serviceName)}",service_version="${escapeLabel(serviceVersion)}"} 1`,
+    ...collection.metrics.flatMap(metricLines),
+  ];
+  return `${lines.join('\n')}\n`;
+}

package/src/runtime-metrics.ts

@@ -0,0 +1,86 @@
+// Single responsibility: the metrics EVERY Ultimate process emits, named to match what the
+// deploy chart already scales on. One place decides these names — `roles.ts` says what a role
+// scales on, this says which series carries it, and `docker/helm` reads the same three words.
+
+import type { Counter, Gauge } from './metrics';
+import { counter, gauge, type Histogram, histogram } from './metrics';
+import type { ScalingSignal } from './roles';
+
+/**
+ * The instrument behind each role's scaling signal.
+ *
+ * `rps` is a RATE, and a rate is derived, never stored: the process emits a monotonic counter and
+ * the adapter differentiates it (`rate(http_requests_total[1m])`), which is also what the chart's
+ * 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({
+  rps: 'http_requests_total',
+  'ws-connections': 'connections',
+  'queue-depth': 'queue_depth',
+  singleton: null,
+  'run-once': null,
+  'per-database': null,
+});
+
+export const requests: Counter = counter('http_requests_total', {
+  unit: '{request}',
+  description: 'HTTP requests served, by route, method and status class',
+});
+
+export const requestDuration: Histogram = histogram('http_request_duration_seconds', {
+  unit: 's',
+  description: 'HTTP server request duration',
+});
+
+export const connections: Gauge = gauge('connections', {
+  unit: '{connection}',
+  description: 'Live websocket connections held by this process',
+});
+
+export const queueDepth: Gauge = gauge('queue_depth', {
+  unit: '{job}',
+  description: 'Jobs waiting to be picked up, by queue',
+});
+
+export const jobs: Counter = counter('jobs_total', {
+  unit: '{job}',
+  description: 'Background jobs finished, by queue and outcome',
+});
+
+export interface RequestSample {
+  readonly method: string;
+  /** The route PATTERN (`/posts/:id`), never the concrete path — one series per pattern. */
+  readonly route: string;
+  readonly status: number;
+  readonly durationMs: number;
+}
+
+/**
+ * One call per served request, from the HTTP pipeline. `status` becomes a status CLASS (`2xx`)
+ * because a label per status code multiplies every series by the number of codes an app can
+ * return, and no autoscaler asks the difference between 201 and 204.
+ */
+export function recordRequest(sample: RequestSample): void {
+  const attributes = {
+    method: sample.method,
+    route: sample.route,
+    status: `${Math.floor(sample.status / 100)}xx`,
+  };
+  requests.add(1, attributes);
+  requestDuration.record(sample.durationMs / 1000, attributes);
+}
+
+/** `+1` on connect, `-1` on close, from the realtime transport. */
+export function recordConnection(delta: number): void {
+  connections.add(delta);
+}
+
+/** Absolute depth, from the worker's own queue read. */
+export function recordQueueDepth(queue: string, depth: number): void {
+  queueDepth.record(depth, { queue });
+}
+
+export function recordJob(queue: string, outcome: 'ok' | 'failed' | 'dead'): void {
+  jobs.add(1, { queue, outcome });
+}

package/src/secret.ts

@@ -0,0 +1,67 @@
+// Single responsibility: a value that cannot be printed by accident. Key-name redaction only
+// catches a secret travelling under a name someone remembered to list; a `Secret` box redacts by
+// VALUE, so the same string is safe in a log line, an error `meta`, a manifest and a snapshot.
+
+export const REDACTED = '[redacted]';
+
+/**
+ * Structural brand, not `instanceof`: two copies of `@ultimat3/core` in one dependency tree must
+ * still recognise each other's secrets, or redaction silently stops applying at the seam.
+ */
+export const SECRET_BRAND: unique symbol = Symbol.for('ultimate.secret');
+
+/** Bun and Node both honour this when rendering a value in `console.log`. */
+const INSPECT = Symbol.for('nodejs.util.inspect.custom');
+
+export interface Secret {
+  readonly [SECRET_BRAND]: true;
+  /** Non-secret name for the value — the env key, the config field. Safe to print. */
+  readonly label: string;
+  toString(): string;
+  toJSON(): string;
+}
+
+interface SecretInternal extends Secret {
+  reveal(): string;
+}
+
+const hidden = (value: unknown): PropertyDescriptor => ({
+  value,
+  enumerable: false,
+  writable: false,
+  configurable: false,
+});
+
+/**
+ * Box a value so every serialisation path renders `[redacted]`: `String()`, template literals,
+ * `+`, `JSON.stringify`, `console.log`, and the logger. `revealSecret()` is the only way out, and
+ * it is a free function on purpose — one greppable call site per place a secret is actually used.
+ *
+ * Everything except `label` is non-enumerable, so `{ ...token }`, `Object.entries(token)` and a
+ * structured-clone of it cannot carry the value back out of the box.
+ */
+export function secret(value: string, label = 'secret'): Secret {
+  const boxed = Object.defineProperties({ label } as { label: string }, {
+    [SECRET_BRAND]: hidden(true),
+    reveal: hidden(() => value),
+    toString: hidden(() => REDACTED),
+    toJSON: hidden(() => REDACTED),
+    [INSPECT]: hidden(() => REDACTED),
+    [Symbol.toPrimitive]: hidden(() => REDACTED),
+  }) as unknown as SecretInternal;
+  return Object.freeze(boxed);
+}
+
+export function isSecret(value: unknown): value is Secret {
+  return typeof value === 'object' && value !== null && SECRET_BRAND in value;
+}
+
+/** The one documented way to read a secret. Every call site is a place worth reviewing. */
+export function revealSecret(value: Secret): string {
+  return (value as SecretInternal).reveal();
+}
+
+/** Reveal only when there is something to reveal — for optional configuration. */
+export function revealOptionalSecret(value: Secret | undefined): string | undefined {
+  return value === undefined ? undefined : revealSecret(value);
+}

package/src/telemetry.ts

@@ -139,6 +139,14 @@ export function resetTelemetry(): void {
   enabled = true;
 }
 
+/**
+ * The service identity every signal carries. One resource for spans and metrics alike, as OTel
+ * defines it — a metric that named a different service than its own traces is unjoinable.
+ */
+export function serviceResource(): SpanResource {
+  return resource;
+}
+
 export function currentSpan(): Span | undefined {
   return activeSpan.getStore();
 }