@procedures/client 0.0.0-stage → 0.2.0

package/dist/procedures/invoke.js

@@ -0,0 +1,343 @@
+/**
+ * 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.
+ *
+ * Each invocation operates with a capability (CAPABILITIES-2026-10, `capability.ts`). A nested
+ * call gets the same capability or a narrower one. The admission refuses a procedure whose
+ * declared effects the capability does not permit (`FORBIDDEN`). The host can give resources
+ * for the capability (`ctx.resources`) and a filter of the output that leaves the host.
+ */
+import { pathToKey } from "./types.js";
+import { validateSchema } from "./schema.js";
+import { PROCEDURE_REGISTRY } from "./registry.js";
+import { nestedCallRefusal } from "./policy.js";
+import { scopeOf, withScope } from "./ref.js";
+import { UNLIMITED_CAPABILITY, capabilityRefusal, examinesNestedCall, narrowCapability } from "./capability.js";
+import { timeoutInterceptor } from "./interceptors.js";
+import { getGlobalEventBus, withEventBusSignal } from "../events/bus.js";
+/** An error of the invocation itself. An error that the handler throws passes through unchanged. */
+export class InvocationError extends Error {
+    name = "InvocationError";
+    code;
+    path;
+    retryable = false;
+    /** The reason of a `FORBIDDEN` error: `effects-undeclared`, `effects-exceeded` or `clearance`. */
+    reason;
+    constructor(code, message, path, reason) {
+        super(message);
+        this.code = code;
+        this.path = path;
+        this.reason = reason;
+    }
+}
+function abortError(path) {
+    return new InvocationError("ABORTED", `Procedure was aborted: ${pathToKey(path)}`, path);
+}
+// =============================================================================
+// Interceptors
+// =============================================================================
+let invocationCount = 0;
+// =============================================================================
+// Invocation
+// =============================================================================
+/** True for a value that `for await` can read: a generator, a stream. A string is not one. */
+export function isAsyncIterable(value) {
+    return (value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof value[Symbol.asyncIterator] === "function");
+}
+/** The output (or one stream item), validated by the output schema of the procedure. */
+async function validateOutput(procedure, output) {
+    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(iterator, signal, path) {
+    if (signal.aborted)
+        return Promise.reject(abortError(path));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortError(path));
+        signal.addEventListener("abort", onAbort, { once: true });
+        iterator.next().then((result) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(result);
+        }, (error) => {
+            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, source, signal) {
+    const iterator = source[Symbol.asyncIterator]();
+    let done = false;
+    let aborted = false;
+    try {
+        for (;;) {
+            let step;
+            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(procedure, input, options = {}) {
+    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 = {
+        id: ++invocationCount,
+        procedure,
+        path,
+        input,
+        metadata: options.metadata ?? {},
+        signal: options.signal,
+        parent: options.parent,
+        depth: options.parent ? options.parent.depth + 1 : 0,
+        capability: options.capability ?? UNLIMITED_CAPABILITY,
+    };
+    // A deadline that the parent does not have (from a host, a request or a narrowed nested call)
+    // ends the invocation at that time, as the timeout interceptor does
+    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 ?? [])]
+        : (options.interceptors ?? []);
+    if (interceptors.length === 0)
+        return runInvocation(invocation, options);
+    const dispatch = (index, current, currentOptions) => {
+        const interceptor = interceptors[index];
+        if (!interceptor)
+            return runInvocation(current, currentOptions);
+        return interceptor(current, (changes) => {
+            if (!changes)
+                return dispatch(index + 1, current, currentOptions);
+            const changed = {
+                ...current,
+                signal: changes.signal ?? current.signal,
+                metadata: changes.metadata ?? current.metadata,
+                capability: changes.capability
+                    ? narrowCapability(current.capability, changes.capability, currentOptions.clearanceOrder)
+                    : current.capability,
+            };
+            return dispatch(index + 1, changed, {
+                ...currentOptions,
+                signal: changed.signal,
+                metadata: changed.metadata,
+                capability: changed.capability,
+            });
+        });
+    };
+    return dispatch(0, invocation, options);
+}
+/** The end of the chain: the validation, the context, the handler and the output. */
+async function runInvocation(invocation, options) {
+    const { procedure, path, input } = invocation;
+    const handler = procedure.handler;
+    if (options.signal?.aborted)
+        throw abortError(path);
+    // The admission: before the input validation, so a refused call learns nothing from its input
+    const parent = invocation.parent;
+    if (!parent || examinesNestedCall(parent.procedure, parent.capability, invocation.capability)) {
+        const refusal = capabilityRefusal(procedure, invocation.capability);
+        if (refusal?.reason === "deadline")
+            throw new InvocationError("TIMEOUT", refusal.message, path);
+        if (refusal)
+            throw new InvocationError("FORBIDDEN", refusal.message, path, refusal.reason);
+    }
+    let data = 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 = await handler(data, createProcedureContext(procedure, { ...options, capability: invocation.capability }, invocation));
+    // The output filter examines only what leaves the host
+    const admit = invocation.depth === 0 ? options.admitItem : undefined;
+    if (isAsyncIterable(result)) {
+        const items = validatedItems(procedure, result, options.signal);
+        return {
+            kind: "stream",
+            items: (admit ? admittedItems(items, admit, invocation) : items),
+        };
+    }
+    const value = await validateOutput(procedure, result);
+    if (admit && !admit(value, invocation)) {
+        throw new InvocationError("FORBIDDEN", `The clearance of the call does not permit the output of ${pathToKey(path)}`, path, "clearance");
+    }
+    return { kind: "value", value: value };
+}
+/** The items that the output filter of the host admits. */
+async function* admittedItems(items, admit, invocation) {
+    for await (const item of items) {
+        if (admit(item, invocation))
+            yield item;
+    }
+}
+/** This function finds the procedure at a path in the registry of the options, then runs it. */
+export async function invokePath(path, input, options = {}) {
+    const procedure = (options.registry ?? PROCEDURE_REGISTRY).get(path);
+    if (!procedure) {
+        throw new InvocationError("NOT_FOUND", `Procedure not found: ${pathToKey(path)}`, path);
+    }
+    return invokeProcedure(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(output, path = []) {
+    if (output.kind === "value")
+        return output.value;
+    let last;
+    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(output) {
+    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(start) {
+    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, options = {}, invocation) {
+    const nestedOptions = invocation ? { ...options, parent: invocation } : options;
+    let client;
+    if (typeof options.client === "function") {
+        client = invocation ? options.client(invocation) : registryClient(procedure, nestedOptions);
+    }
+    else {
+        client = options.client ?? registryClient(procedure, nestedOptions);
+    }
+    const context = {
+        metadata: options.metadata ?? {},
+        path: procedure.path,
+        client,
+        registry: options.registry ?? PROCEDURE_REGISTRY,
+        capability: options.capability ?? UNLIMITED_CAPABILITY,
+        resources: invocation && options.resources ? options.resources(invocation) : EMPTY_RESOURCES,
+    };
+    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 resources of an invocation when the host gives none. */
+const EMPTY_RESOURCES = Object.freeze({});
+/** The client of a procedure's context: it runs the nested calls from the registry. */
+function registryClient(caller, options) {
+    const start = (path, input, callOptions) => {
+        // 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));
+        }
+        // A nested call gets the capability of its caller, or a narrower one that it asks for
+        const narrow = callOptions?.narrow;
+        if (!narrow)
+            return invokePath(path, input, options);
+        let capability;
+        try {
+            capability = narrowCapability(options.capability, narrow, options.clearanceOrder);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        return invokePath(path, input, { ...options, capability });
+    };
+    return {
+        async call(path, input, callOptions) {
+            return outputValue(await start(path, input, callOptions), path);
+        },
+        stream(path, input, callOptions) {
+            return streamOutput(() => start(path, input, callOptions));
+        },
+    };
+}
+//# sourceMappingURL=invoke.js.map

package/dist/procedures/invoke.js.map

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

package/dist/procedures/module.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Procedure modules and explicit registries (architecture review, roadmap 3.1).
+ *
+ * Importing a package registers nothing (ARCHITECTURE-PROPOSALS-2026-10, P9). A host with its own
+ * registry gives it the module of each package: the `./module` entry exports the procedures as
+ * data. The global `PROCEDURE_REGISTRY` gets the procedures of a package from its `./register`
+ * entry (`import "@procedures/git/register"`).
+ *
+ * ```ts
+ * import { createRegistry, Client, LocalTransport } from "@procedures/client";
+ * import gitModule from "@procedures/git/module";
+ *
+ * const registry = createRegistry(gitModule);
+ * const client = new Client(new LocalTransport({ registry })).useRegistry(registry);
+ * ```
+ *
+ * Two registries in one process stay apart: a nested call, `procedure.define` and the expose
+ * rule of a server all use the registry of the invocation (`ctx.registry`).
+ */
+import { ProcedureRegistry } from "./registry.js";
+import type { AnyProcedure, ProcedureModule, RegistrationOptions } from "./types.js";
+/**
+ * The procedures of `@procedures/client`: the control flow (`client.chain`, `client.map` and the
+ * others) and `procedure.define`/`get`/`list`/`delete`. `createRegistry()` always registers this
+ * module. `import "@procedures/client/register"` registers it in the global registry.
+ */
+export declare const clientModule: ProcedureModule;
+/** This function gives a module: its procedures, and the modules whose procedures it calls. */
+export declare function defineModule(name: string, procedures: readonly AnyProcedure[], requires?: readonly ProcedureModule[]): ProcedureModule;
+/**
+ * The modules and their required modules, each one time, with each required module before the
+ * module that requires it.
+ */
+export declare function moduleClosure(modules: readonly ProcedureModule[]): ProcedureModule[];
+/** One module, or a list of modules (a bundle can give a list). */
+export type ModuleInput = ProcedureModule | readonly ProcedureModule[];
+/**
+ * Register the procedures of a module and of its required modules in a registry. A procedure
+ * that the registry has already (the same handler, from a module that two modules require) is
+ * skipped. Another procedure at the same path is an error.
+ */
+export declare function registerModules(registry: ProcedureRegistry, modules: readonly ModuleInput[], options?: RegistrationOptions): ProcedureRegistry;
+/**
+ * A new registry with the procedures of `clientModule` (what the global registry has after
+ * `import "@procedures/client"`) and of each module, with their required modules.
+ */
+export declare function createRegistry(...modules: ModuleInput[]): ProcedureRegistry;
+/**
+ * This function registers the procedures of `clientModule` in a registry: the global registry by
+ * default. A procedure that the registry has already stays. The `./register` entry of the package
+ * starts this function.
+ */
+export declare function registerClientProcedures(registry?: ProcedureRegistry): void;
+//# sourceMappingURL=module.d.ts.map

package/dist/procedures/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../src/procedures/module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAsB,iBAAiB,EAAiB,MAAM,eAAe,CAAC;AAGrF,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAErF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,eAG1B,CAAC;AAEF,+FAA+F;AAC/F,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,YAAY,EAAE,EACnC,QAAQ,GAAE,SAAS,eAAe,EAAO,GACxC,eAAe,CAEjB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,eAAe,EAAE,CAkBpF;AAED,mEAAmE;AACnE,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,SAAS,eAAe,EAAE,CAAC;AAEvE;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,OAAO,CAAC,EAAE,mBAAmB,GAC5B,iBAAiB,CAiBnB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,OAAO,EAAE,WAAW,EAAE,GAAG,iBAAiB,CAE3E;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,GAAE,iBAAsC,GAAG,IAAI,CAI/F"}

package/dist/procedures/module.js

@@ -0,0 +1,103 @@
+/**
+ * Procedure modules and explicit registries (architecture review, roadmap 3.1).
+ *
+ * Importing a package registers nothing (ARCHITECTURE-PROPOSALS-2026-10, P9). A host with its own
+ * registry gives it the module of each package: the `./module` entry exports the procedures as
+ * data. The global `PROCEDURE_REGISTRY` gets the procedures of a package from its `./register`
+ * entry (`import "@procedures/git/register"`).
+ *
+ * ```ts
+ * import { createRegistry, Client, LocalTransport } from "@procedures/client";
+ * import gitModule from "@procedures/git/module";
+ *
+ * const registry = createRegistry(gitModule);
+ * const client = new Client(new LocalTransport({ registry })).useRegistry(registry);
+ * ```
+ *
+ * Two registries in one process stay apart: a nested call, `procedure.define` and the expose
+ * rule of a server all use the registry of the invocation (`ctx.registry`).
+ */
+import { PROCEDURE_REGISTRY, ProcedureRegistry, RegistryError } from "./registry.js";
+import { coreProcedures } from "./core/index.js";
+import { metaProcedures as definitionProcedures } from "./define-procedure.js";
+/**
+ * The procedures of `@procedures/client`: the control flow (`client.chain`, `client.map` and the
+ * others) and `procedure.define`/`get`/`list`/`delete`. `createRegistry()` always registers this
+ * module. `import "@procedures/client/register"` registers it in the global registry.
+ */
+export const clientModule = {
+    name: "@procedures/client",
+    procedures: [...coreProcedures, ...definitionProcedures],
+};
+/** This function gives a module: its procedures, and the modules whose procedures it calls. */
+export function defineModule(name, procedures, requires = []) {
+    return { name, procedures: [...procedures], requires };
+}
+/**
+ * The modules and their required modules, each one time, with each required module before the
+ * module that requires it.
+ */
+export function moduleClosure(modules) {
+    const ordered = [];
+    const seen = new Set();
+    const names = new Set();
+    const visit = (module, trail) => {
+        if (seen.has(module))
+            return;
+        // Two copies of one package (two installs) have one name: the first one counts
+        if (module.name !== undefined && names.has(module.name))
+            return;
+        if (trail.includes(module)) {
+            throw new Error(`Modules require each other in a cycle: ${[...trail, module].map((m) => m.name ?? "?").join(" -> ")}`);
+        }
+        for (const required of module.requires ?? [])
+            visit(required, [...trail, module]);
+        seen.add(module);
+        if (module.name !== undefined)
+            names.add(module.name);
+        ordered.push(module);
+    };
+    for (const module of modules)
+        visit(module, []);
+    return ordered;
+}
+/**
+ * Register the procedures of a module and of its required modules in a registry. A procedure
+ * that the registry has already (the same handler, from a module that two modules require) is
+ * skipped. Another procedure at the same path is an error.
+ */
+export function registerModules(registry, modules, options) {
+    const flat = modules.flatMap((input) => (Array.isArray(input) ? input : [input]));
+    for (const module of moduleClosure(flat)) {
+        for (const procedure of module.procedures) {
+            const path = options?.pathPrefix ? [...options.pathPrefix, ...procedure.path] : procedure.path;
+            const existing = registry.get(path);
+            if (existing && !options?.override) {
+                if (existing.handler === procedure.handler)
+                    continue;
+                throw new RegistryError(`Two modules give the procedure ${path.join(".")}: the second one is ${module.name ?? "a module without a name"}`, path);
+            }
+            registry.register(procedure, options);
+        }
+    }
+    return registry;
+}
+/**
+ * A new registry with the procedures of `clientModule` (what the global registry has after
+ * `import "@procedures/client"`) and of each module, with their required modules.
+ */
+export function createRegistry(...modules) {
+    return registerModules(new ProcedureRegistry(), [clientModule, ...modules]);
+}
+/**
+ * This function registers the procedures of `clientModule` in a registry: the global registry by
+ * default. A procedure that the registry has already stays. The `./register` entry of the package
+ * starts this function.
+ */
+export function registerClientProcedures(registry = PROCEDURE_REGISTRY) {
+    for (const procedure of clientModule.procedures) {
+        if (!registry.has(procedure.path))
+            registry.register(procedure);
+    }
+}
+//# sourceMappingURL=module.js.map

package/dist/procedures/module.js.map

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

package/dist/procedures/policy.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The call policy of a host: which nested calls a procedure can make (deep dive MCP-3).
+ *
+ * A host that serves procedures to an outside caller (the MCP server, a network server) gives an
+ * `expose` rule: the procedures that its callers can reach. A procedure can call other
+ * procedures through `ctx.client`. The policy decides for each nested call, with the immediate
+ * caller:
+ *
+ * - A data-driven caller (control flow, `runs-refs`, a procedure that `procedure.define` made)
+ *   runs refs that its caller chose. It can call only exposed procedures.
+ * - A code caller with `metadata.calls` can call the procedures that it declares, and the
+ *   exposed procedures.
+ * - A code caller without `calls` can call any procedure, unless the host sets `strictCalls`.
+ *   Then it can call only exposed procedures.
+ *
+ * Before, only the first rule existed. An exposed procedure of code could call any procedure, so
+ * a code procedure that turns its input into a call was a confused deputy. The declarations make
+ * the reach of each tool visible: a test of the MCP server pins it.
+ *
+ * A host without `expose` and without `strictCalls` (a library, the local CLI) checks nothing.
+ */
+import type { AnyProcedure, ProcedurePath } from "./types.js";
+/** The call policy of a host. */
+export interface CallPolicy {
+    /** The procedures that the callers of the host can reach. Without it, every procedure is exposed. */
+    expose?: ((path: ProcedurePath) => boolean) | undefined;
+    /**
+     * True: a code procedure without `metadata.calls` can call only exposed procedures. The MCP
+     * server of the dev tools sets it.
+     */
+    strictCalls?: boolean | undefined;
+}
+/** The reason of a refused nested call. */
+export interface CallRefusal {
+    readonly code: "NOT_EXPOSED" | "NOT_DECLARED";
+    readonly message: string;
+}
+/** True when a host has a policy: a nested call is examined only then. */
+export declare function hasCallPolicy(policy: CallPolicy): boolean;
+/**
+ * True when one entry of `calls` allows a procedure key: the same key, or `"ns.*"` for a key
+ * that starts with `"ns."` (at any depth: `"fs.*"` allows `fs.read.json`).
+ */
+export declare function callMatches(entry: string, key: string): boolean;
+/**
+ * This function checks the `calls` of a procedure's metadata and returns it, or undefined when
+ * there is none. It throws for an invalid list. `"*"` alone is refused: a procedure whose
+ * callees come from its input is data-driven and must have the `runs-refs` tag.
+ */
+export declare function validateCalls(calls: unknown, path: ProcedurePath): readonly string[] | undefined;
+/** The `calls` of a procedure, or undefined when it declares none. */
+export declare function declaredCalls(procedure: Pick<AnyProcedure, "path" | "metadata">): readonly string[] | undefined;
+/** One edge of the reach of the exposed procedures: a declared call to a procedure that is not exposed. */
+export interface HiddenCall {
+    readonly from: string;
+    readonly to: string;
+}
+/**
+ * The procedures that are not exposed, but that the exposed procedures can reach through their
+ * `metadata.calls`, also through more than one step. A data-driven procedure reaches only
+ * exposed procedures, and under `strictCalls` a procedure without `calls` does too, so neither
+ * adds an edge. The edges are sorted. A test of the MCP server pins them.
+ */
+export declare function hiddenReach(procedures: readonly AnyProcedure[], expose: (path: ProcedurePath) => boolean): HiddenCall[];
+/**
+ * The refusal of a nested call from `caller` to `path` under `policy`, or undefined when the
+ * call is allowed.
+ */
+export declare function nestedCallRefusal(caller: AnyProcedure, path: ProcedurePath, policy: CallPolicy): CallRefusal | undefined;
+//# sourceMappingURL=policy.d.ts.map

package/dist/procedures/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/procedures/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI9D,iCAAiC;AACjC,MAAM,WAAW,UAAU;IACzB,qGAAqG;IACrG,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IACxD;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACnC;AAED,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,cAAc,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAEzD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAK/D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAsBhG;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,UAAU,CAAC,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAE/G;AAED,2GAA2G;AAC3G,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,SAAS,YAAY,EAAE,EACnC,MAAM,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,GACvC,UAAU,EAAE,CAqBd;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,SAAS,CAmCxH"}