@procedures/client 0.0.0-stage → 0.2.0

package/dist/procedures/storage/types.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Procedure Storage Types
+ *
+ * Types for serializing and persisting procedure definitions.
+ * Enables procedure registry to be backed by CollectionStorage.
+ */
+import type { ProcedurePath, ProcedureMetadata } from "../types.js";
+/**
+ * Reference to a handler that can be loaded at runtime.
+ * Handlers cannot be serialized directly, so we store a reference.
+ */
+export interface HandlerReference {
+    /** Module name or path (e.g., "@mark1russell7/client-cli") */
+    module: string;
+    /** Named export from the module (e.g., "libScanHandler") */
+    export: string;
+}
+/**
+ * Serialized procedure definition for storage.
+ * Contains only JSON-serializable data.
+ */
+export interface SerializedProcedure {
+    /** Procedure path (e.g., ['lib', 'scan']) */
+    path: ProcedurePath;
+    /** Procedure metadata */
+    metadata: ProcedureMetadata;
+    /** Whether this procedure supports streaming */
+    streaming?: boolean | undefined;
+    /** Reference to handler for runtime loading (optional) */
+    handlerRef?: HandlerReference | undefined;
+    /** Timestamp when stored */
+    storedAt?: number | undefined;
+    /** Version for conflict detection */
+    version?: number | undefined;
+}
+/**
+ * Function to load a handler from a reference.
+ * Used to restore handlers when loading procedures from storage.
+ */
+export interface HandlerLoader {
+    /**
+     * Load a handler from a reference.
+     *
+     * @param ref - Handler reference with module and export name
+     * @returns The handler function, or undefined if not found
+     */
+    load(ref: HandlerReference): Promise<unknown | undefined>;
+}
+/**
+ * Sync direction for registry operations.
+ */
+export type SyncDirection = "push" | "pull" | "both";
+/**
+ * Conflict resolution strategy.
+ */
+export type ConflictResolution = "local" | "remote" | "merge" | "error";
+/**
+ * Write strategy for persistence.
+ */
+export type WriteStrategy = "write-through" | "write-back";
+/**
+ * Status of a sync conflict.
+ */
+export interface SyncConflict {
+    /** Procedure path that had conflict */
+    path: ProcedurePath;
+    /** How the conflict was resolved */
+    resolution: ConflictResolution;
+    /** Local version (if any) */
+    local?: SerializedProcedure;
+    /** Remote version (if any) */
+    remote?: SerializedProcedure;
+}
+/**
+ * Result of a sync operation.
+ */
+export interface SyncResult {
+    /** Number of procedures pushed to storage */
+    pushed: number;
+    /** Number of procedures pulled from storage */
+    pulled: number;
+    /** Conflicts encountered during sync */
+    conflicts: SyncConflict[];
+    /** Timestamp of sync completion */
+    timestamp: number;
+}
+/**
+ * Current sync status of the registry.
+ */
+export interface SyncStatus {
+    /** Whether connected to remote storage */
+    connected: boolean;
+    /** Remote endpoint URL (if connected) */
+    endpoint?: string | undefined;
+    /** Last successful sync timestamp */
+    lastSync?: number | undefined;
+    /** Number of pending local changes */
+    pendingChanges: number;
+    /** Whether currently syncing */
+    syncing: boolean;
+}
+/**
+ * Options for SyncedProcedureRegistry.
+ */
+export interface SyncedRegistryOptions {
+    /** Write strategy: write-through (immediate) or write-back (queued) */
+    writeStrategy: WriteStrategy;
+    /** How to resolve conflicts when loading from storage */
+    conflictResolution: ConflictResolution;
+    /** Auto-sync interval in milliseconds (0 to disable) */
+    syncInterval?: number | undefined;
+    /** Handler loader for restoring handlers from references */
+    handlerLoader?: HandlerLoader | undefined;
+    /** Whether to sync on initialization */
+    syncOnInit?: boolean | undefined;
+}
+/**
+ * Configuration for creating a storage-backed registry.
+ */
+export interface ProcedureStorageConfig {
+    /** Storage type to use */
+    type: "memory" | "api" | "hybrid";
+    /** The collection of the core collection procedures for API storage (default: "procedures") */
+    collection?: string | undefined;
+    /** The service of the calls, for a server with other paths (default: `collections.<collection>`) */
+    service?: string | undefined;
+    /** Options for the synced registry */
+    options?: Partial<SyncedRegistryOptions> | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/procedures/storage/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/procedures/storage/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAMpE;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IAEf,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,IAAI,EAAE,aAAa,CAAC;IAEpB,yBAAyB;IACzB,QAAQ,EAAE,iBAAiB,CAAC;IAE5B,gDAAgD;IAChD,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAEhC,0DAA0D;IAC1D,UAAU,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAE1C,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE9B,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAMD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;CAC3D;AAMD;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;AAExE;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,YAAY,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,IAAI,EAAE,aAAa,CAAC;IAEpB,oCAAoC;IACpC,UAAU,EAAE,kBAAkB,CAAC;IAE/B,6BAA6B;IAC7B,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAE5B,8BAA8B;IAC9B,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IAEf,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IAEf,wCAAwC;IACxC,SAAS,EAAE,YAAY,EAAE,CAAC;IAE1B,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,SAAS,EAAE,OAAO,CAAC;IAEnB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE9B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE9B,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IAEvB,gCAAgC;IAChC,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,uEAAuE;IACvE,aAAa,EAAE,aAAa,CAAC;IAE7B,yDAAyD;IACzD,kBAAkB,EAAE,kBAAkB,CAAC;IAEvC,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAElC,4DAA4D;IAC5D,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAE1C,wCAAwC;IACxC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,0BAA0B;IAC1B,IAAI,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAC;IAElC,+FAA+F;IAC/F,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEhC,oGAAoG;IACpG,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE7B,sCAAsC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,GAAG,SAAS,CAAC;CACtD"}

package/dist/procedures/storage/types.js

@@ -0,0 +1,8 @@
+/**
+ * Procedure Storage Types
+ *
+ * Types for serializing and persisting procedure definitions.
+ * Enables procedure registry to be backed by CollectionStorage.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/procedures/storage/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/procedures/storage/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/procedures/types.d.ts

@@ -0,0 +1,468 @@
+/**
+ * Procedure Type System
+ *
+ * Core types for procedure definitions, handlers, and registration.
+ * Procedures are the foundation for typed RPC calls with schema validation.
+ */
+import type { ZodErrorLike } from "../client/validation/types.js";
+import type { ProcedureSchema } from "./schema.js";
+import type { CollectionStorage } from "./collection/storage.js";
+import type { EventBus } from "../events/types.js";
+import type { HydrationEvent } from "./ref.js";
+/**
+ * Procedure path as array of segments.
+ * Forms a tree structure for nested routing.
+ *
+ * @example
+ * ```typescript
+ * ['collections', 'users', 'get']  // collections.users.get
+ * ['weather', 'forecast']           // weather.forecast
+ * ```
+ */
+export type ProcedurePath = string[];
+/**
+ * Convert path array to dot-separated key.
+ */
+export declare function pathToKey(path: ProcedurePath): string;
+/**
+ * Parse dot-separated key to path array.
+ */
+export declare function keyToPath(key: string): ProcedurePath;
+/**
+ * Metadata for procedure documentation and categorization.
+ */
+export interface ProcedureMetadata {
+    /** Human-readable description */
+    description?: string;
+    /** Tags for categorization and filtering */
+    tags?: string[];
+    /** Whether this procedure is deprecated */
+    deprecated?: boolean;
+    /** Deprecation message with migration guidance */
+    deprecationMessage?: string;
+    /**
+     * The procedures that this procedure calls through `ctx.client`: keys (`"shell.run"`) or
+     * namespaces (`"fs.*"`). A host with a call policy lets the procedure call only these and the
+     * exposed procedures (see `policy.ts`, deep dive MCP-3). `"*"` alone is not allowed: a
+     * procedure whose callees come from its input has the `runs-refs` tag.
+     */
+    calls?: readonly string[];
+    /**
+     * The side effects of the procedure (CAPABILITIES-2026-10). A host with a restriction of
+     * effects refuses a procedure without this declaration.
+     */
+    effects?: Effects;
+    /** Custom metadata fields */
+    [key: string]: unknown;
+}
+/**
+ * The side effects of a procedure. The resource names are strings that the application chooses.
+ * The standard names are `fs` (the files of the host), `network` (systems outside the host),
+ * `process` (it starts any program) and `registry` (the procedure registry).
+ */
+export interface Effects {
+    /** The resources that the procedure reads. Absent: not known. */
+    readonly reads?: readonly string[];
+    /** The resources that the procedure changes. An empty list: it changes nothing. Absent: not known. */
+    readonly writes?: readonly string[];
+    /** True: a second call with the same input changes nothing more. The default is false. */
+    readonly idempotent?: boolean;
+    /**
+     * True: the procedure can delete or overwrite data that it did not make. The default is true for
+     * a procedure that writes, as in MCP. A procedure that writes only new data declares false.
+     */
+    readonly destructive?: boolean;
+}
+/** The effects that a capability permits. An absent field permits everything of its kind. */
+export interface PermittedEffects {
+    /** The resources that a call can read: names, or `"any"`. */
+    readonly reads?: readonly string[] | "any";
+    /** The resources that a call can change: names, or `"any"`. An empty list: no change. */
+    readonly writes?: readonly string[] | "any";
+    /** False: a call cannot start a destructive procedure. */
+    readonly destructive?: boolean;
+}
+/**
+ * The types that an application gives to the framework, by declaration merging:
+ *
+ * ```ts
+ * declare module "@procedures/client" {
+ *   interface Register {
+ *     clearance: "public" | "shared" | "private";
+ *     resources: { world: World };
+ *   }
+ * }
+ * ```
+ */
+export interface Register {
+}
+/** The type of a clearance value: `Register["clearance"]`, or `unknown`. */
+export type ClearanceOf = Register extends {
+    clearance: infer C;
+} ? C : unknown;
+/** The type of `ctx.resources`: `Register["resources"]`, or a record of unknown values. */
+export type ResourcesOf = Register extends {
+    resources: infer R;
+} ? R : Readonly<Record<string, unknown>>;
+/**
+ * The permissions of one invocation. A nested call gets the same capability or a narrower one,
+ * and only the host makes a capability (from its authentication). The object is frozen.
+ */
+export interface Capability<C = ClearanceOf> {
+    /** The data that the call can see. Absent: no limit. The application gives the order. */
+    readonly clearance?: C;
+    /** The effects that the call and its nested calls can have. Absent: all effects. */
+    readonly effects?: PermittedEffects;
+    /** The time (milliseconds since the epoch) at which the call and its nested calls stop. */
+    readonly deadline?: number;
+}
+/**
+ * A request for a narrower capability (a nested call, an interceptor). The framework calculates
+ * the result, so a request for more has no effect.
+ */
+export interface CapabilityRequest<C = ClearanceOf> {
+    clearance?: C;
+    effects?: PermittedEffects;
+    /** The time from now, in milliseconds. The result is the earlier of the two deadlines. */
+    timeoutMs?: number;
+}
+/** The order of clearance values: a partial order with a meet (the highest common lower value). */
+export interface ClearanceOrder<C = ClearanceOf> {
+    /** True when `a` is the same as or lower than `b`. */
+    leq(a: C, b: C): boolean;
+    /** The highest value that is the same as or lower than both. */
+    meet(a: C, b: C): C;
+}
+/**
+ * Repository provider for storage access.
+ * Injected into procedure handlers for data access.
+ */
+export interface RepositoryProvider {
+    /**
+     * Get storage for a collection.
+     *
+     * @param collection - Collection name
+     * @returns Storage instance for the collection
+     */
+    getStorage<T>(collection: string): CollectionStorage<T>;
+    /**
+     * Check if a collection exists.
+     *
+     * @param collection - Collection name
+     */
+    hasCollection(collection: string): boolean;
+}
+/**
+ * Context passed to procedure handlers.
+ * Contains request metadata and service access.
+ */
+export interface ProcedureContext {
+    /** Request metadata (auth, tracing, etc.) */
+    metadata: Record<string, unknown>;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Repository provider for storage access */
+    repository?: RepositoryProvider;
+    /** The full path that was called */
+    path: ProcedurePath;
+    /**
+     * Event bus for pub/sub messaging.
+     * Use for streaming coordination and inter-procedure communication.
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to updates in a streaming handler
+     * handler: async function* (input, ctx) {
+     *   yield await getInitial(input.id);
+     *
+     *   for await (const update of ctx.bus.stream(`entity:${input.id}`)) {
+     *     yield update;
+     *   }
+     * }
+     *
+     * // Emit events from another procedure
+     * handler: async (input, ctx) => {
+     *   const result = await saveEntity(input);
+     *   ctx.bus.emit(`entity:${input.id}`, result);
+     *   return result;
+     * }
+     * ```
+     */
+    bus?: EventBus;
+    /**
+     * Client for calling other procedures.
+     * Enables inter-procedure communication via the RPC mechanism.
+     *
+     * @example
+     * ```typescript
+     * handler: async (input, ctx) => {
+     *   // Call fs.mkdir procedure
+     *   await ctx.client.call(["fs", "mkdir"], { path: input.dir });
+     *
+     *   // Call git.init procedure
+     *   await ctx.client.call(["git", "init"], { cwd: input.dir });
+     *
+     *   return { created: true };
+     * }
+     * ```
+     */
+    client: ProcedureClient;
+    /**
+     * The registry of the caller: `ctx.client` finds the nested procedures here. A procedure that
+     * reads or changes the registry (`procedure.define`, `client.lookup`) uses this one. When it is
+     * not set, such a procedure uses `PROCEDURE_REGISTRY`.
+     */
+    registry?: ProcedureRegistryLike;
+    /**
+     * 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
+     * `hydrateInput`, so a trace sees the events of its own program only.
+     */
+    onRef?: ((event: HydrationEvent) => void) | undefined;
+    /**
+     * The capability of this invocation (CAPABILITIES-2026-10): its clearance, permitted effects
+     * and deadline. The nested calls of `ctx.client` get it, or a narrower one. Frozen.
+     */
+    capability: Capability;
+    /**
+     * The resources that the host gives to this invocation, for its capability: a view of a
+     * database for a lower clearance, for example. Empty when the host gives none.
+     */
+    resources: ResourcesOf;
+}
+/**
+ * The part of `ProcedureRegistry` that a procedure can use through `ctx.registry`.
+ */
+export interface ProcedureRegistryLike {
+    get(path: ProcedurePath): AnyProcedure | undefined;
+    has(path: ProcedurePath): boolean;
+    getAll(): AnyProcedure[];
+    register(procedure: AnyProcedure, options?: RegistrationOptions): void;
+    unregister(path: ProcedurePath): boolean;
+}
+/**
+ * Interface for procedure-to-procedure calls.
+ * Implemented by both Client and ProcedureServer's internal caller.
+ */
+export interface ProcedureClient {
+    /**
+     * Call a procedure by path. For a streaming procedure, the result is the last item.
+     */
+    call<TInput = unknown, TOutput = unknown>(path: ProcedurePath, input: TInput, options?: NestedCallOptions): Promise<TOutput>;
+    /**
+     * Call a procedure by path and read each output: each item of a streaming procedure, or the
+     * one value of another procedure. The procedure starts when the caller reads the first item.
+     * An older client has no `stream`.
+     */
+    stream?<TInput = unknown, TOutput = unknown>(path: ProcedurePath, input: TInput, options?: NestedCallOptions): AsyncIterable<TOutput>;
+}
+/** The options of one nested call. */
+export interface NestedCallOptions {
+    /** A narrower capability for the nested call. A request for more has no effect. */
+    narrow?: CapabilityRequest | undefined;
+}
+/**
+ * Standard procedure handler function (single return).
+ * Receives validated input and context, returns output.
+ *
+ * @example
+ * ```typescript
+ * const handler: StandardHandler<{ id: string }, User> = async (input, ctx) => {
+ *   const storage = ctx.repository?.getStorage<User>('users');
+ *   const user = await storage?.get(input.id);
+ *   if (!user) throw new Error('User not found');
+ *   return user;
+ * };
+ * ```
+ */
+export type StandardHandler<TInput = unknown, TOutput = unknown> = (input: TInput, context: ProcedureContext) => Promise<TOutput> | TOutput;
+/**
+ * Generator procedure handler (streaming/multi-yield).
+ * Yields output values one or more times.
+ *
+ * @example
+ * ```typescript
+ * // Single yield (same as standard, but generator syntax)
+ * const handler: GeneratorHandler<{ id: string }, User> = async function* (input, ctx) {
+ *   const user = await fetchUser(input.id);
+ *   yield user;  // yields once
+ * };
+ *
+ * // Multi-yield streaming
+ * const handler: GeneratorHandler<{ roomId: string }, Message> = async function* (input, ctx) {
+ *   // Initial data
+ *   yield await getInitialMessages(input.roomId);
+ *
+ *   // Stream updates
+ *   for await (const msg of ctx.bus.stream(`room:${input.roomId}`)) {
+ *     yield msg;  // yields many times
+ *   }
+ * };
+ * ```
+ */
+export type GeneratorHandler<TInput = unknown, TOutput = unknown> = (input: TInput, context: ProcedureContext) => AsyncGenerator<TOutput, void, unknown>;
+/**
+ * Procedure handler function - supports both standard and generator forms.
+ *
+ * - **Standard handlers**: Return a single value (sync or async)
+ * - **Generator handlers**: Yield one or more values
+ *
+ * The caller's consumption mode (sponge/stream/handlers) determines
+ * how the output is delivered, regardless of handler type.
+ *
+ * @example
+ * ```typescript
+ * // Standard handler (single return)
+ * const handler: ProcedureHandler<{ id: string }, User> = async (input, ctx) => {
+ *   return await fetchUser(input.id);
+ * };
+ *
+ * // Generator handler (streaming)
+ * const handler: ProcedureHandler<{ query: string }, SearchResult> = async function* (input, ctx) {
+ *   for await (const result of search(input.query)) {
+ *     yield result;
+ *   }
+ * };
+ * ```
+ */
+export type ProcedureHandler<TInput = unknown, TOutput = unknown> = StandardHandler<TInput, TOutput> | GeneratorHandler<TInput, TOutput>;
+/**
+ * Full procedure definition with schemas and optional handler.
+ *
+ * @example
+ * ```typescript
+ * const getUserProcedure: Procedure<GetUserInput, User> = {
+ *   path: ['users', 'get'],
+ *   input: z.object({ id: z.string() }),
+ *   output: z.object({ id: z.string(), name: z.string() }),
+ *   metadata: { description: 'Get user by ID', tags: ['users', 'read'] },
+ *   handler: async ({ id }, ctx) => { ... },
+ * };
+ * ```
+ */
+export interface Procedure<TInput = unknown, TOutput = unknown, TMeta extends ProcedureMetadata = ProcedureMetadata> {
+    /** Path in the route tree */
+    path: ProcedurePath;
+    /** Input validation schema: a Standard Schema (zod 4, valibot, arktype) or a `ZodLike` */
+    input: ProcedureSchema<TInput>;
+    /** Output validation schema: a Standard Schema or a `ZodLike` */
+    output: ProcedureSchema<TOutput>;
+    /** Procedure metadata for documentation */
+    metadata: TMeta;
+    /**
+     * Whether this procedure supports streaming (multi-yield).
+     * When true, the handler is expected to be a generator that may yield multiple times.
+     * When false or undefined, the procedure yields exactly once.
+     *
+     * This is a capability declaration - callers can still consume
+     * streaming procedures in sponge mode (getting only the final value).
+     */
+    streaming?: boolean | undefined;
+    /**
+     * Output mode declaration - how the procedure produces its output.
+     *
+     * - `single`: Returns a single value (default) - most procedures
+     * - `stream`: Returns multiple values over time (generator that yields many times)
+     * - `batch`: Returns an array of values all at once
+     *
+     * The consumer can choose their consumption mode (sponge/stream/handlers)
+     * independently. The system translates automatically:
+     *
+     * | Producer Mode | Consumer Mode | Result Type              |
+     * |---------------|---------------|--------------------------|
+     * | single        | sponge        | Promise<T>               |
+     * | single        | stream        | AsyncIterable<T> (1 item)|
+     * | stream        | sponge        | Promise<T> (last value)  |
+     * | stream        | stream        | AsyncIterable<T>         |
+     * | batch         | sponge        | Promise<T[]>             |
+     * | batch         | stream        | AsyncIterable<T>         |
+     */
+    outputMode?: 'single' | 'stream' | 'batch' | undefined;
+    /** Server-side handler implementation (optional for stubs and aggregations) */
+    handler?: ProcedureHandler<TInput, TOutput> | undefined;
+}
+/**
+ * Procedure without type parameters for generic storage.
+ * Uses `any` for handler to allow covariant/contravariant type compatibility.
+ */
+export type AnyProcedure = Procedure<any, any, ProcedureMetadata>;
+/**
+ * How a procedure produces its output.
+ */
+export type OutputMode = 'single' | 'stream' | 'batch';
+/**
+ * Default output mode when not specified.
+ */
+export declare const DEFAULT_OUTPUT_MODE: OutputMode;
+/**
+ * Result of a procedure call.
+ */
+export type ProcedureResult<TOutput> = {
+    success: true;
+    data: TOutput;
+} | {
+    success: false;
+    error: ProcedureError;
+};
+/**
+ * Error from procedure execution.
+ */
+export interface ProcedureError {
+    /** Error code */
+    code: string;
+    /** Error message */
+    message: string;
+    /** Whether the error is retryable */
+    retryable: boolean;
+    /** Validation errors if applicable */
+    validationErrors?: ZodErrorLike;
+    /** The procedure path that failed */
+    path: ProcedurePath;
+}
+/**
+ * Infer input type from a procedure.
+ */
+export type InferProcedureInput<T> = T extends Procedure<infer TInput, any, any> ? TInput : unknown;
+/**
+ * Infer output type from a procedure.
+ */
+export type InferProcedureOutput<T> = T extends Procedure<any, infer TOutput, any> ? TOutput : unknown;
+/**
+ * Infer metadata type from a procedure.
+ */
+export type InferProcedureMetadata<T> = T extends Procedure<any, any, infer TMeta> ? TMeta : ProcedureMetadata;
+/**
+ * Event types emitted by ProcedureRegistry.
+ */
+export type RegistryEventType = "register" | "unregister";
+/**
+ * Listener for registry events.
+ */
+export interface RegistryListener {
+    event: RegistryEventType;
+    listener: (procedure: AnyProcedure) => void;
+}
+/**
+ * Module that exports procedures for registration.
+ */
+export interface ProcedureModule {
+    /** Array of procedures exported by this module */
+    procedures: AnyProcedure[];
+    /** Optional module name for debugging */
+    name?: string;
+    /**
+     * The modules whose procedures this module calls (for example `client-lib` calls `fs.*` and
+     * `git.*`). `createRegistry()` registers them too.
+     */
+    requires?: readonly ProcedureModule[] | undefined;
+}
+/**
+ * Registration options for bulk procedure registration.
+ */
+export interface RegistrationOptions {
+    /** Override existing procedures with same path */
+    override?: boolean;
+    /** Prefix to prepend to all paths */
+    pathPrefix?: ProcedurePath;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/procedures/types.js

@@ -0,0 +1,23 @@
+/**
+ * Procedure Type System
+ *
+ * Core types for procedure definitions, handlers, and registration.
+ * Procedures are the foundation for typed RPC calls with schema validation.
+ */
+/**
+ * Convert path array to dot-separated key.
+ */
+export function pathToKey(path) {
+    return path.join(".");
+}
+/**
+ * Parse dot-separated key to path array.
+ */
+export function keyToPath(key) {
+    return key.split(".");
+}
+/**
+ * Default output mode when not specified.
+ */
+export const DEFAULT_OUTPUT_MODE = 'single';
+//# sourceMappingURL=types.js.map

package/dist/procedures/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/procedures/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwBH;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,IAAmB;IAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;AA8bD;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAe,QAAQ,CAAC"}

package/dist/register.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Importing this file registers the procedures of `@procedures/client` in the global registry:
+ * `import "@procedures/client/register"`. These are the control flow (`client.chain`, `client.map`
+ * and the others) and `procedure.define`/`get`/`list`/`delete`. The other entries of the package
+ * register nothing (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+export {};
+//# sourceMappingURL=register.d.ts.map

package/dist/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/register.js

@@ -0,0 +1,9 @@
+/**
+ * Importing this file registers the procedures of `@procedures/client` in the global registry:
+ * `import "@procedures/client/register"`. These are the control flow (`client.chain`, `client.map`
+ * and the others) and `procedure.define`/`get`/`list`/`delete`. The other entries of the package
+ * register nothing (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+import { registerClientProcedures } from "./procedures/module.js";
+registerClientProcedures();
+//# sourceMappingURL=register.js.map