@ultimat3/core 29.4.0 → 30.0.0

package/src/index.ts

@@ -46,7 +46,12 @@ export {
   withFacts,
 } from './actor';
 export type { AddressClass } from './address-class';
-export { addressNetwork, classifyAddress, isPublicAddress } from './address-class';
+export {
+  addressNetwork,
+  classifyAddress,
+  isPublicAddress,
+  peerAddressClass,
+} from './address-class';
 /** Test support: the one name a live suite gives the database it creates (`probe-databases`). */
 export { APP_CONFIG_FILE, APP_STATE_DIR, appDirOf, appStatePath } from './app-dir';
 export { APP_VERSION_KEY, appVersion, DEFAULT_APP_VERSION } from './app-version';
@@ -72,19 +77,34 @@ export {
 export type {
   AwsCredentials,
   AwsPayload,
+  PresignAwsUrlInput,
+  PresignedAwsUrl,
   SignAwsRequestInput,
   SignedAwsRequest,
 } from './aws-sigv4';
-export { signAwsRequest, UNSIGNED_PAYLOAD } from './aws-sigv4';
+export {
+  MAX_AWS_PRESIGN_SECONDS,
+  presignAwsUrl,
+  signAwsRequest,
+  UNSIGNED_PAYLOAD,
+} from './aws-sigv4';
 export type { BackoffCurve, BackoffOptions, JitterMode, Random } from './backoff';
 export { backoffDelay, jitterStatedDelay } from './backoff';
+export type {
+  Breaker,
+  BreakerOptions,
+  BreakerState,
+  BreakerTicket,
+  BreakerVerdict,
+} from './breaker';
+export { breaker, settleWith } from './breaker';
 export { isCompiledBundle } from './bunfs';
 export type { CacheEvictionOptions } from './cache-eviction';
 export { CACHE_TEMP_GRACE_MS, evictCacheFiles } from './cache-eviction';
 export { CACHE_TIERS, type CacheTierName } from './cache-vocabulary';
 export { canonicalJson, fingerprint } from './canonical-json';
 export type { FetchLike, TransportRequest } from './client-dispatch';
-export { BUILD_ID_HEADER, IDEMPOTENCY_HEADER } from './client-dispatch';
+export { BUILD_ID_HEADER, IDEMPOTENCY_HEADER, REPLAYED_HEADER } from './client-dispatch';
 /**
  * Flight control for a typed client, and OPT-IN by construction: `@ultimat3/action`'s and
  * `@ultimat3/query`'s `client.ts` each name `ClientFlight` as a TYPE only, so a caller that never
@@ -110,8 +130,19 @@ export {
   queryPath,
   splitWords,
 } from './client-paths';
+export type { ActionPin, ClientPins, PinnedActionMethod } from './client-paths-pins';
+export {
+  encodeClientPins,
+  renderedActionPin,
+  renderedQueryPin,
+} from './client-paths-pins';
 export type { TransportFailure } from './client-problem';
-export { MAX_REMOTE_TITLE_LENGTH, remoteTitleOf, withStatedDelay } from './client-problem';
+export {
+  MAX_REMOTE_TITLE_LENGTH,
+  remoteTitleOf,
+  withRequestId,
+  withStatedDelay,
+} from './client-problem';
 /** What a decoder reads off a refusal: the stated `Retry-After`, and the body's display title. */
 export { MAX_RETRY_AFTER_SECONDS, retryAfterSecondsOf } from './client-retry-after';
 /**
@@ -120,6 +151,8 @@ export { MAX_RETRY_AFTER_SECONDS, retryAfterSecondsOf } from './client-retry-aft
  */
 export type { ClientScope } from './client-scope';
 export { onRescope, rescope } from './client-scope';
+export type { StreamRequest } from './client-stream';
+export { clientStream } from './client-stream';
 export { clientTransport } from './client-transport';
 /** What a typed client puts on the wire. `retryForStatus` is what fills a failure's `retry`. */
 export type { WireAnswer } from './client-wire';
@@ -143,6 +176,30 @@ export type {
 } from './config';
 export { defineConfig, INBOX_RETENTION_KEYS } from './config';
 export type { AiConfig, AiConfigInput, McpConfig } from './config-ai';
+export type {
+  AssetsConfig,
+  AssetsRetainConfig,
+  AssetsSection,
+  AssetsSectionInput,
+} from './config-assets';
+export type {
+  ClientErrorsConfig,
+  ClientErrorsSection,
+  ClientErrorsSectionInput,
+  ClientVitalsConfig,
+  ClientVitalsSurface,
+} from './config-client-errors';
+export {
+  CLIENT_ERRORS_DEFAULTS,
+  CLIENT_VITALS_DEFAULTS,
+  CLIENT_VITALS_SURFACES,
+} from './config-client-errors';
+export type {
+  FailureCaptureConfig,
+  FailureCaptureSection,
+  FailureCaptureSectionInput,
+} from './config-failure-capture';
+export { FAILURE_CAPTURE_DEFAULTS } from './config-failure-capture';
 export type { DrainConfig, HealthConfig, ReadinessMode } from './config-health';
 export { READINESS_MODES } from './config-health';
 export type { IslandsConfig, IslandsSection, IslandsSectionInput } from './config-islands';
@@ -210,12 +267,24 @@ export {
   sectionPatterns,
   sitemapSectionIssues,
 } from './config-sitemap';
+export type { AppTimeConfig, TimeSection, TimeSectionInput } from './config-time';
+export { TIME_DEFAULTS } from './config-time';
 export type { ConflictPolicy, ResolveConflictOptions, Row } from './conflict-policy';
 export { resolveConflict } from './conflict-policy';
-export type { Ctx, CtxFacts, CtxInit, CtxPatch, CtxServices, ServiceBag } from './context';
+export type {
+  CompletionBound,
+  Ctx,
+  CtxFacts,
+  CtxInit,
+  CtxPatch,
+  CtxServices,
+  ServiceBag,
+} from './context';
 export {
+  abandonment,
   ctxOf,
   hasContext,
+  runToCompletion,
   runWithContext,
   throwIfAborted,
   tryUseContext,
@@ -242,9 +311,30 @@ export {
 export type { Page } from './cursor-page';
 export { pageOf } from './cursor-page';
 export { compareDecimalText } from './decimal-order';
+// `errors:` on an action and a query: the rule both share, since the two packages are one tier.
+export type { DeclaredErrorsOwner, DeclaredErrorVerdict, ErrorStatusOf } from './declared-errors';
+export {
+  ActionErrorsInvalidError,
+  checkDeclaredErrors,
+  describeDeclaredErrors,
+  ErrorUndeclaredError,
+  enforceDeclared,
+  judgeThrown,
+  LIFETIME_ERROR_CODES,
+  withDeclaredErrors,
+} from './declared-errors';
+export type { DeclaredResponsesWire } from './declared-errors-openapi';
+export { DECLARED_ERRORS_EXTENSION, withDeclaredResponses } from './declared-errors-openapi';
+export type { SourceReader } from './declared-errors-scan';
+export { definedErrorClassCodes, scanHandlerSource } from './declared-errors-scan';
 export { DEFAULT_LOCALE, DEFAULT_TIME_ZONE } from './default-locale';
 export type { Deprecation, DeprecationField, DeprecationRender } from './deprecation';
-export { recordDeprecatedCall, renderDeprecation } from './deprecation';
+export {
+  recordDeprecatedCall,
+  renderDeprecation,
+  successorLink,
+  successorPathOf,
+} from './deprecation';
 export type { DevSecretsOptions } from './dev-secrets';
 export {
   assertNoDevSecretsOutsideLocal,
@@ -255,6 +345,7 @@ export {
   DRAIN_DEADLINE_DEFAULT_MS,
   DRAIN_DEADLINE_MAX_MS,
   WORKER_DRAIN_DEADLINE_MAX_MS,
+  WORKER_RETIRE_DEFAULT_MS,
 } from './drain-deadline';
 export type {
   Env,
@@ -291,14 +382,37 @@ export {
   resolveEnvironment,
   tryResolveEnvironment,
 } from './environment';
+export { ExerciseEnvironmentError, ExerciseUnscopedError } from './exercise-errors';
+// A contract exercise's one loop: `@ultimat3/action`'s and `@ultimat3/query`'s, one tier apart from neither.
+export type {
+  DrawnInput,
+  ExerciseAttempt,
+  ExerciseReport,
+  ExerciseSubject,
+  ExerciseVerdict,
+} from './exercise-run';
+export {
+  assertExerciseScoped,
+  bindDrawn,
+  EXERCISE_RUNS,
+  EXERCISE_RUNS_MAX,
+  exerciseDefect,
+  exerciseReplay,
+  runExercise,
+  sealedHost,
+} from './exercise-run';
 export type {
   CodedErrorInit,
   CoreErrorCode,
+  DefinedError,
+  DefinedErrorExtra,
+  DefineErrorSpec,
   ErrorAudience,
   ErrorCodeDeclaration,
   ErrorCodeDescriptor,
   ErrorCodeEntry,
   ErrorRetry,
+  ErrorText,
   FormatErrorOptions,
   UltimateErrorInit,
   UltimateErrorJSON,
@@ -309,6 +423,7 @@ export {
   classifyThrown,
   DEFAULT_ERROR_RETRY,
   declaredErrorRetry,
+  defineError,
   deniedCallerFix,
   describeErrorCode,
   describeValue,
@@ -349,6 +464,7 @@ export {
 } from './exports/error-contract';
 export type {
   AttributeValue,
+  CapturedValue,
   Counter,
   ErrorReport,
   ErrorReporter,
@@ -356,8 +472,16 @@ export type {
   ErrorScope,
   ErrorSeverity,
   ErrorSource,
+  FailureActor,
+  FailureBundle,
+  FailureCaptureLimits,
+  FailureFact,
+  FailurePrimitive,
+  FailureRead,
+  FailureStore,
   Gauge,
   GaugeOptions,
+  HeldFailure,
   Histogram,
   HistogramOptions,
   HistogramPoint,
@@ -407,6 +531,8 @@ export type {
 export {
   alwaysOffSampler,
   alwaysOnSampler,
+  captureValue,
+  chainErrorReporters,
   collectMetrics,
   configureErrorReporting,
   configureMetrics,
@@ -422,10 +548,16 @@ export {
   defaultSampler,
   ERROR_SOURCES,
   ErrorReporterDsnInvalidError,
+  errorFingerprint,
   errorReport,
+  errorReportersOf,
   exportMetrics,
+  failureCaptureActive,
+  failureCaptureLimits,
   gauge,
   histogram,
+  installedErrorReporter,
+  installedFailureStore,
   isRedactedKey,
   jobs,
   LOG_LEVELS,
@@ -443,6 +575,7 @@ export {
   noopErrorReporter,
   noopExporter,
   noopMetricExporter,
+  OTLP_RETRY_STATUSES,
   OtlpEndpointInvalidError,
   OtlpHeadersInvalidError,
   OtlpProtocolUnsupportedError,
@@ -459,6 +592,8 @@ export {
   REDACTED,
   ratioSampler,
   recordConnection,
+  recordFailureFact,
+  recordFailureInput,
   recordJob,
   recordLeaseLost,
   recordQueueDepth,
@@ -468,6 +603,7 @@ export {
   requestDuration,
   requests,
   resetErrorReporting,
+  resetFailureCaptureWindows,
   resetMetrics,
   resetTelemetry,
   SCALING_METRICS,
@@ -475,13 +611,16 @@ export {
   sentryEnvelope,
   sentryErrorReporter,
   serviceResource,
+  setFailureStore,
   setLoggerContextFields,
   setLogStream,
+  settleFailureCaptures,
   startMetricExport,
   startSpan,
   structuredLogger,
   traceparent,
   tryOtlpEndpoint,
+  withFailureCapture,
   withSpan,
   withSpanContext,
 } from './exports/observability';
@@ -537,7 +676,9 @@ export {
   writeMasterKeyFile,
   writeSecretsFile,
 } from './exports/secrets';
-export { finiteCount, finiteOption } from './finite-option';
+export type { FilledWire } from './fill-wire';
+export { fillWire } from './fill-wire';
+export { finiteCount, finiteOption, MAX_TIMER_MS } from './finite-option';
 export type {
   FlightGate,
   FlightGateLimits,
@@ -551,6 +692,9 @@ export type { GenerationFence } from './generation-fence';
 export { generationFence, isSuperseded } from './generation-fence';
 export type { PublicHealthBody } from './health-disclosure';
 export { DEFAULT_HEALTH_DETAIL_PEERS, healthBody, healthPeerListed } from './health-disclosure';
+// The ONE keyed hash: every HMAC in the framework (`bun run keyed-hasher`).
+export type { HmacAlgorithm, HmacEncoding, HmacInput } from './hmac';
+export { hmac } from './hmac';
 export type { HostDecision, HostRule } from './host-rules';
 export { ANY_HOST, hostDecision, hostMatches } from './host-rules';
 export { escapeHtml } from './html-escape';
@@ -617,6 +761,7 @@ export {
 } from './intl-cache';
 export { isIsoDateTime } from './iso-date';
 export { isJsonObject } from './json-object';
+export { jsonbRefusal } from './json-storable';
 export type { FingerprintMatch } from './keyed-fingerprint';
 export {
   compareFingerprint,
@@ -712,6 +857,7 @@ export {
   CLIENT_NAVIGATION_SURFACE_HEADER,
   CLIENT_PATH_STYLE_META,
   CLIENT_PERSIST_META,
+  CLIENT_PINS_META,
   CLIENT_SCOPE_HEADER,
   CLIENT_SCOPE_META,
   CLIENT_SYNC_META,
@@ -756,11 +902,22 @@ export {
   REQUEST_TIMEOUT_HEADER,
   remainingBudgetMs,
 } from './request-budget';
-export type { RetryDecision, RetryDeps, RetryPolicy, RetryStopReason } from './retry';
-export { retry, retryDecision } from './retry';
+export type { RetryDeps } from './retry';
+export { retry } from './retry';
+export type { RetryDecision, RetryPolicy, RetryStopReason } from './retry-loop';
+export { retryDecision } from './retry-loop';
 export { isRetryableStatus, RETRYABLE_STATUSES } from './retryable-status';
 export type { ResolveRoleOptions, Role, RoleInfo, ScalingSignal } from './roles';
 export { DEFAULT_ROLE, isRole, ROLE_INFO, ROLES, resolveRole } from './roles';
+export { HttpPathInputConflictError, mergePathParams } from './route-path-merge';
+export type { FilledTemplate, TemplateKeyNode } from './route-path-template';
+export {
+  fillTemplate,
+  pathTemplateProblem,
+  templateKeyProblem,
+  templateParams,
+  toOpenApiPath,
+} from './route-path-template';
 export { routeRank } from './route-rank';
 export type { HydrateStrategy, OfflineStrategy, RenderMode } from './route-vocabulary';
 export { HYDRATE_STRATEGIES, OFFLINE_STRATEGIES, RENDER_MODES } from './route-vocabulary';
@@ -791,6 +948,7 @@ export {
   resetServices,
   type ServiceFactory,
 } from './service';
+export { onSessionLost, sessionIsLost } from './session-lost';
 export type { FlightJoin, Scheduler, SingleFlight, SingleFlightOptions } from './single-flight';
 export { singleFlight } from './single-flight';
 export { endOfLiteral, maskLiterals, QUOTES, stripComments } from './source-mask';
@@ -798,12 +956,17 @@ export type { StoreMode } from './store-mode';
 export { STORE_MODES, storeMode } from './store-mode';
 export { THEME_STORAGE_KEY } from './theme-storage';
 export { timingSafeEqual } from './timing-safe-equal';
+// A projected tool's description: `@ultimat3/mcp`'s and `@ultimat3/ai`'s, one tier apart from neither.
+export type { ToolDescriptionSource } from './tool-description';
+export { toolDescription } from './tool-description';
 export {
   frameworkVersion,
   readPackageVersion,
   resolveVersion,
   VERSION_DEFINE,
 } from './version';
+export type { VisibleIntervalOptions } from './visible-interval';
+export { visibleInterval } from './visible-interval';
 // The webhook wire format, at the tier both halves can reach — `@ultimat3/jobs` signs a delivery
 // and `@ultimat3/http` verifies one, and neither may import the other. Same argument
 // `timing-safe-equal.ts` makes for itself, one line above.

package/src/json-storable.ts

@@ -0,0 +1,21 @@
+// What a `jsonb` column refuses of text `JSON.stringify` accepts. Asked of the text, by whoever is
+// about to store it, so a memory store and Postgres answer alike and the refusal lands before a
+// statement does: only production meets `jsonb`, after the work behind the value has already run.
+
+/** One escape at a time, so the second backslash of `\\u0000` is never read as opening a third. */
+const ESCAPE = /\\(?:u(?:0000|d[89a-f][0-9a-f]{2})|[\s\S])/g;
+
+/**
+ * Why `jsonb` would refuse this `JSON.stringify` output, or `undefined` when it would not. A pair
+ * of surrogates is written raw by `JSON.stringify`, so an escaped surrogate in its output is always
+ * a lone one. The reason names the class of thing, never the text, which can carry anything.
+ */
+export function jsonbRefusal(text: string): string | undefined {
+  // Nearly every value holds no `\u` at all: the scan is paid only by one that does.
+  if (!text.includes('\\u')) return undefined;
+  for (const [token] of text.matchAll(ESCAPE)) {
+    if (token === '\\u0000') return 'a NUL character in a string, which jsonb has no form for';
+    if (token.startsWith('\\ud')) return 'a lone surrogate in a string, which jsonb refuses';
+  }
+  return undefined;
+}

package/src/keyed-fingerprint.ts

@@ -6,6 +6,7 @@
 
 import { canonicalJson, fingerprint } from './canonical-json';
 import { currentSigningSecret } from './cursor';
+import { hmac } from './hmac';
 import { timingSafeEqual } from './timing-safe-equal';
 
 /** The format tag. A stored value without it predates keying (see `compareFingerprint`). */
@@ -23,9 +24,7 @@ const LEGACY = /^[0-9a-f]{16}$/;
 
 /** One key per purpose, derived from the signing secret, so no two uses share a MAC key. */
 function derivedKey(purpose: string): string {
-  return new Bun.CryptoHasher('sha256', currentSigningSecret())
-    .update(`ultimate:keyed-fingerprint:${purpose}`)
-    .digest('hex');
+  return hmac('sha256', currentSigningSecret(), `ultimate:keyed-fingerprint:${purpose}`, 'hex');
 }
 
 /**
@@ -43,10 +42,7 @@ function keyId(key: string): string {
  */
 export function keyedFingerprint(value: unknown, purpose: string): string {
   const key = derivedKey(purpose);
-  const mac = new Bun.CryptoHasher('sha256', key)
-    .update(canonicalJson(value))
-    .digest('hex')
-    .slice(0, 32);
+  const mac = hmac('sha256', key, canonicalJson(value), 'hex').slice(0, 32);
   return `${KEYED_FINGERPRINT_VERSION}:${keyId(key)}:${mac}`;
 }
 

package/src/lifecycle.ts

@@ -280,7 +280,11 @@ function remainingBudget(reason: ShutdownReason): number {
 }
 
 async function runPhase(phase: ShutdownPhase, reason: ShutdownReason): Promise<void> {
-  for (const registration of registrations.filter((entry) => entry.phase === phase)) {
+  const hooks = registrations.filter((entry) => entry.phase === phase);
+  // Resources are released in reverse of acquisition, and only `close` releases any: an exporter
+  // registered at boot flushes after what it serves has ended its last span.
+  if (phase === 'close') hooks.reverse();
+  for (const registration of hooks) {
     const outcome = await settleWithin(() => registration.hook(reason), remainingBudget(reason));
     if (outcome.kind === 'failed') {
       report('error', 'shutdown hook failed', {

package/src/logger.ts

@@ -361,7 +361,7 @@ function timestamp(clock: Clock): string {
  * `LOG_LEVEL`, and the default where there is no environment to read it from.
  *
  * A BROWSER has no `process` binding at all, and this read runs at MODULE INIT — `logger` at the
- * foot of this file is `structuredLogger()` evaluated when the module is. Measured on ai-maxxing's
+ * foot of this file is `structuredLogger()` evaluated when the module is. Measured on one adopter's
  * session console island: `@ultimat3/realtime`'s `channel.ts` calls `logger.warn`, so the shaker
  * keeps `logger`, and the island's chunk died on `ReferenceError: process is not defined` before a
  * line of the app's own code ran — the wrapper rendered `data-x-failed="process is not defined"`

package/src/otlp-metric-exporter.ts

@@ -13,6 +13,7 @@ import type {
 import {
   assertFiniteOtlpBound,
   OTLP_SCOPE,
+  type OtlpPostOptions,
   otlpAttributes,
   otlpEndpoint,
   otlpHeaders,
@@ -100,6 +101,10 @@ export interface OtlpMetricExporterOptions {
   readonly timeoutMs?: number | undefined;
   /** Injected by tests; the preload seals the real one. */
   readonly fetch?: typeof globalThis.fetch | undefined;
+  /** The retry's wait, die and clock, passed to `postOtlp`. Injected by tests. */
+  readonly sleep?: OtlpPostOptions['sleep'];
+  readonly random?: OtlpPostOptions['random'];
+  readonly now?: OtlpPostOptions['now'];
   /**
    * Epoch ms this process's counters started at. Defaults to the first export, which is close
    * enough for a rate and exact for a restart detector; pass the boot time when you have it.
@@ -121,6 +126,7 @@ export function otlpMetricExporter(options: OtlpMetricExporterOptions = {}): Otl
   const headers = otlpHeaders(options.headers, process.env, 'metrics');
   const timeoutMs = assertFiniteOtlpBound('timeoutMs', options.timeoutMs ?? 10_000);
   const send = options.fetch ?? globalThis.fetch;
+  const seams = { sleep: options.sleep, random: options.random, now: options.now };
   let startedAtMs = options.startedAtMs;
   /** The ONE POST in flight, and the one body waiting behind it — never a chain. */
   let sending: Promise<void> | undefined;
@@ -138,7 +144,7 @@ export function otlpMetricExporter(options: OtlpMetricExporterOptions = {}): Otl
     const body = waiting;
     waiting = undefined;
     if (body === undefined) return Promise.resolve();
-    sending = postOtlp({ url, headers, body, timeoutMs, fetch: send })
+    sending = postOtlp({ url, headers, body, timeoutMs, fetch: send, ...seams })
       .then(
         () => undefined,
         () => undefined,

package/src/otlp-post.ts

@@ -0,0 +1,147 @@
+// Single responsibility: deliver one OTLP/HTTP body, again when the collector says "not now". A
+// rolling restart of a collector answers 503 to every pod at once, and a single-shot POST turned
+// each of those answers into a lost window of traces on the surface an operator reads in an outage.
+
+import type { Random } from './backoff';
+import { retryAfterSecondsOf } from './client-retry-after';
+import { systemClock } from './clock';
+import { renderThrowable } from './error-render';
+import { UltimateError } from './errors';
+import { logger } from './logger';
+import { type RetryPolicy, retryLoop } from './retry-loop';
+
+/**
+ * The OTLP/HTTP specification's retryable answers, and only those. Not `isRetryableStatus`: that
+ * table answers "may a client repeat this call?", and a 500 or a 400 from a validating collector
+ * rejects the same batch identically on every attempt.
+ */
+export const OTLP_RETRY_STATUSES: ReadonlySet<number> = new Set([429, 502, 503, 504]);
+
+/** Core's curve, the same shape `outbound()` defaults to; `timeoutMs` adds the time budget. */
+const OTLP_RETRY_POLICY: Omit<RetryPolicy, 'timeBudgetMs'> = Object.freeze({
+  attempts: 3,
+  base: 250,
+  max: 5_000,
+  jitter: 'full',
+});
+
+export interface OtlpPostOptions {
+  readonly url: string;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+  /** The WHOLE export — every attempt and every wait between them — so a batch is held no longer. */
+  readonly timeoutMs: number;
+  readonly fetch: typeof globalThis.fetch;
+  /** Injected so a retry schedule is provable without waiting for one. Defaults to a timer. */
+  readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+  /** The jitter's die. Defaults to `Math.random`. */
+  readonly random?: Random | undefined;
+  /** Monotonic ms the budget is measured on. Defaults to the system clock. */
+  readonly now?: (() => number) | undefined;
+}
+
+/** How one export ended. Every one of them is a log line or silence, never a rejection. */
+type Outcome =
+  | { readonly kind: 'delivered' }
+  | { readonly kind: 'rejected'; readonly status: number }
+  | { readonly kind: 'failed'; readonly error: unknown };
+
+/**
+ * why: an `UltimateError` only so `retryDecision` can classify it and read the stated delay off
+ * `meta.retryAfterSeconds` — `classifyThrown` reads nothing but that brand. It is control flow, the
+ * same rule a job's suspension follows: thrown inside `retryLoop`, caught in `postOtlp`, and never
+ * seen by a caller or a log line. `X_DRAINING` is the existing core code that means exactly this
+ * answer (the responder is restarting or shedding, try again), so no code is minted for a value
+ * that cannot escape.
+ */
+class OtlpRetryable extends UltimateError {
+  readonly outcome: Exclude<Outcome, { kind: 'delivered' }>;
+  constructor(outcome: Exclude<Outcome, { kind: 'delivered' }>, retryAfterSeconds?: number) {
+    super({
+      code: 'X_DRAINING',
+      cause: 'the OTLP collector asked for this batch again',
+      fix: 'postOtlp(request)   # nothing to run: packages/core/src/otlp-post.ts sends the batch again itself',
+      retry: retryAfterSeconds === undefined ? 'retryable' : 'retry-after',
+      meta: retryAfterSeconds === undefined ? undefined : { retryAfterSeconds },
+    });
+    this.outcome = outcome;
+  }
+}
+
+/**
+ * A REF'D wait: it holds the process open, because `timeoutMs` already bounds it and the drain
+ * deadline bounds a shutdown. Unref'd, a shutdown flush answered 503 exited mid-wait — the batch
+ * lost and its line never printed. The same shape as `retry.ts`'s `abortableTimer`.
+ */
+const retryTimer = (ms: number): Promise<void> =>
+  new Promise<void>((done) => {
+    setTimeout(done, ms);
+  });
+
+function logOutcome(url: string, outcome: Outcome, attempts: number): void {
+  if (outcome.kind === 'rejected') {
+    logger.warn('otlp export rejected', { url, status: outcome.status, attempts });
+  } else if (outcome.kind === 'failed') {
+    logger.warn('otlp export failed', {
+      url,
+      attempts,
+      // `renderThrowable`: the read that renders a caught value must not itself throw, or the
+      // export failure this function exists to swallow escapes as an unhandled rejection.
+      error: renderThrowable(outcome.error),
+    });
+  }
+}
+
+/**
+ * Never throws and never rejects. Telemetry delivery is not the request: a collector that is down
+ * must not become the app's outage, and the alternative — an unhandled rejection from a `void`ed
+ * promise — takes the process with it on Bun. One line per batch, never per attempt, so a collector
+ * that stays down is not also a log flood.
+ *
+ * `retryLoop`, not `retry()`: `retry()` adopts the ambient request's signal and deadline, and a
+ * span batch flushed from inside a request would then die with that request. This send belongs to
+ * the process, and its one lifetime is `timeoutMs`.
+ */
+export async function postOtlp(options: OtlpPostOptions): Promise<void> {
+  const now = options.now ?? ((): number => systemClock.monotonic());
+  const startedAt = now();
+  let attempts = 0;
+  const send = async (): Promise<Outcome> => {
+    attempts += 1;
+    const remaining = Math.max(1, Math.ceil(options.timeoutMs - (now() - startedAt)));
+    const signal = AbortSignal.timeout(remaining);
+    let response: Response;
+    try {
+      response = await options.fetch(options.url, {
+        method: 'POST',
+        headers: { ...options.headers },
+        body: options.body,
+        signal,
+      });
+    } catch (error) {
+      // The budget's own abort ends the export: what remained of `timeoutMs` is spent.
+      if (signal.aborted) return { kind: 'failed', error };
+      throw new OtlpRetryable({ kind: 'failed', error });
+    }
+    if (response.ok) return { kind: 'delivered' };
+    const rejected = { kind: 'rejected', status: response.status } as const;
+    if (!OTLP_RETRY_STATUSES.has(response.status)) return rejected;
+    const stated = retryAfterSecondsOf(
+      response.headers.get('retry-after'),
+      response.headers.get('date'),
+    );
+    throw new OtlpRetryable(rejected, stated);
+  };
+  let outcome: Outcome;
+  try {
+    outcome = await retryLoop(
+      send,
+      { ...OTLP_RETRY_POLICY, timeBudgetMs: options.timeoutMs },
+      { sleep: options.sleep ?? retryTimer, now, random: options.random },
+    );
+  } catch (failure) {
+    outcome =
+      failure instanceof OtlpRetryable ? failure.outcome : { kind: 'failed', error: failure };
+  }
+  logOutcome(options.url, outcome, attempts);
+}