@ultimat3/core 1.2.0 → 2.0.0

package/src/error-retry.ts

@@ -0,0 +1,100 @@
+// Single responsibility: is this error worth trying again? One classification per code, carried on
+// every `UltimateError` and in `--json`, so a client never has to hardcode a table of codes.
+// The cycle with ./errors is the same deliberate one ./error-codes has: nothing here touches
+// UltimateError at module-evaluation time.
+
+import { UltimateError } from './errors';
+
+/**
+ * `terminal` — the same call will fail the same way forever (a config fault, a validation error,
+ * a permission denial). `retryable` — a transient failure; back off and try again. `retry-after`
+ * — retryable, but the responder said WHEN, and the client must read `Retry-After` / the error's
+ * `meta` rather than guessing.
+ */
+export type ErrorRetry = 'terminal' | 'retryable' | 'retry-after';
+
+export const ERROR_RETRY_KINDS = ['terminal', 'retryable', 'retry-after'] as const;
+
+/**
+ * Fail closed. An unclassified code is a code nobody thought about, and a client that retries one
+ * during an incident triples the load on a service that is already broken — `X_TENANCY_UNSCOPED`
+ * and `X_DB_DRIFT` are 500s and permanent config faults, so `status >= 500` was never the answer.
+ */
+export const DEFAULT_ERROR_RETRY: ErrorRetry = 'terminal';
+
+/**
+ * Core's own codes, and closed: an app that could reclassify `X_DRAINING` as terminal would be an
+ * app whose clients stop retrying a rolling restart, which is the one case retrying always wins.
+ * Only the exceptions are listed — everything else is `terminal` by the default above.
+ */
+const CORE_ERROR_RETRY: Readonly<Record<string, ErrorRetry>> = Object.freeze({
+  X_DRAINING: 'retryable',
+  // A deadline that expired is the canonical back-off-and-try-again case: nothing about the
+  // request was wrong, the budget ran out. Deliberately NOT `retry-after` — that spelling means
+  // the responder named a time, and a timeout by definition produced no such answer. Its twin
+  // `X_ABORTED` (the caller went away) is left to the `terminal` DEFAULT rather than listed here:
+  // the answer is the same, and listing it would close a door nobody has asked to open.
+  X_TIMEOUT: 'retryable',
+});
+
+const REGISTERED = new Map<string, ErrorRetry>();
+
+export function isErrorRetry(value: unknown): value is ErrorRetry {
+  return typeof value === 'string' && (ERROR_RETRY_KINDS as readonly string[]).includes(value);
+}
+
+function retryInvalid(code: string, cause: string): UltimateError {
+  return new UltimateError({
+    code: 'X_ERROR_RETRY_INVALID',
+    cause: `${code}: ${cause}`,
+    fix: `x errors list --json   # then registerErrorRetry({ ${code}: 'retryable' }) with one of ${ERROR_RETRY_KINDS.join(' | ')}`,
+    meta: { code },
+  });
+}
+
+/**
+ * Declare how the codes this package or app throws should be retried. Call it once at boot beside
+ * the module that declares the codes — importing that module IS the registration, the convention
+ * `registerErrorCodes` and `registerErrorStatus` already use.
+ *
+ * ```ts
+ * registerErrorRetry({ X_OAUTH_EXCHANGE_FAILED: 'retryable', X_RATE_LIMITED: 'retry-after' });
+ * ```
+ *
+ * Re-registering the same value is fine — a module imported twice is not a bug. Registering a
+ * DIFFERENT value throws, so two packages can never disagree about whether a code is safe to
+ * hammer, and core's own codes cannot be moved at all.
+ */
+export function registerErrorRetry(retries: Readonly<Record<string, ErrorRetry>>): void {
+  for (const [code, retry] of Object.entries(retries)) {
+    if (!isErrorRetry(retry)) {
+      throw retryInvalid(code, `"${String(retry)}" is not ${ERROR_RETRY_KINDS.join(' | ')}`);
+    }
+    const core = CORE_ERROR_RETRY[code];
+    if (core !== undefined) {
+      throw retryInvalid(code, `the framework already classifies it as ${core}`);
+    }
+    const existing = REGISTERED.get(code);
+    if (existing !== undefined && existing !== retry) {
+      throw retryInvalid(code, `already registered as ${existing}`);
+    }
+    REGISTERED.set(code, retry);
+  }
+}
+
+/** Test seam. Production registers once at boot and never unregisters. */
+export function resetErrorRetry(): void {
+  REGISTERED.clear();
+}
+
+// Core table first: `registerErrorRetry` already refuses those codes, so the order is
+// belt-and-braces — but it is the belt that keeps "core's classifications are fixed" true even if
+// a future caller reaches the map some other way.
+export function retryFor(code: string): ErrorRetry {
+  return CORE_ERROR_RETRY[code] ?? REGISTERED.get(code) ?? DEFAULT_ERROR_RETRY;
+}
+
+/** Every classification a package or app declared, for `x errors list` and the manifest. */
+export function registeredErrorRetry(): Readonly<Record<string, ErrorRetry>> {
+  return Object.fromEntries([...REGISTERED].sort(([a], [b]) => a.localeCompare(b)));
+}

