@procedures/client 0.0.0-stage → 0.1.0

package/dist/procedures/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Procedure System
+ *
+ * Type-safe procedure definitions with schema validation,
+ * registry for auto-discovery, and server integration.
+ */
+export type { ProcedurePath, ProcedureMetadata, RepositoryProvider, ProcedureContext, ProcedureHandler, Procedure, AnyProcedure, ProcedureResult, ProcedureError, InferProcedureInput, InferProcedureOutput, InferProcedureMetadata, RegistryEventType, RegistryListener, ProcedureModule, RegistrationOptions, ProcedureRegistryLike, } from "./types.js";
+export { pathToKey, keyToPath } from "./types.js";
+export { ProcedureRegistry, RegistryError, PROCEDURE_REGISTRY, assertValidPath } from "./registry.js";
+export { defineProcedure, defineStub, createProcedure, ProcedureBuilder, namespace, validateProcedure, } from "./define.js";
+export type { ProcedureDefinition, ProcedureStub } from "./define.js";
+export { createCollectionProcedures } from "./collection/index.js";
+export type { CollectionStorage, StorageMetadata } from "./collection/index.js";
+export { registerModule, registerProcedures, createAndRegister, } from "./discovery.js";
+export { clientModule, defineModule, moduleClosure, registerModules, createRegistry, } from "./module.js";
+export type { ModuleInput } from "./module.js";
+export { PROCEDURE_SYMBOL, PROCEDURE_JSON_KEY, PROCEDURE_WHEN_KEY, PROCEDURE_NAME_KEY, WHEN_IMMEDIATE, WHEN_NEVER, WHEN_PARENT, isProcedureRef, isProcedureRefJson, isAnyProcedureRef, getRefWhen, getRefName, shouldExecuteRef, proc, ProcedureRefBuilder, fromJson, toJson, normalizeRef, hydrateInput, prepareRootCall, observeHydration, isControlFlowPath, isDataDriven, markDataDriven, RUNS_REFS_TAG, RAW_INPUT_TAG, takesRawInput, rawInputRule, MAX_DATA_DEPTH, LITERAL_KEY, isLiteral, isPlainObject, createRefScope, lookupOutputRef, resolveOutputRef, withScope, scopeOf, executeRef, extractTemplate, parseProcedureJson, stringifyProcedureJson, } from "./ref.js";
+export type { ProcedureWhen, ProcedureRef, ProcedureRefJson, AnyProcedureRef, RefExecutor, HydrateOptions, HydrationEvent, StepResultInfo, ContinueDecision, OutputRef, RefScope, } from "./ref.js";
+export { coreProcedures, coreModule, allCoreProcedures, allCoreModules, chainProcedure, parallelProcedure, conditionalProcedure, andProcedure, orProcedure, notProcedure, allProcedure, anyProcedure, noneProcedure, mapProcedure, reduceProcedure, identityProcedure, constantProcedure, throwProcedure, tryCatchProcedure, anySchema, typedAnySchema, zodAdapter, outputSchema, type ZodLikeSchema, } from "./core/index.js";
+export { validateSchema, validateSchemaAsync, jsonSchemaOf, isStandardSchema, describeIssues, } from "./schema.js";
+export type { StandardSchemaV1, StandardJSONSchemaConverter, ProcedureSchema, InferSchema, SchemaResult, JsonSchema, JsonSchemaTarget, JsonSchemaSource, } from "./schema.js";
+export { defineProcedureProcedure, getProcedureProcedure, listProceduresProcedure, deleteProcedureProcedure, metaProcedures, getRuntimeProcedure, hasRuntimeProcedure, getAllRuntimeProcedures, clearRuntimeProcedures, isRuntimeDefined, runtimeProgramOf, } from "./define-procedure.js";
+export type { AggregationDefinition, DefineProcedureInput, DefineProcedureOutput, } from "./define-procedure.js";
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/procedures/index.js

