@procedures/client 0.2.3 → 0.4.0

package/src/procedures/idempotency.ts

@@ -0,0 +1,152 @@
+/**
+ * Idempotency of calls (roadmap R1).
+ *
+ * The retry middleware gives each call one idempotency key, and each try of the call sends the
+ * same key. `ProcedureServer` keeps the result of a keyed call to a procedure that is not
+ * repeatable. A second try with the same key gets that result, and the handler does not run
+ * again. So a retry cannot do a write two times.
+ */
+
+import type { Method } from "../client/types.js";
+import { methodToPath } from "../server/method.js";
+import type { AnyProcedure, Effects, ProcedurePath } from "./types.js";
+import { optionalMs, type Duration } from "../duration.js";
+import { TIMER_DEFAULTS } from "../timers.js";
+
+// This file imports no module of the invocation, so the retry middleware stays small in a browser
+
+/** The metadata key of the idempotency key of a call. Each try of one call sends the same key. */
+export const IDEMPOTENCY_KEY_METADATA = "idempotency-key";
+
+/** The longest idempotency key that a server accepts. A longer key is ignored. */
+export const MAX_IDEMPOTENCY_KEY_LENGTH = 200;
+
+/**
+ * True when a second call with the same input changes nothing more: the procedure is idempotent,
+ * or it changes nothing (`writes: []`). Undeclared effects are not repeatable.
+ */
+export function isRepeatable(effects: Effects | undefined): boolean {
+  if (effects === undefined) return false;
+  if (effects.idempotent === true) return true;
+  return effects.writes !== undefined && effects.writes.length === 0;
+}
+
+/**
+ * This function gives the `idempotent` option of the retry middleware from the procedures that
+ * the client knows: true for a repeatable procedure, false for another one, and undefined for a
+ * path that the registry does not have.
+ */
+export function idempotentIn(registry: { get(path: ProcedurePath): AnyProcedure | undefined }): (method: Method) => boolean | undefined {
+  return (method) => {
+    const procedure = registry.get(methodToPath(method));
+    if (procedure === undefined) return undefined;
+    const effects = (procedure.metadata as { effects?: Effects } | undefined)?.effects;
+    return isRepeatable(effects !== null && typeof effects === "object" ? effects : undefined);
+  };
+}
+
+/**
+ * This function gives the effects of the procedures that the client knows, by method: the
+ * `effects` option of the cache middleware (roadmap R13). A path that the registry does not have
+ * gives undefined.
+ */
+export function effectsIn(registry: { get(path: ProcedurePath): AnyProcedure | undefined }): (method: Method) => Effects | undefined {
+  return (method) => {
+    const effects = (registry.get(methodToPath(method))?.metadata as { effects?: Effects } | undefined)?.effects;
+    return effects !== null && typeof effects === "object" ? effects : undefined;
+  };
+}
+
+/** This function makes a new idempotency key: a random UUID. */
+export function newIdempotencyKey(): string {
+  const random = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto?.randomUUID;
+  if (random) return random.call(globalThis.crypto);
+  // An older runtime without randomUUID: 128 random bits from Math.random
+  let key = "";
+  for (let index = 0; index < 4; index++) key += Math.floor(Math.random() * 0x100000000).toString(16).padStart(8, "0");
+  return key;
+}
+
+/** The idempotency key of a call, from its metadata, or undefined. */
+export function idempotencyKeyOf(metadata: Record<string, unknown> | undefined): string | undefined {
+  const key = metadata?.[IDEMPOTENCY_KEY_METADATA];
+  return typeof key === "string" && key.length > 0 && key.length <= MAX_IDEMPOTENCY_KEY_LENGTH ? key : undefined;
+}
+
+/** The options of the idempotency cache of a server. */
+export interface IdempotencyOptions {
+  /** How long the server keeps a result after the call ends. The default is 10 minutes. */
+  readonly ttl?: Duration;
+  /** The most results that the server keeps. The oldest finished result goes first. The default is 1000. */
+  readonly maxEntries?: number;
+  /** The clock of the cache, in milliseconds. The default is `Date.now`. */
+  readonly now?: () => number;
+}
+
+interface Entry<T> {
+  readonly done: Promise<T>;
+  /** The end time of the call, or undefined while it runs. */
+  settledAt: number | undefined;
+}
+
+/**
+ * The results of keyed calls. The first call with a key runs. A call with the same key while the
+ * first runs waits for it. A later call gets the same result until the time to live ends.
+ */
+export class IdempotencyCache<T> {
+  private readonly entries = new Map<string, Entry<T>>();
+  private readonly ttlMs: number;
+  private readonly maxEntries: number;
+  private readonly now: () => number;
+
+  constructor(options: IdempotencyOptions = {}) {
+    this.ttlMs = optionalMs(options.ttl, "ttl") ?? TIMER_DEFAULTS.idempotency.ttlMs;
+    this.maxEntries = options.maxEntries ?? 1000;
+    this.now = options.now ?? Date.now;
+  }
+
+  /** The number of results and calls that the cache holds. */
+  get size(): number {
+    return this.entries.size;
+  }
+
+  /**
+   * The result of the call with this key. `run` starts only for the first call. `keep` tells if
+   * the cache keeps a result: a result that is not kept lets the next call with the key run again.
+   */
+  run(key: string, run: () => Promise<T>, keep: (result: T) => boolean): { result: Promise<T>; first: boolean } {
+    this.evict();
+    const existing = this.entries.get(key);
+    if (existing) return { result: existing.done, first: false };
+    const entry: Entry<T> = {
+      done: run().then(
+        (result) => {
+          if (keep(result)) entry.settledAt = this.now();
+          else if (this.entries.get(key) === entry) this.entries.delete(key);
+          return result;
+        },
+        (error: unknown) => {
+          if (this.entries.get(key) === entry) this.entries.delete(key);
+          throw error;
+        },
+      ),
+      settledAt: undefined,
+    };
+    this.entries.set(key, entry);
+    return { result: entry.done, first: true };
+  }
+
+  /** This function removes the expired results, and the oldest finished results above the limit. */
+  private evict(): void {
+    const now = this.now();
+    for (const [key, entry] of this.entries) {
+      if (entry.settledAt !== undefined && now - entry.settledAt >= this.ttlMs) this.entries.delete(key);
+    }
+    if (this.entries.size < this.maxEntries) return;
+    // A Map keeps the order of insertion, so the first finished entries are the oldest
+    for (const [key, entry] of this.entries) {
+      if (this.entries.size < this.maxEntries) break;
+      if (entry.settledAt !== undefined) this.entries.delete(key);
+    }
+  }
+}

