@procedures/client 0.0.0-stage → 0.1.0

package/src/procedures/interceptors.ts

@@ -0,0 +1,272 @@
+/**
+ * Interceptors for every host (roadmap 1.2): a timeout, tracing and metrics.
+ *
+ * An interceptor runs around each invocation of `invokeProcedure()`, also the nested calls. A
+ * host takes a list: `ProcedureServer({ interceptors })`, `new Client({ interceptors })` or
+ * `invokeProcedure(procedure, input, { interceptors })`. See `invoke.ts` for the types.
+ */
+
+import { InvocationError, type Interceptor, type Invocation, type ProcedureOutput } from "./invoke.js";
+import { pathToKey, type ProcedurePath } from "./types.js";
+
+// =============================================================================
+// Timeout
+// =============================================================================
+
+export interface TimeoutInterceptorOptions {
+  /** The time limit in milliseconds. 0 or less: no limit. */
+  ms: number;
+  /**
+   * The invocations to limit. The default is the calls of the host (depth 0): a nested call gets
+   * the signal of its parent, so the limit of the parent ends it too.
+   */
+  appliesTo?: ((invocation: Invocation) => boolean) | undefined;
+  /** This function gets each invocation that the interceptor limits (for tests and logs). */
+  onLimit?: ((invocation: Invocation) => void) | undefined;
+}
+
+/** A signal that aborts when one of the signals aborts. */
+function anySignal(signals: AbortSignal[]): AbortSignal {
+  const any = (AbortSignal as { any?: (signals: AbortSignal[]) => AbortSignal }).any;
+  if (any) return any(signals);
+  const controller = new AbortController();
+  for (const signal of signals) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+      break;
+    }
+    signal.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+  }
+  return controller.signal;
+}
+
+function timeoutError(path: ProcedurePath, ms: number): InvocationError {
+  return new InvocationError("TIMEOUT", `Procedure timed out after ${ms} ms: ${pathToKey(path)}`, path);
+}
+
+/**
+ * The items of a stream until the deadline. At the deadline, the reader gets the TIMEOUT error
+ * and the stream gets `return()`.
+ */
+async function* itemsUntil<T>(
+  items: AsyncGenerator<T, void, undefined>,
+  deadline: Promise<never>,
+  done: () => void,
+): AsyncGenerator<T, void, undefined> {
+  let finished = false;
+  try {
+    for (;;) {
+      const step = await Promise.race([items.next(), deadline]);
+      if (step.done) {
+        finished = true;
+        return;
+      }
+      yield step.value;
+    }
+  } finally {
+    done();
+    // The generator can wait on an await that the aborted signal ends later: do not wait for it
+    if (!finished) void items.return(undefined).catch(() => undefined);
+  }
+}
+
+/**
+ * This interceptor ends an invocation that runs longer than `ms`: the reader gets a TIMEOUT
+ * error, and the handler's signal aborts. A handler that ignores its signal can run on, but its
+ * result is not used. For a stream, the limit covers the whole stream.
+ */
+export function timeoutInterceptor(options: TimeoutInterceptorOptions): Interceptor {
+  const { ms } = options;
+  const appliesTo = options.appliesTo ?? ((invocation: Invocation) => invocation.depth === 0);
+  return async (invocation, next) => {
+    if (!(ms > 0) || !appliesTo(invocation)) return next();
+    options.onLimit?.(invocation);
+
+    const controller = new AbortController();
+    const signal = invocation.signal ? anySignal([invocation.signal, controller.signal]) : controller.signal;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const deadline = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => {
+        const error = timeoutError(invocation.path, ms);
+        controller.abort(error);
+        reject(error);
+      }, ms);
+    });
+    // A deadline that no one waits for must not be an unhandled rejection
+    deadline.catch(() => undefined);
+    const stop = (): void => clearTimeout(timer);
+
+    let output: ProcedureOutput<unknown>;
+    try {
+      output = await Promise.race([next({ signal }), deadline]);
+    } catch (error) {
+      stop();
+      throw error;
+    }
+    if (output.kind === "value") {
+      stop();
+      return output;
+    }
+    return { kind: "stream", items: itemsUntil(output.items, deadline, stop) };
+  };
+}
+
+// =============================================================================
+// Tracing
+// =============================================================================
+
+/** One invocation as a span of a trace. */
+export interface InvocationSpan {
+  readonly id: string;
+  /** The span of the invocation whose handler made this call. A call of a host has none. */
+  readonly parentId: string | undefined;
+  /** The same for every span of one call of a host. */
+  readonly traceId: string;
+  readonly path: ProcedurePath;
+  readonly key: string;
+  readonly depth: number;
+  /** The start, in milliseconds from `now()`. */
+  readonly start: number;
+  end: number | undefined;
+  durationMs: number | undefined;
+  status: "running" | "ok" | "error";
+  /** The message of the error. */
+  error?: string | undefined;
+  /** The code of an invocation error (`TIMEOUT`, `VALIDATION_ERROR` and so on). */
+  code?: string | undefined;
+  kind?: "value" | "stream" | undefined;
+  /** The number of items of a stream. */
+  items?: number | undefined;
+}
+
+export interface TracingInterceptorOptions {
+  /** This function gets each span when its invocation ends (a stream: when the stream ends). */
+  onSpan: (span: InvocationSpan) => void;
+  /** This function gets each span when its invocation starts. */
+  onStart?: ((span: InvocationSpan) => void) | undefined;
+  /** The clock. The default is `performance.now()`. */
+  now?: (() => number) | undefined;
+}
+
+let traceCount = 0;
+
+/**
+ * This interceptor makes a span for each invocation, with the span of its parent. A host can
+ * send the spans to a trace backend, a log or the site's trace view.
+ */
+export function tracingInterceptor(options: TracingInterceptorOptions): Interceptor {
+  const now = options.now ?? (() => performance.now());
+  const prefix = `t${++traceCount}-${Math.random().toString(36).slice(2, 8)}`;
+  let spanCount = 0;
+  /** The open spans, by the id of their invocation */
+  const open = new Map<number, InvocationSpan>();
+
+  const finish = (span: InvocationSpan, invocationId: number, error?: unknown): void => {
+    span.end = now();
+    span.durationMs = span.end - span.start;
+    if (error !== undefined) {
+      span.status = "error";
+      span.error = error instanceof Error ? error.message : String(error);
+      const code = (error as { code?: unknown }).code;
+      if (typeof code === "string") span.code = code;
+    } else {
+      span.status = "ok";
+    }
+    open.delete(invocationId);
+    options.onSpan(span);
+  };
+
+  return async (invocation, next) => {
+    const parent = invocation.parent ? open.get(invocation.parent.id) : undefined;
+    const id = `${prefix}-${++spanCount}`;
+    const span: InvocationSpan = {
+      id,
+      parentId: parent?.id,
+      traceId: parent?.traceId ?? id,
+      path: invocation.path,
+      key: pathToKey(invocation.path),
+      depth: invocation.depth,
+      start: now(),
+      end: undefined,
+      durationMs: undefined,
+      status: "running",
+    };
+    open.set(invocation.id, span);
+    options.onStart?.(span);
+
+    let output: ProcedureOutput<unknown>;
+    try {
+      output = await next();
+    } catch (error) {
+      finish(span, invocation.id, error);
+      throw error;
+    }
+    if (output.kind === "value") {
+      span.kind = "value";
+      finish(span, invocation.id);
+      return output;
+    }
+    span.kind = "stream";
+    span.items = 0;
+    const items = output.items;
+    return {
+      kind: "stream",
+      items: (async function* () {
+        let failure: unknown;
+        try {
+          for await (const item of items) {
+            span.items = (span.items ?? 0) + 1;
+            yield item;
+          }
+        } catch (error) {
+          failure = error;
+          throw error;
+        } finally {
+          finish(span, invocation.id, failure);
+        }
+      })(),
+    };
+  };
+}
+
+// =============================================================================
+// Metrics
+// =============================================================================
+
+/** The counts of one procedure. */
+export interface ProcedureMetrics {
+  calls: number;
+  errors: number;
+  /** The sum of the durations, in milliseconds. */
+  totalMs: number;
+  maxMs: number;
+}
+
+/** A metrics interceptor and its counts. */
+export interface MetricsInterceptor {
+  interceptor: Interceptor;
+  /** A copy of the counts, by procedure key. */
+  snapshot(): Record<string, ProcedureMetrics>;
+  reset(): void;
+}
+
+/** This function makes an interceptor that counts the calls, the errors and the time of each procedure. */
+export function metricsInterceptor(options: { now?: () => number } = {}): MetricsInterceptor {
+  const counts = new Map<string, ProcedureMetrics>();
+  const record = (key: string, duration: number, failed: boolean): void => {
+    const entry = counts.get(key) ?? { calls: 0, errors: 0, totalMs: 0, maxMs: 0 };
+    entry.calls++;
+    if (failed) entry.errors++;
+    entry.totalMs += duration;
+    entry.maxMs = Math.max(entry.maxMs, duration);
+    counts.set(key, entry);
+  };
+  return {
+    interceptor: tracingInterceptor({
+      onSpan: (span) => record(span.key, span.durationMs ?? 0, span.status === "error"),
+      ...(options.now ? { now: options.now } : {}),
+    }),
+    snapshot: () => Object.fromEntries([...counts].map(([key, value]) => [key, { ...value }])),
+    reset: () => counts.clear(),
+  };
+}

