@procedures/client 0.3.0 → 0.4.0

package/src/adapters/websocket/client/transport.ts

@@ -96,6 +96,23 @@ interface PendingRequest {
  * const client = new Client({ transport });
  * ```
  */
+/** The `readyState` of an open socket. The global `WebSocket` and the `ws` package use the same number. */
+const OPEN = 1;
+
+/**
+ * The error handler of a socket that the transport left. A `WebSocket` of the `ws` package that
+ * closes during its handshake emits an error. Without a handler, that error ends the process.
+ */
+const ignoreError = (): void => undefined;
+
+/** This function removes the handlers of the transport from a socket, and keeps `ignoreError`. */
+function detach(ws: WebSocket): void {
+  ws.onopen = null;
+  ws.onmessage = null;
+  ws.onclose = null;
+  ws.onerror = ignoreError;
+}
+
 function errorItem<TRes>(id: string, code: string, message: string, retryable: boolean): ResponseItem<TRes> {
   return { id, status: { type: "error", code, message, retryable }, payload: null as TRes, metadata: {} };
 }
@@ -368,10 +385,7 @@ export class WebSocketTransport implements Transport {
     const ws = this.ws;
     this.ws = null;
     if (ws) {
-      ws.onopen = null;
-      ws.onmessage = null;
-      ws.onclose = null;
-      ws.onerror = null;
+      detach(ws);
       try {
         // A socket of the ws package ends at once. close() waits for the answer of a peer that can
         // be dead (finding of roadmap R36).
@@ -500,7 +514,7 @@ export class WebSocketTransport implements Transport {
     return new IncomingCalls({
       handler,
       send: (frame) => ws.send(JSON.stringify(frame)),
-      isOpen: () => this.ws === ws && ws.readyState === WebSocket.OPEN,
+      isOpen: () => this.ws === ws && ws.readyState === OPEN,
       // A call of the server that this client opened: the client trusts it, so it has no
       // credentials (a ProcedureServer applies no token to it)
       requestOf: (frame, signal) => ({
@@ -854,10 +868,7 @@ export class WebSocketTransport implements Transport {
     if (this.ws) {
       const ws = this.ws;
       this.ws = null;
-      ws.onopen = null;
-      ws.onmessage = null;
-      ws.onclose = null;
-      ws.onerror = null;
+      detach(ws);
       ws.close();
     }
 

package/src/adapters/websocket/client/types.ts

@@ -170,8 +170,9 @@ export interface WebSocketTransportOptions {
   onTransition?: (transition: MachineTransition) => void;
 
   /**
-   * The class of the sockets. The default is the global `WebSocket`. In Node, give the `WebSocket`
-   * of the `ws` package: a drop then ends its socket at once with `terminate()`. The global
+   * The class of the sockets. The default is the global `WebSocket`. The `WebSocketTransport` of
+   * the Node entry `@procedures/client/node` has the `WebSocket` of the `ws` package as its
+   * default. With that class, a drop ends its socket at once with `terminate()`. The global
    * `WebSocket` has only `close()`, which waits for the answer of the peer. With a dead peer, the
    * socket stays open until the kernel stops it, at most 15 minutes (the harness cells of R36).
    */

package/src/client/errors/README.md

@@ -213,6 +213,8 @@ console.error(formatError(error, true)); // include stack trace
 2. Add metadata to `ERROR_REGISTRY` in `registry.ts` or `HTTP_ERROR_REGISTRY` in `http-errors.ts`
 3. If HTTP-related, add to `HTTP_STATUS_ERROR_MAP` in `http-errors.ts`
 
+`ERROR_CODES` of the wire protocol (`src/protocol.ts`, `WIRE-PROTOCOL.md`) is the source of the codes of the protocol. `ERROR_REGISTRY` has an entry for each of them, and that entry takes its HTTP status and its retry flag from `ERROR_CODES`. To add a code of the protocol, add it to `ERROR_CODES`. A code without texts in `registry.ts` gets the meaning of the protocol as its texts. `defineProtocolError` gives a code of the protocol its own texts.
+
 Example:
 ```typescript
 // 1. Add to ErrorCode enum

package/src/client/errors/http-errors.ts

@@ -8,6 +8,7 @@
 import { ErrorCategory, ErrorSeverity, type ErrorMetadata } from "./types.js";
 import { ErrorCode } from "./codes.js";
 import { HTTPStatus } from "./http-status.js";
+import { httpStatusOf } from "../../protocol.js";
 
 /**
  * Helper to create HTTP error metadata.
@@ -595,6 +596,10 @@ export function httpStatusToErrorCode(status: number): ErrorCode {
  * ```
  */
 export function errorCodeToHTTPStatus(code: ErrorCode): HTTPStatus {
+  // A code of the wire protocol has the status of ERROR_CODES: before, TIMEOUT gave 408 here and
+  // 504 on the wire
+  const protocolStatus = httpStatusOf(code);
+  if (protocolStatus !== undefined) return protocolStatus as HTTPStatus;
   // Build map from HTTP_STATUS_ERROR_MAP
   const entry = HTTP_STATUS_ERROR_MAP.find(([, errorCode]) => errorCode === code);
   return entry?.[0] ?? HTTPStatus.INTERNAL_SERVER_ERROR;

package/src/client/errors/index.ts

@@ -20,7 +20,7 @@
  * console.log(error.metadata.userMessage);  // User-friendly message
  * console.log(error.metadata.devMessage);   // Developer diagnostic
  * console.log(error.metadata.suggestions);  // Suggested actions
- * console.log(error.metadata.retryable);    // true
+ * console.log(error.metadata.retryable);    // false (ERROR_CODES of the protocol)
  *
  * // Format for logging
  * console.log(formatError(error));

package/src/client/errors/registry.ts

@@ -15,6 +15,7 @@ import {
 } from "./types.js";
 import { HTTP_ERROR_REGISTRY } from "./http-errors.js";
 import { ErrorCode } from "./codes.js";
+import { ERROR_CODES, type ProtocolErrorCode } from "../../protocol.js";
 
 /**
  * Create error metadata with defaults.
@@ -47,12 +48,71 @@ function defineError(
   return result;
 }
 
+/** The texts of an entry. For a code of the protocol, `ERROR_CODES` gives the status and the retry flag. */
+type ProtocolErrorTexts = Omit<ErrorMetadata, "code" | "httpStatus" | "retryable">;
+
 /**
- * Universal Error Registry
- *
- * Protocol-agnostic error codes with rich metadata.
+ * This function makes the entry of a code of the wire protocol. The HTTP status and the retry
+ * flag come from `ERROR_CODES` (`protocol.ts`, `WIRE-PROTOCOL.md`), the source of these facts.
+ */
+function defineProtocolError(code: ProtocolErrorCode, texts: ProtocolErrorTexts): ErrorMetadata {
+  const info = ERROR_CODES[code];
+  return defineError(code, { ...texts, httpStatus: info.http, retryable: info.retryable });
+}
+
+/** The category of each code of the protocol, for a code that the registry does not describe. */
+const PROTOCOL_CATEGORIES: Readonly<Record<ProtocolErrorCode, ErrorCategory>> = {
+  NOT_FOUND: ErrorCategory.CLIENT,
+  NO_HANDLER: ErrorCategory.SERVER,
+  NOT_EXPOSED: ErrorCategory.AUTH,
+  NOT_DECLARED: ErrorCategory.AUTH,
+  FORBIDDEN: ErrorCategory.AUTH,
+  UNAUTHORIZED: ErrorCategory.AUTH,
+  VALIDATION_ERROR: ErrorCategory.CLIENT,
+  INVALID_REQUEST: ErrorCategory.PROTOCOL,
+  PROTOCOL_VERSION: ErrorCategory.PROTOCOL,
+  OUTPUT_VALIDATION_ERROR: ErrorCategory.SERVER,
+  NO_OUTPUT: ErrorCategory.SERVER,
+  HANDLER_ERROR: ErrorCategory.SERVER,
+  INTERNAL_ERROR: ErrorCategory.SERVER,
+  NOT_ACCEPTABLE: ErrorCategory.CLIENT,
+  DUPLICATE: ErrorCategory.CLIENT,
+  DUPLICATE_REQUEST: ErrorCategory.CLIENT,
+  ABORTED: ErrorCategory.CANCELLED,
+  TIMEOUT: ErrorCategory.TIMEOUT,
+  UNAVAILABLE: ErrorCategory.SERVER,
+  CONNECTION_CLOSED: ErrorCategory.NETWORK,
+  CONNECTION_NOT_FOUND: ErrorCategory.CLIENT,
+};
+
+/**
+ * This function gives the registry with one entry for each code of the protocol. The status and
+ * the retry flag of such an entry come from `ERROR_CODES`, so the two lists agree (before, the
+ * registry gave `TIMEOUT` the status 408 and two codes another retry flag). A code without texts
+ * here gets the meaning of the protocol as its texts.
+ */
+function withProtocolCodes(described: ErrorRegistry): ErrorRegistry {
+  const registry: ErrorRegistry = { ...described };
+  for (const code of Object.keys(ERROR_CODES) as ProtocolErrorCode[]) {
+    const info = ERROR_CODES[code];
+    const meaning = `${info.meaning}.`;
+    const texts: ProtocolErrorTexts = described[code] ?? {
+      summary: info.meaning,
+      detail: meaning,
+      category: PROTOCOL_CATEGORIES[code],
+      severity: info.retryable ? ErrorSeverity.WARNING : ErrorSeverity.ERROR,
+      userMessage: meaning,
+      devMessage: meaning,
+    };
+    registry[code] = { ...texts, code, httpStatus: info.http, retryable: info.retryable };
+  }
+  return registry;
+}
+
+/**
+ * The entries with their own texts. `ERROR_REGISTRY` adds the codes of the protocol.
  */
-export const ERROR_REGISTRY: ErrorRegistry = {
+const DESCRIBED_ERRORS = {
   //
   // ═══ Network Errors ═══
   //
@@ -108,16 +168,14 @@ export const ERROR_REGISTRY: ErrorRegistry = {
   // ═══ Timeout Errors ═══
   //
 
-  TIMEOUT: defineError(ErrorCode.TIMEOUT, {
+  TIMEOUT: defineProtocolError("TIMEOUT", {
     summary: "Request timed out",
     detail:
       "The request exceeded the configured timeout duration. This may indicate slow server response, network congestion, or overly aggressive timeout settings.",
     category: ErrorCategory.TIMEOUT,
-    retryable: true,
     severity: ErrorSeverity.WARNING,
     userMessage: "The request took too long to complete. Please try again.",
     devMessage: "Request exceeded timeout threshold. Consider increasing timeout or optimizing server response time.",
-    httpStatus: 408,
     suggestions: [
       "Try again with a longer timeout",
       "Check server performance",
@@ -159,11 +217,10 @@ export const ERROR_REGISTRY: ErrorRegistry = {
   // ═══ Cancellation Errors ═══
   //
 
-  ABORTED: defineError(ErrorCode.ABORTED, {
+  ABORTED: defineProtocolError("ABORTED", {
     summary: "Request was aborted",
     detail: "The request was explicitly cancelled by the client via AbortSignal. This is user-initiated.",
     category: ErrorCategory.CANCELLED,
-    retryable: false,
     severity: ErrorSeverity.INFO,
     userMessage: "The request was cancelled.",
     devMessage: "Request aborted via AbortSignal. This is expected and not an error condition.",
@@ -269,15 +326,13 @@ export const ERROR_REGISTRY: ErrorRegistry = {
     ],
   }),
 
-  UNAUTHORIZED: defineError(ErrorCode.UNAUTHORIZED, {
+  UNAUTHORIZED: defineProtocolError("UNAUTHORIZED", {
     summary: "Unauthorized",
     detail: "Authentication is required but was not provided or is invalid.",
     category: ErrorCategory.AUTH,
-    retryable: false,
     severity: ErrorSeverity.ERROR,
     userMessage: "Authentication required. Please sign in.",
     devMessage: "Missing or invalid authentication credentials. Check auth token/API key.",
-    httpStatus: 401,
     suggestions: [
       "Provide valid authentication credentials",
       "Check token hasn't expired",
@@ -285,15 +340,13 @@ export const ERROR_REGISTRY: ErrorRegistry = {
     ],
   }),
 
-  FORBIDDEN: defineError(ErrorCode.FORBIDDEN, {
+  FORBIDDEN: defineProtocolError("FORBIDDEN", {
     summary: "Forbidden",
     detail: "The authenticated user doesn't have permission to access this resource.",
     category: ErrorCategory.AUTH,
-    retryable: false,
     severity: ErrorSeverity.ERROR,
     userMessage: "You don't have permission to access this resource.",
     devMessage: "Insufficient permissions. Check user roles and resource ACLs.",
-    httpStatus: 403,
     suggestions: [
       "Verify user has required permissions",
       "Check resource access control lists",
@@ -301,15 +354,13 @@ export const ERROR_REGISTRY: ErrorRegistry = {
     ],
   }),
 
-  NOT_FOUND: defineError(ErrorCode.NOT_FOUND, {
+  NOT_FOUND: defineProtocolError("NOT_FOUND", {
     summary: "Not found",
     detail: "The requested resource does not exist.",
     category: ErrorCategory.CLIENT,
-    retryable: false,
     severity: ErrorSeverity.ERROR,
     userMessage: "The requested item was not found.",
     devMessage: "Resource not found. Verify ID/path is correct and resource exists.",
-    httpStatus: 404,
     suggestions: [
       "Verify the resource ID is correct",
       "Check the resource hasn't been deleted",
@@ -402,17 +453,15 @@ export const ERROR_REGISTRY: ErrorRegistry = {
   // ═══ Server Errors (5xx) ═══
   //
 
-  INTERNAL_ERROR: defineError(ErrorCode.INTERNAL_ERROR, {
+  INTERNAL_ERROR: defineProtocolError("INTERNAL_ERROR", {
     summary: "Internal server error",
     detail: "The server encountered an unexpected condition. This is a server-side bug.",
     category: ErrorCategory.SERVER,
-    retryable: true,
     severity: ErrorSeverity.CRITICAL,
     userMessage: "Server error occurred. Please try again later.",
     devMessage: "Internal server error. Check server logs for details.",
-    httpStatus: 500,
+    // The protocol says that a retry does not help (ERROR_CODES: retryable false)
     suggestions: [
-      "Retry the request",
       "Check server logs",
       "Contact server team",
     ],
@@ -554,6 +603,14 @@ export const ERROR_REGISTRY: ErrorRegistry = {
   ...HTTP_ERROR_REGISTRY,
 } as const satisfies ErrorRegistry;
 
+/**
+ * Universal Error Registry
+ *
+ * Protocol-agnostic error codes with rich metadata. Each code of the wire protocol has an entry,
+ * and `ERROR_CODES` gives its HTTP status and its retry flag.
+ */
+export const ERROR_REGISTRY: ErrorRegistry = withProtocolCodes(DESCRIBED_ERRORS);
+
 /**
  * Get error metadata by code.
  *

package/src/client/middleware/rate-limit.ts

@@ -83,7 +83,6 @@ export class RateLimitError extends Error {
  */
 interface QueuedRequest {
   resolve: () => void;
-  reject: (error: Error) => void;
   timestamp: number;
 }
 
@@ -208,7 +207,6 @@ export function createRateLimitMiddleware(
           signal?.removeEventListener("abort", onAbort);
           resolve(true);
         },
-        reject: () => resolve(false),
         timestamp: Date.now(),
       };
       // A queued request whose caller aborts leaves the queue (before, it kept its place)

package/src/client/middleware/timeout.ts

@@ -170,19 +170,12 @@ async function* runWithTimeout<TReq, TRes>(
         phase = "done";
         return;
       }
-      if (result.value.status.type === "error" && timedOut()) {
-        // The transport saw the aborted signal and reported ABORTED: it is a timeout
-        yield timeoutItem();
-        return;
-      }
+      // An item or an error of the transport comes before the abort. `nextOrAbort` adds its abort
+      // listener before it calls `next()`, so a later abort gives ABORTED_FIRST, not an item.
       yield result.value;
     }
   } catch (error) {
     phase = "done";
-    if (timedOut()) {
-      yield timeoutItem();
-      return;
-    }
     throw error;
   } finally {
     clearTimeout(timeoutId);

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/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;
   },
 });

package/src/procedures/core/meta.ts

@@ -14,6 +14,7 @@ import {
   parseProcedureJson,
   stringifyProcedureJson,
   isAnyProcedureRef,
+  isProcedureRef,
   isOutputRef,
   isPlainObject,
   resolveOutputRef,
@@ -58,18 +59,37 @@ const ImportOutputSchema = z.looseObject({
 
 type ImportProcedure = Procedure<ImportInput, ImportOutput, { description: string; tags: string[] }>;
 
+/**
+ * This function gives true for the runtime form of a procedure reference whose path is a list of
+ * texts. `client.import` accepts only such a value at the top level.
+ */
+function isImportableRef(value: unknown): boolean {
+  if (!isProcedureRef(value)) return false;
+  const path = (value as { path?: unknown }).path;
+  return Array.isArray(path) && path.length > 0 && path.every((segment) => typeof segment === "string");
+}
+
 const importProcedure: ImportProcedure = defineProcedure({
   path: ["import"],
   input: ImportInputSchema,
   output: ImportOutputSchema,
   metadata: {
-    description: "Parse procedure aggregation from JSON string",
+    description:
+      "Parse a procedure reference ({ $proc, input }) from JSON text. Other JSON, for example a number or a list, gives success false.",
     tags: ["core", "meta"],
   },
   handler: async (input: ImportInput): Promise<ImportOutput> => {
     try {
       if (input.json) {
         const procedure = parseProcedureJson(input.json);
+        // Before, each JSON value gave success true, for example 42 (catalog test, roadmap R29)
+        if (!isImportableRef(procedure)) {
+          return {
+            procedure: null,
+            success: false,
+            error: "The JSON is not a procedure reference. A reference is an object whose $proc is a list of texts.",
+          };
+        }
         return { procedure, success: true };
       }
       if (input.path) {
@@ -107,8 +127,19 @@ interface ExportInput {
   pretty?: boolean | undefined;
 }
 
+/**
+ * This function gives a schema of a required value: undefined has no JSON text, so the input
+ * schema refuses it with `VALIDATION_ERROR`. Before, the call failed with
+ * `OUTPUT_VALIDATION_ERROR` (catalog test, roadmap R29).
+ */
+const definedValue = (description: string) =>
+  z
+    .unknown()
+    .refine((value) => value !== undefined, { message: "The value is missing: undefined has no JSON text" })
+    .describe(description);
+
 const ExportInputSchema = z.object({
-  procedure: z.unknown().optional().describe("Procedure reference to serialize"),
+  procedure: definedValue("The procedure reference to serialize. The procedure refuses a missing value (undefined) with VALIDATION_ERROR, because undefined has no JSON text."),
   pretty: z.boolean().optional().describe("Pretty print JSON output"),
 });
 
@@ -134,13 +165,15 @@ const exportProcedure: ExportProcedure = defineProcedure({
   input: ExportInputSchema,
   output: ExportOutputSchema,
   metadata: {
-    description: "Serialize procedure aggregation to JSON string",
+    description: "Serialize a procedure reference to JSON text. It refuses a missing procedure (undefined) with VALIDATION_ERROR.",
     // The refs of the input are data: exec() must not run them (deep dive CORE-5)
     tags: ["core", "meta", RAW_INPUT_TAG],
   },
   handler: async (input: ExportInput): Promise<ExportOutput> => {
     try {
-      const json = stringifyProcedureJson(input.procedure, input.pretty ? 2 : undefined);
+      const json = stringifyProcedureJson(input.procedure, input.pretty ? 2 : undefined) as string | undefined;
+      // A function or a symbol has no JSON text either: an error result, not an invalid output
+      if (json === undefined) return { json: "", success: false, error: "The procedure has no JSON text" };
       return { json, success: true };
     } catch (error) {
       return {
@@ -268,7 +301,7 @@ interface StringifyJsonInput {
 }
 
 const StringifyJsonInputSchema = z.object({
-  value: z.unknown().optional().describe("Value to stringify"),
+  value: definedValue("The value to write as JSON. The procedure refuses a missing value (undefined) with VALIDATION_ERROR, because undefined has no JSON text."),
   pretty: z.boolean().optional().describe("Pretty print with indentation"),
   indent: z.union([z.number(), z.string()]).optional().describe("Custom indentation (number of spaces or string)"),
 });
@@ -280,13 +313,16 @@ const stringifyJsonProcedure: StringifyJsonProcedure = defineProcedure({
   input: StringifyJsonInputSchema,
   output: stringOutput("The JSON text"),
   metadata: {
-    description: "Stringify value to JSON (with procedure ref support)",
+    description: "Stringify value to JSON (with procedure ref support). It refuses a missing value (undefined) with VALIDATION_ERROR.",
     // The refs of the input are data: exec() must not run them (deep dive CORE-5)
     tags: ["core", "meta", RAW_INPUT_TAG],
   },
   handler: async (input: StringifyJsonInput): Promise<string> => {
     const indent = input.pretty ? (input.indent ?? 2) : input.indent;
-    return stringifyProcedureJson(input.value, indent as number);
+    const json = stringifyProcedureJson(input.value, indent as number) as string | undefined;
+    // A function or a symbol has no JSON text either: a clear error, not an invalid output
+    if (json === undefined) throw new Error("The value has no JSON text");
+    return json;
   },
 });