@@ -0,0 +1,69 @@
+/**
+ * Procedure System
+ *
+ * Type-safe procedure definitions with schema validation,
+ * registry for auto-discovery, and server integration.
+ */
+// Type utilities
+export { pathToKey, keyToPath } from "./types.js";
+// Registry
+export { ProcedureRegistry, RegistryError, PROCEDURE_REGISTRY, assertValidPath } from "./registry.js";
+// Definition helpers
+export { defineProcedure, defineStub, createProcedure, ProcedureBuilder, namespace, validateProcedure, } from "./define.js";
+// Collection procedures
+export { createCollectionProcedures } from "./collection/index.js";
+// Manual registration helpers
+export { registerModule, registerProcedures, createAndRegister, } from "./discovery.js";
+// Modules and explicit registries (roadmap 3.1)
+export { clientModule, defineModule, moduleClosure, registerModules, createRegistry, } from "./module.js";
+// Procedure reference system (procedure-as-data)
+export { 
+// Constants
+PROCEDURE_SYMBOL, PROCEDURE_JSON_KEY, PROCEDURE_WHEN_KEY, PROCEDURE_NAME_KEY, WHEN_IMMEDIATE, WHEN_NEVER, WHEN_PARENT, 
+// Type guards
+isProcedureRef, isProcedureRefJson, isAnyProcedureRef, getRefWhen, getRefName, shouldExecuteRef, 
+// Builder
+proc, ProcedureRefBuilder, 
+// Conversion
+fromJson, toJson, normalizeRef, 
+// Hydration
+hydrateInput, prepareRootCall, observeHydration, isControlFlowPath, isDataDriven, markDataDriven, RUNS_REFS_TAG, RAW_INPUT_TAG, takesRawInput, rawInputRule, MAX_DATA_DEPTH, LITERAL_KEY, isLiteral, isPlainObject, createRefScope, lookupOutputRef, resolveOutputRef, withScope, scopeOf, executeRef, 
+// Templates
+extractTemplate, parseProcedureJson, stringifyProcedureJson, } from "./ref.js";
+// Core language procedures (chain, parallel, if, etc.)
+export { coreProcedures, coreModule, 
+// Every core procedure (math, comparison, string, type, object, array, meta too). Not registered by default.
+allCoreProcedures, allCoreModules, chainProcedure, parallelProcedure, conditionalProcedure, andProcedure, orProcedure, notProcedure, allProcedure, anyProcedure, noneProcedure, mapProcedure, reduceProcedure, identityProcedure, constantProcedure, throwProcedure, tryCatchProcedure, 
+// Schemas and result types
+anySchema, typedAnySchema, zodAdapter, outputSchema, } from "./core/index.js";
+// Schemas: Standard Schema v1, validation and JSON Schema (roadmap 2.1)
+export { validateSchema, validateSchemaAsync, jsonSchemaOf, isStandardSchema, describeIssues, } from "./schema.js";
+// Meta-procedures for runtime procedure definition
+export { defineProcedureProcedure, getProcedureProcedure, listProceduresProcedure, deleteProcedureProcedure, metaProcedures, getRuntimeProcedure, hasRuntimeProcedure, getAllRuntimeProcedures, clearRuntimeProcedures, isRuntimeDefined, runtimeProgramOf, } from "./define-procedure.js";
+// The storage layer, the synced registry and the procedure.store/load/sync/remote/register
+// procedures moved to @procedures/store (roadmap 3.2): the program store.
+// =============================================================================
+// Auto-register core procedures
+// =============================================================================
+import { coreProcedures as _coreProcedures } from "./core/index.js";
+import { metaProcedures as _metaProcedures } from "./define-procedure.js";
+import { PROCEDURE_REGISTRY } from "./registry.js";
+// Register core procedures when this module is imported
+// This ensures client.* procedures are available without explicit registration
+try {
+    for (const proc of _coreProcedures) {
+        if (!PROCEDURE_REGISTRY.has(proc.path)) {
+            PROCEDURE_REGISTRY.register(proc);
+        }
+    }
+    // Also register meta-procedures
+    for (const proc of _metaProcedures) {
+        if (!PROCEDURE_REGISTRY.has(proc.path)) {
+            PROCEDURE_REGISTRY.register(proc);
+        }
+    }
+}
+catch {
+    // Ignore errors during auto-registration (e.g., if already registered)
+}
+//# sourceMappingURL=index.js.map

package/dist/procedures/index.js.map

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

