@procedures/client 0.52.3 → 0.53.1

package/dist/tracing/traceparent.js.map

@@ -1 +1 @@
-{"version":3,"file":"traceparent.js","sourceRoot":"","sources":["../../src/tracing/traceparent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"traceparent.js","sourceRoot":"","sources":["../../src/tracing/traceparent.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/client",
-  "version": "0.52.3",
+  "version": "0.53.1",
   "description": "Procedures as data for TypeScript: define typed procedures once and call them in process, over HTTP, WebSocket, the CLI or MCP. Streaming, middleware, retries, caching and a JSON program format.",
   "keywords": [
     "rpc",
@@ -112,19 +112,29 @@
   },
   "dependencies": {
     "@mark1russell7/algebra": "^0.8.0",
-    "@mark1russell7/coeval": "^0.22.0",
+    "@mark1russell7/coeval": "^0.26.1",
     "@mark1russell7/collections": "^0.5.0",
     "@mark1russell7/quantity": "^0.3.0",
-    "@mark1russell7/service": "^0.6.0",
+    "@mark1russell7/service": "^0.8.3",
+    "@opentelemetry/api": "^1.9.0",
     "@types/ws": "^8.18.1",
     "ws": "^8.18.3",
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@mark1russell7/api-report": "^0.4.1",
+    "@mark1russell7/api-report": "^0.5.0",
     "@mark1russell7/cue": "^2.1.1",
-    "@mark1russell7/rigor-bench": "^0.2.25",
+    "@mark1russell7/otel-ts": "^0.6.0",
+    "@mark1russell7/rigor-bench": "^0.2.33",
     "@mark1russell7/rigor-statistics": "^0.1.9",
+    "@mark1russell7/rigor-testkit": "^0.1.2",
+    "@opentelemetry/api-logs": "^0.223.0",
+    "@opentelemetry/context-async-hooks": "^2.12.0",
+    "@opentelemetry/core": "^2.12.0",
+    "@opentelemetry/sdk-logs": "^0.223.0",
+    "@opentelemetry/sdk-metrics": "^2.12.0",
+    "@opentelemetry/sdk-node": "~0.223.0",
+    "@opentelemetry/sdk-trace-base": "^2.12.0",
     "@stryker-mutator/core": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
     "@types/express": "^5.0.0",

package/src/adapters/http/server/cors.ts

@@ -50,6 +50,8 @@ export const DEFAULT_CORS_HEADERS: readonly string[] = Object.freeze([
   HTTPHeaders.SPAN_ID,
   HTTPHeaders.PARENT_SPAN_ID,
   "traceparent",
+  "tracestate",
+  "baggage",
   PROTOCOL_HEADER,
   HTTPHeaders.METADATA,
   // The narrowing key of a call (CLI-30)

package/src/adapters/port/transport.ts

@@ -45,6 +45,50 @@ export interface PortLike {
   start?(): void;
 }
 
+/** The listener of a port of the main process of Electron: it gets an event, and the message is its `data`. */
+type MainListener = (event: { readonly data: unknown }) => void;
+
+/**
+ * A port of the main process of Electron (`MessagePortMain`). The listener of its `on` gets an event with the message
+ * in `data`. The Node form of `PortLike` gets the message itself, so `electronPortOf` changes the form.
+ */
+export interface MainPortLike {
+  postMessage(message: unknown): void;
+  on(type: "message", listener: MainListener): unknown;
+  off?(type: "message", listener: MainListener): unknown;
+  start(): void;
+}
+
+/**
+ * This function gives the `PortLike` of a port of the main process of Electron. Each listener gets the `data` of the
+ * event. `off` removes the listener that `on` added, so the close of a `PortTransport` stops to listen.
+ *
+ * @example
+ * ```typescript
+ * const { port1, port2 } = new MessageChannelMain();
+ * new PortTransport(electronPortOf(port1), { serve: server });
+ * window.webContents.postMessage("ports", null, [port2]);
+ * ```
+ */
+export function electronPortOf(port: MainPortLike): PortLike {
+  const listeners = new Map<(data: unknown) => void, MainListener>();
+  return {
+    postMessage: (message) => port.postMessage(message),
+    on(type, listener) {
+      const each: MainListener = (event) => listener(event.data);
+      listeners.set(listener, each);
+      return port.on(type, each);
+    },
+    off(type, listener) {
+      const each = listeners.get(listener);
+      if (each === undefined) return undefined;
+      listeners.delete(listener);
+      return port.off?.(type, each);
+    },
+    start: () => port.start(),
+  };
+}
+
 /** The options of a `PortTransport`. */
 export interface PortTransportOptions {
   /** The handler of the calls of the other side, for example a `ProcedureServer`. */

package/src/browser.ts

@@ -469,8 +469,8 @@ export type { MachineDocument, MachineTransition, MachineTransitionDef, MachineT
 export { TIMER_DEFAULTS } from "./timers.js";
 export type { TimerDefaults } from "./timers.js";
 // The transport over a message port: a Web Worker, a MessageChannel (roadmap R27)
-export { PortTransport } from "./adapters/port/transport.js";
-export type { PortLike, PortTransportOptions } from "./adapters/port/transport.js";
+export { PortTransport, electronPortOf } from "./adapters/port/transport.js";
+export type { MainPortLike, PortLike, PortTransportOptions } from "./adapters/port/transport.js";
 // The W3C trace context: one trace from the client to the handler (roadmap R16)
 export { TRACEPARENT_METADATA_KEY, formatTraceparent, parseTraceparent, newTraceId, newSpanId, isW3cIds } from "./tracing/traceparent.js";
 export type { TraceContext } from "./tracing/traceparent.js";

package/src/client/batch-executor.ts

@@ -460,6 +460,9 @@ export function determineStrategy(
 
 /**
  * Semaphore for limiting concurrent executions.
+ *
+ * @deprecated Use `semaphore()` of `@mark1russell7/collections`, the home of the semaphore. Its `run(task)` replaces
+ * `withPermit(fn)`, and its `acquire()` gives the release function. The next MINOR break of `@procedures/client` removes this class.
  */
 export class Semaphore {
   private permits: number;

package/src/client/client.ts

@@ -70,6 +70,8 @@ import {
 import { narrowCapability } from "../procedures/capability.js";
 import { DEADLINE_METADATA_KEY, TIMEOUT_METADATA_KEY, absorbTimeout, writeRemainingTime } from "./deadline.js";
 import { ms } from "../duration.js";
+import { context as otelContext, SpanKind, trace } from "@opentelemetry/api";
+import { asInternalCall, callParent, callerTraceOf, endApiSpan, injectContext, startApiSpan, type CallerTrace } from "../tracing/otel.js";
 import type { Capability, ClearanceOrder, NestedCallOptions } from "../procedures/types.js";
 import { PROCEDURE_REGISTRY } from "../procedures/registry.js";
 import { validateSchema } from "../procedures/schema.js";
@@ -825,8 +827,9 @@ export class Client<TContext = {}> {
     // remaining time again for each try (roadmap R10)
     absorbTimeout(message.metadata);
 
-    // Compose middleware chain
-    const runner = this.composeMiddleware<TReq, TRes>();
+    // Compose middleware chain. The trace context that the caller gave in the metadata is read
+    // before a middleware or a try writes its own (roadmap C19 of otel-ts).
+    const runner = this.composeMiddleware<TReq, TRes>(callerTraceOf(message.metadata as Record<string, unknown>));
 
     // Execute through middleware chain
     const context: ClientContext<TReq> = { message };
@@ -897,7 +900,7 @@ export class Client<TContext = {}> {
         metadata["timeout"] = NO_SUBSCRIPTION_TIMEOUT as unknown as NonNullable<Metadata["timeout"]>;
         Object.assign(metadata, message.metadata);
         absorbTimeout(metadata);
-        return this.composeMiddleware<TReq, TRes>()({ message: { ...message, metadata } });
+        return this.composeMiddleware<TReq, TRes>(callerTraceOf(metadata as Record<string, unknown>))({ message: { ...message, metadata } });
       };
       this.subscriptionTransport = { send };
     }
@@ -907,17 +910,40 @@ export class Client<TContext = {}> {
   /**
    * Compose middleware chain using universal middleware composition.
    *
+   * @param caller - The trace context that the caller gave in the metadata of the call. It is the
+   *   parent of the span of each try when no span is active (roadmap C19 of otel-ts).
    * @returns Composed runner function
    * @private
    */
-  private composeMiddleware<TReq, TRes>(): ClientRunner<TReq, TRes> {
+  private composeMiddleware<TReq, TRes>(caller: CallerTrace): ClientRunner<TReq, TRes> {
     // Innermost function: call transport
     const self = this;
     const transportRunner: ClientRunner<TReq, TRes> = async function* (context: ClientContext<TReq>) {
       // The remaining time of the deadline goes with each try, so the server stops the handler
       // when this client stops waiting (roadmap R10)
       writeRemainingTime(context.message.metadata);
-      yield* self.transport.send<TReq, TRes>(context.message);
+      // With an SDK of OpenTelemetry, each try is a span of the API, and the propagator writes its
+      // context into the metadata, with the mark of an internal call (roadmap C8 of otel-ts)
+      const { metadata, method } = context.message;
+      const active = callParent(caller, otelContext.active());
+      const span = startApiSpan(`${method.service}.${method.operation}`, SpanKind.CLIENT, active);
+      if (span === undefined) {
+        yield* self.transport.send<TReq, TRes>(context.message);
+        return;
+      }
+      const own = span.spanContext();
+      const parent = trace.getSpanContext(active);
+      metadata.tracing = { traceId: own.traceId, spanId: own.spanId, ...(parent ? { parentSpanId: parent.spanId } : {}) };
+      injectContext(asInternalCall(trace.setSpan(active, span)), metadata as Record<string, unknown>);
+      let failure: unknown;
+      try {
+        yield* self.transport.send<TReq, TRes>(context.message);
+      } catch (error) {
+        failure = error;
+        throw error;
+      } finally {
+        endApiSpan(span, failure);
+      }
     };
 
     // The first middleware is the outermost one (onion model)

package/src/client/middleware/cache.ts

@@ -137,6 +137,8 @@ const VOLATILE_METADATA = new Set([
   "idempotency-key",
   "procedure-timeout",
   "traceparent",
+  "tracestate",
+  "baggage",
 ]);
 
 /** The part of the metadata that can change a response. */

package/src/client/middleware/rate-limit.ts

@@ -308,8 +308,10 @@ export function createRateLimitMiddleware(
     while (queue.length > 0) {
       const decision = take();
       if (!decision.allowed) {
-        // The time until the next whole token
-        const wait = Math.max(1, Math.ceil(valueIn(decision.retryAfter, "ms")));
+        // The time until the next whole token. A take of one unit is never over a burst of 1 or more,
+        // so a capacity refusal does not occur here. If it occurs, the queue waits one window.
+        const wait =
+          decision.cause === "capacity" ? Math.max(1, window) : Math.max(1, Math.ceil(valueIn(decision.retryAfter, "ms")));
         drainTimer = clock.after(wait, () => {
           drainTimer = undefined;
           scheduleDrain();

package/src/procedures/interceptors.ts

@@ -10,6 +10,8 @@ import { InvocationError, closableUnread, type Interceptor, type Invocation, typ
 import { pathToKey, type ProcedurePath } from "./types.js";
 import { toMs, type Duration } from "../duration.js";
 import { TRACEPARENT_METADATA_KEY, formatTraceparent, newSpanId, newTraceId, parseTraceparent } from "../tracing/traceparent.js";
+import { context as otelContext, isSpanContextValid, SpanKind, trace, type Span } from "@opentelemetry/api";
+import { endApiSpan, remoteParent, startApiSpan } from "../tracing/otel.js";
 
 // =============================================================================
 // Timeout
@@ -134,7 +136,10 @@ export interface InvocationSpan {
    * remote caller, when the caller sent a `traceparent` (roadmap R16), or none.
    */
   readonly parentId: string | undefined;
-  /** True when the parent span is in another process: the caller of a host. */
+  /**
+   * True when the parent span came from the `traceparent` of the call: the caller of a host. With an
+   * SDK of OpenTelemetry, a local call of a client also has a remote parent: the span of its client.
+   */
   readonly remoteParent?: boolean | undefined;
   /** The same for every span of one call of a host, and of its caller when it sent a trace. */
   readonly traceId: string;
@@ -162,6 +167,12 @@ export interface TracingInterceptorOptions {
   onStart?: ((span: InvocationSpan) => void) | undefined;
   /** The clock. The default is `performance.now()`. */
   now?: (() => number) | undefined;
+  /**
+   * With an SDK of OpenTelemetry, each invocation is also a span of the API, and the span ids come
+   * from it: a host span (`SERVER`) for a call of a host, an `INTERNAL` span for a nested call.
+   * The handler runs in the context of its span. Default: true. With no SDK, this option does nothing.
+   */
+  apiSpans?: boolean | undefined;
 }
 
 
@@ -173,6 +184,8 @@ export function tracingInterceptor(options: TracingInterceptorOptions): Intercep
   const now = options.now ?? (() => performance.now());
   /** The open spans, by the id of their invocation */
   const open = new Map<number, InvocationSpan>();
+  /** The open spans of the API, by the id of their invocation */
+  const apiOpen = new Map<number, Span>();
 
   const finish = (span: InvocationSpan, invocationId: number, error?: unknown): void => {
     span.end = now();
@@ -186,22 +199,35 @@ export function tracingInterceptor(options: TracingInterceptorOptions): Intercep
       span.status = "ok";
     }
     open.delete(invocationId);
+    const apiSpan = apiOpen.get(invocationId);
+    if (apiSpan !== undefined) {
+      apiOpen.delete(invocationId);
+      endApiSpan(apiSpan, error);
+    }
     options.onSpan(span);
   };
 
   return async (invocation, next) => {
     const parent = invocation.parent ? open.get(invocation.parent.id) : undefined;
-    // A call of a host continues the trace of its caller (W3C traceparent, roadmap R16)
-    const remote = parent ? undefined : parseTraceparent(invocation.metadata[TRACEPARENT_METADATA_KEY]);
+    const key = pathToKey(invocation.path);
+    // With an SDK, the span of the API gives the ids (roadmap C8 of otel-ts, D5). The parent is the
+    // span of the parent invocation, else the span of the traceparent of the call.
+    const parentApi = invocation.parent ? apiOpen.get(invocation.parent.id) : undefined;
+    const apiParent = parentApi !== undefined ? trace.setSpan(otelContext.active(), parentApi) : remoteParent(invocation.metadata);
+    const apiSpan = options.apiSpans === false ? undefined : startApiSpan(key, invocation.parent ? SpanKind.INTERNAL : SpanKind.SERVER, apiParent);
+    const apiParentSpan = apiSpan === undefined ? undefined : trace.getSpanContext(apiParent);
+    // With no SDK: a call of a host continues the trace of its caller (W3C traceparent, roadmap R16)
+    const remote = parent || apiSpan ? undefined : parseTraceparent(invocation.metadata[TRACEPARENT_METADATA_KEY]);
     // W3C span ids, so a trace backend can join the spans of the client and of the server
-    const id = newSpanId();
+    const id = apiSpan?.spanContext().spanId ?? newSpanId();
+    const apiParentId = apiParentSpan !== undefined && isSpanContextValid(apiParentSpan) ? apiParentSpan.spanId : undefined;
     const span: InvocationSpan = {
       id,
-      parentId: parent?.id ?? remote?.spanId,
-      ...(remote ? { remoteParent: true } : {}),
-      traceId: parent?.traceId ?? remote?.traceId ?? newTraceId(),
+      parentId: apiSpan ? apiParentId : (parent?.id ?? remote?.spanId),
+      ...(remote || (apiParentId !== undefined && apiParentSpan?.isRemote === true) ? { remoteParent: true } : {}),
+      traceId: apiSpan?.spanContext().traceId ?? parent?.traceId ?? remote?.traceId ?? newTraceId(),
       path: invocation.path,
-      key: pathToKey(invocation.path),
+      key,
       depth: invocation.depth,
       start: now(),
       end: undefined,
@@ -209,12 +235,16 @@ export function tracingInterceptor(options: TracingInterceptorOptions): Intercep
       status: "running",
     };
     open.set(invocation.id, span);
+    if (apiSpan !== undefined) apiOpen.set(invocation.id, apiSpan);
     options.onStart?.(span);
 
     let output: ProcedureOutput<unknown>;
     try {
       // The nested calls (and their remote calls) carry the span of this invocation (R16)
-      output = await next({ metadata: { ...invocation.metadata, [TRACEPARENT_METADATA_KEY]: formatTraceparent(span.traceId, id) } });
+      const sampled = apiSpan === undefined || (apiSpan.spanContext().traceFlags & 1) === 1;
+      const run = () => next({ metadata: { ...invocation.metadata, [TRACEPARENT_METADATA_KEY]: formatTraceparent(span.traceId, id, sampled) } });
+      // The handler runs in the context of its span, so its logs, metrics and calls get the ids
+      output = await (apiSpan === undefined ? run() : otelContext.with(trace.setSpan(apiParent, apiSpan), run));
     } catch (error) {
       finish(span, invocation.id, error);
       throw error;
@@ -286,6 +316,7 @@ export function metricsInterceptor(options: { now?: () => number } = {}): Metric
   };
   return {
     interceptor: tracingInterceptor({
+      apiSpans: false,
       onSpan: (span) => record(span.key, span.durationMs ?? 0, span.status === "error"),
       ...(options.now ? { now: options.now } : {}),
     }),

package/src/server/host-policy.ts

@@ -96,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;
   /**
@@ -137,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;
@@ -190,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,
@@ -212,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,17 @@ 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.
@@ -497,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 =
@@ -937,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;
@@ -953,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 {
@@ -966,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) {
@@ -1063,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 } : {}) };
   }
 
@@ -1144,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
@@ -1160,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,
@@ -1182,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;