@procedures/client 0.3.0 → 0.5.0

package/src/events/remote.ts

@@ -0,0 +1,369 @@
+/**
+ * The subscriber of the remote events (`documentation/EVENTS.md`).
+ *
+ * A peer subscribes to the topics of the bus of another peer with a streaming call of the
+ * procedure `events.subscribe`. The first item of the stream confirms the subscription, and each
+ * other item is one event. The frames are the frames of each call: credit is the backpressure,
+ * and a cancel is the unsubscribe. Thus each transport with streams carries a subscription:
+ * WebSocket in the two directions, HTTP with NDJSON, a message port and the local transport.
+ *
+ * - `remoteEvents()` gives an async iterator of the events.
+ * - `subscribeRemote()` calls a handler for each event, and gives the unsubscribe function.
+ *
+ * After a failure that a retry can repair (a closed connection, `UNAVAILABLE`, `TIMEOUT`), the
+ * subscriber sends the call again after a backoff. The delivery is at most once: the events
+ * between the failure and the new confirmation are lost. Each other error ends the subscription.
+ *
+ * This file imports only types and the backoff, so a page or a worker that subscribes stays small.
+ */
+
+import type { Message, Method, ResponseItem, Transport } from "../client/types.js";
+import { backoffDelay } from "@mark1russell7/service/backoff";
+
+/** The path of the procedure of a subscription. */
+export const EVENTS_SUBSCRIBE_PATH: readonly ["events", "subscribe"] = Object.freeze(["events", "subscribe"] as const);
+
+/** The method of the procedure of a subscription. */
+const SUBSCRIBE_METHOD: Method = Object.freeze({ service: "events", operation: "subscribe" });
+
+/** The input of `events.subscribe`. */
+export interface SubscribeInput {
+  /** The topics: from 1 to 64 names of 1 to 256 characters. */
+  readonly topics: readonly string[];
+}
+
+/**
+ * An item of the stream of `events.subscribe`. The first item is `subscribed`. Each other item is
+ * an `event`. A subscriber ignores an item of another type: it comes from a newer publisher.
+ */
+export type EventItem =
+  | { readonly type: "subscribed"; readonly topics: readonly string[] }
+  | {
+      readonly type: "event";
+      readonly topic: string;
+      readonly data: unknown;
+      /** The number of the event in its subscription, from 1. A gap shows lost events. */
+      readonly seq: number;
+      /** The number of events that the publisher dropped immediately before this one. */
+      readonly dropped?: number | undefined;
+    };
+
+/** One event that a subscriber gets. */
+export interface RemoteEvent<T = unknown> {
+  /** The topic (the channel of the bus of the publisher). */
+  readonly topic: string;
+  /** The data of the event, after a trip as JSON. */
+  readonly data: T;
+  /** The number of the event in its subscription, from 1. A resubscribe starts again at 1. */
+  readonly seq: number;
+  /** The number of events that the publisher dropped immediately before this one: 0 without a loss. */
+  readonly dropped: number;
+  /** The id of the subscription. It stays the same after a resubscribe. */
+  readonly subscription: string;
+}
+
+/**
+ * The handler of the events of a subscription. When it gives a promise, the subscriber waits for
+ * it before the next event, so a slow handler holds the credit of its own subscription only.
+ */
+export type RemoteEventHandler<T = unknown> = (data: T, event: RemoteEvent<T>) => void | Promise<void>;
+
+/** The options of a subscription. */
+export interface RemoteEventsOptions {
+  /** When this signal aborts, the subscription ends: the transport sends a cancel. */
+  signal?: AbortSignal | undefined;
+  /**
+   * True: the subscriber sends the call again after a failure that a retry can repair. False: such
+   * a failure ends the subscription.
+   * @default true
+   */
+  resubscribe?: boolean | undefined;
+  /**
+   * This function gives the time before resubscribe try `attempt` (from 1), in milliseconds. The
+   * default is an exponential backoff from 250 ms to 30 s with full jitter. The WebSocket
+   * transport uses its reconnect backoff.
+   */
+  backoff?: ((attempt: number) => number) | undefined;
+  /** This function gets the topics of each confirmation: the first one, and one after each resubscribe. */
+  onSubscribed?: ((topics: readonly string[]) => void) | undefined;
+  /** The metadata of the call, for example a trace. */
+  metadata?: Record<string, unknown> | undefined;
+}
+
+/** The options of `subscribeRemote()`. */
+export interface SubscribeOptions extends RemoteEventsOptions {
+  /**
+   * This function gets the error that ends the subscription: a refusal (`TOPIC_NOT_FOUND`,
+   * `FORBIDDEN`), an older publisher (`NOT_FOUND`), or a transport that closed. An unsubscribe is
+   * not an error.
+   */
+  onError?: ((error: SubscriptionError) => void) | undefined;
+}
+
+/**
+ * The unsubscribe function of a subscription. A second call does nothing. `ready` resolves at the
+ * first confirmation of the publisher. It rejects when the subscription ends before it.
+ */
+export interface Subscription {
+  (): void;
+  /** This promise resolves when the publisher confirms the subscription the first time. */
+  readonly ready: Promise<void>;
+  /** The id of the subscription: the `subscription` of its events. */
+  readonly id: string;
+}
+
+/** The error that ends a subscription. */
+export class SubscriptionError extends Error {
+  override readonly name = "SubscriptionError";
+
+  constructor(
+    /** The code: a code of the protocol, for example `TOPIC_NOT_FOUND`. */
+    readonly code: string,
+    message: string,
+    /** True when a resubscribe can repair the failure. */
+    readonly retryable: boolean,
+    /** The reason of a `FORBIDDEN` error, for example `topic-not-allowed`. */
+    readonly reason?: string | undefined,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * The parts that a transport adds to its subscriptions. The WebSocket transport waits for its
+ * connection, uses its reconnect backoff, ends its subscriptions at `close()`, and gives each
+ * event to its `onEvent` option.
+ */
+export interface SubscriptionHooks {
+  /** When this signal aborts, each subscription ends without an error. */
+  readonly lifetime?: AbortSignal | undefined;
+  /**
+   * This function resolves when the transport can send the call. It rejects when the transport
+   * closed. After a lost connection, the subscriber waits for it, not for a backoff.
+   */
+  readonly ready?: ((signal: AbortSignal) => Promise<void>) | undefined;
+  /** The backoff, when the options give none. */
+  readonly backoff?: ((attempt: number) => number) | undefined;
+  /** This function gets each event of each subscription. */
+  readonly onEvent?: ((event: RemoteEvent) => void) | undefined;
+  /** False: no resubscribe, whatever the options say (a server cannot reach a closed connection). */
+  readonly resubscribe?: boolean | undefined;
+}
+
+/** The part of a transport that a subscription uses. */
+export type EventTransport = Pick<Transport, "send">;
+
+/** The codes after which a resubscribe can succeed, also when the item does not say retryable. */
+const RESUBSCRIBE_CODES: ReadonlySet<string> = new Set(["UNAVAILABLE", "TIMEOUT", "CONNECTION_CLOSED", "ABORTED"]);
+
+/** The default backoff: from 250 ms, twice as long at each try, at most 30 s, with full jitter. */
+function defaultBackoff(attempt: number): number {
+  return backoffDelay({ base: 250, factor: 2, cap: 30_000, jitter: { kind: "subtract", fraction: 1 } }, attempt);
+}
+
+let subscriptions = 0;
+
+/** The topics of a subscription as a list. */
+function topicList(topics: string | readonly string[]): readonly string[] {
+  return typeof topics === "string" ? [topics] : [...topics];
+}
+
+/** A signal that aborts when one of the signals aborts, and a function that removes its listeners. */
+function linkSignals(signals: ReadonlyArray<AbortSignal | undefined>): { signal: AbortSignal; unlink: () => void } {
+  const controller = new AbortController();
+  const present = signals.filter((signal): signal is AbortSignal => signal !== undefined);
+  const abort = (): void => controller.abort();
+  if (present.some((signal) => signal.aborted)) controller.abort();
+  else for (const signal of present) signal.addEventListener("abort", abort, { once: true });
+  return {
+    signal: controller.signal,
+    unlink: () => {
+      for (const signal of present) signal.removeEventListener("abort", abort);
+    },
+  };
+}
+
+/** This function waits for a time, or until the signal aborts. */
+function pause(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted || !(ms > 0)) return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = (): void => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal.addEventListener("abort", done, { once: true });
+  });
+}
+
+/** The error of an error item of the call. */
+function errorOfItem(item: ResponseItem<unknown>): SubscriptionError {
+  const status = item.status;
+  if (status.type !== "error") return new SubscriptionError("INTERNAL_ERROR", "The item is not an error", false);
+  const code = String(status.code);
+  const reason = item.metadata?.["reason"];
+  return new SubscriptionError(code, status.message, status.retryable === true || RESUBSCRIBE_CODES.has(code), typeof reason === "string" ? reason : undefined);
+}
+
+/** The error of a call that failed in the transport: the connection closed. A resubscribe can repair it. */
+function errorOfFailure(error: unknown): SubscriptionError {
+  if (error instanceof SubscriptionError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  return new SubscriptionError("CONNECTION_CLOSED", message, true);
+}
+
+/** The events of a subscription, with each resubscribe. The generator ends at the unsubscribe. */
+async function* eventsOf<T>(
+  transport: EventTransport,
+  topics: readonly string[],
+  options: RemoteEventsOptions,
+  hooks: SubscriptionHooks,
+  id: string,
+): AsyncGenerator<RemoteEvent<T>, void, undefined> {
+  const { signal, unlink } = linkSignals([options.signal, hooks.lifetime]);
+  const resubscribe = hooks.resubscribe !== false && options.resubscribe !== false;
+  const backoff = options.backoff ?? hooks.backoff ?? defaultBackoff;
+  let attempt = 0;
+  let tries = 0;
+  try {
+    for (;;) {
+      if (signal.aborted) return;
+      if (hooks.ready) {
+        await hooks.ready(signal);
+        if (signal.aborted) return;
+      }
+      const message: Message<SubscribeInput> = {
+        id: `${id}.${++tries}`,
+        method: SUBSCRIBE_METHOD,
+        payload: { topics: [...topics] },
+        metadata: { ...(options.metadata ?? {}) },
+        signal,
+      };
+      let failure: { error: SubscriptionError; lost: boolean } | undefined;
+      try {
+        for await (const item of transport.send<SubscribeInput, EventItem>(message)) {
+          if (item.status.type === "error") {
+            failure = { error: errorOfItem(item), lost: false };
+            break;
+          }
+          const payload = item.payload as EventItem | undefined;
+          if (payload === null || typeof payload !== "object") continue;
+          if (payload.type === "subscribed") {
+            attempt = 0;
+            options.onSubscribed?.(payload.topics);
+          } else if (payload.type === "event") {
+            const event: RemoteEvent<T> = {
+              topic: payload.topic,
+              data: payload.data as T,
+              seq: payload.seq,
+              dropped: payload.dropped ?? 0,
+              subscription: id,
+            };
+            hooks.onEvent?.(event as RemoteEvent);
+            yield event;
+          }
+        }
+      } catch (error) {
+        failure = { error: errorOfFailure(error), lost: true };
+      }
+      // An unsubscribe, or the end of the transport: no error
+      if (signal.aborted) return;
+      // The publisher ended the subscription
+      if (!failure) return;
+      if (!resubscribe || !failure.error.retryable) throw failure.error;
+      attempt++;
+      // After a lost connection, the transport waits for its reconnect: no second backoff
+      if (!(failure.lost && hooks.ready)) await pause(backoff(attempt), signal);
+    }
+  } finally {
+    unlink();
+  }
+}
+
+/**
+ * This function gives the events of a subscription to topics of the bus of the other side. The
+ * iteration sends the call. A `break` of the reader, or the abort of the signal, sends the cancel.
+ * An error that ends the subscription ends the iteration with a `SubscriptionError`.
+ *
+ * @param transport - The transport to the publisher: HTTP, WebSocket, a message port, local
+ * @param topics - One topic, or a list of 1 to 64 topics
+ * @param options - The signal, the resubscribe, the backoff and the confirmation handler
+ * @param hooks - The parts that a transport adds (its connection, its backoff, its `onEvent`)
+ */
+export function remoteEvents<T = unknown>(
+  transport: EventTransport,
+  topics: string | readonly string[],
+  options: RemoteEventsOptions = {},
+  hooks: SubscriptionHooks = {},
+): AsyncIterable<RemoteEvent<T>> {
+  const list = topicList(topics);
+  return {
+    [Symbol.asyncIterator]: () => eventsOf<T>(transport, list, options, hooks, `events-${++subscriptions}`),
+  };
+}
+
+/**
+ * This function subscribes to topics of the bus of the other side, and calls the handler for each
+ * event in order. It gives the unsubscribe function, with the `ready` promise of the first
+ * confirmation. An error of the handler goes to `console.error`, and the subscription goes on.
+ *
+ * @param transport - The transport to the publisher
+ * @param topics - One topic, or a list of 1 to 64 topics
+ * @param handler - The handler of each event: it gets the data and the event
+ * @param options - The options of `remoteEvents()`, and the `onError` handler of the end
+ * @param hooks - The parts that a transport adds
+ */
+export function subscribeRemote<T = unknown>(
+  transport: EventTransport,
+  topics: string | readonly string[],
+  handler: RemoteEventHandler<T>,
+  options: SubscribeOptions = {},
+  hooks: SubscriptionHooks = {},
+): Subscription {
+  const controller = new AbortController();
+  const id = `events-${++subscriptions}`;
+  let confirmed = false;
+  let confirm: () => void = () => undefined;
+  let refuse: (error: SubscriptionError) => void = () => undefined;
+  const ready = new Promise<void>((resolve, reject) => {
+    confirm = resolve;
+    refuse = reject;
+  });
+  // A caller that does not wait for `ready` gets no unhandled rejection
+  ready.catch(() => undefined);
+  const { signal, unlink } = linkSignals([options.signal, controller.signal]);
+  const settings: RemoteEventsOptions = {
+    ...options,
+    signal,
+    onSubscribed: (list) => {
+      if (!confirmed) {
+        confirmed = true;
+        confirm();
+      }
+      options.onSubscribed?.(list);
+    },
+  };
+
+  void (async () => {
+    try {
+      for await (const event of { [Symbol.asyncIterator]: () => eventsOf<T>(transport, topicList(topics), settings, hooks, id) }) {
+        try {
+          await handler(event.data, event);
+        } catch (error) {
+          console.error(`[events] The handler of ${event.topic} failed:`, error);
+        }
+      }
+      if (!confirmed) refuse(new SubscriptionError("ABORTED", "The subscription ended before its confirmation", false));
+    } catch (error) {
+      const failure = errorOfFailure(error);
+      if (!confirmed) refuse(failure);
+      options.onError?.(failure);
+    } finally {
+      unlink();
+    }
+  })();
+
+  const unsubscribe = (): void => controller.abort();
+  return Object.assign(unsubscribe, { ready, id });
+}

package/src/index.ts

@@ -6,6 +6,10 @@
  *
  * This entry point is for Node. It exports the browser-safe entry point
  * ("@procedures/client/browser") and the server transports, which use `http` and `ws`.
+ *
+ * The `WebSocketTransport` of this entry uses the global `WebSocket`, because some applications
+ * bundle this entry for a browser. The Node entry "@procedures/client/node" has a
+ * `WebSocketTransport` whose sockets are of the `ws` package: a drop ends them at once.
  */
 
 export * from "./browser.js";

package/src/node.ts

@@ -0,0 +1,11 @@
+/**
+ * The Node entry of `@procedures/client`: `@procedures/client/node`.
+ *
+ * This entry exports the client transports with the defaults of Node. Its `WebSocketTransport`
+ * uses the `WebSocket` class of the `ws` package, so a drop ends a socket at once with
+ * `terminate()` (finding of roadmap R36). The other entries keep the global `WebSocket`: a browser
+ * bundle imports `@procedures/client/browser`, and that entry does not import `ws`.
+ */
+
+export { WebSocketTransport } from "./adapters/websocket/client/node.js";
+export type { WebSocketTransportOptions, WebSocketClass } from "./adapters/websocket/client/types.js";

package/src/procedures/collection/index.ts

@@ -37,6 +37,7 @@ export {
 
 export type {
   GetInput,
+  GetFoundOutput,
   SetInput,
   DeleteInput,
   HasInput,

package/src/procedures/collection/procedures.ts

@@ -33,6 +33,7 @@ import {
   deleteBatchInputSchema,
   deleteBatchOutputSchema,
   type GetInput,
+  type GetFoundOutput,
   type SetInput,
   type DeleteInput,
   type HasInput,
@@ -107,7 +108,11 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
       },
       handler: async (input: GetInput, ctx : ProcedureContext) => {
         const storage = getStorage(ctx);
-        return storage.get(input.id);
+        const value = await storage.get(input.id);
+        if (input.found !== true) return value;
+        // The output with `found` keeps a stored null apart from a missing id, in one call
+        const output: GetFoundOutput = value === undefined ? { found: false } : { found: true, value };
+        return output;
       },
     }),
 

package/src/procedures/collection/schemas.ts

@@ -117,6 +117,12 @@ export const valueSchema : ZodLike<unknown> = createSchema<unknown>((data) => {
  */
 export interface GetInput {
   id: string;
+  /**
+   * True: the output is `{ found, value }` (a `GetFoundOutput`), so a stored `null` and a missing
+   * id give different outputs. Without it, the output is the item, or `null` on the wire for a
+   * missing id. `ApiStorage` of `@procedures/store` sends it.
+   */
+  found?: boolean;
 }
 
 export const getInputSchema : ZodLike<GetInput> = createSchema<GetInput>((data) => {
@@ -138,11 +144,31 @@ export const getInputSchema : ZodLike<GetInput> = createSchema<GetInput>((data)
       },
     };
   }
-  return { success: true, data: { id: data["id"] } };
+  const found = data["found"];
+  if (found !== undefined && typeof found !== "boolean") {
+    return {
+      success: false,
+      error: {
+        message: "found must be a boolean",
+        errors: [{ path: ["found"], message: "found must be a boolean" }],
+      },
+    };
+  }
+  return { success: true, data: found === true ? { id: data["id"], found: true } : { id: data["id"] } };
 });
 
 /**
- * Output for get operation - the item or undefined.
+ * The output of `get` with `found: true` in the input. `found` is true when the collection has
+ * the id. Then `value` is the item, also when the item is `null`.
+ */
+export interface GetFoundOutput {
+  found: boolean;
+  value?: unknown;
+}
+
+/**
+ * Output for get operation: the item, or undefined for a missing id. With `found: true` in the
+ * input, the output is a `GetFoundOutput`.
  */
 export const getOutputSchema : ZodLike<unknown> = createSchema<unknown>((data) => {
   // Accept any value (item) or undefined

package/src/procedures/collection/storage.ts

@@ -9,9 +9,16 @@
  * the collections package (roadmap 3.3).
  *
  * Each method gives a Promise: a caller cannot tell a local storage from a remote one.
+ *
+ * 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`.
+ * - 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.
  */
 export interface CollectionStorage<T> {
-  /** The item with this id, or undefined. */
+  /** The item with this id, or undefined. A stored null is null. */
   get(id: string): Promise<T | undefined>;
   /** Every item of the collection. */
   getAll(): Promise<T[]>;
@@ -50,7 +57,10 @@ export interface CollectionStorage<T> {
    * that keeps no writes does not have this method. `ProcedureServer.useStorage` calls it.
    */
   flush?(): Promise<void>;
-  /** Release the resources of the storage. */
+  /**
+   * This method releases the resources of the storage. After it, each operation rejects. A second
+   * `close()` does nothing.
+   */
   close(): Promise<void>;
   /** The kind, the size and the statistics of the storage. */
   getMetadata?(): Promise<StorageMetadata>;
@@ -65,6 +75,8 @@ export interface CollectionStorage<T> {
  *   the first call, a version of an older run, or a change log that dropped old deletes.
  * - When `full` is false, `changed` has the items that changed after the version, and `deleted`
  *   has the ids that were deleted after it.
+ * - The order of a full result is the order of the entries. The order of a delta is the order of
+ *   the last change of each id.
  */
 export interface StorageChanges<T> {
   /** The version of the storage that includes these changes. */

package/src/procedures/core/array.ts

@@ -10,6 +10,7 @@ import { anyOutput, arrayOutput, booleanOutput, numberOutput } from "./outputs.j
 import { defineProcedure, namespace } from "../define.js";
 import type { AnyProcedure, Procedure } from "../types.js";
 import { PURE_EFFECTS, withEffects } from "../effects.js";
+import { isPlainObject } from "../ref.js";
 
 /**
  * This function gives the own field `key` of an item, or undefined. A field of the prototype
@@ -301,10 +302,47 @@ interface UniqueInput {
 }
 
 const UniqueInputSchema = z.object({
-  items: z.array(z.unknown()).describe("The array"),
-  key: z.string().optional().describe("The key (a field name of the items)"),
+  items: z.array(z.unknown()).describe("The array. Equal JSON values are duplicates: objects and arrays compare by value."),
+  key: z.string().optional().describe("The key (a field name of the items). The values of the field compare by value."),
 });
 
+/**
+ * This function gives a function that makes a text key for a value: two equal JSON values get
+ * the same key. An array compares by its items in order, and a plain object by its own fields in
+ * any order. A number and its string get different keys. Another object (a `Date`, a `Map`) and
+ * a symbol compare by identity.
+ */
+function valueKeys(): (value: unknown) => string {
+  const identities = new Map<unknown, number>();
+  const identity = (value: unknown): string => {
+    let id = identities.get(value);
+    if (id === undefined) {
+      id = identities.size;
+      identities.set(value, id);
+    }
+    return `#${id}`;
+  };
+  const keyOf = (value: unknown, parents: Set<unknown>): string => {
+    if (typeof value === "string") return JSON.stringify(value);
+    // -0 and 0 are one value, and NaN is one value, as in a Set
+    if (typeof value === "number") return Object.is(value, -0) ? "0" : String(value);
+    if (typeof value === "bigint") return `${value}n`;
+    if (value === null || value === undefined || typeof value === "boolean") return String(value);
+    // A cycle is not JSON: its object compares by identity
+    if (parents.has(value) || (!Array.isArray(value) && !isPlainObject(value))) return identity(value);
+    parents.add(value);
+    const text = Array.isArray(value)
+      ? `[${value.map((item) => keyOf(item, parents)).join(",")}]`
+      : `{${Object.keys(value)
+          .sort()
+          .map((field) => `${JSON.stringify(field)}:${keyOf(value[field], parents)}`)
+          .join(",")}}`;
+    parents.delete(value);
+    return text;
+  };
+  return (value) => keyOf(value, new Set());
+}
+
 type UniqueProcedure = Procedure<UniqueInput, unknown[], { description: string; tags: string[] }>;
 
 const uniqueProcedure: UniqueProcedure = defineProcedure({
@@ -312,20 +350,19 @@ const uniqueProcedure: UniqueProcedure = defineProcedure({
   input: UniqueInputSchema,
   output: arrayOutput("The items without duplicates"),
   metadata: {
-    description: "Remove duplicate values (optionally by key)",
+    description: "Remove duplicate values (optionally by key). It compares by value and keeps the first item of each value.",
     tags: ["core", "array"],
   },
   handler: async (input: UniqueInput): Promise<unknown[]> => {
-    if (input.key) {
-      const seen = new Set<unknown>();
-      return input.items.filter((item) => {
-        const val = fieldOf(item, input.key!);
-        if (seen.has(val)) return false;
-        seen.add(val);
-        return true;
-      });
-    }
-    return [...new Set(input.items)];
+    // Before, objects compared by reference, so two equal objects both stayed (catalog test, R29)
+    const keyOf = valueKeys();
+    const seen = new Set<string>();
+    return input.items.filter((item) => {
+      const key = keyOf(input.key ? fieldOf(item, input.key) : item);
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
   },
 });
 
@@ -623,8 +660,8 @@ interface FilterInput {
   value?: unknown | undefined;
   /** Values to match (any of these) */
   values?: unknown[] | undefined;
-  /** Match mode: 'equals', 'not', 'in', 'notIn', 'contains', 'startsWith', 'endsWith' */
-  match?: 'equals' | 'not' | 'in' | 'notIn' | 'contains' | 'startsWith' | 'endsWith' | 'gt' | 'gte' | 'lt' | 'lte' | undefined;
+  /** Match mode: 'equals', 'not', 'in', 'notIn', 'contains', 'startsWith', 'endsWith', 'gt', 'gte', 'lt', 'lte' */
+  match?:'equals' | 'not' | 'in' | 'notIn' | 'contains' | 'startsWith' | 'endsWith' | 'gt' | 'gte' | 'lt' | 'lte' | undefined;
   /** Invert the filter */
   invert?: boolean | undefined;
 }
@@ -634,7 +671,7 @@ const FilterInputSchema = z.object({
   key: z.string().optional().describe("Property to match against"),
   value: z.unknown().optional().describe("Value to match (equality check)"),
   values: z.array(z.unknown()).optional().describe("Values to match (any of these)"),
-  match: z.enum(["equals", "not", "in", "notIn", "contains", "startsWith", "endsWith", "gt", "gte", "lt", "lte"]).optional().describe("Match mode: 'equals', 'not', 'in', 'notIn', 'contains', 'startsWith', 'endsWith'"),
+  match: z.enum(["equals", "not", "in", "notIn", "contains", "startsWith", "endsWith", "gt", "gte", "lt", "lte"]).optional().describe("Match mode (default 'equals'): 'equals' and 'not' compare with value, 'in' and 'notIn' with values. 'contains', 'startsWith' and 'endsWith' compare strings. 'gt', 'gte', 'lt' and 'lte' compare numbers."),
   invert: z.boolean().optional().describe("Invert the filter"),
 });
 

package/src/procedures/core/index.ts

@@ -84,9 +84,16 @@ const ConditionalInputSchema = z.looseObject({
 const LogicInputSchema = z.looseObject({
   values: z.array(z.unknown()).describe("The operands, in order: values or calls. The evaluation stops at the deciding value."),
 });
-const NotInputSchema = z.looseObject({ value: operand("The value or call to negate") });
+// not, all, any and none take values (roadmap R29, the owner's choice). They do not run a call in
+// their operands: a call is an object, thus truthy. In a program, the calls of their input run
+// first, as for each procedure that is not control flow. client.and and client.or run calls.
+const NotInputSchema = z.looseObject({
+  value: operand("The value to negate. This procedure does not run a call: a call is an object, thus truthy."),
+});
 const VariadicBoolInputSchema = z.looseObject({
-  values: z.array(z.unknown()).describe("The values or calls to evaluate"),
+  values: z
+    .array(z.unknown())
+    .describe("The values to evaluate. This procedure does not run calls: a call is an object, thus truthy. client.and and client.or run calls."),
 });
 const MapInputSchema = z.looseObject({
   items: operand("The array, or a call that gives it"),

package/src/procedures/core/logic.ts

@@ -184,7 +184,7 @@ export const orMetadata: LogicMetadata = {
  * Metadata for the NOT operator.
  */
 export const notMetadata: LogicMetadata = {
-  description: "Logical NOT",
+  description: "Logical NOT of a value",
   tags: ["core", "logic"],
   arity: "unary",
   commutative: false, // n/a for unary

package/src/procedures/core/math.ts

@@ -151,10 +151,14 @@ const modProcedure: ModProcedure = defineProcedure({
   input: ModInputSchema,
   output: numberOutput("The remainder of a divided by b"),
   metadata: {
-    description: "Modulo (remainder of a / b)",
+    description: "Modulo (remainder of a / b). It refuses b = 0, as client.divide does.",
     tags: ["core", "math"],
   },
   handler: async (input: ModInput): Promise<number> => {
+    // Before, b = 0 gave NaN, and client.divide refused it (catalog test, roadmap R29)
+    if (input.b === 0) {
+      throw new Error("Division by zero");
+    }
     return input.a % input.b;
   },
 });