package/dist/procedures/interceptors.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 { type Interceptor, type Invocation } from "./invoke.js";
+import { type ProcedurePath } from "./types.js";
+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;
+}
+/**
+ * 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 declare function timeoutInterceptor(options: TimeoutInterceptorOptions): Interceptor;
+/** 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;
+}
+/**
+ * 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 declare function tracingInterceptor(options: TracingInterceptorOptions): Interceptor;
+/** 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 declare function metricsInterceptor(options?: {
+    now?: () => number;
+}): MetricsInterceptor;
+//# sourceMappingURL=interceptors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"interceptors.d.ts","sourceRoot":"","sources":["../../src/procedures/interceptors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAmB,KAAK,WAAW,EAAE,KAAK,UAAU,EAAwB,MAAM,aAAa,CAAC;AACvG,OAAO,EAAa,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAM3D,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,UAAU,EAAE,UAAU,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IAC9D,2FAA2F;IAC3F,OAAO,CAAC,EAAE,CAAC,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAC1D;AA+CD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,WAAW,CAkClF;AAMD,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,MAAM,EAAE,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC;IACnC,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;IACtC,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,yBAAyB;IACxC,8FAA8F;IAC9F,MAAM,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC;IACvC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACvD,qDAAqD;IACrD,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CAClC;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,WAAW,CAyElF;AAMD,mCAAmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,4CAA4C;AAC5C,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC7C,KAAK,IAAI,IAAI,CAAC;CACf;AAED,2GAA2G;AAC3G,wBAAgB,kBAAkB,CAAC,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAO,GAAG,kBAAkB,CAkB3F"}

package/dist/procedures/interceptors.js

@@ -0,0 +1,193 @@
+/**
+ * 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 } from "./invoke.js";
+import { pathToKey } from "./types.js";
+/** A signal that aborts when one of the signals aborts. */
+function anySignal(signals) {
+    const any = 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, ms) {
+    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(items, deadline, done) {
+    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) {
+    const { ms } = options;
+    const appliesTo = options.appliesTo ?? ((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;
+        const deadline = new Promise((_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 = () => clearTimeout(timer);
+        let output;
+        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) };
+    };
+}
+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) {
+    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();
+    const finish = (span, invocationId, error) => {
+        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.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 = {
+            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;
+        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;
+                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);
+                }
+            })(),
+        };
+    };
+}
+/** This function makes an interceptor that counts the calls, the errors and the time of each procedure. */
+export function metricsInterceptor(options = {}) {
+    const counts = new Map();
+    const record = (key, duration, failed) => {
+        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(),
+    };
+}
+//# sourceMappingURL=interceptors.js.map

package/dist/procedures/interceptors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptors.js","sourceRoot":"","sources":["../../src/procedures/interceptors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAA2D,MAAM,aAAa,CAAC;AACvG,OAAO,EAAE,SAAS,EAAsB,MAAM,YAAY,CAAC;AAkB3D,2DAA2D;AAC3D,SAAS,SAAS,CAAC,OAAsB;IACvC,MAAM,GAAG,GAAI,WAAiE,CAAC,GAAG,CAAC;IACnF,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC,OAAO,CAAC,CAAC;IAC7B,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAChC,MAAM;QACR,CAAC;QACD,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO,UAAU,CAAC,MAAM,CAAC;AAC3B,CAAC;AAED,SAAS,YAAY,CAAC,IAAmB,EAAE,EAAU;IACnD,OAAO,IAAI,eAAe,CAAC,SAAS,EAAE,6BAA6B,EAAE,QAAQ,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;AACxG,CAAC;AAED;;;GAGG;AACH,KAAK,SAAS,CAAC,CAAC,UAAU,CACxB,KAAyC,EACzC,QAAwB,EACxB,IAAgB;IAEhB,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,CAAC;QACH,SAAS,CAAC;YACR,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC;YAC1D,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACd,QAAQ,GAAG,IAAI,CAAC;gBAChB,OAAO;YACT,CAAC;YACD,MAAM,IAAI,CAAC,KAAK,CAAC;QACnB,CAAC;IACH,CAAC;YAAS,CAAC;QACT,IAAI,EAAE,CAAC;QACP,4FAA4F;QAC5F,IAAI,CAAC,QAAQ;YAAE,KAAK,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACrE,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAkC;IACnE,MAAM,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC;IACvB,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC,UAAsB,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC;IAC5F,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE;QAChC,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;YAAE,OAAO,IAAI,EAAE,CAAC;QACvD,OAAO,CAAC,OAAO,EAAE,CAAC,UAAU,CAAC,CAAC;QAE9B,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;QACzG,IAAI,KAAgD,CAAC;QACrD,MAAM,QAAQ,GAAG,IAAI,OAAO,CAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;YACvD,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBACtB,MAAM,KAAK,GAAG,YAAY,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAChD,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBACxB,MAAM,CAAC,KAAK,CAAC,CAAC;YAChB,CAAC,EAAE,EAAE,CAAC,CAAC;QACT,CAAC,CAAC,CAAC;QACH,sEAAsE;QACtE,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,GAAS,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAE7C,IAAI,MAAgC,CAAC;QACrC,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC5D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,EAAE,CAAC;YACP,MAAM,KAAK,CAAC;QACd,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC5B,IAAI,EAAE,CAAC;YACP,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC;IAC7E,CAAC,CAAC;AACJ,CAAC;AAuCD,IAAI,UAAU,GAAG,CAAC,CAAC;AAEnB;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAkC;IACnE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,IAAI,EAAE,UAAU,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IAC5E,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,oDAAoD;IACpD,MAAM,IAAI,GAAG,IAAI,GAAG,EAA0B,CAAC;IAE/C,MAAM,MAAM,GAAG,CAAC,IAAoB,EAAE,YAAoB,EAAE,KAAe,EAAQ,EAAE;QACnF,IAAI,CAAC,GAAG,GAAG,GAAG,EAAE,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC;QACxC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC;YACtB,IAAI,CAAC,KAAK,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACpE,MAAM,IAAI,GAAI,KAA4B,CAAC,IAAI,CAAC;YAChD,IAAI,OAAO,IAAI,KAAK,QAAQ;gBAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjD,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACrB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QAC1B,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC,CAAC;IAEF,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE;QAChC,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9E,MAAM,EAAE,GAAG,GAAG,MAAM,IAAI,EAAE,SAAS,EAAE,CAAC;QACtC,MAAM,IAAI,GAAmB;YAC3B,EAAE;YACF,QAAQ,EAAE,MAAM,EAAE,EAAE;YACpB,OAAO,EAAE,MAAM,EAAE,OAAO,IAAI,EAAE;YAC9B,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,GAAG,EAAE,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC;YAC/B,KAAK,EAAE,UAAU,CAAC,KAAK;YACvB,KAAK,EAAE,GAAG,EAAE;YACZ,GAAG,EAAE,SAAS;YACd,UAAU,EAAE,SAAS;YACrB,MAAM,EAAE,SAAS;SAClB,CAAC;QACF,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC9B,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;QAExB,IAAI,MAAgC,CAAC;QACrC,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;QACxB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;YACnC,MAAM,KAAK,CAAC;QACd,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC;YACpB,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC;YAC5B,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;QACf,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3B,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,CAAC,KAAK,SAAS,CAAC;gBACrB,IAAI,OAAgB,CAAC;gBACrB,IAAI,CAAC;oBACH,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;wBAC/B,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;wBACnC,MAAM,IAAI,CAAC;oBACb,CAAC;gBACH,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO,GAAG,KAAK,CAAC;oBAChB,MAAM,KAAK,CAAC;gBACd,CAAC;wBAAS,CAAC;oBACT,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;gBACvC,CAAC;YACH,CAAC,CAAC,EAAE;SACL,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAuBD,2GAA2G;AAC3G,MAAM,UAAU,kBAAkB,CAAC,OAAO,GAA2B,EAAE;IACrE,MAAM,MAAM,GAAG,IAAI,GAAG,EAA4B,CAAC;IACnD,MAAM,MAAM,GAAG,CAAC,GAAW,EAAE,QAAgB,EAAE,MAAe,EAAQ,EAAE;QACtE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QAC/E,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,IAAI,MAAM;YAAE,KAAK,CAAC,MAAM,EAAE,CAAC;QAC3B,KAAK,CAAC,OAAO,IAAI,QAAQ,CAAC;QAC1B,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAC9C,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACzB,CAAC,CAAC;IACF,OAAO;QACL,WAAW,EAAE,kBAAkB,CAAC;YAC9B,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,IAAI,CAAC,EAAE,IAAI,CAAC,MAAM,KAAK,OAAO,CAAC;YACjF,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7C,CAAC;QACF,QAAQ,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC;QAC1F,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE;KAC5B,CAAC;AACJ,CAAC"}