package/src/errors.ts

@@ -3,6 +3,8 @@
 // overlay and `--json`. Never throw a bare Error anywhere in the framework.
 
 import { describeErrorCode } from './error-codes';
+import { isThrownError, renderCauseValue, renderMetaRecord, renderThrowable } from './error-render';
+import { DEFAULT_ERROR_RETRY, type ErrorRetry, isErrorRetry, retryFor } from './error-retry';
 
 /**
  * Structural brand. `instanceof` is unreliable across duplicated module instances and across
@@ -20,6 +22,12 @@ export interface UltimateErrorInit {
   readonly fix: string;
   readonly docs?: string | undefined;
   readonly meta?: Readonly<Record<string, unknown>> | undefined;
+  /**
+   * Overrides the code's registered classification for this one throw — the same code can be
+   * transient at one call site and permanent at another. Defaults to `retryFor(code)`, which
+   * defaults to `terminal`.
+   */
+  readonly retry?: ErrorRetry | undefined;
   /** The underlying thrown value, when this error wraps one. */
   readonly sourceError?: unknown;
 }
@@ -30,6 +38,8 @@ export interface UltimateErrorJSON {
   readonly cause: string;
   readonly fix: string;
   readonly docs: string;
+  /** Whether a client may try again. Always present — a client never has to infer it. */
+  readonly retry: ErrorRetry;
   readonly meta?: Readonly<Record<string, unknown>> | undefined;
   readonly stack?: string | undefined;
 }
