@nxtedition/nxt-undici 7.4.2 → 7.5.0

package/lib/interceptor/priority.js

@@ -1,14 +1,17 @@
 import { Scheduler } from '@nxtedition/scheduler'
 import { DecoratorHandler } from '../utils.js'
+import { traceWrite, traceSafe, traceUrl } from '../trace.js'
 
 class Handler extends DecoratorHandler {
   #scheduler
   #onIdle
+  #trace
 
-  constructor(handler, scheduler, onIdle) {
+  constructor(handler, scheduler, onIdle, trace) {
     super(handler)
     this.#scheduler = scheduler
     this.#onIdle = onIdle
+    this.#trace = trace
   }
 
   onConnect(abort) {
@@ -30,8 +33,34 @@ class Handler extends DecoratorHandler {
     if (this.#scheduler) {
       const scheduler = this.#scheduler
       this.#scheduler = null
+
+      // Slot-release timestamp is captured BEFORE release(): it synchronously
+      // pumps queued dispatches, whose work must not inflate this request's
+      // holdMs. Emission happens after release + eviction, inside the same
+      // once-guard as release() (every terminal callback funnels here), so
+      // the end doc cannot double-fire and the writer never observes a
+      // handler that still holds the slot.
+      const trace = this.#trace
+      const released = trace !== null ? performance.now() : 0
+
       scheduler.release()
       this.#onIdle?.()
+
+      if (trace !== null) {
+        traceSafe(
+          trace.write,
+          {
+            id: trace.id,
+            key: trace.key,
+            priority: trace.priority,
+            phase: 'end',
+            pending: null,
+            waitMs: Math.round(trace.dispatched - trace.acquired),
+            holdMs: Math.round(released - trace.dispatched),
+          },
+          'undici:priority',
+        )
+      }
     }
   }
 }
@@ -66,9 +95,30 @@ export default () => (dispatch) => {
       }
     }
 
-    const priorityHandler = new Handler(handler, scheduler, onIdle)
-    scheduler.acquire(
+    // Trace state (op 'undici:priority') is resolved once per request:
+    // capture-once keeps the queued/end pair on one writer, and when tracing
+    // is off the cost is one property read — no clock reads, no string work.
+    // `acquired` must be stamped BEFORE acquire(): a free slot invokes the
+    // callback synchronously and `dispatched` would otherwise predate it.
+    const write = traceWrite(opts.trace)
+    const trace =
+      write !== null
+        ? {
+            write,
+            id: opts.id ?? null,
+            key: traceUrl({ origin: key }),
+            priority: String(opts.priority).slice(0, 16),
+            acquired: performance.now(),
+            dispatched: 0,
+          }
+        : null
+
+    const priorityHandler = new Handler(handler, scheduler, onIdle, trace)
+    const acquired = scheduler.acquire(
       (priorityHandler) => {
+        if (trace !== null) {
+          trace.dispatched = performance.now()
+        }
         try {
           dispatch(opts, priorityHandler)
         } catch (err) {
@@ -78,5 +128,25 @@ export default () => (dispatch) => {
       opts.priority,
       priorityHandler,
     )
+
+    // acquire() returns false only when no slot was free and the request was
+    // queued — the breadcrumb for a request that enters the queue and never
+    // leaves. pending is the post-enqueue queue depth, so it counts this
+    // request.
+    if (!acquired && trace !== null) {
+      traceSafe(
+        trace.write,
+        {
+          id: trace.id,
+          key: trace.key,
+          priority: trace.priority,
+          phase: 'queued',
+          pending: scheduler.pending,
+          waitMs: null,
+          holdMs: null,
+        },
+        'undici:priority',
+      )
+    }
   }
 }

package/lib/interceptor/proxy.js

@@ -108,10 +108,13 @@ function eqiLower(a, b) {
 // allocation-free and letting the common (non-hop) header bail out in a single
 // comparison.
 /**
+ * Exported for reuse by the cache interceptor: RFC 9111 §3.1 forbids storing
+ * hop-by-hop fields, which is the same set a proxy must not retransmit.
+ *
  * @param {string} key
  * @returns {boolean}
  */
-function isHopByHop(key) {
+export function isHopByHop(key) {
   switch (key.length) {
     case 2:
       return eqiLower(key, 'te')

package/lib/interceptor/redirect.js

@@ -1,5 +1,6 @@
 import assert from 'node:assert'
 import { DecoratorHandler, isDisturbed, parseURL, parseHeaders, buildURL } from '../utils.js'
+import { traceWrite, traceSafe, traceUrl } from '../trace.js'
 
 const redirectableStatusCodes = [300, 301, 302, 303, 307, 308]
 
@@ -105,6 +106,13 @@ class Handler extends DecoratorHandler {
       }
     }
 
+    // The redirect decision is final past this point, so trace work stays off
+    // the non-redirect path entirely. Resolve the writer per emission (trace
+    // survives the opts spread across hops) and capture `from` before #opts
+    // is rebuilt below.
+    const write = traceWrite(this.#opts.trace)
+    const from = write !== null ? traceUrl(this.#opts) : null
+
     // Build the base URL by concatenating origin + path via buildURL rather
     // than `new URL(path, origin)`: the latter is unsafe when `path` is
     // protocol-relative (e.g. `//evil-host/x`, reachable via a request URL like
@@ -140,6 +148,24 @@ class Handler extends DecoratorHandler {
         body: null,
       }
     }
+
+    if (write !== null) {
+      traceSafe(
+        write,
+        {
+          id: this.#opts.id ?? null,
+          // Post-rewrite method for the next hop (303 may have swapped it above).
+          method: this.#opts.method ?? null,
+          statusCode,
+          from,
+          to: traceUrl(this.#opts),
+          // #count is 1-based: incremented above for this hop, so the first
+          // followed redirect emits count 1.
+          count: this.#count,
+        },
+        'undici:redirect',
+      )
+    }
   }
 
   onData(chunk) {

package/lib/interceptor/response-retry.js

@@ -8,6 +8,7 @@ import {
   parseHeaders,
 } from '../utils.js'
 import { RequestAbortedError } from '../errors.js'
+import { traceWrite, traceSafe, traceErr, traceUrl } from '../trace.js'
 
 // Maximum number of >= 400 response body bytes buffered for replay in case
 // the response is not retried. Larger bodies are passed straight through and
@@ -16,6 +17,30 @@ const MAX_ERROR_BODY_SIZE = 256 * 1024
 
 function noop() {}
 
+// Emit an `undici:retry` trace doc at the point a retry is actually scheduled.
+// Cold path only — a retry already implies a failed attempt — so resolving the
+// writer per emission (same resolution as the trace interceptor: explicit
+// opts.trace wins, absent falls back to the global) costs nothing on the
+// request hot path. `cause` is the triggering failure: the attempt's error, or
+// the bare status code for a status-code retry without one.
+function traceRetry(opts, retryCount, delay, cause) {
+  const write = traceWrite(opts.trace)
+  if (write !== null) {
+    traceSafe(
+      write,
+      {
+        id: opts.id ?? null,
+        method: opts.method ?? null,
+        url: traceUrl(opts),
+        retryCount,
+        delayMs: delay,
+        err: traceErr(cause),
+      },
+      'undici:retry',
+    )
+  }
+}
+
 // Subscribe `onAbort` to an EventEmitter-style OR EventTarget-style signal and
 // return an unsubscribe function; return null when it cannot be done safely.
 //
@@ -618,6 +643,7 @@ class Handler extends DecoratorHandler {
             Math.min(retryAfter, 60e3)
           : Math.min(10e3, retryCount * 1e3)
       this.#opts.logger?.debug({ statusCode, retryAfter, delay, retryCount }, 'retry delay')
+      traceRetry(this.#opts, retryCount, delay, err ?? statusCode)
       return this.#backoff(delay, opts)
     }
 
@@ -638,13 +664,17 @@ class Handler extends DecoratorHandler {
         'UND_ERR_SOCKET',
       ].includes(err.code)
     ) {
+      const delay = Math.min(10e3, retryCount * 1e3)
       this.#opts.logger?.debug({ err, retryCount }, 'retry delay')
-      return this.#backoff(Math.min(10e3, retryCount * 1e3), opts)
+      traceRetry(this.#opts, retryCount, delay, err)
+      return this.#backoff(delay, opts)
     }
 
     if (err?.message && ['other side closed'].includes(err.message)) {
+      const delay = Math.min(10e3, retryCount * 1e3)
       this.#opts.logger?.debug({ err, retryCount }, 'retry delay')
-      return this.#backoff(Math.min(10e3, retryCount * 1e3), opts)
+      traceRetry(this.#opts, retryCount, delay, err)
+      return this.#backoff(delay, opts)
     }
 
     return false

package/lib/interceptor/response-verify.js

@@ -1,7 +1,38 @@
 import crypto from 'node:crypto'
 import { DecoratorHandler, parseContentRange } from '../utils.js'
+import { traceWrite, traceSafe, traceUrl } from '../trace.js'
+
+// Emit an `undici:verify` trace doc carrying the by-how-much/what-values
+// detail of a verification failure, immediately before the error is delivered.
+// The undici:request end doc already tags THAT the request failed; this doc is
+// for fingerprinting truncation vs corruption. Cold path only — every call
+// site is an already-failing branch — so the writer is resolved per emission
+// (explicit opts.trace wins, absent falls back to the global) at zero cost on
+// the per-chunk hot path. Hash values are origin-influenced strings (a
+// duplicated Content-MD5 header keeps `expected` as an array of conflicting
+// values, which String() flattens), so bound them.
+function traceVerify(opts, kind, expectedSize, actualSize, expectedHash, actualHash) {
+  const write = traceWrite(opts.trace)
+  if (write !== null) {
+    traceSafe(
+      write,
+      {
+        id: opts.id ?? null,
+        method: opts.method ?? null,
+        url: traceUrl(opts),
+        kind,
+        expectedSize,
+        actualSize,
+        expectedHash: expectedHash != null ? String(expectedHash).slice(0, 64) : null,
+        actualHash: actualHash != null ? String(actualHash).slice(0, 64) : null,
+      },
+      'undici:verify',
+    )
+  }
+}
 
 class Handler extends DecoratorHandler {
+  #opts
   #verifyOpts
   #contentMD5
   #expectedSize
@@ -12,6 +43,8 @@ class Handler extends DecoratorHandler {
   constructor(opts, { handler }) {
     super(handler)
 
+    // Retained only for failure-time trace tagging (id/method/url).
+    this.#opts = opts
     this.#verifyOpts = opts.verify === true ? { hash: true, size: true } : opts.verify
   }
 
@@ -70,6 +103,7 @@ class Handler extends DecoratorHandler {
         expected: this.#expectedSize,
         actual: this.#pos,
       })
+      traceVerify(this.#opts, 'overrun', this.#expectedSize, this.#pos, null, null)
       super.onError(err)
       // Returning false only applies backpressure; the socket would stay
       // paused until bodyTimeout. Abort to release the connection now.
@@ -84,6 +118,7 @@ class Handler extends DecoratorHandler {
     const contentMD5 = this.#hasher?.digest('base64')
 
     if (this.#expectedSize != null && this.#pos !== this.#expectedSize) {
+      traceVerify(this.#opts, 'size', this.#expectedSize, this.#pos, null, null)
       super.onError(
         Object.assign(new Error('Response body size mismatch'), {
           expected: this.#expectedSize,
@@ -91,6 +126,7 @@ class Handler extends DecoratorHandler {
         }),
       )
     } else if (this.#contentMD5 != null && contentMD5 !== this.#contentMD5) {
+      traceVerify(this.#opts, 'hash', null, null, this.#contentMD5, contentMD5)
       super.onError(
         Object.assign(new Error('Response Content-MD5 mismatch'), {
           expected: this.#contentMD5,

package/lib/sqlite-cache-store.js

@@ -2,7 +2,7 @@ import { DatabaseSync } from 'node:sqlite'
 import { parseRangeHeader, getFastNow } from './utils.js'
 
 // Bump version when the URL key format or schema changes to invalidate old caches.
-const VERSION = 10
+const VERSION = 11
 
 // Registry of live stores so process-level broadcasts (nxt:offPeak,
 // nxt:clearCache) can reach them. Stores are held via WeakRef so that a store
@@ -51,8 +51,9 @@ function forEachStore(fn) {
 }
 
 /**
- * @typedef {import('undici-types/cache-interceptor.d.ts').default.CacheStore} CacheStore
- * @implements {CacheStore}
+ * Synchronous get/set/delete cache store backed by node:sqlite. Note: this is
+ * NOT undici's stream-based CacheStore interface (createWriteStream); the
+ * cache interceptor in this package drives it directly.
  *
  * @typedef {{
  *  id: Readonly<number>,
@@ -66,6 +67,7 @@ function forEachStore(fn) {
  *  etag?: string
  *  cacheControlDirectives?: string
  *  cachedAt: number
+ *  staleAt: number
  *  deleteAt: number
  * }} SqliteStoreValue
  */
@@ -100,6 +102,21 @@ export class SqliteCacheStore {
    */
   #evictQuery
 
+  /**
+   * @type {import('node:sqlite').StatementSync}
+   */
+  #deleteByUrlQuery
+
+  /**
+   * @type {import('node:sqlite').StatementSync}
+   */
+  #supersedeFullQuery
+
+  /**
+   * @type {import('node:sqlite').StatementSync}
+   */
+  #supersede206Query
+
   #insertBatch = []
   #insertSeq = 0
   #closed = false
@@ -136,6 +153,7 @@ export class SqliteCacheStore {
         body BLOB NULL,
         start INTEGER NOT NULL,
         end INTEGER NOT NULL,
+        staleAt INTEGER NOT NULL,
         deleteAt INTEGER NOT NULL,
         statusCode INTEGER NOT NULL,
         statusMessage TEXT NOT NULL,
@@ -148,6 +166,12 @@ export class SqliteCacheStore {
 
       CREATE INDEX IF NOT EXISTS idx_cacheInterceptorV${VERSION}_getValuesQuery ON cacheInterceptorV${VERSION}(url, method, start, deleteAt);
       CREATE INDEX IF NOT EXISTS idx_cacheInterceptorV${VERSION}_deleteExpiredValuesQuery ON cacheInterceptorV${VERSION}(deleteAt);
+      -- Covers the supersede-on-flush DELETEs (#supersedeFullQuery /
+      -- #supersede206Query), whose predicate is url+method+vary (+statusCode,
+      -- and start/end for 206) — so a re-cache supersedes via an index seek
+      -- instead of scanning every row for a hot url+method with many Vary
+      -- variants or partial windows.
+      CREATE INDEX IF NOT EXISTS idx_cacheInterceptorV${VERSION}_supersedeQuery ON cacheInterceptorV${VERSION}(url, method, vary, statusCode, start, end);
     `)
 
     // Drop tables left behind by previous schema versions. gc(), clear() and
@@ -200,6 +224,7 @@ export class SqliteCacheStore {
         body,
         start,
         end,
+        staleAt,
         deleteAt,
         statusCode,
         statusMessage,
@@ -215,7 +240,7 @@ export class SqliteCacheStore {
         AND start <= ?
         AND deleteAt > ?
       ORDER BY
-        cachedAt DESC, id DESC
+        id DESC
     `)
 
     this.#insertValueQuery = this.#db.prepare(`
@@ -225,6 +250,7 @@ export class SqliteCacheStore {
         body,
         start,
         end,
+        staleAt,
         deleteAt,
         statusCode,
         statusMessage,
@@ -233,7 +259,7 @@ export class SqliteCacheStore {
         cacheControlDirectives,
         vary,
         cachedAt
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `)
 
     this.#deleteExpiredValuesQuery = this.#db.prepare(
@@ -246,6 +272,35 @@ export class SqliteCacheStore {
       `DELETE FROM cacheInterceptorV${VERSION} WHERE id IN (SELECT id FROM cacheInterceptorV${VERSION} ORDER BY deleteAt ASC LIMIT ?)`,
     )
 
+    // RFC 9111 §4.4 invalidation: a successful unsafe request invalidates every
+    // stored response for the URI, across methods and vary variants.
+    this.#deleteByUrlQuery = this.#db.prepare(
+      `DELETE FROM cacheInterceptorV${VERSION} WHERE url = ?`,
+    )
+
+    // Supersede queries: a newly flushed row replaces prior rows for the same
+    // representation so hot keys don't accumulate dead duplicates until gc.
+    // Receipt order (insertion order), NOT cachedAt, decides who wins — the
+    // same semantics as upstream undici's update-in-place set(). cachedAt is
+    // backdated by the corrected initial age (RFC 9111 §4.2.3), so a
+    // replacement fetched through a relay advertising a large Age (or a 304
+    // freshening with a skewed origin Date) can carry an OLDER cachedAt than
+    // the stale row it replaces; keying supersede or the read sort on
+    // cachedAt would let the stale row win every read, forever. `vary IS ?`
+    // is NULL-safe and compares the serialized-JSON text, deterministic
+    // because both sides are produced by the same CacheHandler code path
+    // (key order = Vary header order). A new full (non-206) representation
+    // supersedes all prior full ones regardless of byte window; a 206 only
+    // supersedes the exact same window so distinct partials coexist, and
+    // never a 200 row (matchesValue routes range and non-range requests to
+    // different rows).
+    this.#supersedeFullQuery = this.#db.prepare(
+      `DELETE FROM cacheInterceptorV${VERSION} WHERE url = ? AND method = ? AND vary IS ? AND statusCode != 206`,
+    )
+    this.#supersede206Query = this.#db.prepare(
+      `DELETE FROM cacheInterceptorV${VERSION} WHERE url = ? AND method = ? AND vary IS ? AND statusCode = 206 AND start = ? AND end = ?`,
+    )
+
     this.#ref = new WeakRef(this)
     stores.add(this.#ref)
     // The store itself doubles as the unregister token so close() can drop
@@ -371,7 +426,7 @@ export class SqliteCacheStore {
       setImmediate(this.#flush)
     }
 
-    this.#insertBatch.push({
+    const entry = {
       // Monotonic per-store sequence used only to break cachedAt ties in
       // #findValue (newest write wins). Not persisted — #flush ignores it.
       seq: this.#insertSeq++,
@@ -380,6 +435,9 @@ export class SqliteCacheStore {
       body,
       start: value.start,
       end: value.end,
+      // staleAt column is NOT NULL; default to deleteAt when the caller omits
+      // it (pre-v11 value shape) — matches this package's staleAt === deleteAt.
+      staleAt: value.staleAt ?? value.deleteAt,
       deleteAt: value.deleteAt,
       statusCode: value.statusCode,
       statusMessage: value.statusMessage,
@@ -390,7 +448,56 @@ export class SqliteCacheStore {
         : null,
       vary: value.vary ? JSON.stringify(value.vary) : null,
       cachedAt: value.cachedAt,
-    })
+    }
+
+    // Coalesce within the pending batch: a stampede of identical misses would
+    // otherwise commit N identical rows. Receipt order wins (see the
+    // #supersede* query comments): the entry being added supersedes every
+    // pending entry for the same representation.
+    for (let i = this.#insertBatch.length - 1; i >= 0; i--) {
+      const other = this.#insertBatch[i]
+      if (
+        other.url === entry.url &&
+        other.method === entry.method &&
+        other.vary === entry.vary &&
+        (entry.statusCode !== 206
+          ? other.statusCode !== 206
+          : other.statusCode === 206 && other.start === entry.start && other.end === entry.end)
+      ) {
+        this.#insertBatch.splice(i, 1)
+      }
+    }
+
+    this.#insertBatch.push(entry)
+  }
+
+  /**
+   * Invalidates every stored response for the key's URI (RFC 9111 §4.4) —
+   * across methods and vary variants. Pending batched inserts for the URI are
+   * dropped as well: a batch entry flushed after the DELETE would otherwise
+   * resurrect the invalidated response. Note this only covers THIS process's
+   * batch — with a shared on-disk store, another process's in-flight batch
+   * can still transiently resurrect an entry (bounded by its ~10ms flush
+   * slice); cross-process invalidation is inherently best-effort.
+   *
+   * @param {import('undici-types/cache-interceptor.d.ts').default.CacheKey} key
+   */
+  delete(key) {
+    assertCacheKey(key)
+
+    if (this.#closed) {
+      return
+    }
+
+    const url = makeValueUrl(key)
+
+    for (let i = this.#insertBatch.length - 1; i >= 0; i--) {
+      if (this.#insertBatch[i].url === url) {
+        this.#insertBatch.splice(i, 1)
+      }
+    }
+
+    this.#deleteByUrlQuery.run(url)
   }
 
   #flush = (final = false) => {
@@ -412,6 +519,7 @@ export class SqliteCacheStore {
               body,
               start,
               end,
+              staleAt,
               deleteAt,
               statusCode,
               statusMessage,
@@ -421,12 +529,21 @@ export class SqliteCacheStore {
               vary,
               cachedAt,
             } = this.#insertBatch[n++]
+            // Supersede prior rows for the same representation (see the
+            // #supersede* query comments) inside the same transaction, so a
+            // re-cache replaces instead of accumulating.
+            if (statusCode === 206) {
+              this.#supersede206Query.run(url, method, vary, start, end)
+            } else {
+              this.#supersedeFullQuery.run(url, method, vary)
+            }
             this.#insertValueQuery.run(
               url,
               method,
               body,
               start,
               end,
+              staleAt,
               deleteAt,
               statusCode,
               statusMessage,
@@ -534,16 +651,14 @@ export class SqliteCacheStore {
       return undefined
     }
 
-    // Newest representation wins. cachedAt is millisecond-resolution, so a
-    // re-cache within the same millisecond produces a tie; break it
-    // deterministically toward the freshest write: pending batch entries
-    // (tagged with a monotonic seq) are always newer than any flushed DB row,
-    // and within each source a higher seq/id wins.
+    // Most recently WRITTEN representation wins — receipt order, not
+    // cachedAt (see the #supersede* query comments: cachedAt is backdated by
+    // the corrected initial age, so a fresher write can carry an older
+    // cachedAt). Pending batch entries (tagged with a monotonic seq) are
+    // always newer than any flushed DB row, and within each source a higher
+    // seq/id wins.
     if (values.length > 1) {
       values.sort((a, b) => {
-        if (a.cachedAt !== b.cachedAt) {
-          return b.cachedAt - a.cachedAt
-        }
         const aBatch = a.seq != null
         const bBatch = b.seq != null
         if (aBatch !== bBatch) {
@@ -657,6 +772,7 @@ function makeResult(value) {
       ? JSON.parse(value.cacheControlDirectives)
       : undefined,
     cachedAt: value.cachedAt,
+    staleAt: value.staleAt,
     deleteAt: value.deleteAt,
   }
 }
@@ -704,6 +820,16 @@ function assertCacheValue(value) {
     }
   }
 
+  // staleAt is optional for backward compatibility: pre-v11 callers of the
+  // public SqliteCacheStore.set() omit it, and set() defaults it to deleteAt
+  // (this package's staleAt === deleteAt semantics). Validate the type only
+  // when supplied.
+  if (value.staleAt !== undefined && typeof value.staleAt !== 'number') {
+    throw new TypeError(
+      `expected value.staleAt to be number, got ${printType(value.staleAt)} [${value.staleAt}]`,
+    )
+  }
+
   if (typeof value.statusMessage !== 'string') {
     throw new TypeError(
       `expected value.statusMessage to be string, got ${printType(value.statusMessage)} [${value.statusMessage}]`,

package/lib/trace.js

@@ -0,0 +1,87 @@
+// Trace plumbing shared by the interceptors. The writer contract and the
+// generic helpers live in @nxtedition/trace; only the nxt-undici-specific
+// pieces (dispatch-opts url tagging, undici-flavored option validation) are
+// implemented here.
+//
+// Importing @nxtedition/trace statically is safe despite the package cycle
+// (@nxtedition/trace flushes through nxt-undici): the trace package imports
+// nxt-undici lazily at first flush precisely so consumers can depend on it
+// statically. The only constraint is publish order — @nxtedition/trace must
+// be published before a nxt-undici release that depends on it.
+//
+// The contract in short: a writer is `{ write }` where `write` is the trace
+// function while tracing is enabled and null while disabled (it flips between
+// the two at runtime), so call sites gate on the resolved fn at zero cost when
+// off. `write` must not call back into the request being traced — emission
+// happens inside dispatch/handler control flow, and reentrancy there is
+// unsupported.
+
+import { validateTrace as validateTraceWriter } from '@nxtedition/trace'
+import { InvalidArgumentError } from './errors.js'
+
+// installTrace is part of the surface: the per-thread default writer lives in
+// the Symbol.for('@nxtedition/app/trace') slot and is mirrored
+// module-locally inside @nxtedition/trace, so a
+// writer must be installed through installTrace — a bare slot assignment only
+// propagates on the next mirror refresh.
+export { traceWrite, traceSafe, traceErr, installTrace } from '@nxtedition/trace'
+
+/**
+ * @typedef {import('@nxtedition/trace').TraceWriter} TraceWriter
+ */
+
+/**
+ * Validate an opts.trace value, rethrowing the package's plain Error as the
+ * InvalidArgumentError (UND_ERR_INVALID_ARG) that dispatch option validation
+ * is expected to throw. Returns the input unchanged.
+ *
+ * @param {unknown} trace
+ * @returns {TraceWriter | null | undefined}
+ */
+export function validateTrace(trace) {
+  try {
+    return validateTraceWriter(trace)
+  } catch {
+    throw new InvalidArgumentError('invalid trace')
+  }
+}
+
+/**
+ * Bounded origin+path tag for trace docs. Mirrors log.js's sanitizeOrigin
+ * userinfo guard: an origin string carrying `user:pass@host` credentials is
+ * reduced to URL#origin (which never contains userinfo) before it can reach
+ * the trace index; if such a string is not a parseable URL, prefer losing the
+ * value over risking embedded credentials. Never throws — evaluated while
+ * building docs inside handler control flow.
+ *
+ * @param {{ origin?: unknown, path?: unknown }} opts
+ * @returns {string | null}
+ */
+export function traceUrl(opts) {
+  try {
+    const origin = opts.origin
+    let str
+    if (origin == null) {
+      str = ''
+    } else if (origin instanceof URL) {
+      // Real URL instances already expose a credential-free origin.
+      str = origin.origin
+    } else {
+      // Raw dispatch()/compose() callers may pass URL-like objects or arrays
+      // (defaultLookup resolves those deeper in the chain) — stringify rather
+      // than lose the doc.
+      str = typeof origin === 'string' ? origin : String(origin)
+      if (str.includes('@')) {
+        try {
+          str = new URL(str).origin
+        } catch {
+          str = '[redacted]'
+        }
+      }
+    }
+    const path = typeof opts.path === 'string' ? opts.path : ''
+    return `${str}${path}`.slice(0, 256)
+  } catch {
+    return null
+  }
+}