package/src/procedures/index.ts

@@ -54,7 +54,22 @@ export {
   explainInvocation,
   checkEffects,
 } from "./capability.js";
-export { PURE_EFFECTS, REGISTRY_READ_EFFECTS, withEffects } from "./effects.js";
+export { PURE_EFFECTS, REGISTRY_READ_EFFECTS, withEffects, INFERRED_EFFECTS_METADATA_KEY, inferredEffectsOf, effectsValue } from "./effects.js";
+// One manifest type (roadmap R17)
+export { MANIFEST_FORMAT, describeProcedure as describeProcedureEntry, describeRegistry, exposedProcedures, hashOf } from "./manifest.js";
+export type { ProcedureEntry, ProcedureManifest, CliDescription, DescribeOptions, DescribeRegistryOptions } from "./manifest.js";
+// Idempotency of calls (roadmap R1)
+export {
+  IDEMPOTENCY_KEY_METADATA,
+  MAX_IDEMPOTENCY_KEY_LENGTH,
+  IdempotencyCache,
+  idempotencyKeyOf,
+  idempotentIn,
+  effectsIn,
+  isRepeatable,
+  newIdempotencyKey,
+} from "./idempotency.js";
+export type { IdempotencyOptions } from "./idempotency.js";
 export type { ToolHints, CapabilityRefusal, CapabilityRefusalReason, InvocationExplanation, EffectsViolation } from "./capability.js";
 
 // Registry
@@ -73,7 +88,7 @@ export type { ProcedureDefinition, ProcedureStub } from "./define.js";
 
 // Collection procedures
 export { createCollectionProcedures } from "./collection/index.js";
