@procedures/client 0.46.0 → 0.47.1

package/src/adapters/websocket/server/transport.ts

@@ -13,7 +13,8 @@
 
 import type { IncomingMessage } from "http";
 import type { Duplex } from "stream";
-import { WebSocketServer, WebSocket } from "ws";
+import { createRequire } from "node:module";
+import type { WebSocketServer, WebSocket } from "ws";
 import type { ServerTransport, ServerRequest } from "../../../server/types.js";
 import type { Message, ResponseItem, Transport } from "../../../client/types.js";
 import { pathToMethod } from "../../../server/method.js";
@@ -44,6 +45,17 @@ import {
   type Subscription,
 } from "../../../events/remote.js";
 
+/** The `readyState` of an open socket: `WebSocket.OPEN` of `ws`. */
+const OPEN = 1;
+
+/**
+ * This function gives the `WebSocketServer` class of `ws`. The start of the first server loads the
+ * package, not the import of this file: a process without a socket does not load `ws` (roadmap O93).
+ */
+function webSocketServerClass(): typeof WebSocketServer {
+  return (createRequire(import.meta.url)("ws") as { WebSocketServer: typeof WebSocketServer }).WebSocketServer;
+}
+
 /**
  * WebSocket server transport adapter.
  *
@@ -192,7 +204,7 @@ export class WebSocketServerTransport implements ServerTransport {
     this.intakeStopped = false;
     if (this.wss) return;
     // The "no server" mode: upgrade() takes the upgrades of the path, and leaves the others alone
-    this.wss = new WebSocketServer({
+    this.wss = new (webSocketServerClass())({
       noServer: true,
       path: this.options.path,
       perMessageDeflate: this.options.perMessageDeflate,
@@ -396,7 +408,7 @@ export class WebSocketServerTransport implements ServerTransport {
     const credentials = requestCredentials({ headers: req.headers as Record<string, unknown>, url: req.url, socket: req.socket }, { tokenQuery: "token" });
 
     // The calls of this connection in the two directions (roadmap R24)
-    const isOpen = (): boolean => ws.readyState === WebSocket.OPEN;
+    const isOpen = (): boolean => ws.readyState === OPEN;
     const send = (frame: WebSocketMessage): void => this.send(ws, frame);
     this.channels.set(connectionId, {
       incoming: new IncomingCalls({
@@ -573,7 +585,7 @@ export class WebSocketServerTransport implements ServerTransport {
    * the socket has written this frame, or the signal aborts.
    */
   private sendWithBackpressure(ws: WebSocket, message: WebSocketMessage, signal: AbortSignal): Promise<void> {
-    if (ws.readyState !== WebSocket.OPEN) return Promise.resolve();
+    if (ws.readyState !== OPEN) return Promise.resolve();
     return new Promise<void>((resolve) => {
       let waiting = false;
       const onAbort = (): void => resolve();
@@ -618,7 +630,7 @@ export class WebSocketServerTransport implements ServerTransport {
    * Send message to client.
    */
   private send(ws: WebSocket, message: WebSocketMessage): void {
-    if (ws.readyState === WebSocket.OPEN) {
+    if (ws.readyState === OPEN) {
       ws.send(JSON.stringify(message));
     }
   }

package/src/browser.ts

@@ -194,6 +194,10 @@ export {
   registerModules,
   createRegistry,
   registerClientProcedures,
+  // The lazy registry (roadmap O93)
+  createLazyRegistry,
+  resolveIn,
+  loadAllIn,
   callerOf,
   // Procedure reference system (procedure-as-data)
   PROCEDURE_SYMBOL,
@@ -224,6 +228,7 @@ export {
   RAW_INPUT_TAG,
   takesRawInput,
   rawInputRule,
+  preloadRefPaths,
   MAX_DATA_DEPTH,
   LITERAL_KEY,
   isLiteral,
@@ -261,6 +266,8 @@ export {
   // Every core procedure (math, comparison, string, type, object, array, meta too). Not registered by default.
   allCoreProcedures,
   allCoreModules,
+  // Only the math procedures: a bundle that imports only these gets no other core procedure (roadmap O95)
+  mathProcedures,
   chainProcedure,
   traceProcedure,
   parallelProcedure,
@@ -361,6 +368,10 @@ export type {
   CallerOptions,
   RegistrationOptions,
   ProcedureRegistryLike,
+  LazyRegistryOptions,
+  RegistryResolver,
+  ProcedureRegistryOptions,
+  ResolvingRegistry,
   ProcedureDefinition,
   ProcedureStub,
   InferProcedureInput,

package/src/client/client.ts

@@ -52,7 +52,7 @@ import type {
   StreamingCallResponse,
   ProcedureCallResult,
 } from "./call-types.js";
-import { buildResponse, toMiddlewareContext } from "./call-types.js";
+import { buildResponse, flattenRoute, toMiddlewareContext } from "./call-types.js";
 import { RouteResolver, type ResolvedRoute, type RouteResolutionResult } from "./route-resolver.js";
 import { BatchExecutor, type ExecutionContext } from "./batch-executor.js";
 import type { ProcedureRegistry } from "../procedures/registry.js";
@@ -88,6 +88,7 @@ import {
   isAnyProcedureRef,
   isPlainObject,
   normalizeRef,
+  preloadRefPaths,
   rawInputRule,
   type ProcedureRef,
   type AnyProcedureRef,
@@ -566,6 +567,15 @@ export class Client<TContext = {}> {
    * `root` starts the root call.
    */
   private runRef(ref: ProcedureRef, caller: CallerContext, root: (path: ProcedurePath, input: unknown) => unknown): Promise<unknown> {
+    // A lazy registry loads the packages of the paths of the program first: the raw-input rule
+    // below reads only the procedures that have loaded (roadmap O93). An eager registry does not wait.
+    const preload = preloadRefPaths(this.procedureRegistry, ref);
+    if (preload) return preload.then(() => this.startProgram(ref, caller, root));
+    return this.startProgram(ref, caller, root);
+  }
+
+  /** This function starts a program on the kernel, after the paths of a lazy registry loaded. */
+  private startProgram(ref: ProcedureRef, caller: CallerContext, root: (path: ProcedurePath, input: unknown) => unknown): Promise<unknown> {
     // A procedure that takes its input raw (control flow, the `runs-refs` and `raw-input` tags,
     // `procedure.define`) gets its operand refs RAW: it runs them itself, with correct
     // ordering/laziness/error-scoping. Eagerly hydrating here would run the operands up-front
@@ -703,7 +713,8 @@ export class Client<TContext = {}> {
     input: unknown,
     caller: CallerContext = {}
   ): Promise<TOutput> {
-    const procedure = this.procedureRegistry.get(path);
+    // A miss of a lazy registry loads the packages of the path (roadmap O93). A hit does not wait.
+    const procedure = this.procedureRegistry.get(path) ?? (this.procedureRegistry.lazy ? await this.procedureRegistry.resolve(path) : undefined);
     if (procedure?.handler) {
       const options = this.invokeOptions(caller);
       return outputValue(await invokeProcedure<TOutput>(procedure, input, options), path);
@@ -726,7 +737,7 @@ export class Client<TContext = {}> {
   ): AsyncIterable<TOutput> {
     const self = this;
     return (async function* () {
-      const procedure = self.procedureRegistry.get(path);
+      const procedure = self.procedureRegistry.get(path) ?? (self.procedureRegistry.lazy ? await self.procedureRegistry.resolve(path) : undefined);
       if (procedure?.handler) {
         const options = self.invokeOptions(caller);
         yield* outputItems(await invokeProcedure<TOutput>(procedure, input, options));
@@ -950,7 +961,7 @@ export class Client<TContext = {}> {
    *
    * @example
    * ```typescript
-   * import { z } from "zod";
+   * import * as z from "zod";
    *
    * const client = new Client({ transport })
    *   .use(createZodMiddleware())
@@ -1099,6 +1110,8 @@ export class Client<TContext = {}> {
   async route<TRoute extends Route>(
     request: CallRequest<TRoute>
   ): Promise<CallResponse<TRoute>> {
+    // A lazy registry loads the packages of the paths first: the resolver reads only what has loaded (roadmap O93)
+    if (this.procedureRegistry.lazy) await this.loadRoutePaths(request.route);
     const resolver = this.getRouteResolver();
     const executor = this.getBatchExecutor();
 
@@ -1135,6 +1148,35 @@ export class Client<TContext = {}> {
   routeStream<TRoute extends Route>(
     request: CallRequest<TRoute>
   ): StreamingCallResponse<TRoute> {
+    // A lazy registry without each path of the route: the stream starts after the packages loaded (roadmap O93)
+    const registry = this.procedureRegistry;
+    if (registry.lazy && flattenRoute(request.route).some((entry) => !registry.has(entry.path))) {
+      const started = this.loadRoutePaths(request.route).then(() => this.routeStreamLoaded(request));
+      const complete = started.then((response) => response.complete);
+      // A caller that reads only the results gets the load error there: the promise is not an unhandled rejection
+      complete.catch(() => undefined);
+      return {
+        results: (async function* () {
+          yield* (await started).results;
+        })(),
+        complete,
+      };
+    }
+    return this.routeStreamLoaded(request);
+  }
+
+  /**
+   * This function loads the packages of the paths of a route into a lazy registry. A package that
+   * did not load rejects the promise, with the load error as the `cause`.
+   */
+  private async loadRoutePaths(route: Route): Promise<void> {
+    for (const entry of flattenRoute(route)) {
+      if (!this.procedureRegistry.has(entry.path)) await this.procedureRegistry.resolve(entry.path);
+    }
+  }
+
+  /** This function starts the stream of a route whose procedures the registry has. */
+  private routeStreamLoaded<TRoute extends Route>(request: CallRequest<TRoute>): StreamingCallResponse<TRoute> {
     const resolver = this.getRouteResolver();
     const executor = this.getBatchExecutor();
 

package/src/client/errors/known-codes.ts

@@ -0,0 +1,22 @@
+/**
+ * The known error codes of the client, without their texts (roadmap O95).
+ *
+ * The error policy of a server needs only the codes, not the summaries and the suggestions of
+ * `ERROR_REGISTRY`. This module gives the codes from `ErrorCode` and `ERROR_CODES`, so a bundle
+ * of the server engine gets no copy of the texts. A test makes sure that this set and the keys of
+ * `ERROR_REGISTRY` are equal.
+ */
+
+import { ErrorCode } from "./codes.js";
+import { ERROR_CODES } from "../../protocol.js";
+
+/** The known error codes: each value of `ErrorCode` and each code of the wire protocol. */
+export const KNOWN_ERROR_CODES: ReadonlySet<string> = new Set<string>([...Object.values(ErrorCode), ...Object.keys(ERROR_CODES)]);
+
+/**
+ * This function gives `true` for a known error code. It gives the same answer as
+ * `isKnownErrorCode` of the registry, but it does not import the texts of the registry.
+ */
+export function isKnownCode(code: unknown): code is string {
+  return typeof code === "string" && KNOWN_ERROR_CODES.has(code);
+}

package/src/client/validation/index.ts

@@ -6,7 +6,7 @@
  *
  * @example
  * ```typescript
- * import { z } from "zod";
+ * import * as z from "zod";
  * import { Client } from "client";
  * import { createZodMiddleware, ValidationError } from "client/client/validation";
  *

package/src/events/publisher.ts

@@ -32,7 +32,7 @@
  * events (`dropped`). The bus never waits for a subscriber.
  */
 
-import { z } from "zod";
+import * as z from "zod";
 import { createProcedure } from "../procedures/define.js";
 import { InvocationError, type Invocation } from "../procedures/invoke.js";
 import { capabilityRefusal } from "../procedures/capability.js";

package/src/procedures/core/array.ts

@@ -5,7 +5,7 @@
  * The namespace of all these procedures is "client": for example client.first and client.filter.
  */
 
-import { z } from "zod";
+import * as z from "zod";
 import { anyOutput, arrayOutput, booleanOutput, numberOutput } from "./outputs.js";
 import { defineProcedure, namespace } from "../define.js";
 import type { AnyProcedure, Procedure } from "../types.js";

package/src/procedures/core/comparison.ts

@@ -5,7 +5,7 @@
  * The namespace of all these procedures is "client": for example client.eq and client.gt.
  */
 
-import { z } from "zod";
+import * as z from "zod";
 import { booleanOutput } from "./outputs.js";
 import { defineProcedure, namespace } from "../define.js";
 import type { AnyProcedure, Procedure } from "../types.js";

package/src/procedures/core/index.ts

@@ -46,7 +46,7 @@
  */
 
 import { PURE_EFFECTS, REGISTRY_READ_EFFECTS, withEffects } from "../effects.js";
-import { z } from "zod";
+import * as z from "zod";
 import { anyOutput, booleanOutput } from "./outputs.js";
 import { defineProcedure, namespace } from "../define.js";
 import type {
@@ -136,6 +136,7 @@ const TryCatchInputSchema = z.looseObject({
 import {
   isAnyProcedureRef,
   normalizeRef,
+  preloadRefPaths,
   createRefScope,
   scopeOf,
   getRefWhen,
@@ -349,6 +350,8 @@ const traceProcedure: TraceProcedure = defineProcedure({
     if (!ctx?.client) throw new Error("client.trace: a run needs a client context");
     const registry = ctx.registry ?? PROCEDURE_REGISTRY;
     const limit = upTo ?? Number.POSITIVE_INFINITY;
+    // A lazy registry loads the paths of the steps first: the facts below read their effects (roadmap O93)
+    await preloadRefPaths(registry, steps);
 
     // The facts of each step before the run: its name, its path and the declared effects of its procedure
     const rows: TraceRow[] = steps.map((step, index) => {

package/src/procedures/core/math.ts

@@ -5,7 +5,7 @@
  * The namespace of all these procedures is "client": for example client.add and client.multiply.
  */
 
-import { z } from "zod";
+import * as z from "zod";
 import { numberOutput } from "./outputs.js";
 import { defineProcedure, namespace } from "../define.js";
 import type { AnyProcedure, Procedure } from "../types.js";

package/src/procedures/core/meta.ts

@@ -6,7 +6,7 @@
  * The namespace of all these procedures is "client": for example client.import and client.eval.
  */
 
-import { z } from "zod";
+import * as z from "zod";
 import { anyOutput, stringOutput } from "./outputs.js";
 import { defineProcedure, namespace } from "../define.js";
 import type { AnyProcedure, Procedure } from "../types.js";

package/src/procedures/core/object.ts

@@ -5,7 +5,7 @@
  * The namespace of all these procedures is "client": for example client.get and client.set.
  */
 
-import { z } from "zod";
+import * as z from "zod";
 import { anyOutput, arrayOutput, booleanOutput, recordOutput } from "./outputs.js";
 import { defineProcedure, namespace } from "../define.js";
 import type { AnyProcedure, Procedure } from "../types.js";

package/src/procedures/core/operands.ts

@@ -9,6 +9,7 @@ import {
   isAnyProcedureRef,
   isOutputRef,
   lookupOutputRef,
+  preloadRefPaths,
   rawInputRule,
   scopeOf,
   RUNS_REFS_TAG,
@@ -41,7 +42,11 @@ function executorOf(ctx: ProcedureContext): <TIn, TOut>(path: ProcedurePath, inp
  * each step of a chain (`client.trace`).
  */
 export function runControlFlow(name: string, input: unknown, ctx: ProcedureContext, options: Pick<RunControlOptions, "onStep"> = {}): Promise<unknown> {
-  return runControl(name, input, { executor: executorOf(ctx), rawInput: rawRule(ctx), onRef: ctx.onRef, scope: scopeOf(input), onStep: options.onStep });
+  // A lazy registry loads the paths of the operands before the raw-input rule reads them (roadmap O93)
+  const preload = preloadRefPaths(ctx.registry, input);
+  const run = (): Promise<unknown> =>
+    runControl(name, input, { executor: executorOf(ctx), rawInput: rawRule(ctx), onRef: ctx.onRef, scope: scopeOf(input), onStep: options.onStep });
+  return preload ? preload.then(run) : run();
 }
 
 /**
@@ -70,6 +75,7 @@ export function substituteRefs(value: unknown, scope: RefScope): unknown {
  * in `scope` and runs its nested refs, as `exec()` does for an input.
  */
 export async function hydrateOperand(value: unknown, ctx: ProcedureContext, scope?: RefScope): Promise<unknown> {
+  await preloadRefPaths(ctx.registry, value);
   return hydrateInput(value, executorOf(ctx), { scope, rawInput: rawRule(ctx), onRef: ctx.onRef });
 }
 
@@ -86,6 +92,7 @@ export async function callOperand(
   ctx: ProcedureContext,
   options: { scope?: RefScope | undefined; extra?: Record<string, unknown> | undefined } = {},
 ): Promise<unknown> {
+  await preloadRefPaths(ctx.registry, ref);
   return runOperand(ref, { executor: executorOf(ctx), rawInput: rawRule(ctx), onRef: ctx.onRef, scope: options.scope, extra: options.extra });
 }
 

package/src/procedures/core/outputs.ts

@@ -6,7 +6,7 @@
  * helpers give each output a real zod 4 schema with a description.
  */
 
-import { z } from "zod";
+import * as z from "zod";
 
 /**
  * Any JavaScript number, also `NaN` and `Infinity`. zod 4's `z.number()` refuses both, but

package/src/procedures/core/string.ts

@@ -5,7 +5,7 @@
  * The namespace of all these procedures is "client": for example client.concat and client.split.
  */
 
-import { z } from "zod";
+import * as z from "zod";
 import { booleanOutput, numberOutput, stringOutput } from "./outputs.js";
 import { defineProcedure, namespace } from "../define.js";
 import type { AnyProcedure, Procedure } from "../types.js";

package/src/procedures/core/type.ts

@@ -5,7 +5,7 @@
  * The namespace of all these procedures is "client": for example client.typeof and client.isArray.
  */
 
-import { z } from "zod";
+import * as z from "zod";
 import { anyOutput, booleanOutput, stringOutput } from "./outputs.js";
 import { defineProcedure, namespace } from "../define.js";
 import type { AnyProcedure, Procedure } from "../types.js";

package/src/procedures/define-procedure.ts

@@ -26,7 +26,7 @@
  */
 
 import { defineProcedure, validateProcedure } from "./define.js";
-import { PROCEDURE_REGISTRY, assertValidPath } from "./registry.js";
+import { PROCEDURE_REGISTRY, assertValidPath, loadAllIn, resolveIn } from "./registry.js";
 import type {
   Procedure,
   ProcedurePath,
@@ -36,13 +36,14 @@ import type {
   ProcedureRegistryLike,
   Effects,
 } from "./types.js";
-import { z } from "zod";
+import * as z from "zod";
 import { anySchema } from "./core/schemas.js";
 import { keyToPath, pathToKey } from "./types.js";
 import {
   createRefScope,
   isAnyProcedureRef,
   markDataDriven,
+  preloadRefPaths,
   rawInputRule,
   RUNS_REFS_TAG,
 } from "./ref.js";
@@ -211,7 +212,11 @@ function createAggregationHandler(
     const scope = createRefScope();
     scope.outputs.set("input", input);
     const executor = <TIn, TOut>(path: ProcedurePath, value: TIn): Promise<TOut> => ctx.client.call<TIn, TOut>(path, value);
-    const options = { scope, rawInput: rawInputRule(ctx.registry ?? PROCEDURE_REGISTRY), onRef: ctx.onRef };
+    const registry = ctx.registry ?? PROCEDURE_REGISTRY;
+    // A lazy registry loads the paths of the body before the raw-input rule reads them (roadmap O93)
+    const preload = preloadRefPaths(registry, aggregation);
+    if (preload) await preload;
+    const options = { scope, rawInput: rawInputRule(registry), onRef: ctx.onRef };
     if (isAnyProcedureRef(aggregation)) {
       return runProgram(aggregation, { ...options, executor });
     }
@@ -327,7 +332,8 @@ export const defineProcedureProcedure: Procedure<
     }
 
     const pathKey = pathToKey(path);
-    const existing = registry.get(path);
+    // A lazy registry loads the package of the path first: a procedure of a package is not new (roadmap O93)
+    const existing = await resolveIn(registry, path);
     // A procedure outside the expose rule of the host is not the caller's to replace (R17)
     if (existing && ctx?.expose && !ctx.expose(path)) {
       throw new InvocationError(
@@ -473,7 +479,8 @@ export const getProcedureProcedure: Procedure<
   },
   handler: async (input: ProcedureGetInput, ctx?: ProcedureContext) => {
     const path = typeof input.path === "string" ? keyToPath(input.path) : input.path;
-    const procedure = (ctx?.registry ?? PROCEDURE_REGISTRY).get(path);
+    // A lazy registry loads the package of the path first (roadmap O93)
+    const procedure = await resolveIn(ctx?.registry ?? PROCEDURE_REGISTRY, path);
     // A procedure outside the expose rule of the host is not found (R17)
     if (!procedure || (ctx?.expose && !ctx.expose(procedure.path))) {
       return { found: false as const };
@@ -513,7 +520,10 @@ export const listProceduresProcedure: Procedure<
     output: "json",
   },
   handler: async (input: ProcedureListInput, ctx?: ProcedureContext) => {
-    let all = (ctx?.registry ?? PROCEDURE_REGISTRY).getAll();
+    const registry = ctx?.registry ?? PROCEDURE_REGISTRY;
+    // A lazy registry loads each package first: the list has each procedure (roadmap O93)
+    await loadAllIn(registry);
+    let all = registry.getAll();
     // Only the procedures that the host exposes (R17)
     if (ctx?.expose) all = all.filter((procedure) => ctx.expose!(procedure.path));
     if (input.runtime) all = all.filter(isRuntimeDefined);
@@ -539,11 +549,15 @@ export const manifestProcedure: Procedure<{ namespace?: string | undefined }, Pr
     shorts: { namespace: "n" },
     output: "json",
   },
-  handler: async (input: { namespace?: string | undefined }, ctx?: ProcedureContext) =>
-    describeRegistry(ctx?.registry ?? PROCEDURE_REGISTRY, {
+  handler: async (input: { namespace?: string | undefined }, ctx?: ProcedureContext) => {
+    const registry = ctx?.registry ?? PROCEDURE_REGISTRY;
+    // A lazy registry loads each package first: the manifest has each procedure (roadmap O93)
+    await loadAllIn(registry);
+    return describeRegistry(registry, {
       ...(ctx?.expose ? { expose: ctx.expose } : {}),
       ...(input.namespace ? { include: (procedure: AnyProcedure) => procedure.path[0] === input.namespace } : {}),
-    }),
+    });
+  },
 });
 
 /**
@@ -568,7 +582,8 @@ export const deleteProcedureProcedure: Procedure<
     if (ctx?.expose && !ctx.expose(input.path)) {
       return { deleted: false };
     }
-    const existing = registry.get(input.path);
+    // A lazy registry loads the package of the path first (roadmap O93)
+    const existing = await resolveIn(registry, input.path);
     if (!existing) {
       return { deleted: false };
     }

package/src/procedures/index.ts

@@ -114,7 +114,8 @@ export { NARROWING_METADATA_KEY, NARROWING_HEADER, narrowingOf, narrowWithin, ad
 export type { NarrowingNote, WireNarrowing, NarrowedCapability } from "./narrowing.js";
 
 // Registry
-export { ProcedureRegistry, RegistryError, PROCEDURE_REGISTRY, assertValidPath } from "./registry.js";
+export { ProcedureRegistry, RegistryError, PROCEDURE_REGISTRY, assertValidPath, resolveIn, loadAllIn } from "./registry.js";
+export type { RegistryResolver, ProcedureRegistryOptions, ResolvingRegistry } from "./registry.js";
 
 // Definition helpers
 export {
@@ -223,9 +224,10 @@ export {
   moduleClosure,
   registerModules,
   createRegistry,
+  createLazyRegistry,
   registerClientProcedures,
 } from "./module.js";
-export type { ModuleInput, PackageDefinition } from "./module.js";
+export type { ModuleInput, PackageDefinition, LazyRegistryOptions } from "./module.js";
 // One call for a registry of some modules, `invokePath` and `outputValue`
 export { callerOf } from "./caller.js";
 export type { Caller, CallerOptions } from "./caller.js";
@@ -262,6 +264,7 @@ export {
   RAW_INPUT_TAG,
   takesRawInput,
   rawInputRule,
+  preloadRefPaths,
   MAX_DATA_DEPTH,
   LITERAL_KEY,
   isLiteral,
@@ -338,6 +341,8 @@ export {
   // Every core procedure (math, comparison, string, type, object, array, meta too). Not registered by default.
   allCoreProcedures,
   allCoreModules,
+  // Only the math procedures: a bundle that imports only these gets no other core procedure (roadmap O95)
+  mathProcedures,
   chainProcedure,
   traceProcedure,
   type TraceRow,

package/src/procedures/invoke.ts

@@ -440,6 +440,13 @@ export async function invokeProcedure<TOutput = unknown>(
   return dispatch(0, invocation, options) as Promise<ProcedureOutput<TOutput>>;
 }
 
+/** True when the declared effects of a procedure read or write the registry. */
+function usesRegistry(procedure: AnyProcedure): boolean {
+  const effects = (procedure.metadata as { effects?: { reads?: unknown; writes?: unknown } } | undefined)?.effects;
+  const names = (list: unknown): boolean => Array.isArray(list) && list.includes("registry");
+  return names(effects?.reads) || names(effects?.writes);
+}
+
 /** 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;
@@ -472,6 +479,11 @@ async function runInvocation<TOutput>(invocation: Invocation, options: InvokeOpt
     data = parsed.value === input ? input : withScope(parsed.value, scopeOf(input));
   }
 
+  // A procedure that declares a read or a write of the registry sees each procedure of a lazy
+  // registry (roadmap O93). An eager registry does not wait here.
+  const registry = options.registry;
+  if (registry?.lazy && usesRegistry(procedure)) await registry.loadAll();
+
   // The handler starts here, before the first await (the site's trace depends on it)
   const result: unknown = await handler(data, createProcedureContext(procedure, { ...options, capability: invocation.capability }, invocation));
   // The output filter examines only what leaves the host
@@ -508,7 +520,9 @@ export async function invokePath<TOutput = unknown>(
   input: unknown,
   options: InvokeOptions = {},
 ): Promise<ProcedureOutput<TOutput>> {
-  const procedure = (options.registry ?? PROCEDURE_REGISTRY).get(path);
+  const registry = options.registry ?? PROCEDURE_REGISTRY;
+  // A miss of a lazy registry loads the packages of the path (roadmap O93). A hit does not wait.
+  const procedure = registry.get(path) ?? (registry.lazy ? await registry.resolve(path) : undefined);
   if (!procedure) {
     throw new InvocationError("NOT_FOUND", `Procedure not found: ${pathToKey(path)}`, path);
   }