@@ -48,6 +58,7 @@ export class UltimateError extends Error {
   declare readonly cause: string;
   readonly fix: string;
   readonly docs: string;
+  readonly retry: ErrorRetry;
   readonly meta: Readonly<Record<string, unknown>> | undefined;
   readonly sourceError: unknown;
 
@@ -63,6 +74,7 @@ export class UltimateError extends Error {
     this.title = described.title;
     this.fix = init.fix;
     this.docs = init.docs ?? described.docs;
+    this.retry = init.retry ?? retryFor(init.code);
     this.meta = init.meta;
     this.sourceError = init.sourceError;
   }
@@ -82,6 +94,13 @@ export class UltimateError extends Error {
     return lines.join('\n');
   }
 
+  /**
+   * `meta` is the only field here the framework does not build itself — `parseId` puts the value
+   * it rejected straight in — so it goes through `renderMetaRecord`, which returns a record that
+   * serialises unchanged and degrades only the keys that would have thrown. `--json` on every
+   * error is a promise this method keeps; a `meta` that throws breaks it one layer past the
+   * constructor.
+   */
   toJSON(): UltimateErrorJSON {
     return {
       code: this.code,
@@ -89,14 +108,22 @@ export class UltimateError extends Error {
       cause: this.cause,
       fix: this.fix,
       docs: this.docs,
-      meta: this.meta,
+      retry: this.retry,
+      meta: renderMetaRecord(this.meta),
       stack: this.stack,
     };
   }
 }
 
 export function isUltimateError(value: unknown): value is UltimateError {
-  return typeof value === 'object' && value !== null && ULTIMATE_ERROR_BRAND in value;
+  // TOTAL, like `isThrownError`: `in` runs a `Proxy`'s `has` trap, and every caller asks this
+  // question inside a `catch` block that has nothing left to answer with if the probe itself
+  // throws. `false` is the honest answer for a value that refuses to be examined.
+  try {
+    return typeof value === 'object' && value !== null && ULTIMATE_ERROR_BRAND in value;
+  } catch {
+    return false;
+  }
 }
 
 /** Init for a subclass that owns its code. */
@@ -139,13 +166,21 @@ export function notImplemented(feature: string, fix: string): never {
   throw new NotImplementedError({ cause: `${feature} is not implemented by this driver`, fix });
 }
 
-/** Normalise anything caught into an `UltimateError` without losing the original. */
+/**
+ * Normalise anything caught into an `UltimateError` without losing the original.
+ *
+ * `renderCauseValue`, not `String(value)`: this is the framework's universal normaliser — the CLI's
+ * every catch, `formatError`, the HTTP 500 path — and `String()` runs the value's own `toString`,
+ * so a thrown object could make the wrapper throw and take both errors with it.
+ */
 export function toUltimateError(value: unknown, fix?: string): UltimateError {
   if (isUltimateError(value)) return value;
-  const cause =
-    value instanceof Error
-      ? `${value.name}: ${value.message}`
-      : `non-error value thrown: ${String(value)}`;
+  // `isThrownError` / `renderThrowable`, not `instanceof` and `.message` directly: a `Proxy` traps
+  // `getPrototypeOf` and a subclass can put a getter on `message`, so both reads throw where this
+  // function is the last thing standing between a caught value and a surface that must answer.
+  const cause = isThrownError(value)
+    ? renderThrowable(value)
+    : `non-error value thrown: ${renderCauseValue(value)}`;
   return new InternalError({
     cause,
     fix: fix ?? 'fix the underlying failure named in cause, then re-run',
@@ -153,6 +188,19 @@ export function toUltimateError(value: unknown, fix?: string): UltimateError {
   });
 }
 
+/**
+ * May a client try this again? The one question a retry loop asks, answered from the error rather
+ * than from a status code — `X_DB_DRIFT` and `X_TENANCY_UNSCOPED` are both 500s and neither is
+ * worth a second attempt. A value that is not an Ultimate error is `terminal`: fail closed.
+ */
+export function errorRetry(value: unknown): ErrorRetry {
+  if (!isUltimateError(value)) return DEFAULT_ERROR_RETRY;
+  // Read defensively: the brand is duck-typed across duplicated module instances, so a value from
+  // an older copy of this package can satisfy the guard without carrying the field.
+  const retry: unknown = value.retry;
+  return isErrorRetry(retry) ? retry : DEFAULT_ERROR_RETRY;
+}
+
 /** Render any caught value with the 3-line contract, so CLI output never varies. */
 export function formatError(value: unknown, options?: FormatErrorOptions): string {
   return toUltimateError(value).format(options);

package/src/exports/error-contract.ts

@@ -0,0 +1,61 @@
+// The error-contract slice of `@ultimat3/core`'s public surface: `UltimateError` and its shipped
+// subclasses, the code registry every package registers into, the safe renderers a message is
+// 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,
+  ErrorCodeDeclaration,
+  ErrorCodeDescriptor,
+  ErrorCodeEntry,
+} from '../error-codes';
+export {
+  CORE_ERROR_CODES,
+  describeErrorCode,
+  ERROR_DOCS_BASE,
+  errorCodeSnapshot,
+  errorDocsUrl,
+  hasErrorCode,
+  listErrorCodes,
+  registerErrorCodes,
+  resetErrorCodes,
+} from '../error-codes';
+export {
+  describeValue,
+  isThrownError,
+  MAX_RENDERED_LENGTH,
+  renderCauseValue,
+  renderFixLiteral,
+  renderThrowable,
+  stringField,
+} from '../error-render';
+export type { ErrorRetry } from '../error-retry';
+export {
+  DEFAULT_ERROR_RETRY,
+  ERROR_RETRY_KINDS,
+  isErrorRetry,
+  registerErrorRetry,
+  registeredErrorRetry,
+  resetErrorRetry,
+  retryFor,
+} from '../error-retry';
+export type {
+  CodedErrorInit,
+  FormatErrorOptions,
+  UltimateErrorInit,
+  UltimateErrorJSON,
+} from '../errors';
+export {
+  ConfigInvalidError,
+  EnvMissingError,
+  errorRetry,
+  formatError,
+  InternalError,
+  isUltimateError,
+  NotImplementedError,
+  notImplemented,
+  toUltimateError,
+  ULTIMATE_ERROR_BRAND,
+  UltimateError,
+} from '../errors';
+export { SCHEMA_ERROR_CODE_TITLES } from '../schema-error-codes';

package/src/exports/observability.ts

@@ -0,0 +1,161 @@
+// The observability slice of `@ultimat3/core`'s public surface, in one place: logging, metrics,
+// tracing, sampling, the OTLP transports and error reporting. One group because they are one
+// subject — a process's own account of what it did — and `index.ts` re-exports every name below
+// explicitly, so this file changes what a reader looks at and never what the package exports.
+
+export type {
+  ErrorReport,
+  ErrorReporter,
+  ErrorReportingOptions,
+  ErrorScope,
+  ErrorSeverity,
+  ErrorSource,
+  MemoryErrorReporter,
+  ReportErrorOptions,
+} from '../error-reporter';
+export {
+  configureErrorReporting,
+  ERROR_SOURCES,
+  errorReport,
+  memoryErrorReporter,
+  noopErrorReporter,
+  reportError,
+  resetErrorReporting,
+} from '../error-reporter';
+export type {
+  SentryDsn,
+  SentryEnvelopeOptions,
+  SentryReporterOptions,
+} from '../error-reporter-sentry';
+export {
+  ErrorReporterDsnInvalidError,
+  parseSentryDsn,
+  sentryEnvelope,
+  sentryErrorReporter,
+} from '../error-reporter-sentry';
+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,
+  DEFAULT_MAX_SERIES,
+  exportMetrics,
+  gauge,
+  histogram,
+  MetricCardinalityError,
+  MetricNameInvalidError,
+  MetricValueInvalidError,
+  memoryMetricExporter,
+  noopMetricExporter,
+  OVERFLOW_ATTRIBUTE,
+  resetMetrics,
+  startMetricExport,
+} from '../metrics';
+export { METRICS_CONTENT_TYPE, METRICS_PATH, metricsText } from '../metrics-text';
+export type { OtlpAnyValue, OtlpKeyValue, OtlpSignal } from '../otlp';
+export {
+  OTLP_ENDPOINT_KEY,
+  OTLP_HEADERS_KEY,
+  OTLP_PROTOCOL_KEY,
+  OTLP_SCOPE,
+  OtlpEndpointInvalidError,
+  OtlpProtocolUnsupportedError,
+  otlpAttributes,
+  otlpEndpoint,
+  otlpHeaders,
+  otlpResource,
+  tryOtlpEndpoint,
+  unixNano,
+} from '../otlp';
+export type { OtlpMetricExporter, OtlpMetricExporterOptions } from '../otlp-metric-exporter';
+export { otlpMetricExporter, otlpMetricsRequest } from '../otlp-metric-exporter';
+export type { OtlpSpanExporter, OtlpSpanExporterOptions } from '../otlp-span-exporter';
+export { otlpSpanExporter, otlpTraceRequest } from '../otlp-span-exporter';
+export type { RequestSample } from '../runtime-metrics';
+export {
+  connections,
+  jobs,
+  leasesLost,
+  queueDepth,
+  recordConnection,
+  recordJob,
+  recordLeaseLost,
+  recordQueueDepth,
+  recordRequest,
+  requestDuration,
+  requests,
+  SCALING_METRICS,
+} from '../runtime-metrics';
+export type { Sampler } from '../sampler';
+export {
+  alwaysOffSampler,
+  alwaysOnSampler,
+  DEFAULT_SAMPLE_RATIO,
+  defaultSampler,
+  OTEL_SAMPLER_ARG_KEY,
+  OTEL_SAMPLER_KEY,
+  parentBasedRatioSampler,
+  ratioSampler,
+  resetDefaultSampler,
+  samplerFromEnv,
+} from '../sampler';
+export type {
+  AttributeValue,
+  MemoryExporter,
+  ReadableSpan,
+  Span,
+  SpanAttributes,
+  SpanContext,
+  SpanEvent,
+  SpanExporter,
+  SpanKind,
+  SpanResource,
+  SpanStatus,
+  SpanStatusCode,
+  StartSpanOptions,
+  TelemetryOptions,
+} from '../telemetry';
+export {
+  configureTelemetry,
+  currentSampler,
+  currentSpan,
+  currentSpanContext,
+  memoryExporter,
+  noopExporter,
+  parseTraceparent,
+  resetTelemetry,
+  serviceResource,
+  startSpan,
+  traceparent,
+  withSpan,
+  withSpanContext,
+} from '../telemetry';

package/src/exports/secrets.ts

@@ -0,0 +1,71 @@
+// The secrets slice of `@ultimat3/core`'s public surface: the redacted-by-value `Secret`, the
+// committed envelope, the files and install path around it, and the codes it throws. One group
+// because they are one path — a committed ciphertext to a value `defineEnv` can read — and
+// `index.ts` re-exports every name below explicitly, so the package's surface is unchanged.
+
+export type { Secret } from '../secret';
+export {
+  isSecret,
+  revealOptionalSecret,
+  revealSecret,
+  SECRET_BRAND,
+  secret,
+} from '../secret';
+export type {
+  SecretSummary,
+  SecretsEnvelope,
+  SecretsLocation,
+  SecretValues,
+} from '../secrets';
+export {
+  assertSecretValues,
+  describeSecrets,
+  generateMasterKey,
+  masterKeyId,
+  openSecrets,
+  parseMasterKey,
+  parseSecretsEnvelope,
+  SECRET_NAME,
+  SECRETS_ALG,
+  SECRETS_IV_BYTES,
+  SECRETS_KEY_BYTES,
+  SECRETS_KEY_HEX_LENGTH,
+  SECRETS_KEY_ID_LENGTH,
+  SECRETS_TAG_BYTES,
+  SECRETS_VERSION,
+  sealSecrets,
+  serializeSecretValues,
+} from '../secrets';
+export type { SecretsErrorCode } from '../secrets-errors';
+export {
+  SECRETS_ERROR_CODES,
+  SecretsFileInvalidError,
+  SecretsFileMissingError,
+  SecretsKeyInvalidError,
+  SecretsKeyMismatchError,
+  SecretsKeyMissingError,
+  SecretsPlaintextInvalidError,
+  SecretsTamperedError,
+} from '../secrets-errors';
+export type {
+  MasterKeyRef,
+  MasterKeySource,
+  SecretsInstallOptions,
+  SecretsInstallReport,
+} from '../secrets-store';
+export {
+  findMasterKey,
+  installSecrets,
+  masterKeyIdOf,
+  masterKeyPath,
+  readSecretsFile,
+  requireMasterKey,
+  SECRETS_FILE,
+  SECRETS_KEY_ENV,
+  SECRETS_KEY_FILE,
+  SECRETS_KEY_MODE,
+  secretsFileExists,
+  secretsPath,
+  writeMasterKeyFile,
+  writeSecretsFile,
+} from '../secrets-store';

package/src/ids.ts

@@ -2,6 +2,7 @@
 // database indexes, cursors and log sorting all want time-ordered keys.
 
 import { type Clock, systemClock } from './clock';
+import { describeValue } from './error-render';
 import { UltimateError } from './errors';
 
 /** Nominal typing without a runtime cost. `Brand<string, 'post'>` never mixes with `'user'`. */
@@ -28,6 +29,16 @@ function randomBytes(length: number): Uint8Array {
   return bytes;
 }
 
+/**
+ * A full 10 bits, from both bytes. Reading `bytes[0]` alone masked an 8-bit value with a 10-bit
+ * mask, so the seed only ever reached 255 while `COUNTER_SEED_MASK` declared 1023 — the constant
+ * and the code disagreed, and the second byte was allocated on every `uuid()` for nothing.
+ */
+function seedCounter(): number {
+  const bytes = randomBytes(2);
+  return (((bytes[0] ?? 0) << 8) | (bytes[1] ?? 0)) & COUNTER_SEED_MASK;
+}
+
 export function randomHex(byteLength: number): string {
   const bytes = randomBytes(byteLength);
   let out = '';
@@ -51,10 +62,10 @@ export function uuid(clock: Clock = systemClock): string {
     counter += 1;
     if (counter > COUNTER_MAX) {
       epochMs += 1;
-      counter = randomBytes(2)[0]! & COUNTER_SEED_MASK;
+      counter = seedCounter();
     }
   } else {
-    counter = randomBytes(2)[0]! & COUNTER_SEED_MASK;
+    counter = seedCounter();
   }
   lastEpochMs = epochMs;
 
@@ -62,7 +73,9 @@ export function uuid(clock: Clock = systemClock): string {
   const randA = counter.toString(16).padStart(3, '0');
   const tail = randomHex(8);
   // Force the RFC variant bits (0b10) into the first nibble of `rand_b`.
-  const variantNibble = HEX[(Number.parseInt(tail[0]!, 16) & 0x3) | 0x8]!;
+  // charAt, not [], because the index is provably 0x8–0xb: a non-null assertion here would be
+  // unenforceable style debt in the one file that made `noNonNullAssertion` unraisable.
+  const variantNibble = HEX.charAt((Number.parseInt(tail.charAt(0), 16) & 0x3) | 0x8);
 
   return [
     timeHex.slice(0, 8),
@@ -77,14 +90,20 @@ export function isUuid(value: unknown): boolean {
   return typeof value === 'string' && UUID_RE.test(value);
 }
 
+/** The actionable half of an id rejection: what was wanted. Carries no caller data, ever. */
+const UUID_SHAPE = '8-4-4-4-12 lowercase hex, version 7';
+
 /** Recover the generation instant from a v7 id — cheap debugging and cursor windows. */
 export function uuidTimestamp(id: string): Date {
   if (!isUuid(id)) {
     throw new UltimateError({
       code: 'X_ID_INVALID',
-      cause: `"${id}" is not a UUIDv7`,
+      // `describeValue`, never the id itself: this `cause` reaches the log index and the HTTP
+      // problem document, and the strings that arrive here wrong are session tokens and API keys
+      // as often as they are typos. The expected shape is the half that helps the reader.
+      cause: `expected a UUIDv7 (${UUID_SHAPE}), received ${describeValue(id)}`,
       fix: 'generate ids with uuid() from @ultimat3/core',
-      meta: { id },
+      meta: { received: describeValue(id) },
     });
   }
   return new Date(Number.parseInt(id.slice(0, 8) + id.slice(9, 13), 16));
@@ -108,9 +127,11 @@ export function parseId<K extends string>(kind: K, value: unknown): Id<K> {
   if (!isUuid(value)) {
     throw new UltimateError({
       code: 'X_ID_INVALID',
-      cause: `expected a ${kind} UUIDv7, received ${JSON.stringify(value)}`,
+      cause: `expected a ${kind} UUIDv7 (${UUID_SHAPE}), received ${describeValue(value)}`,
       fix: `pass an id produced by typedId<'${kind}'>()`,
-      meta: { kind, value },
+      // `received`, not `value`: `meta` rides into the problem document and the log line too, and
+      // redaction is by key — there is no key here that a redaction list could ever cover.
+      meta: { kind, received: describeValue(value) },
     });
   }
   return value as Id<K>;
@@ -125,6 +146,27 @@ export function spanId(): string {
   return randomHex(8);
 }
 
+const TRACE_ID_RE = /^[0-9a-f]{32}$/;
+const SPAN_ID_RE = /^[0-9a-f]{16}$/;
+const ALL_ZERO = /^0+$/;
+
+/**
+ * The ONE definition of "is this a W3C trace id" — `traceparent` parsing, and any layer that
+ * accepts an id from outside, ask here rather than carrying a second regex.
+ *
+ * A dashed UUID is the failure this predicate exists to name: `uuid()` produces 36 characters with
+ * hyphens, every OTLP collector rejects it, and nothing downstream said so — the trace simply
+ * never appeared. Mint trace ids with `traceId()`, never `uuid()`. All-zero is invalid per the
+ * spec: it is the wire's spelling of "no trace", not a trace whose id happens to be zero.
+ */
+export function isTraceId(value: unknown): boolean {
+  return typeof value === 'string' && TRACE_ID_RE.test(value) && !ALL_ZERO.test(value);
+}
+
+export function isSpanId(value: unknown): boolean {
+  return typeof value === 'string' && SPAN_ID_RE.test(value) && !ALL_ZERO.test(value);
+}
+
 /** Test-only: reset the monotonic counter so a frozen clock produces a fresh sequence. */
 export function resetIdCounter(): void {
   lastEpochMs = -1;