-export type { CollectionStorage, StorageMetadata } from "./collection/index.js";
+export type { CollectionStorage, StorageChanges, StorageMetadata } from "./collection/index.js";
 
 // Manual registration helpers
 export {
@@ -211,6 +226,7 @@ export type {
 export {
   defineProcedureProcedure,
   getProcedureProcedure,
+  manifestProcedure,
   listProceduresProcedure,
   deleteProcedureProcedure,
   metaProcedures,

package/src/procedures/interceptors.ts

@@ -8,14 +8,16 @@
 
 import { InvocationError, type Interceptor, type Invocation, type ProcedureOutput } from "./invoke.js";
 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";
 
 // =============================================================================
 // Timeout
 // =============================================================================
 
 export interface TimeoutInterceptorOptions {
-  /** The time limit in milliseconds. 0 or less: no limit. */
-  ms: number;
+  /** The time limit, for example `minutes(10)`. 0 or less: no limit. */
+  limit: Duration;
   /**
    * 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.
@@ -76,6 +78,14 @@ async function* itemsUntil<T>(
  * result is not used. For a stream, the limit covers the whole stream.
  */
 export function timeoutInterceptor(options: TimeoutInterceptorOptions): Interceptor {
+  return timeoutAfterMs({ ...options, ms: toMs(options.limit, "limit") });
+}
+
+/**
+ * The timeout interceptor with a limit in milliseconds. The invocation uses it for the deadline
+ * of a capability, which is a time in milliseconds.
+ */
+export function timeoutAfterMs(options: Omit<TimeoutInterceptorOptions, "limit"> & { ms: number }): Interceptor {
   const { ms } = options;
   const appliesTo = options.appliesTo ?? ((invocation: Invocation) => invocation.depth === 0);
   return async (invocation, next) => {
@@ -119,9 +129,14 @@ export function timeoutInterceptor(options: TimeoutInterceptorOptions): Intercep
 /** 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. */
+  /**
+   * The span of the invocation whose handler made this call. A call of a host has the span of its
+   * remote caller, when the caller sent a `traceparent` (roadmap R16), or none.
+   */
   readonly parentId: string | undefined;
-  /** The same for every span of one call of a host. */
+  /** True when the parent span is in another process: the caller of a host. */
+  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;
   readonly path: ProcedurePath;
   readonly key: string;
@@ -149,7 +164,6 @@ export interface TracingInterceptorOptions {
   now?: (() => number) | undefined;
 }
 
-let traceCount = 0;
 
 /**
  * This interceptor makes a span for each invocation, with the span of its parent. A host can
@@ -157,8 +171,6 @@ let traceCount = 0;
  */
 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>();
 
@@ -179,11 +191,15 @@ export function tracingInterceptor(options: TracingInterceptorOptions): Intercep
 
   return async (invocation, next) => {
     const parent = invocation.parent ? open.get(invocation.parent.id) : undefined;
-    const id = `${prefix}-${++spanCount}`;
+    // 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]);
+    // W3C span ids, so a trace backend can join the spans of the client and of the server
+    const id = newSpanId();
     const span: InvocationSpan = {
       id,
-      parentId: parent?.id,
-      traceId: parent?.traceId ?? id,
+      parentId: parent?.id ?? remote?.spanId,
+      ...(remote ? { remoteParent: true } : {}),
+      traceId: parent?.traceId ?? remote?.traceId ?? newTraceId(),
       path: invocation.path,
       key: pathToKey(invocation.path),
       depth: invocation.depth,
@@ -197,7 +213,8 @@ export function tracingInterceptor(options: TracingInterceptorOptions): Intercep
 
     let output: ProcedureOutput<unknown>;
     try {
-      output = await next();
+      // 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) } });
     } catch (error) {
       finish(span, invocation.id, error);
       throw error;

package/src/procedures/invoke.ts

@@ -39,7 +39,7 @@ import { PROCEDURE_REGISTRY } from "./registry.js";
 import { nestedCallRefusal } from "./policy.js";
 import { scopeOf, withScope, type HydrationEvent } from "./ref.js";
 import { UNLIMITED_CAPABILITY, capabilityRefusal, examinesNestedCall, narrowCapability, type CapabilityRefusalReason } from "./capability.js";
-import { timeoutInterceptor } from "./interceptors.js";
+import { timeoutAfterMs } from "./interceptors.js";
 import type { EventBus } from "../events/types.js";
 import { getGlobalEventBus, withEventBusSignal } from "../events/bus.js";
 
@@ -61,16 +61,29 @@ export type InvocationErrorCode =
   /** The capability of the call does not permit it (CAPABILITIES-2026-10). `reason` tells why. */
   | "FORBIDDEN";
 
+/**
+ * The reason of a `FORBIDDEN` error. It is a refusal of the capability, or a refusal of a module
+ * that the host configured:
+ * - `outside-root`: the input has a path outside the root of the host (`createFsModule({ root })`
+ *   of `@procedures/fs`).
+ * - `host-not-allowed`: the input has a URL whose host the host does not allow, or a redirect goes
+ *   to such a host (`createHttpModule({ allow })` of `@procedures/http`).
+ */
+export type ForbiddenReason = CapabilityRefusalReason | "outside-root" | "host-not-allowed";
+
 /** 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;
-  /** The reason of a `FORBIDDEN` error: `effects-undeclared`, `effects-exceeded` or `clearance`. */
-  readonly reason: CapabilityRefusalReason | undefined;
+  /**
+   * The reason of a `FORBIDDEN` error: `effects-undeclared`, `effects-exceeded`, `clearance`,
+   * `deadline`, `outside-root` or `host-not-allowed`.
+   */
+  readonly reason: ForbiddenReason | undefined;
 
-  constructor(code: InvocationErrorCode, message: string, path: ProcedurePath, reason?: CapabilityRefusalReason) {
+  constructor(code: InvocationErrorCode, message: string, path: ProcedurePath, reason?: ForbiddenReason) {
     super(message);
     this.code = code;
     this.path = path;
@@ -304,7 +317,7 @@ export async function invokeProcedure<TOutput = unknown>(
   const deadline = invocation.capability.deadline;
   const ownDeadline = deadline !== undefined && options.parent?.capability.deadline !== deadline;
   const interceptors = ownDeadline
-    ? [timeoutInterceptor({ ms: Math.max(0, deadline - Date.now()), appliesTo: () => true }), ...(options.interceptors ?? [])]
+    ? [timeoutAfterMs({ ms: Math.max(0, deadline - Date.now()), appliesTo: () => true }), ...(options.interceptors ?? [])]
     : (options.interceptors ?? []);
   if (interceptors.length === 0) return runInvocation<TOutput>(invocation, options);
 
@@ -468,6 +481,7 @@ export function createProcedureContext(
     resources: invocation && options.resources ? options.resources(invocation) : (EMPTY_RESOURCES as ResourcesOf),
   };
   if (options.signal) context.signal = options.signal;
+  if (options.expose) context.expose = options.expose;
   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

package/src/procedures/manifest.ts

@@ -0,0 +1,158 @@
+/**
+ * One manifest type (roadmap R17).
+ *
+ * Before, ten systems described procedures, with three manifest formats, three version schemes
+ * and no shared type: `procedure.get` gave booleans for the schemas, `manifest.generate` gave
+ * JSON Schemas but no effects, `_discovery.announce` gave no schemas, the MCP tool list gave the
+ * effects as hints, and none of them obeyed the expose rule of the host. This module is the one
+ * description: a function of a procedure, and a function of a registry with the expose rule.
+ * The introspection procedures, the compiler (R20) and the SDK generators read it.
+ */
+
+import { pathToKey, type AnyProcedure, type Effects, type ProcedurePath } from "./types.js";
+import { jsonSchemaOf, type JsonSchema } from "./schema.js";
+import { isDataDriven } from "./ref.js";
+import { isRuntimeDefined } from "./runtime-programs.js";
+
+/** The format of a manifest. A change that is not compatible makes a new format. */
+export const MANIFEST_FORMAT = "procedures.manifest/1";
+
+/** The command-line metadata of a procedure: how `mark` reads its arguments and prints its result. */
+export interface CliDescription {
+  readonly args?: readonly string[] | undefined;
+  readonly shorts?: Readonly<Record<string, string>> | undefined;
+  readonly output?: string | undefined;
+  readonly interactive?: boolean | undefined;
+}
+
+/** The description of one procedure. */
+export interface ProcedureEntry {
+  readonly path: ProcedurePath;
+  readonly key: string;
+  readonly description?: string | undefined;
+  readonly tags?: readonly string[] | undefined;
+  /** The declared effects. Absent: not declared. */
+  readonly effects?: Effects | undefined;
+  /** The JSON Schema of the input (draft-07). */
+  readonly input?: JsonSchema | undefined;
+  /** The JSON Schema of the output (draft-07). */
+  readonly output?: JsonSchema | undefined;
+  /** The procedures that a procedure of code calls (`metadata.calls`). */
+  readonly calls?: readonly string[] | undefined;
+  /** True: the stream of the procedure can run without an end (R15). */
+  readonly unboundedStream?: boolean | undefined;
+  /** True: the procedure runs its input as a program (control flow, a defined procedure). */
+  readonly dataDriven: boolean;
+  /** True: `procedure.define` made it at run time. */
+  readonly runtime: boolean;
+  /** True: the procedure has a handler, so it can run here. */
+  readonly hasHandler: boolean;
+  readonly deprecated?: boolean | undefined;
+  readonly cli?: CliDescription | undefined;
+}
+
+/** The description of the procedures of a registry. */
+export interface ProcedureManifest {
+  readonly format: typeof MANIFEST_FORMAT;
+  /** A hash of the entries: two manifests with the same hash describe the same procedures. */
+  readonly hash: string;
+  readonly procedures: readonly ProcedureEntry[];
+}
+
+/** The options of `describeProcedure` and `describeRegistry`. */
+export interface DescribeOptions {
+  /** False leaves out the JSON Schemas. The default is true. */
+  readonly schemas?: boolean | undefined;
+}
+
+/** The options of `describeRegistry`. */
+export interface DescribeRegistryOptions extends DescribeOptions {
+  /** The expose rule of the host: a procedure outside it is not in the manifest. */
+  readonly expose?: ((path: ProcedurePath) => boolean) | undefined;
+  /** More filtering: a procedure for which it gives false is not in the manifest. */
+  readonly include?: ((procedure: AnyProcedure) => boolean) | undefined;
+  /** True keeps the procedures without a handler (stubs of a remote host). The default is false. */
+  readonly withoutHandler?: boolean | undefined;
+}
+
+/** This function describes one procedure. */
+export function describeProcedure(procedure: AnyProcedure, options: DescribeOptions = {}): ProcedureEntry {
+  const meta = (procedure.metadata ?? {}) as Record<string, unknown>;
+  const schemas = options.schemas !== false;
+  const effects = meta["effects"];
+  const calls = meta["calls"];
+  const cli: CliDescription = {
+    ...(Array.isArray(meta["args"]) ? { args: meta["args"] as string[] } : {}),
+    ...(meta["shorts"] && typeof meta["shorts"] === "object" ? { shorts: meta["shorts"] as Record<string, string> } : {}),
+    ...(typeof meta["output"] === "string" ? { output: meta["output"] } : {}),
+    ...(typeof meta["interactive"] === "boolean" ? { interactive: meta["interactive"] } : {}),
+  };
+  const input = schemas ? jsonSchemaOf(procedure.input, { io: "input" }) : undefined;
+  const output = schemas ? jsonSchemaOf(procedure.output, { io: "output" }) : undefined;
+  return {
+    path: procedure.path,
+    key: pathToKey(procedure.path),
+    ...(typeof meta["description"] === "string" ? { description: meta["description"] } : {}),
+    ...(Array.isArray(meta["tags"]) ? { tags: meta["tags"] as string[] } : {}),
+    ...(effects && typeof effects === "object" ? { effects: effects as Effects } : {}),
+    ...(input ? { input } : {}),
+    ...(output ? { output } : {}),
+    ...(Array.isArray(calls) ? { calls: calls as string[] } : {}),
+    ...((meta["stream"] as { unbounded?: unknown } | undefined)?.unbounded === true ? { unboundedStream: true } : {}),
+    dataDriven: isDataDriven(procedure),
+    runtime: isRuntimeDefined(procedure),
+    hasHandler: typeof procedure.handler === "function",
+    ...(meta["deprecated"] === true ? { deprecated: true } : {}),
+    ...(Object.keys(cli).length > 0 ? { cli } : {}),
+  };
+}
+
+/** The procedures of a registry, as the expose rule of the host shows them. */
+export function exposedProcedures(
+  registry: { getAll(): AnyProcedure[] },
+  options: Pick<DescribeRegistryOptions, "expose" | "include" | "withoutHandler"> = {},
+): AnyProcedure[] {
+  return registry
+    .getAll()
+    .filter(
+      (procedure) =>
+        (options.withoutHandler === true || typeof procedure.handler === "function") &&
+        (!options.expose || options.expose(procedure.path)) &&
+        (!options.include || options.include(procedure)),
+    );
+}
+
+/**
+ * This function describes the procedures of a registry that the expose rule shows, in the order
+ * of their keys, with a hash of the description.
+ */
+export function describeRegistry(registry: { getAll(): AnyProcedure[] }, options: DescribeRegistryOptions = {}): ProcedureManifest {
+  const procedures = exposedProcedures(registry, options)
+    .map((procedure) => describeProcedure(procedure, options))
+    .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  return { format: MANIFEST_FORMAT, hash: hashOf(procedures), procedures };
+}
+
+/** A stable JSON text: the keys of each object in order. */
+function stableJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  const object = value as Record<string, unknown>;
+  return `{${Object.keys(object)
+    .sort()
+    .filter((key) => object[key] !== undefined)
+    .map((key) => `${JSON.stringify(key)}:${stableJson(object[key])}`)
+    .join(",")}}`;
+}
+
+/** A 64-bit FNV-1a hash of the stable JSON of a value, as 16 hex digits. */
+export function hashOf(value: unknown): string {
+  const text = stableJson(value);
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  for (let index = 0; index < text.length; index++) {
+    hash ^= BigInt(text.charCodeAt(index));
+    hash = (hash * prime) & 0xffffffffffffffffn;
+  }
+  return hash.toString(16).padStart(16, "0");
+}

package/src/procedures/ref.ts

@@ -22,7 +22,8 @@
  * - `"$never"`: Never execute during hydration, pass as pure data (with its whole subtree)
  * - `"$parent"`: Defer to parent procedure (pass as data)
  * - `"someName"`: Defer to the runner that gives this name in its `contextStack`
- *   (`dag.traverse` gives "dag.traverse", `core.catch` gives "catch")
+ *   (`dag.traverse` gives "dag.traverse". `client.tryCatch` gives no name: it is control flow,
+ *   and it runs its `try` and `catch` operands itself.)
  *
  * A deferred ref is data at every depth: hydration of the input that holds it does not run it.
  * The procedure that receives it runs it later (deep dive CORE-11).
@@ -681,7 +682,8 @@ export interface HydrateOptions {
 
   /**
    * The context names of the runner. A ref with `$when: "<name>"` runs only when this list has
-   * the name. A runner such as `core.catch` gives its own name here when it hydrates its operand.
+   * the name. A runner such as `dag.traverse` gives its own name here when it hydrates its operand.
+   * (Control flow such as `client.tryCatch` runs its operands itself and gives no name.)
    */
   contextStack?: string[] | undefined;
 

package/src/procedures/runtime-programs.ts

@@ -0,0 +1,27 @@
+/**
+ * The handlers that `procedure.define` made, with the program (the aggregation) of each. The
+ * registry is the only store of the procedures: a procedure is runtime-defined when its handler
+ * is a key here. (Before, a separate map kept them, and `procedure.delete` removed only the map
+ * entry: deep dive CORE-3.) The program is kept here, not only in the metadata: a caller that
+ * gives its own metadata to `procedure.define` replaces the metadata.
+ *
+ * This module imports nothing, so the manifest (R17) and `procedure.define` can both use it
+ * without an import cycle.
+ */
+
+const RUNTIME_PROGRAMS = new WeakMap<object, unknown>();
+
+/** This function records the program of a handler that `procedure.define` made. */
+export function markRuntimeProgram(handler: object, program: unknown): void {
+  RUNTIME_PROGRAMS.set(handler, program);
+}
+
+/** True for a procedure that `procedure.define` made. */
+export function isRuntimeDefined(procedure: { handler?: unknown }): boolean {
+  return typeof procedure.handler === "function" && RUNTIME_PROGRAMS.has(procedure.handler);
+}
+
+/** The program of a handler that `procedure.define` made, or undefined. */
+export function runtimeProgramOfHandler(handler: unknown): unknown {
+  return typeof handler === "function" ? RUNTIME_PROGRAMS.get(handler) : undefined;
+}

package/src/procedures/types.ts

@@ -75,6 +75,14 @@ export interface ProcedureMetadata {
    */
   effects?: Effects;
 
+  /**
+   * The stream of the procedure (roadmap R15). `unbounded: true`: the stream can run without an
+   * end (a `follow` of logs, the output of a server process). A face that collects a stream
+   * refuses such a call or stops it at a limit: HTTP without NDJSON refuses it, and MCP stops it
+   * at its stream limits.
+   */
+  stream?: { readonly unbounded?: boolean } | undefined;
+
   /** Custom metadata fields */
   [key: string]: unknown;
 }
@@ -260,6 +268,14 @@ export interface ProcedureContext {
    */
   registry?: ProcedureRegistryLike;
 
+  /**
+   * The expose rule of the host: the procedures that its callers reach. The introspection
+   * procedures (`procedure.list`, `procedure.get`, `procedure.manifest` and the others) show only
+   * these (roadmap R17: before, a handler could not know the rule, so an MCP tool listed the
+   * procedures that the host does not expose). Absent: every procedure.
+   */
+  expose?: ((path: ProcedurePath) => boolean) | undefined;
+
   /**
    * The hydration observer of the program that runs this procedure (`client.exec(ref, input,
    * { onRef })`). A procedure that hydrates refs itself (control flow, a runner) gives it to