package/src/procedures/invoke.ts

@@ -0,0 +1,413 @@
+/**
+ * Procedure invocation: the one way to run a procedure.
+ *
+ * `Client.exec()`, `Client.route()`, the local transport and `ProcedureServer` run each
+ * procedure through `invokeProcedure()`. The function validates the input, makes the context,
+ * runs the handler and validates each output. Thus every host applies the same rules
+ * (ARCHITECTURE-PROPOSALS-2026-10 P1).
+ *
+ * A handler gives one value, or it is a generator that yields values (a stream). The result
+ * tells which: `{ kind: "value" }` or `{ kind: "stream" }`. A caller that wants one value uses
+ * `outputValue()` (the last item of a stream). A caller that wants each value uses `outputItems()`.
+ *
+ * Interceptors run around each invocation, the nested calls too (roadmap 1.2): policy, tracing,
+ * timeouts and metrics for every host. `interceptors.ts` has a timeout, a tracing and a metrics
+ * interceptor.
+ */
+
+import type {
+  AnyProcedure,
+  ProcedureClient,
+  ProcedureContext,
+  ProcedurePath,
+  RepositoryProvider,
+} from "./types.js";
+import { pathToKey } from "./types.js";
+import { validateSchema } from "./schema.js";
+import type { ProcedureRegistry } from "./registry.js";
+import { PROCEDURE_REGISTRY } from "./registry.js";
+import { nestedCallRefusal } from "./policy.js";
+import { scopeOf, withScope, type HydrationEvent } from "./ref.js";
+import type { EventBus } from "../events/types.js";
+import { getGlobalEventBus, withEventBusSignal } from "../events/bus.js";
+
+// =============================================================================
+// Errors
+// =============================================================================
+
+/** The reasons for which an invocation fails before or after the handler. */
+export type InvocationErrorCode =
+  | "NOT_FOUND"
+  | "NO_HANDLER"
+  | "NOT_EXPOSED"
+  | "NOT_DECLARED"
+  | "VALIDATION_ERROR"
+  | "OUTPUT_VALIDATION_ERROR"
+  | "NO_OUTPUT"
+  | "ABORTED"
+  | "TIMEOUT";
+
+/** An error of the invocation itself. An error that the handler throws passes through unchanged. */
+export class InvocationError extends Error {
+  override readonly name = "InvocationError";
+  readonly code: InvocationErrorCode;
+  readonly path: ProcedurePath;
+  readonly retryable: boolean = false;
+
+  constructor(code: InvocationErrorCode, message: string, path: ProcedurePath) {
+    super(message);
+    this.code = code;
+    this.path = path;
+  }
+}
+
+function abortError(path: ProcedurePath): InvocationError {
+  return new InvocationError("ABORTED", `Procedure was aborted: ${pathToKey(path)}`, path);
+}
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** The output of an invocation: one value, or a stream of values. */
+export type ProcedureOutput<T = unknown> =
+  | { readonly kind: "value"; readonly value: T }
+  | { readonly kind: "stream"; readonly items: AsyncGenerator<T, void, undefined> };
+
+export interface InvokeOptions {
+  /**
+   * The hydration observer of the program (see `HydrateOptions.onRef`). It goes to the context
+   * (`ctx.onRef`) and to the nested calls, so the hydrations of this program report to it.
+   */
+  onRef?: ((event: HydrationEvent) => void) | undefined;
+  /** The nested calls of `ctx.client` find their procedures here. The default is `PROCEDURE_REGISTRY`. */
+  registry?: ProcedureRegistry | undefined;
+  metadata?: Record<string, unknown> | undefined;
+  /** When the signal aborts, a stream stops, and its handler gets `return()`. */
+  signal?: AbortSignal | undefined;
+  repository?: RepositoryProvider | undefined;
+  /** The bus of `ctx.bus`. The default is the global bus of `getGlobalEventBus()`. */
+  bus?: EventBus | undefined;
+  /** The input is valid already (for example, the route resolver validated it). */
+  inputValidated?: boolean | undefined;
+  /**
+   * This client replaces the default `ctx.client`, for example a Client that sends unknown paths
+   * to its transport. A function gets the invocation, so its nested calls can name their parent.
+   */
+  client?: ProcedureClient | ((invocation: Invocation) => ProcedureClient) | undefined;
+  /**
+   * The expose rule of a server. A data-driven procedure (control flow, `runs-refs`, a procedure
+   * that `procedure.define` made) can call only the paths for which it gives true. A code
+   * procedure with `metadata.calls` can call what it declares and the exposed paths. See
+   * `policy.ts` (deep dive MCP-3).
+   */
+  expose?: ((path: ProcedurePath) => boolean) | undefined;
+  /** True: a code procedure without `metadata.calls` can call only the exposed paths. */
+  strictCalls?: boolean | undefined;
+  /** The interceptors of each invocation, the outermost first. The nested calls get them too. */
+  interceptors?: readonly Interceptor[] | undefined;
+  /** The invocation whose handler makes this call. The context client sets it for a nested call. */
+  parent?: Invocation | undefined;
+}
+
+// =============================================================================
+// Interceptors
+// =============================================================================
+
+let invocationCount = 0;
+
+/** One invocation, as an interceptor sees it. */
+export interface Invocation {
+  /** A number that identifies the invocation in this process. `next()` keeps it. */
+  readonly id: number;
+  readonly procedure: AnyProcedure;
+  readonly path: ProcedurePath;
+  /** The input before its validation. */
+  readonly input: unknown;
+  readonly metadata: Record<string, unknown>;
+  readonly signal: AbortSignal | undefined;
+  /** The invocation whose handler made this nested call. A call of a host has none. */
+  readonly parent: Invocation | undefined;
+  /** 0 for a call of a host, 1 for its nested calls, and so on. */
+  readonly depth: number;
+}
+
+/** The changes that an interceptor gives to the next step: the handler and the nested calls get them. */
+export interface InvocationChanges {
+  signal?: AbortSignal | undefined;
+  metadata?: Record<string, unknown> | undefined;
+}
+
+/** The rest of the chain: the next interceptors, then the validation and the handler. */
+export type InvocationNext = (changes?: InvocationChanges) => Promise<ProcedureOutput<unknown>>;
+
+/**
+ * A function around an invocation. It can examine the invocation, refuse it (throw), change its
+ * signal or metadata (`next(changes)`), and examine or wrap the output.
+ */
+export type Interceptor = (invocation: Invocation, next: InvocationNext) => Promise<ProcedureOutput<unknown>>;
+
+// =============================================================================
+// Invocation
+// =============================================================================
+
+/** True for a value that `for await` can read: a generator, a stream. A string is not one. */
+export function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
+  return (
+    value !== null &&
+    (typeof value === "object" || typeof value === "function") &&
+    typeof (value as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === "function"
+  );
+}
+
+/** The output (or one stream item), validated by the output schema of the procedure. */
+async function validateOutput(procedure: AnyProcedure, output: unknown): Promise<unknown> {
+  const result = await validateSchema(procedure.output, output);
+  if (!result.ok) {
+    throw new InvocationError(
+      "OUTPUT_VALIDATION_ERROR",
+      `Output validation failed for ${pathToKey(procedure.path)}: ${result.message}`,
+      procedure.path,
+    );
+  }
+  return result.value;
+}
+
+/** The next item, or an abort error when the signal aborts first. */
+function nextOrAbort<T>(iterator: AsyncIterator<T>, signal: AbortSignal, path: ProcedurePath): Promise<IteratorResult<T>> {
+  if (signal.aborted) return Promise.reject(abortError(path));
+  return new Promise((resolve, reject) => {
+    const onAbort = (): void => reject(abortError(path));
+    signal.addEventListener("abort", onAbort, { once: true });
+    iterator.next().then(
+      (result) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(result);
+      },
+      (error: unknown) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * The items of a handler's stream, each validated with the output schema. When the reader stops
+ * early or an item is not valid, the handler's generator gets `return()`, so its `finally` runs.
+ */
+async function* validatedItems(
+  procedure: AnyProcedure,
+  source: AsyncIterable<unknown>,
+  signal: AbortSignal | undefined,
+): AsyncGenerator<unknown, void, undefined> {
+  const iterator = source[Symbol.asyncIterator]();
+  let done = false;
+  let aborted = false;
+  try {
+    for (;;) {
+      let step: IteratorResult<unknown>;
+      try {
+        step = signal ? await nextOrAbort(iterator, signal, procedure.path) : await iterator.next();
+      } catch (error) {
+        // The handler threw (its generator is done), or the signal aborted (it is not)
+        if (error instanceof InvocationError && error.code === "ABORTED") aborted = true;
+        else done = true;
+        throw error;
+      }
+      if (step.done) {
+        done = true;
+        return;
+      }
+      yield await validateOutput(procedure, step.value);
+    }
+  } finally {
+    if (!done) {
+      // The generator of an aborted handler can wait on an await: do not wait for it
+      const closing = Promise.resolve(iterator.return?.()).catch(() => undefined);
+      if (!aborted) await closing;
+    }
+  }
+}
+
+/**
+ * This function runs a procedure: it validates the input, makes the context, runs the handler
+ * and validates the output. It throws an `InvocationError` for an invocation that cannot run,
+ * and the handler's own error when the handler throws. The interceptors of the options run
+ * around these steps.
+ */
+export async function invokeProcedure<TOutput = unknown>(
+  procedure: AnyProcedure,
+  input: unknown,
+  options: InvokeOptions = {},
+): Promise<ProcedureOutput<TOutput>> {
+  const { path } = procedure;
+  if (!procedure.handler) {
+    throw new InvocationError("NO_HANDLER", `Procedure has no handler: ${pathToKey(path)}`, path);
+  }
+  if (options.signal?.aborted) throw abortError(path);
+
+  const invocation: Invocation = {
+    id: ++invocationCount,
+    procedure,
+    path,
+    input,
+    metadata: options.metadata ?? {},
+    signal: options.signal,
+    parent: options.parent,
+    depth: options.parent ? options.parent.depth + 1 : 0,
+  };
+  const interceptors = options.interceptors ?? [];
+  if (interceptors.length === 0) return runInvocation<TOutput>(invocation, options);
+
+  const dispatch = (index: number, current: Invocation, currentOptions: InvokeOptions): Promise<ProcedureOutput<unknown>> => {
+    const interceptor = interceptors[index];
+    if (!interceptor) return runInvocation(current, currentOptions);
+    return interceptor(current, (changes) => {
+      if (!changes) return dispatch(index + 1, current, currentOptions);
+      const changed: Invocation = {
+        ...current,
+        signal: changes.signal ?? current.signal,
+        metadata: changes.metadata ?? current.metadata,
+      };
+      return dispatch(index + 1, changed, { ...currentOptions, signal: changed.signal, metadata: changed.metadata });
+    });
+  };
+  return dispatch(0, invocation, options) as Promise<ProcedureOutput<TOutput>>;
+}
+
+/** The end of the chain: the validation, the context, the handler and the output. */
+async function runInvocation<TOutput>(invocation: Invocation, options: InvokeOptions): Promise<ProcedureOutput<TOutput>> {
+  const { procedure, path, input } = invocation;
+  const handler = procedure.handler!;
+  if (options.signal?.aborted) throw abortError(path);
+
+  let data: unknown = input;
+  if (!options.inputValidated) {
+    // A synchronous schema gives its result at once, so the handler starts before an await
+    let parsed = validateSchema(procedure.input, input);
+    if (parsed instanceof Promise) parsed = await parsed;
+    if (!parsed.ok) {
+      throw new InvocationError(
+        "VALIDATION_ERROR",
+        `Input validation failed for ${pathToKey(path)}: ${parsed.message}`,
+        path,
+      );
+    }
+    // A parse makes a new object, without the hidden scope of a raw input (`withScope()`). The
+    // scope goes onto the parsed data, so a runner with a Zod schema can read the names of the
+    // caller (docs review DOC-10: before, each runner needed its own workaround).
+    data = parsed.value === input ? input : withScope(parsed.value, scopeOf(input));
+  }
+
+  // The handler starts here, before the first await (the site's trace depends on it)
+  const result: unknown = await handler(data, createProcedureContext(procedure, options, invocation));
+  if (isAsyncIterable(result)) {
+    return { kind: "stream", items: validatedItems(procedure, result, options.signal) as AsyncGenerator<TOutput, void, undefined> };
+  }
+  return { kind: "value", value: (await validateOutput(procedure, result)) as TOutput };
+}
+
+/** This function finds the procedure at a path in the registry of the options, then runs it. */
+export async function invokePath<TOutput = unknown>(
+  path: ProcedurePath,
+  input: unknown,
+  options: InvokeOptions = {},
+): Promise<ProcedureOutput<TOutput>> {
+  const procedure = (options.registry ?? PROCEDURE_REGISTRY).get(path);
+  if (!procedure) {
+    throw new InvocationError("NOT_FOUND", `Procedure not found: ${pathToKey(path)}`, path);
+  }
+  return invokeProcedure<TOutput>(procedure, input, options);
+}
+
+// =============================================================================
+// Consumption
+// =============================================================================
+
+/**
+ * One value of an output: the value, or the last item of a stream (the "sponge" mode). An
+ * empty stream is an error.
+ */
+export async function outputValue<T>(output: ProcedureOutput<T>, path: ProcedurePath = []): Promise<T> {
+  if (output.kind === "value") return output.value;
+  let last: { value: T } | undefined;
+  for await (const item of output.items) last = { value: item };
+  if (!last) {
+    throw new InvocationError("NO_OUTPUT", `Procedure gave no output: ${pathToKey(path)}`, path);
+  }
+  return last.value;
+}
+
+/** Each value of an output: the items of a stream, or the one value. */
+export async function* outputItems<T>(output: ProcedureOutput<T>): AsyncGenerator<T, void, undefined> {
+  if (output.kind === "value") {
+    yield output.value;
+    return;
+  }
+  yield* output.items;
+}
+
+/** The items of an output that `start` gives. Nothing runs until the reader asks for the first item. */
+export async function* streamOutput<T>(start: () => Promise<ProcedureOutput<T>>): AsyncGenerator<T, void, undefined> {
+  yield* outputItems(await start());
+}
+
+// =============================================================================
+// Context
+// =============================================================================
+
+/**
+ * The context of a procedure. Its `client` calls other procedures through `invokePath()` with
+ * the same options, so the nested calls get the same metadata, signal, rules and interceptors.
+ * With an invocation, the nested calls name it as their parent.
+ */
+export function createProcedureContext(
+  procedure: AnyProcedure,
+  options: InvokeOptions = {},
+  invocation?: Invocation,
+): ProcedureContext {
+  const nestedOptions: InvokeOptions = invocation ? { ...options, parent: invocation } : options;
+  let client: ProcedureClient;
+  if (typeof options.client === "function") {
+    client = invocation ? options.client(invocation) : registryClient(procedure, nestedOptions);
+  } else {
+    client = options.client ?? registryClient(procedure, nestedOptions);
+  }
+  const context: ProcedureContext = {
+    metadata: options.metadata ?? {},
+    path: procedure.path,
+    client,
+    registry: options.registry ?? PROCEDURE_REGISTRY,
+  };
+  if (options.signal) context.signal = options.signal;
+  if (options.repository) context.repository = options.repository;
+  if (options.onRef) context.onRef = options.onRef;
+  // Every context has a bus. With a signal, the waits of the handler on the bus end when the
+  // invocation aborts, so a stream handler that waits on ctx.bus.stream() can finish. (Before,
+  // no host set ctx.bus: deep dive CORE-15.)
+  const bus = options.bus ?? getGlobalEventBus();
+  context.bus = options.signal ? withEventBusSignal(bus, options.signal) : bus;
+  return context;
+}
+
+/** The client of a procedure's context: it runs the nested calls from the registry. */
+function registryClient(caller: AnyProcedure, options: InvokeOptions): ProcedureClient {
+  const start = <TOutput>(path: ProcedurePath, input: unknown): Promise<ProcedureOutput<TOutput>> => {
+    // The call policy of the host, with the immediate caller (BUGS-2026-07 H18, deep dive MCP-3).
+    // It runs before the lookup, so a refused path tells nothing about the procedure.
+    const refusal = nestedCallRefusal(caller, path, options);
+    if (refusal) {
+      return Promise.reject(new InvocationError(refusal.code, refusal.message, path));
+    }
+    return invokePath<TOutput>(path, input, options);
+  };
+  return {
+    async call<TInput, TOutput>(path: ProcedurePath, input: TInput): Promise<TOutput> {
+      return outputValue(await start<TOutput>(path, input), path);
+    },
+    stream<TInput, TOutput>(path: ProcedurePath, input: TInput): AsyncIterable<TOutput> {
+      return streamOutput(() => start<TOutput>(path, input));
+    },
+  };
+}