@procedures/client 0.52.2 → 0.53.1

package/src/procedures/module.ts

@@ -159,6 +159,9 @@ export interface LazyRegistryOptions {
   readonly warn?: ((message: string) => void) | undefined;
 }
 
+/** The most paths with no package in the index that a lazy registry warns about: 1000. */
+const MOST_WARNED_PATHS = 1000;
+
 /** The first line of the message of an error. */
 function firstLine(error: unknown): string {
   return (error instanceof Error ? error.message : String(error)).split("\n")[0] ?? "";
@@ -216,9 +219,14 @@ export function createLazyRegistry(options: LazyRegistryOptions): ProcedureRegis
       if (named !== undefined && named.length > 0) {
         targets = named;
       } else {
-        if (!warnedPaths.has(key)) {
+        // The set has a bound: a caller can send many names that the index does not have (audit 2026-11-08)
+        if (!warnedPaths.has(key) && warnedPaths.size < MOST_WARNED_PATHS) {
           warnedPaths.add(key);
-          warn(`the index has no package for ${key}: each package loads`);
+          warn(
+            warnedPaths.size < MOST_WARNED_PATHS
+              ? `the index has no package for ${key}: each package loads`
+              : `the index has no package for ${key}: each package loads. The next paths with no package get no warning.`,
+          );
         }
         targets = packages;
       }

package/src/server/host-policy.ts

@@ -59,11 +59,22 @@ export function exposePatterns(patterns: readonly string[]): (path: ProcedurePat
   };
 }
 
+/**
+ * This function tells if a list of excluded keys names a path. An entry can be the key of the path
+ * (`collections.e2e%2Etabs.delete`) or its segments joined with plain dots
+ * (`collections.e2e.tabs.delete`), the form before CLI-75. So an exclusion of the old form still
+ * hides its procedure (audit 2026-11-08). The plain form can hide one more path, but not one less.
+ */
+function isExcluded(excluded: ReadonlySet<string>, path: ProcedurePath): boolean {
+  // path-check: the raw form of an exclude entry before CLI-75, compared as text, not decoded.
+  return excluded.has(pathToKey(path)) || excluded.has(path.join("."));
+}
+
 /** The rule of a tool surface: the namespaces, less the excluded keys. */
 export function surfaceRule(surface: ToolSurface): (path: ProcedurePath) => boolean {
   const namespaces = new Set(surface.namespaces);
   const excluded = new Set(surface.exclude ?? []);
-  return (path) => namespaces.has(path[0] ?? "") && !excluded.has(pathToKey(path));
+  return (path) => namespaces.has(path[0] ?? "") && !isExcluded(excluded, path);
 }
 
 /** The options of `hostPolicy()`. */
@@ -85,6 +96,12 @@ export interface HostPolicyOptions {
    * query) and gives a bearer token, a principal and a narrowing (`ProcedureServerOptions`).
    */
   principalOf?: PrincipalOf | undefined;
+  /**
+   * The callers whose `baggage` the handler gets (C10), more than a local request and a request
+   * with the token. The function runs after the checks of the request, so it can read
+   * `request.principal`. Without it, no other caller sets the baggage of the services.
+   */
+  trustBaggage?: ((request: ServerRequest<unknown>) => boolean) | undefined;
   /** The browser checks of the network transports (`allowedOrigins`, `allowedHosts`, `allowGet`). */
   browser?: BrowserGuardOptions | undefined;
   /**
@@ -126,6 +143,8 @@ export interface HostPolicy {
   readonly token: string | undefined;
   /** The request hook of the network requests, or undefined for none. */
   readonly principalOf?: PrincipalOf | undefined;
+  /** The callers whose baggage the handler gets (C10), or undefined for none more. */
+  readonly trustBaggage?: ((request: ServerRequest<unknown>) => boolean) | undefined;
   readonly browser: BrowserGuardOptions;
   /** The capability of a call from a caller, or undefined for no limits. */
   readonly capabilityOf: ((request?: ServerRequest<unknown>) => Capability | undefined) | undefined;
@@ -163,7 +182,7 @@ function exposeOf(options: HostPolicyOptions): ((path: ProcedurePath) => boolean
           : surfaceRule(expose as ToolSurface);
   const excluded = new Set(options.exclude ?? []);
   if (excluded.size === 0) return rule;
-  return (path) => !excluded.has(pathToKey(path)) && (rule ? rule(path) : true);
+  return (path) => !isExcluded(excluded, path) && (rule ? rule(path) : true);
 }
 
 /** This function builds the policy of a host from its options. */
@@ -179,6 +198,7 @@ export function hostPolicy(options: HostPolicyOptions = {}): HostPolicy {
     interceptors,
     token: options.token,
     ...(options.principalOf ? { principalOf: options.principalOf } : {}),
+    ...(options.trustBaggage ? { trustBaggage: options.trustBaggage } : {}),
     browser: options.browser ?? {},
     capabilityOf: capabilityOfOptions(options),
     clearanceOrder: options.clearanceOrder,
@@ -201,6 +221,8 @@ export function procedureServerOptions(policy: HostPolicy, registry?: ProcedureR
     ...(policy.token !== undefined ? { token: policy.token } : {}),
     // The request hook of the policy: the credentials of a cookie, a header or the query (CLI-2a)
     ...(policy.principalOf ? { principalOf: policy.principalOf } : {}),
+    // The callers whose baggage the handler gets (C10)
+    ...(policy.trustBaggage ? { trustBaggage: policy.trustBaggage } : {}),
     ...(policy.interceptors.length > 0 ? { interceptors: policy.interceptors } : {}),
     ...(policy.capabilityOf ? { capability: policy.capabilityOf } : {}),
     ...(policy.clearanceOrder ? { clearanceOrder: policy.clearanceOrder } : {}),

package/src/server/limits.ts

@@ -236,9 +236,22 @@ export function limitedCall(procedure: { readonly path: ProcedurePath; readonly
 /**
  * This function gives the response of a refused call: `RATE_LIMITED`, retryable, with the wait in
  * `retry-after` (milliseconds) and the cause in `reason`. The failure of a store stays on the server.
+ * A refusal with the cause `capacity` is not retryable and has no wait: no wait lets its units in.
  */
 export function rateLimitedResponse(id: string, refusal: CallLimitRefusal): ServerResponse<unknown> {
   const { limit, refused } = refusal;
+  if (refused.cause === "capacity") {
+    return {
+      id,
+      status: {
+        type: "error",
+        code: "RATE_LIMITED",
+        message: `The limit ${limit} of the host refuses the call at each time: ${refused.units} units are over its capacity of ${refused.capacity}`,
+        retryable: false,
+      },
+      metadata: { reason: refused.cause },
+    };
+  }
   const waitMs = valueIn(refused.retryAfter, "ms");
   const seconds = retryAfterSeconds(refused.retryAfter);
   return {

package/src/server/procedure-server.ts

@@ -13,6 +13,8 @@ import type { Admission, AmbientCredentials, Credentials, Method, Principal, Pri
 import { methodName, methodToPath, pathToMethod } from "./method.js";
 import { isLocalCredentials } from "./request-auth.js";
 import { STREAM_METADATA_KEY } from "./stream-metadata.js";
+import { context as otelContext } from "@opentelemetry/api";
+import { callerContext } from "../tracing/otel.js";
 import type {
   AnyProcedure,
   ProcedurePath,
@@ -151,6 +153,20 @@ export interface ProcedureServerOptions extends ServerOptions {
    */
   token?: string | undefined;
 
+  /**
+   * Which callers can set the baggage of a call (roadmap item C10 of otel-ts). Each handler runs in
+   * the context of its caller: the remote span of the `traceparent` and `tracestate` of the
+   * metadata is its parent. The `baggage` of the metadata goes into the context only from a
+   * trusted caller. Without it, the handler runs with no baggage, so an end user cannot set the
+   * baggage of the services.
+   *
+   * A local request (`LOCAL_CREDENTIALS`) and a request with the token of the server are always
+   * trusted. This function can trust more requests, for example the requests of a principal of a
+   * service. It runs after the checks of the request, so it can read `request.principal`. An
+   * error of the function means "not trusted". The default trusts no other request.
+   */
+  trustBaggage?: ((request: ServerRequest<unknown>) => boolean) | undefined;
+
   /**
    * This function gives the principal of a request, or undefined to refuse it with
    * `UNAUTHORIZED`. It runs after the token check. The capability function can read
@@ -455,11 +471,22 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
   private readonly token: string | undefined;
   private readonly principalOf: PrincipalOf | undefined;
   private readonly authenticate: ProcedureServerOptions["authenticate"];
+  private readonly trustBaggage: ProcedureServerOptions["trustBaggage"];
+  /**
+   * The requests whose caller can set the baggage (C10): a local request, a request with the
+   * token of the server, or a request with the admission of such a request.
+   */
+  private readonly trustedCallers = new WeakSet<ServerRequest<unknown>>();
   /**
    * The admissions of this server (CLI-2b): the identity of each object of admitted credentials
    * that `admission()` gave. Only this server adds an entry, so a request cannot claim one.
    */
-  private readonly admissions = new WeakMap<Credentials, { readonly principal: Principal | undefined; readonly narrowing: ServerRequest<unknown>["narrowing"] }>();
+  private readonly admissions = new WeakMap<Credentials, { readonly principal: Principal | undefined; readonly narrowing: ServerRequest<unknown>["narrowing"]; readonly trusted: boolean }>();
+  /**
+   * The admission of each request object. The late lookup of a lazy registry admits a request
+   * before it loads packages, and the call of the same request uses that result again.
+   */
+  private readonly admitted = new WeakMap<ServerRequest<unknown>, Promise<ServerResponse<unknown> | undefined>>();
   /** The functions that `drain()` waits on: each one runs when no call is in flight */
   private idleWaiters: Array<() => void> = [];
   /** The publisher of the remote events, from the option `events`, or undefined. */
@@ -492,6 +519,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
     this.token = options.token;
     this.principalOf = options.principalOf;
     this.authenticate = options.authenticate;
+    this.trustBaggage = options.trustBaggage;
     const ambient = options.ambientCredentials ?? (this.principalOf ? "always" : this.authenticate ? "cookies" : undefined);
     this.ambientCredentials = ambient === false ? undefined : ambient;
     this.debugReport =
@@ -847,7 +875,20 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
    */
   protected override findLateHandler(method: Method, request: ServerRequest<unknown>): Promise<ServerHandler | null> | null {
     if (!this.servesRegistry || !this.procedureRegistry.lazy) return null;
-    return this.procedureRegistry.resolve(methodToPath(method)).then(() => this.findHandler(method, request));
+    const path = methodToPath(method);
+    // A path outside the expose rule of the face loads nothing, as findHandler() gives it no handler
+    if (request.expose !== undefined) {
+      const rule: unknown = request.expose;
+      if (typeof rule !== "function" || rule(path) !== true) return null;
+    }
+    return (async (): Promise<ServerHandler | null> => {
+      // Only an admitted request loads packages (audit 2026-11-08). Before, a caller with no
+      // credentials loaded packages, and got the load errors of the packages.
+      const refusal = await this.admit(request);
+      if (refusal) return () => Promise.resolve(refusal);
+      await this.procedureRegistry.resolve(path);
+      return this.findHandler(method, request);
+    })();
   }
 
   /**
@@ -896,9 +937,20 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
    * request hook refuses it, and the hook does not run (CLI-1). The authenticate function gives
    * the principal. The credentials of an admission of this server (`admission()`) skip the
    * checks: the request gets the principal and the narrowing of that admission (CLI-2b). The
-   * function gives an UNAUTHORIZED response, or undefined when the request passes.
-   */
-  private async admit(request: ServerRequest<unknown>): Promise<ServerResponse<unknown> | undefined> {
+   * function gives an UNAUTHORIZED response, or undefined when the request passes. The checks
+   * run one time for each request object.
+   */
+  private admit(request: ServerRequest<unknown>): Promise<ServerResponse<unknown> | undefined> {
+    let result = this.admitted.get(request);
+    if (result === undefined) {
+      result = this.checkRequest(request);
+      this.admitted.set(request, result);
+    }
+    return result;
+  }
+
+  /** The checks of `admit()` for one request object. */
+  private async checkRequest(request: ServerRequest<unknown>): Promise<ServerResponse<unknown> | undefined> {
     const unauthorized = (message: string): ServerResponse<unknown> => ({
       id: request.id,
       status: { type: "error", code: "UNAUTHORIZED", message, retryable: false },
@@ -908,6 +960,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
     // again. Only this server makes such credentials, so a copy or a forgery has no entry.
     const admitted = request.credentials !== undefined ? this.admissions.get(request.credentials) : undefined;
     if (admitted) {
+      if (admitted.trusted) this.trustedCallers.add(request);
       if (admitted.principal) request.principal = admitted.principal;
       if (admitted.narrowing) {
         const order = this.capabilityOptions.clearanceOrder;
@@ -924,6 +977,8 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
     // A local face (this process, MCP over stdio, a message port) sets the local marker. The
     // marker key is a symbol, so a request from the network cannot carry it (CLI-1).
     const credentials = isLocalCredentials(request.credentials) ? undefined : request.credentials;
+    // A local caller is a part of this process: it can set the baggage (C10)
+    if (isLocalCredentials(request.credentials)) this.trustedCallers.add(request);
     let identity: RequestIdentity | undefined;
     if (this.principalOf && credentials !== undefined) {
       try {
@@ -937,6 +992,8 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
       const bearer = identity?.bearer ?? credentials.bearer;
       if (!tokenMatches(this.token, bearer)) return unauthorized("Unauthorized: this server requires its token");
       request.principal = { id: "token", via: "token" };
+      // A caller with the token of the server is a service of the operator: it can set the baggage (C10)
+      this.trustedCallers.add(request);
     }
     if (identity?.principal) request.principal = identity.principal;
     if (identity?.narrowing) {
@@ -1034,7 +1091,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
       return { ok: false, code: "UNAUTHORIZED", message: refusal.status.type === "error" ? refusal.status.message : "Unauthorized" };
     }
     const admitted: Credentials = Object.freeze({ ...credentials });
-    this.admissions.set(admitted, { principal: request.principal, narrowing: request.narrowing });
+    this.admissions.set(admitted, { principal: request.principal, narrowing: request.narrowing, trusted: this.trustedCallers.has(request) });
     return { ok: true, credentials: admitted, ...(request.principal ? { principal: request.principal } : {}) };
   }
 
@@ -1115,6 +1172,17 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
     };
   }
 
+  /** True when the caller of `request` can set the baggage of the call (C10). */
+  private trustsCaller(request: ServerRequest<unknown>): boolean {
+    if (this.trustedCallers.has(request)) return true;
+    if (!this.trustBaggage) return false;
+    try {
+      return this.trustBaggage(request) === true;
+    } catch {
+      return false;
+    }
+  }
+
   /** Run a procedure for a request with a signal. */
   private async run(procedure: AnyProcedure, request: ServerRequest<unknown>, signal: AbortSignal | undefined): Promise<ServerResponse<unknown>> {
     // The call uses the storages that it takes until its end: the end of a stream, for a stream
@@ -1131,7 +1199,10 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
         const message = `The server cannot narrow the capability of the request: ${error instanceof Error ? error.message : String(error)}`;
         return errorResponse(request.id, Object.assign(new Error(message), { code: "INTERNAL_ERROR" }), request);
       }
-      const output = await invokeProcedure(procedure, request.payload, {
+      // The handler runs in the context of its caller (C10): its trace always, its baggage only
+      // when the caller is trusted
+      const caller = callerContext(request.metadata, this.trustsCaller(request));
+      const output = await otelContext.with(caller, () => invokeProcedure(procedure, request.payload, {
         registry: this.procedureRegistry,
         metadata: request.metadata,
         signal,
@@ -1153,7 +1224,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
         ...(request.principal !== undefined ? { principal: request.principal } : {}),
         // The bus of the remote events is the bus of the procedures (EVENTS.md)
         ...(this.publisher ? { bus: this.publisher.bus } : {}),
-      });
+      }));
       if (output.kind === "stream") {
         // The faces that collect a stream read this mark (roadmap R15)
         const unbounded = (procedure.metadata as { stream?: { unbounded?: boolean } } | undefined)?.stream?.unbounded === true;

package/src/tracing/otel.ts

@@ -0,0 +1,122 @@
+/**
+ * The context of OpenTelemetry for the calls of a client and the invocations of a host (roadmap
+ * item C8 of otel-ts, decisions D5 and D6). This module uses `@opentelemetry/api` only. The API
+ * does nothing until a program registers an SDK, for example with `startNodeTelemetry()` of
+ * `@mark1russell7/otel-ts/node`.
+ *
+ * - With an SDK, each call gets a span of the API, and the registered propagator writes the
+ *   context of the call into its metadata: `traceparent`, `tracestate` and `baggage`.
+ * - With no SDK, `startApiSpan` gives undefined, and the W3C code of `traceparent.ts` operates as
+ *   before (D6).
+ */
+import { context, createContextKey, isSpanContextValid, propagation, ROOT_CONTEXT, SpanStatusCode, trace } from "@opentelemetry/api";
+import type { Context, Span, SpanKind, TextMapSetter } from "@opentelemetry/api";
+
+/** The name of the tracer of the spans of this package */
+export const TRACER_NAME = "@procedures/client";
+
+/**
+ * The key of the mark `internal call`. It is the same key as the key of `withInternalCall` of
+ * `@mark1russell7/otel-ts/context`, because `createContextKey` gives `Symbol.for(description)`.
+ * The propagator of otel-ts sends the baggage only on a call with this mark. A test pins the
+ * description against otel-ts.
+ */
+export const INTERNAL_CALL_KEY: symbol = createContextKey("@mark1russell7/otel-ts/context internal call");
+
+/** This function gives `from` with the mark `internal call`. */
+export function asInternalCall(from: Context): Context {
+  return from.setValue(INTERNAL_CALL_KEY, true);
+}
+
+/**
+ * This function starts a span of the API, or gives undefined when no SDK gives the span ids of
+ * its own. With no SDK, the API gives a span with no ids, or with the ids of its parent.
+ */
+export function startApiSpan(name: string, kind: SpanKind, parent: Context): Span | undefined {
+  const parentSpan = trace.getSpanContext(parent);
+  const span = trace.getTracer(TRACER_NAME).startSpan(name, { kind }, parent);
+  const own = span.spanContext();
+  if (isSpanContextValid(own) && own.spanId !== parentSpan?.spanId) return span;
+  span.end();
+  return undefined;
+}
+
+/** This function ends `span`, with the status of `error` when the call failed. */
+export function endApiSpan(span: Span, error?: unknown): void {
+  if (error !== undefined) {
+    span.recordException(error instanceof Error ? error : String(error));
+    span.setStatus({ code: SpanStatusCode.ERROR, message: error instanceof Error ? error.message : String(error) });
+    const code = (error as { code?: unknown } | null)?.code;
+    if (typeof code === "string") span.setAttribute("procedure.error.code", code);
+  }
+  span.end();
+}
+
+const metadataSetter: TextMapSetter<Record<string, unknown>> = {
+  set: (carrier, key, value) => {
+    carrier[key] = value;
+  },
+};
+
+/** This function writes the context `from` into `metadata`, with the registered propagator. */
+export function injectContext(from: Context, metadata: Record<string, unknown>): void {
+  propagation.inject(from, metadata, metadataSetter);
+}
+
+/**
+ * This function gives the parent context of an invocation of a host: the active context, with the
+ * remote span of the `traceparent` and `tracestate` of `metadata` when they are valid. The baggage
+ * of the metadata is not read: the host reads it only from a trusted caller (`@procedures/peer`).
+ */
+export function remoteParent(metadata: Record<string, unknown>, from: Context = context.active()): Context {
+  const traceparent = metadata["traceparent"];
+  if (typeof traceparent !== "string") return from;
+  const carrier: Record<string, string> = { traceparent };
+  if (typeof metadata["tracestate"] === "string") carrier["tracestate"] = metadata["tracestate"];
+  const extracted = propagation.extract(from, carrier);
+  return isSpanContextValid(trace.getSpanContext(extracted) ?? { traceId: "", spanId: "", traceFlags: 0 }) ? extracted : from;
+}
+
+/** The trace context that the caller of a call gave in its metadata: `traceparent` and `tracestate`, strings only */
+export type CallerTrace = { readonly traceparent?: string; readonly tracestate?: string };
+
+/** This function gives the `traceparent` and `tracestate` of `metadata`, before the client writes its own. */
+export function callerTraceOf(metadata: Readonly<Record<string, unknown>>): CallerTrace {
+  const { traceparent, tracestate } = metadata;
+  return {
+    ...(typeof traceparent === "string" ? { traceparent } : {}),
+    ...(typeof tracestate === "string" ? { tracestate } : {}),
+  };
+}
+
+/**
+ * This function gives the parent context of a try of a call of a client (roadmap item C19 of
+ * otel-ts): the active context when it has a valid span, else the remote span of `caller`, the
+ * trace context that the caller gave in the metadata of the call. For example, `mark` gives the
+ * environment variables `TRACEPARENT` and `TRACESTATE` there. Without this, the span of the call
+ * started a new trace, and the propagator wrote that trace over the trace context of the caller.
+ */
+export function callParent(caller: CallerTrace, from: Context = context.active()): Context {
+  const active = trace.getSpanContext(from);
+  return active !== undefined && isSpanContextValid(active) ? from : remoteParent(caller, from);
+}
+
+/**
+ * This function gives the context of the caller of an invocation of a host (roadmap item C10 of
+ * otel-ts): the handler runs in it, so its logs, metrics, spans and nested calls carry the ids of
+ * the caller.
+ *
+ * - The remote span of the `traceparent` and `tracestate` of `metadata` is always the parent.
+ * - The `baggage` of `metadata` replaces the baggage of `from` only when the caller is trusted.
+ * - When the caller is not trusted, the context has no baggage: an end user cannot set the
+ *   baggage of the services. The baggage of `from` can come from the headers of the same request,
+ *   for example from the HTTP instrumentation of an SDK, so the function removes it too.
+ */
+export function callerContext(metadata: Record<string, unknown>, trusted: boolean, from: Context = context.active()): Context {
+  const parent = remoteParent(metadata, from);
+  if (!trusted) return propagation.getBaggage(parent) === undefined ? parent : propagation.deleteBaggage(parent);
+  const baggage = metadata["baggage"];
+  if (typeof baggage !== "string") return parent;
+  const extracted = propagation.getBaggage(propagation.extract(ROOT_CONTEXT, { baggage }));
+  return extracted === undefined ? parent : propagation.setBaggage(parent, extracted);
+}

package/src/tracing/traceparent.ts

@@ -4,16 +4,32 @@
  * the metadata of a call (and HTTP as the `traceparent` header). The tracing interceptor of a
  * server continues that trace, and gives it to the nested calls, so one trace goes from the
  * client to the last handler. Before, the client and the server made two traces.
+ *
+ * The checks of the ids are `isValidTraceId` and `isValidSpanId` of `@opentelemetry/api`
+ * (decision D7 of otel-ts). They refuse an id of only zeros.
  */
+import { isValidSpanId, isValidTraceId } from "@opentelemetry/api";
 
-/** The metadata key of the W3C trace context of a call. */
+/**
+ * The metadata key of the W3C trace context of a call.
+ *
+ * @deprecated With an SDK of OpenTelemetry, the registered propagator writes and reads the trace
+ * context (roadmap C8 of otel-ts). A later MINOR removes this export, when each app registers an SDK (D6).
+ */
 export const TRACEPARENT_METADATA_KEY = "traceparent";
 
+/** The form of version 00. The ids in it have only lowercase digits, as W3C Trace Context requires. */
 const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
-const ZERO_TRACE = "0".repeat(32);
-const ZERO_SPAN = "0".repeat(16);
 
-/** A trace context: the trace, the span of the caller, and the sampled flag. */
+/** An uppercase hex digit. The checks of the API accept it, but W3C Trace Context does not. */
+const UPPERCASE_HEX = /[A-F]/;
+
+/**
+ * A trace context: the trace, the span of the caller, and the sampled flag.
+ *
+ * @deprecated With an SDK of OpenTelemetry, the registered propagator writes and reads the trace
+ * context (roadmap C8 of otel-ts). A later MINOR removes this export, when each app registers an SDK (D6).
+ */
 export interface TraceContext {
   readonly traceId: string;
   readonly spanId: string;
@@ -51,34 +67,59 @@ function randomHex(bytes: number): string {
   return hex;
 }
 
-/** This function makes a new trace id: 32 random hex digits. */
+/**
+ * This function makes a new trace id: 32 random hex digits.
+ *
+ * @deprecated With an SDK of OpenTelemetry, the registered propagator writes and reads the trace
+ * context (roadmap C8 of otel-ts). A later MINOR removes this export, when each app registers an SDK (D6).
+ */
 export function newTraceId(): string {
   const id = randomHex(16);
-  return id === ZERO_TRACE ? newTraceId() : id;
+  return isValidTraceId(id) ? id : newTraceId();
 }
 
-/** This function makes a new span id: 16 random hex digits. */
+/**
+ * This function makes a new span id: 16 random hex digits.
+ *
+ * @deprecated With an SDK of OpenTelemetry, the registered propagator writes and reads the trace
+ * context (roadmap C8 of otel-ts). A later MINOR removes this export, when each app registers an SDK (D6).
+ */
 export function newSpanId(): string {
   const id = randomHex(8);
-  return id === ZERO_SPAN ? newSpanId() : id;
+  return isValidSpanId(id) ? id : newSpanId();
 }
 
-/** True when the ids have the W3C form. */
+/**
+ * This function gives true when the ids have the W3C form.
+ *
+ * @deprecated With an SDK of OpenTelemetry, the registered propagator writes and reads the trace
+ * context (roadmap C8 of otel-ts). A later MINOR removes this export, when each app registers an SDK (D6).
+ */
 export function isW3cIds(traceId: string, spanId: string): boolean {
-  return /^[0-9a-f]{32}$/.test(traceId) && /^[0-9a-f]{16}$/.test(spanId) && traceId !== ZERO_TRACE && spanId !== ZERO_SPAN;
+  return isValidTraceId(traceId) && isValidSpanId(spanId) && !UPPERCASE_HEX.test(traceId) && !UPPERCASE_HEX.test(spanId);
 }
 
-/** The `traceparent` of a trace and a span. */
+/**
+ * This function gives the `traceparent` of a trace and a span.
+ *
+ * @deprecated With an SDK of OpenTelemetry, the registered propagator writes and reads the trace
+ * context (roadmap C8 of otel-ts). A later MINOR removes this export, when each app registers an SDK (D6).
+ */
 export function formatTraceparent(traceId: string, spanId: string, sampled = true): string {
   return `00-${traceId}-${spanId}-${sampled ? "01" : "00"}`;
 }
 
-/** The trace context of a `traceparent` value, or undefined when it is not valid. */
+/**
+ * This function gives the trace context of a `traceparent` value, or undefined when it is not valid.
+ *
+ * @deprecated With an SDK of OpenTelemetry, the registered propagator writes and reads the trace
+ * context (roadmap C8 of otel-ts). A later MINOR removes this export, when each app registers an SDK (D6).
+ */
 export function parseTraceparent(value: unknown): TraceContext | undefined {
   if (typeof value !== "string") return undefined;
   const match = TRACEPARENT.exec(value.trim().toLowerCase());
   if (!match) return undefined;
-  const [, traceId, spanId, flags] = match;
-  if (traceId === ZERO_TRACE || spanId === ZERO_SPAN) return undefined;
-  return { traceId: traceId!, spanId: spanId!, sampled: (parseInt(flags!, 16) & 1) === 1 };
+  const [, traceId = "", spanId = "", flags = ""] = match;
+  if (!isValidTraceId(traceId) || !isValidSpanId(spanId)) return undefined;
+  return { traceId, spanId, sampled: (parseInt(flags, 16) & 1) === 1 };
 }