package/dist/procedures/invoke.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 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 type { ProcedureRegistry } from "./registry.js";
+import { type HydrationEvent } from "./ref.js";
+import type { EventBus } from "../events/types.js";
+/** 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 declare class InvocationError extends Error {
+    readonly name = "InvocationError";
+    readonly code: InvocationErrorCode;
+    readonly path: ProcedurePath;
+    readonly retryable: boolean;
+    constructor(code: InvocationErrorCode, message: string, path: ProcedurePath);
+}
+/** 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;
+}
+/** 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>>;
+/** True for a value that `for await` can read: a generator, a stream. A string is not one. */
+export declare function isAsyncIterable(value: unknown): value is AsyncIterable<unknown>;
+/**
+ * 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 declare function invokeProcedure<TOutput = unknown>(procedure: AnyProcedure, input: unknown, options?: InvokeOptions): Promise<ProcedureOutput<TOutput>>;
+/** This function finds the procedure at a path in the registry of the options, then runs it. */
+export declare function invokePath<TOutput = unknown>(path: ProcedurePath, input: unknown, options?: InvokeOptions): Promise<ProcedureOutput<TOutput>>;
+/**
+ * One value of an output: the value, or the last item of a stream (the "sponge" mode). An
+ * empty stream is an error.
+ */
+export declare function outputValue<T>(output: ProcedureOutput<T>, path?: ProcedurePath): Promise<T>;
+/** Each value of an output: the items of a stream, or the one value. */
+export declare function outputItems<T>(output: ProcedureOutput<T>): AsyncGenerator<T, void, undefined>;
+/** The items of an output that `start` gives. Nothing runs until the reader asks for the first item. */
+export declare function streamOutput<T>(start: () => Promise<ProcedureOutput<T>>): AsyncGenerator<T, void, undefined>;
+/**
+ * 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 declare function createProcedureContext(procedure: AnyProcedure, options?: InvokeOptions, invocation?: Invocation): ProcedureContext;
+//# sourceMappingURL=invoke.d.ts.map

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

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