@procedures/client 0.7.0 → 0.8.0

package/src/events/types.ts

@@ -82,9 +82,10 @@ export interface EventBus {
    *
    * @param channel - Channel to subscribe to
    * @param handler - Handler function called for each event
+   * @param options - `onClear`: the function that runs when `clear()` or `clearAll()` removes the handler
    * @returns Unsubscribe function
    */
-  on<T>(channel: string, handler: EventHandler<T>): Unsubscribe;
+  on<T>(channel: string, handler: EventHandler<T>, options?: EventListenOptions): Unsubscribe;
 
   /**
    * Subscribe to a single event on a channel.
@@ -177,7 +178,8 @@ export interface TypedEventBus<TChannels extends ChannelMap> {
   emit<K extends keyof TChannels & string>(channel: K, data: TChannels[K]): void;
   on<K extends keyof TChannels & string>(
     channel: K,
-    handler: EventHandler<TChannels[K]>
+    handler: EventHandler<TChannels[K]>,
+    options?: EventListenOptions
   ): Unsubscribe;
   once<K extends keyof TChannels & string>(channel: K, options?: EventWaitOptions): Promise<TChannels[K]>;
   stream<K extends keyof TChannels & string>(channel: K, options?: EventWaitOptions): AsyncIterable<TChannels[K]>;
@@ -238,6 +240,17 @@ export interface EventWaitOptions {
   signal?: AbortSignal | undefined;
 }
 
+/**
+ * Options for a handler of `on()`.
+ */
+export interface EventListenOptions {
+  /**
+   * This function runs one time when `clear()` or `clearAll()` removes the handler. An unsubscribe
+   * does not run it. The publisher of the remote events uses it to end a subscription with notice.
+   */
+  onClear?: (() => void) | undefined;
+}
+
 /**
  * Options for creating an event bus.
  */

package/src/procedures/caller.ts

@@ -0,0 +1,45 @@
+/**
+ * A caller of the procedures of some modules (`callerOf`). An app that calls the procedures of a
+ * package in its own process repeats three steps: a registry of the module, `invokePath` and
+ * `outputValue`. A caller does the three steps in one call. jarvis had four copies of them.
+ */
+
+import type { ProcedurePath } from "./types.js";
+import type { ProcedureRegistry } from "./registry.js";
+import { invokePath, outputValue, type InvokeOptions } from "./invoke.js";
+import { createRegistry, type ModuleInput } from "./module.js";
+
+/** The options of one call of a caller: the options of `invokePath` without the registry. */
+export type CallerOptions = Omit<InvokeOptions, "registry">;
+
+/** A function that runs the procedures of its modules (`callerOf`). */
+export interface Caller {
+  /**
+   * This function runs the procedure at `path` with `input`, and gives one value: the value of
+   * the procedure, or the last item of its stream. An empty stream rejects with `NO_OUTPUT`, and
+   * a path that the modules do not have rejects with `NOT_FOUND`.
+   */
+  <T = unknown>(path: ProcedurePath, input: unknown, options?: CallerOptions): Promise<T>;
+  /** The registry of the caller: `clientModule` and the modules, with their required modules. The first use makes it. */
+  readonly registry: ProcedureRegistry;
+}
+
+/**
+ * This function makes a caller of the procedures of the modules. The registry of the modules is
+ * made at the first call, so a caller costs nothing until it calls. The caller does not use the
+ * global registry.
+ *
+ * @example
+ * const gh = callerOf(ghModule);
+ * const runs = await gh<RunList>(["gh", "run", "list"], { repo: "owner/name" });
+ */
+export function callerOf(...modules: ModuleInput[]): Caller {
+  let registry: ProcedureRegistry | undefined;
+  const registryOf = (): ProcedureRegistry => (registry ??= createRegistry(...modules));
+  const call = async <T = unknown>(path: ProcedurePath, input: unknown, options: CallerOptions = {}): Promise<T> => {
+    const output = await invokePath<T>(path, input, { ...options, registry: registryOf() });
+    return outputValue(output, path);
+  };
+  Object.defineProperty(call, "registry", { get: registryOf, enumerable: true });
+  return call as Caller;
+}

package/src/procedures/collection/index.ts

@@ -21,6 +21,8 @@ export {
   getAllOutputSchema,
   entriesInputSchema,
   entriesOutputSchema,
+  idsInputSchema,
+  idsOutputSchema,
   changesInputSchema,
   changesOutputSchema,
   sizeInputSchema,
@@ -44,6 +46,7 @@ export type {
   GetAllInput,
   EntriesInput,
   CollectionEntry,
+  IdsInput,
   ChangesInput,
   ChangesOutput,
   SizeInput,

package/src/procedures/collection/procedures.ts

@@ -20,6 +20,8 @@ import {
   getAllOutputSchema,
   entriesInputSchema,
   entriesOutputSchema,
+  idsInputSchema,
+  idsOutputSchema,
   changesInputSchema,
   changesOutputSchema,
   sizeInputSchema,
@@ -39,6 +41,7 @@ import {
   type HasInput,
   type GetAllInput,
   type EntriesInput,
+  type IdsInput,
   type ChangesInput,
   type ChangesOutput,
   type SizeInput,
@@ -199,6 +202,25 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
       },
     }),
 
+    // Ids: the ids of the items without the values, for a full sync
+    defineProcedure({
+      path: [...basePath, "ids"],
+      input: idsInputSchema,
+      output: idsOutputSchema,
+      metadata: {
+        effects: { reads: [resource], writes: [] },
+        description: `Get the ids of the items of ${collectionName}, without the values`,
+        tags: ["collections", collectionName, "read"],
+      },
+      handler: async (_input: IdsInput, ctx: ProcedureContext) => {
+        const storage = getStorage(ctx);
+        if (storage.getIds) return storage.getIds();
+        // A storage without getIds() gives its entries: the values stay on the server
+        if (storage.getEntries) return (await storage.getEntries()).map(([id]) => id);
+        throw new Error(`The storage of ${collectionName} cannot give the ids of its items`);
+      },
+    }),
+
     // Changes: the items that changed after a version, for a delta sync (roadmap R28)
     defineProcedure({
       path: [...basePath, "changes"],

package/src/procedures/collection/schemas.ts

@@ -406,6 +406,43 @@ export const entriesOutputSchema : ZodLike<CollectionEntry[]> = createSchema<Col
   };
 });
 
+// =============================================================================
+// Ids Operation Schemas
+// =============================================================================
+
+/** Input for ids operation - empty object. */
+export interface IdsInput {}
+
+export const idsInputSchema : ZodLike<IdsInput> = createSchema<IdsInput>((data) => {
+  if (!isObject(data)) {
+    return {
+      success: false,
+      error: {
+        message: "Input must be an object",
+        errors: [{ path: [], message: "Input must be an object" }],
+      },
+    };
+  }
+  return { success: true, data: {} };
+});
+
+/**
+ * Output for ids operation: the ids of the items, in the order of the entries, without the
+ * values. A full sync needs only the ids.
+ */
+export const idsOutputSchema : ZodLike<string[]> = createSchema<string[]>((data) => {
+  if (isArray(data) && data.every((id) => isString(id))) {
+    return { success: true, data: data as string[] };
+  }
+  return {
+    success: false,
+    error: {
+      message: "Output must be an array of ids",
+      errors: [{ path: [], message: "Output must be an array of ids" }],
+    },
+  };
+});
+
 // =============================================================================
 // Changes Operation Schemas
 // =============================================================================

package/src/procedures/collection/storage.ts

@@ -13,6 +13,7 @@
  * The contract (the suite of `@procedures/collections/testing` tests it for each storage):
  * - A storage keeps a copy of each value that a write takes, and each read gives a new copy.
  * - A stored `null` reads back as `null`. A missing id reads back as `undefined`.
+ * - `getIds()` gives the ids of `getEntries()`, in the same order.
  * - A delta of `getChangesSince` follows the order of the last change of each id.
  * - After `close()`, each operation rejects with an error whose message says "closed". A second
  *   `close()` does nothing.
@@ -27,6 +28,11 @@ export interface CollectionStorage<T> {
    * them does not have this method.
    */
   getEntries?(): Promise<Array<[string, T]>>;
+  /**
+   * The ids of the items, in the order of the entries, without the values. A storage that cannot
+   * give the ids cheaply does not have this method.
+   */
+  getIds?(): Promise<string[]>;
   /**
    * The changes after a version (roadmap R28). A storage without a change log does not have
    * this method, and a sync uses `getEntries()`.

package/src/procedures/index.ts

@@ -25,6 +25,7 @@ export type {
   RegistrationOptions,
   ProcedureRegistryLike,
   Effects,
+  FsRootRules,
   PermittedEffects,
   Register,
   ClearanceOf,
@@ -107,6 +108,9 @@ export {
   registerClientProcedures,
 } from "./module.js";
 export type { ModuleInput } from "./module.js";
+// One call for a registry of some modules, `invokePath` and `outputValue`
+export { callerOf } from "./caller.js";
+export type { Caller, CallerOptions } from "./caller.js";
 
 // Procedure reference system (procedure-as-data)
 export {

package/src/procedures/invoke.ts

@@ -486,6 +486,8 @@ export function createProcedureContext(
   if (options.expose) context.expose = options.expose;
   if (options.repository) context.repository = options.repository;
   if (options.onRef) context.onRef = options.onRef;
+  // The procedure of the parent invocation made this call (roadmap R33: the root of the files)
+  if (invocation?.parent) context.caller = invocation.parent.procedure;
   // 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.)

package/src/procedures/types.ts

@@ -83,10 +83,56 @@ export interface ProcedureMetadata {
    */
   stream?: { readonly unbounded?: boolean } | undefined;
 
+  /**
+   * The rules of the procedure under a root of the files (roadmap R33): the inputs that name a
+   * path, or the reason that a root cannot confine it. A host with a root (`--fs-root`,
+   * `MCP_FS_ROOT`) reads them. Without the rules, the host decides from `effects`.
+   */
+  fsRoot?: FsRootRules | undefined;
+
   /** Custom metadata fields */
   [key: string]: unknown;
 }
 
+/**
+ * The rules of a procedure under a root of the files (roadmap R33). A host with a root keeps each
+ * path of these inputs in the root, or it refuses the procedure. `confineToRoot()` of
+ * `@procedures/fs` applies the rules. Without a root, the rules change nothing.
+ */
+export interface FsRootRules {
+  /**
+   * The input that names the working folder. When the call gives no value, the procedure gets the
+   * root. A relative value starts at the root.
+   */
+  readonly cwd?: string;
+  /**
+   * The inputs that name a file or a folder: a text, or a list of texts. A relative path starts at
+   * the root. The procedure gets the absolute path.
+   */
+  readonly paths?: readonly string[];
+  /**
+   * The inputs that name a file or a folder relative to the working folder, for example the files
+   * of an archive. A relative name starts at the working folder, or at the root without `cwd`.
+   * The host examines each path, and it does not change the value.
+   */
+  readonly names?: readonly string[];
+  /**
+   * The inputs of `paths` whose default is outside the working folder. Under a root, a call
+   * without a value of such an input is refused.
+   */
+  readonly required?: readonly string[];
+  /** The values of the inputs that are not paths, for example `:memory:` of SQLite. */
+  readonly values?: readonly string[];
+  /** The reason that a root cannot confine the procedure. Under a root, the host refuses it. */
+  readonly refuse?: string;
+  /**
+   * True for a procedure that starts the program of its input (`shell.run`). Under a root, the
+   * host refuses a call of a client. It accepts the nested call of a confined procedure that
+   * names this procedure in `metadata.calls`.
+   */
+  readonly program?: boolean;
+}
+
 // =============================================================================
 // Capabilities (CAPABILITIES-2026-10)
 // =============================================================================
@@ -294,6 +340,13 @@ export interface ProcedureContext {
    * database for a lower clearance, for example. Empty when the host gives none.
    */
   resources: ResourcesOf;
+
+  /**
+   * The procedure whose handler made this call through its `ctx.client`. A call of a host or a
+   * client has no caller. The framework sets it from the invocation, so an input cannot change
+   * it. The root of the files reads it (roadmap R33).
+   */
+  caller?: AnyProcedure | undefined;
 }
 
 /**

package/src/protocol.ts

@@ -47,7 +47,8 @@ export type ProtocolErrorCode =
   | "UNAVAILABLE"
   | "CONNECTION_CLOSED"
   | "CONNECTION_NOT_FOUND"
-  | "TOPIC_NOT_FOUND";
+  | "TOPIC_NOT_FOUND"
+  | "TOPIC_CLEARED";
 
 /**
  * The error codes of the protocol, on each face (HTTP, WebSocket, MCP, local). An error that a
@@ -78,6 +79,7 @@ export const ERROR_CODES: Readonly<Record<ProtocolErrorCode, ErrorCodeInfo>> = {
   CONNECTION_CLOSED: { http: 503, retryable: true, meaning: "The connection closed before the call left" },
   CONNECTION_NOT_FOUND: { http: 404, retryable: false, meaning: "The server has no connection with this id" },
   TOPIC_NOT_FOUND: { http: 404, retryable: false, meaning: "The topic rule of the host has no topic with this name" },
+  TOPIC_CLEARED: { http: 410, retryable: false, meaning: "The host cleared a topic of the subscription: clear() of its bus removed the listener" },
 };
 
 /** True when a code is an error code of the protocol. */

package/src/server/procedure-server.ts

@@ -24,6 +24,7 @@ import { IdempotencyCache, idempotencyKeyOf, isRepeatable, type IdempotencyOptio
 import { optionalMs, type Duration } from "../duration.js";
 import type { CollectionStorage } from "../procedures/collection/storage.js";
 import { TIMER_DEFAULTS } from "../timers.js";
+import { realClock, type Clock } from "../clock.js";
 import { errorCodeOf } from "../protocol.js";
 import { EventPublisher, type EventPublisherOptions } from "../events/publisher.js";
 import { getGlobalEventBus } from "../events/bus.js";
@@ -49,8 +50,18 @@ export interface UseStorageOptions {
    * flush fails, the old storage stays and `useStorage` throws.
    */
   drain?: boolean | undefined;
-  /** True: the server closes the old storage after the change. */
+  /**
+   * True: the server closes the old storage after the change. The close waits for the calls that
+   * took the old storage, for the time of `grace` at most.
+   */
   close?: boolean | undefined;
+  /**
+   * The longest time that the close waits for the calls on the old storage, for example
+   * `seconds(5)`. When the time ends, the server closes the old storage. A call that still uses it
+   * then fails with the error of a closed storage. 0: the server closes it at once.
+   * @default 30 seconds (`TIMER_DEFAULTS.server.storageGraceMs`)
+   */
+  grace?: Duration | undefined;
 }
 
 /**
@@ -66,6 +77,12 @@ export interface ProcedureServerOptions extends ServerOptions {
   /** Collections to configure with storage backends */
   collections?: Record<string, CollectionStorage<unknown>>;
 
+  /**
+   * The clock of the wait of `useStorage` for the calls on an old storage (roadmap R35). The
+   * default is the clock of the platform. A test gives a fake clock.
+   */
+  clock?: Clock | undefined;
+
   /**
    * The procedures that the callers of this server can reach. `registerFromRegistry()` registers
    * only these procedures. A data-driven procedure (control flow, `eval`, a procedure that
@@ -166,6 +183,15 @@ export interface StopOptions {
   grace?: Duration | undefined;
 }
 
+/** The items of a stream. At the end of the stream, or when its reader stops, `release` runs. */
+async function* releasedAtEnd<T>(items: AsyncIterable<T>, release: () => void): AsyncGenerator<T, void, undefined> {
+  try {
+    yield* items;
+  } finally {
+    release();
+  }
+}
+
 /** A signal that aborts when one of the signals aborts. */
 function joinSignals(first: AbortSignal | undefined, second: AbortSignal): AbortSignal {
   if (!first) return second;
@@ -271,6 +297,10 @@ export function errorResponse(id: string, error: unknown): ServerResponse<unknow
 export class ProcedureServer extends Server implements RepositoryProvider {
   private readonly procedureRegistry: ProcedureRegistry;
   private readonly storages = new Map<string, CollectionStorage<unknown>>();
+  /** For each storage: the calls in flight that took it, and the closes that wait for them */
+  private readonly storageUses = new Map<CollectionStorage<unknown>, { calls: number; waiters: Array<() => void> }>();
+  /** The clock of the wait of `useStorage` */
+  private readonly clock: Clock;
   /** The procedures that `registerProcedure` pinned, by key */
   private readonly pinnedProcedures = new Map<string, AnyProcedure>();
   /**
@@ -308,6 +338,7 @@ export class ProcedureServer extends Server implements RepositoryProvider {
     super(options);
 
     this.procedureRegistry = options.registry ?? PROCEDURE_REGISTRY;
+    this.clock = options.clock ?? realClock;
     this.expose = options.expose;
     this.strictCalls = options.strictCalls ?? false;
     this.interceptors = options.interceptors ?? [];
@@ -379,7 +410,11 @@ export class ProcedureServer extends Server implements RepositoryProvider {
    *   failed flush keeps the old storage and throws. A call that arrives during the flush goes
    *   to the old storage.
    * - `close`: the server closes the old storage after the change. The close of a
-   *   `HybridStorage` sends the writes that arrived during the flush.
+   *   `HybridStorage` sends the writes that arrived during the flush. An old storage that another
+   *   collection still uses stays open: the server closes it when the last collection leaves it.
+   * - The new calls use the new storage at once. Before the close, the server waits for the calls
+   *   that took the old storage, for the time of `grace` at most. Before, such a call could fail
+   *   because the storage was closed.
    *
    * @param name - Collection name
    * @param storage - Storage backend
@@ -396,20 +431,76 @@ export class ProcedureServer extends Server implements RepositoryProvider {
     return this.replaceStorage(name, storage as CollectionStorage<unknown>, options);
   }
 
-  /** The change of `useStorage` with options: flush the old storage, change, close the old one. */
+  /**
+   * The change of `useStorage` with options: flush the old storage, change, wait for the calls on
+   * the old storage, and close it.
+   */
   private async replaceStorage(name: string, storage: CollectionStorage<unknown>, options: UseStorageOptions): Promise<this> {
+    const graceMs = optionalMs(options.grace, "grace") ?? TIMER_DEFAULTS.server.storageGraceMs;
     const old = this.storages.get(name);
     const other = old !== undefined && old !== storage ? old : undefined;
     if (other && options.drain) {
       await other.flush?.();
     }
     this.storages.set(name, storage);
-    if (other && options.close) {
+    // Another collection that uses the same storage keeps it open. Before, the close broke the
+    // calls of that collection (tracker O31).
+    if (other && options.close && ![...this.storages.values()].includes(other)) {
+      await this.callsOnStorageEnded(other, graceMs);
       await other.close();
     }
     return this;
   }
 
+  /** A promise that resolves when no call uses the storage, or when `graceMs` ends. */
+  private callsOnStorageEnded(storage: CollectionStorage<unknown>, graceMs: number): Promise<void> {
+    const use = this.storageUses.get(storage);
+    if (!use || graceMs <= 0) return Promise.resolve();
+    return new Promise<void>((resolve) => {
+      const done = (): void => {
+        cancel();
+        const index = use.waiters.indexOf(done);
+        if (index >= 0) use.waiters.splice(index, 1);
+        resolve();
+      };
+      const cancel = this.clock.after(graceMs, done);
+      use.waiters.push(done);
+    });
+  }
+
+  /**
+   * The repository of one call. The call is a user of each storage that it takes, until
+   * `release()`. Then a close of `useStorage` can go on.
+   */
+  private callRepository(): { repository: RepositoryProvider; release: () => void } {
+    const taken = new Set<CollectionStorage<unknown>>();
+    let released = false;
+    const repository: RepositoryProvider = {
+      getStorage: <T>(collection: string): CollectionStorage<T> => {
+        const storage = this.getStorage<unknown>(collection);
+        if (!released && !taken.has(storage)) {
+          taken.add(storage);
+          const use = this.storageUses.get(storage) ?? { calls: 0, waiters: [] };
+          use.calls++;
+          this.storageUses.set(storage, use);
+        }
+        return storage as CollectionStorage<T>;
+      },
+      hasCollection: (collection: string): boolean => this.hasCollection(collection),
+    };
+    const release = (): void => {
+      if (released) return;
+      released = true;
+      for (const storage of taken) {
+        const use = this.storageUses.get(storage);
+        if (!use || --use.calls > 0) continue;
+        this.storageUses.delete(storage);
+        for (const waiter of use.waiters.slice()) waiter();
+      }
+    };
+    return { repository, release };
+  }
+
   /**
    * Configure multiple storages at once.
    *
@@ -645,6 +736,9 @@ export class ProcedureServer extends Server implements RepositoryProvider {
 
   /** Run a procedure for a request with a signal. */
   private async run(procedure: AnyProcedure, request: ServerRequest<unknown>, signal: AbortSignal | undefined): Promise<ServerResponse<unknown>> {
+    // The call uses the storages that it takes until its end: the end of a stream, for a stream
+    const { repository, release } = this.callRepository();
+    let streams = false;
     try {
       // One invocation path for every host (ARCHITECTURE-PROPOSALS P1): input validation, the
       // context, the expose rule for nested calls (BUGS-2026-07 H18) and output validation
@@ -653,7 +747,7 @@ export class ProcedureServer extends Server implements RepositoryProvider {
         registry: this.procedureRegistry,
         metadata: request.metadata,
         signal,
-        repository: this,
+        repository,
         expose: this.expose,
         strictCalls: this.strictCalls,
         interceptors: this.interceptors,
@@ -669,16 +763,19 @@ export class ProcedureServer extends Server implements RepositoryProvider {
       if (output.kind === "stream") {
         // The faces that collect a stream read this mark (roadmap R15)
         const unbounded = (procedure.metadata as { stream?: { unbounded?: boolean } } | undefined)?.stream?.unbounded === true;
+        streams = true;
         return {
           id: request.id,
           status: { type: "success", code: 200 },
-          stream: output.items,
+          stream: releasedAtEnd(output.items, release),
           metadata: unbounded ? { [STREAM_METADATA_KEY]: "unbounded" } : {},
         };
       }
       return { id: request.id, status: { type: "success", code: 200 }, payload: output.value, metadata: {} };
     } catch (error) {
       return errorResponse(request.id, error);
+    } finally {
+      if (!streams) release();
     }
   }
 

package/src/timers.ts

@@ -58,6 +58,11 @@ export interface TimerDefaults {
   readonly server: {
     /** The time that `ProcedureServer.stop()` waits for the calls that run. */
     readonly stopGraceMs: number;
+    /**
+     * The longest time that `ProcedureServer.useStorage` with `close` waits for the calls on the
+     * old storage, before it closes the old storage.
+     */
+    readonly storageGraceMs: number;
   };
 }
 
@@ -85,5 +90,7 @@ export const TIMER_DEFAULTS: TimerDefaults = Object.freeze({
   // stream then stays open (WIRE-PROTOCOL.md, "The keep-alive of an NDJSON stream").
   httpServer: Object.freeze({ keepAliveMs: 15_000 }),
   idempotency: Object.freeze({ ttlMs: 10 * 60_000 }),
-  server: Object.freeze({ stopGraceMs: 0 }),
+  // 30 s: the request time of the WebSocket client. A call that runs longer timed out at its
+  // client already.
+  server: Object.freeze({ stopGraceMs: 0, storageGraceMs: 30_000 }),
 });