@larc-iu/plaid-client 0.2.0-alpha.14 → 0.2.0-alpha.17

package/src/index.js

@@ -5,6 +5,8 @@
 import { transformRequest, transformResponse } from "./transforms.js";
 import {
   makeRequest,
+  queueRequest,
+  restampDocumentVersion,
   extractDocumentVersions,
   parseErrorBody,
   makeHttpError,
@@ -117,6 +119,93 @@ async function anonymousGet(baseUrl, path, options = {}) {
  */
 const MAX_BATCH_OPS = 1000;
 
+/**
+ * A batch is the client with a different `_request` (see `queueRequest`) and
+ * its own copy of the bundles. Everything else resolves to the client through
+ * the prototype: the token and base URL, strict mode and the document versions
+ * it tracks, the open logical operation.
+ */
+function openBatch(client) {
+  const batch = Object.create(client);
+  batch.client = client;
+  batch.operations = [];
+  // The document each queued op's strict-mode stamp is for (null for none),
+  // index for index with `operations`.
+  batch.stampedDocuments = [];
+  batch.open = true;
+  batch._request = (method, path, options = {}) =>
+    queueRequest(batch, method, path, options);
+  batch.batch = () => {
+    throw new Error("A batch is not nestable: queue on the batch you have");
+  };
+  batch.batched = batch.batch;
+  batch.submit = () => submitBatch(batch);
+  batch.abort = () => {
+    batch.operations = [];
+    batch.stampedDocuments = [];
+    batch.open = false;
+  };
+  batch._installResources();
+  return batch;
+}
+
+async function submitBatch(batch) {
+  if (!batch.open) {
+    throw new Error("This batch was already submitted or aborted");
+  }
+  batch.open = false;
+  const ops = batch.operations;
+  const stamps = batch.stampedDocuments;
+  batch.operations = [];
+  batch.stampedDocuments = [];
+  if (ops.length === 0) return [];
+  const client = batch.client;
+  const url = `${client.baseUrl}/api/v1/batch`;
+  // The server caps a batch at MAX_BATCH_OPS so one transaction cannot hold
+  // the write lock without bound. A larger batch goes as consecutive
+  // requests, results concatenated in queue order: it could not have been one
+  // transaction anyway, and a repair or bulk edit over a big document must
+  // not fail on its size alone. Past the first request, a strict-mode stamp
+  // claims the version the requests before it left (learned from their
+  // results), not the one the document had when the op was queued, which the
+  // first request has already moved on.
+  //
+  // Each request is atomic, the whole is not: a failure leaves the requests
+  // before it saved. The error says so, as `committed` (how many operations
+  // were saved) and `committedResults` (their results, in queue order), so a
+  // caller can tell a partial write from a batch that saved nothing. The
+  // failed request itself counts as unsaved, even when its answer was lost.
+  const results = [];
+  try {
+    await sendChunks(client, url, ops, stamps, results);
+  } catch (error) {
+    if (error && typeof error === "object") {
+      error.committed = results.length;
+      error.committedResults = results;
+    }
+    throw error;
+  }
+  return results;
+}
+
+async function sendChunks(client, url, ops, stamps, results) {
+  for (let i = 0; i < ops.length; i += MAX_BATCH_OPS) {
+    let chunk = ops.slice(i, i + MAX_BATCH_OPS);
+    if (i > 0) {
+      chunk = chunk.map((op, j) => {
+        const docId = stamps[i + j];
+        if (!docId) return op;
+        const path = restampDocumentVersion(
+          op.path,
+          client.documentVersions[docId],
+        );
+        return { ...op, path };
+      });
+    }
+    results.push(...(await client._postBatch(url, chunk)));
+  }
+}
+
 class PlaidClient {
   /**
    * Create a new PlaidClient instance
@@ -142,8 +231,6 @@ class PlaidClient {
         : options.timeout !== undefined
           ? options.timeout
           : DEFAULT_BATCH_TIMEOUT_MS;
-    this.isBatching = false;
-    this.batchOperations = [];
     this.documentVersions = {};
     this.strictModeDocumentId = null;
     // Set to a DocumentLockLost while a `documents.locked()` block's keep-alive
@@ -161,8 +248,16 @@ class PlaidClient {
     this.onAuthError = options.onAuthError || null;
     this._authErrorFired = false;
 
-    // --- API Bundles ---
+    this._installResources();
+  }
 
+  /**
+   * The API bundles (`client.documents`, `client.tokens`, ...). Installed on
+   * the client, and again on every batch it opens (see `batch()`): a batch is
+   * a view of the client with its own `_request`, so the same bundles built
+   * on it queue instead of sending.
+   */
+  _installResources() {
     this.vocabLinks = {
       /**
        * Create a new vocab link between tokens and a vocab item.
@@ -205,7 +300,6 @@ class PlaidClient {
         this._request("PUT", `/api/v1/vocab-links/${id}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a vocab link.
@@ -214,29 +308,23 @@ class PlaidClient {
       deleteMetadata: (id, auditMessage) =>
         this._request("DELETE", `/api/v1/vocab-links/${id}/metadata`, {
           auditMessage,
-          skipResponseTransform: true,
         }),
       /**
-       * Patch (shallow-merge) metadata for a vocab link. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * Edit metadata for a vocab link with a list of ops applied in order, in one operation. `{op: 'set', path, value}` writes value at path, creating missing objects along it; `{op: 'delete', path}` removes the key at path (a no-op when absent). A path is a non-empty array of keys, the first a top-level key. A path through a non-object is refused (400). See metadataOps and applyMetadataOps.
        * @param {string} id - The resource ID
-       * @param {any} body - The metadata patch
+       * @param {Array<{op: string, path: string[], value?: any}>} body - The metadata ops
        */
       patchMetadata: (id, body, auditMessage) =>
         this._request("PATCH", `/api/v1/vocab-links/${id}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Get a vocab link by ID
        * @param {string} id - The resource ID
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      get: (id, asOf) =>
-        this._request("GET", `/api/v1/vocab-links/${id}`, {
-          bypassBatch: true,
-          queryParams: { "as-of": asOf },
-        }),
+      get: (id) =>
+        this._request("GET", `/api/v1/vocab-links/${id}`),
       /**
        * Delete a vocab link
        * @param {string} id - The resource ID
@@ -247,16 +335,113 @@ class PlaidClient {
 
     this.vocabLayers = {
       /**
-       * Get a vocab layer by ID
+       * Get a vocab layer by ID. With `asOf`, the vocabulary as it was at that
+       * instant, read from its history: the same shape as the live read, its
+       * entries with `includeItems`. A vocabulary that did not exist then is a
+       * 404, a malformed or pruned time a 400.
        * @param {string} id - The resource ID
        * @param {boolean} [includeItems] - Include vocab items
-       * @param {string} [asOf] - Temporal query timestamp
+       * @param {string} [asOf] - The moment to read at (ISO-8601 instant)
        */
       get: (id, includeItems, asOf) =>
         this._request("GET", `/api/v1/vocab-layers/${id}`, {
-          bypassBatch: true,
           queryParams: { "include-items": includeItems, "as-of": asOf },
         }),
+      /**
+       * One entry of the vocabulary as it was at `asOf`, also when it has
+       * been deleted since. The same shape as `vocabItems.get`. A 404 when
+       * the entry was not in this vocabulary at that time.
+       * @param {string} id - The vocabulary ID
+       * @param {string} itemId - The entry ID
+       * @param {string} asOf - The moment to read at (ISO-8601 instant)
+       */
+      getItemAt: (id, itemId, asOf) =>
+        this._request("GET", `/api/v1/vocab-layers/${id}/items/${itemId}`, {
+          queryParams: { "as-of": asOf },
+        }),
+      /**
+       * Get the audit log of a vocabulary: every change to it or to its
+       * entries, folded into entries as the document log is. Links are not
+       * listed, they belong to the document they annotate. Transparently
+       * follows pagination cursors and returns the full flat array.
+       * @param {string} id - The vocabulary ID
+       * @param {string} [startTime] - Start of time range
+       * @param {string} [endTime] - End of time range
+       * @param {string[]|string} [opTypes] - Only return operations of these
+       *   types, spelled as in an entry's `op/type` (e.g.
+       *   `['vocab-item/delete', 'vocab-item/restore']`)
+       * @param {string} [itemId] - Only the changes that wrote this one entry,
+       *   each with only its operations that did
+       */
+      audit: (id, startTime, endTime, opTypes, itemId) =>
+        listAll(this, `/api/v1/vocab-layers/${id}/audit`, {
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+            "item-id": itemId,
+          },
+        }),
+      /**
+       * One page of the same log, newest-first with `order: "desc"`. Use this
+       * rather than audit() wherever the caller wants the recent end of a log
+       * that may be long: audit() walks every page before it resolves.
+       * @param {string} id - The vocabulary ID
+       * @param {object} [opts]
+       * @param {"asc"|"desc"} [opts.order] - "desc" pages newest-first
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @param {string} [opts.itemId] - Only the changes that wrote this one
+       *   entry, each with only its operations that did
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      auditPage: (
+        id,
+        { startTime, endTime, opTypes, order, limit, cursor, itemId } = {},
+      ) =>
+        listPage(this, `/api/v1/vocab-layers/${id}/audit`, {
+          limit,
+          cursor,
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+            order,
+            "item-id": itemId,
+          },
+        }),
+      /**
+       * Put one entry of the vocabulary back as it was at `asOf`, as one
+       * operation. A deleted entry comes back under its original id with its
+       * form and fields, and a living one has its form and fields set back.
+       * Links are not part of an entry: a deleted entry's links come back
+       * through each document's own `documents.restore`. Resolves to
+       * `{inserted, form, metadata, total}`, `total` 0 when nothing changes.
+       * A form set back bumps every linking document, and the new versions
+       * come back in X-Document-Versions (or, past fifty documents,
+       * X-Document-Versions-Omitted), which the client takes up as on any
+       * write. A time when the entry did not exist is a 400. Maintainers of
+       * the vocabulary only.
+       * @param {string} id - The vocabulary ID
+       * @param {string} itemId - The entry ID
+       * @param {string} asOf - The moment to go back to (ISO-8601 instant),
+       *   typically a history entry's `endTime`
+       * @param {object} [options] - `{ dryRun }`: with `dryRun` true nothing
+       *   is written and the summary says what would change
+       * @param {string} [auditMessage] - Custom audit message for this operation
+       */
+      restoreItem: (id, itemId, asOf, { dryRun } = {}, auditMessage) =>
+        this._request(
+          "POST",
+          `/api/v1/vocab-layers/${id}/items/${itemId}/restore`,
+          {
+            queryParams: {
+              "as-of": asOf,
+              "dry-run": dryRun ? "true" : undefined,
+            },
+            auditMessage,
+          },
+        ),
       /**
        * Delete a vocab layer.
        * @param {string} id - The resource ID
@@ -301,35 +486,29 @@ class PlaidClient {
       /**
        * List all vocab layers accessible to user. Transparently follows
        * pagination cursors and returns the full flat array.
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      list: (asOf) =>
-        listAll(this, "/api/v1/vocab-layers", { query: { "as-of": asOf } }),
+      list: () => listAll(this, "/api/v1/vocab-layers"),
       /**
        * Fetch a single page of vocab layers.
        * @param {object} [opts]
        * @param {number} [opts.limit] - Page size (1..1000; server default 100)
        * @param {string} [opts.cursor] - Opaque cursor from a previous page
-       * @param {string} [opts.asOf] - Temporal query timestamp
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
-      listPage: ({ limit, cursor, asOf } = {}) =>
+      listPage: ({ limit, cursor } = {}) =>
         listPage(this, "/api/v1/vocab-layers", {
           limit,
           cursor,
-          query: { "as-of": asOf },
         }),
       /**
        * Async-iterate vocab layers page by page; yields each page's entries array.
        * @param {object} [opts]
        * @param {number} [opts.pageSize] - Per-request page size
-       * @param {string} [opts.asOf] - Temporal query timestamp
        * @returns {AsyncGenerator<Array>}
        */
-      iterPages: ({ pageSize, asOf } = {}) =>
+      iterPages: ({ pageSize } = {}) =>
         iterPages(this, "/api/v1/vocab-layers", {
           pageSize,
-          query: { "as-of": asOf },
         }),
       /**
        * Create a new vocab layer. Note: this also registers the user as a maintainer.
@@ -374,7 +553,6 @@ class PlaidClient {
         this._request("PUT", `/api/v1/relations/${relationId}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a relation.
@@ -383,18 +561,16 @@ class PlaidClient {
       deleteMetadata: (relationId, auditMessage) =>
         this._request("DELETE", `/api/v1/relations/${relationId}/metadata`, {
           auditMessage,
-          skipResponseTransform: true,
         }),
       /**
-       * Patch (shallow-merge) metadata for a relation. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * Edit metadata for a relation with a list of ops applied in order, in one operation. `{op: 'set', path, value}` writes value at path, creating missing objects along it; `{op: 'delete', path}` removes the key at path (a no-op when absent). A path is a non-empty array of keys, the first a top-level key. A path through a non-object is refused (400). See metadataOps and applyMetadataOps.
        * @param {string} relationId - The relation ID
-       * @param {any} body - The metadata patch
+       * @param {Array<{op: string, path: string[], value?: any}>} body - The metadata ops
        */
       patchMetadata: (relationId, body, auditMessage) =>
         this._request("PATCH", `/api/v1/relations/${relationId}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Update the target span of a relation.
@@ -409,13 +585,9 @@ class PlaidClient {
       /**
        * Get a relation by ID.
        * @param {string} relationId - The relation ID
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      get: (relationId, asOf) =>
-        this._request("GET", `/api/v1/relations/${relationId}`, {
-          bypassBatch: true,
-          queryParams: { "as-of": asOf },
-        }),
+      get: (relationId) =>
+        this._request("GET", `/api/v1/relations/${relationId}`),
       /**
        * Delete a relation.
        * @param {string} relationId - The relation ID
@@ -483,7 +655,7 @@ class PlaidClient {
         }),
       /**
        * Update many relations in a single operation: set values and/or patch metadata.
-       * @param {Array} body - Objects of the shape `{id, value?, metadata?}`. `value` is set only when the key is present (null sends JSON null); `metadata` is a patch, a null value deleting that key. The relations may lie in several documents of one project; every document touched has its version bumped and every new version comes back in `X-Document-Versions`. A `document-version` precondition is accepted only when every entry lies in one document. An unknown id refuses the whole update.
+       * @param {Array} body - Objects of the shape `{id, value?, metadata?}`. `value` is set only when the key is present (null sends JSON null); `metadata` is a list of metadata ops, as for patchMetadata. The relations may lie in several documents of one project; every document touched has its version bumped and every new version comes back in `X-Document-Versions` (past fifty documents, only their number, in `X-Document-Versions-Omitted`). A `document-version` precondition is accepted only when every entry lies in one document. An unknown id refuses the whole update.
        * @returns {Promise<{count: number}>} How many relations were updated.
        */
       bulkUpdate: (body, auditMessage) =>
@@ -528,13 +700,9 @@ class PlaidClient {
       /**
        * Get a span layer by ID.
        * @param {string} spanLayerId - The span layer ID
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      get: (spanLayerId, asOf) =>
-        this._request("GET", `/api/v1/span-layers/${spanLayerId}`, {
-          bypassBatch: true,
-          queryParams: { "as-of": asOf },
-        }),
+      get: (spanLayerId) =>
+        this._request("GET", `/api/v1/span-layers/${spanLayerId}`),
       /**
        * Delete a span layer.
        * @param {string} spanLayerId - The span layer ID
@@ -607,13 +775,9 @@ class PlaidClient {
       /**
        * Get a span by ID.
        * @param {string} spanId - The span ID
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      get: (spanId, asOf) =>
-        this._request("GET", `/api/v1/spans/${spanId}`, {
-          bypassBatch: true,
-          queryParams: { "as-of": asOf },
-        }),
+      get: (spanId) =>
+        this._request("GET", `/api/v1/spans/${spanId}`),
       /**
        * Delete a span.
        * @param {string} spanId - The span ID
@@ -645,7 +809,7 @@ class PlaidClient {
         this._request("DELETE", "/api/v1/spans/bulk", { auditMessage, body }),
       /**
        * Update many spans in a single operation: set values and/or patch metadata.
-       * @param {Array} body - Objects of the shape `{id, value?, metadata?}`. `value` is set only when the key is present (null sends JSON null); `metadata` is a patch, a null value deleting that key. The spans may lie in several documents of one project; every document touched has its version bumped and every new version comes back in `X-Document-Versions`. A `document-version` precondition is accepted only when every entry lies in one document. An unknown id refuses the whole update.
+       * @param {Array} body - Objects of the shape `{id, value?, metadata?}`. `value` is set only when the key is present (null sends JSON null); `metadata` is a list of metadata ops, as for patchMetadata. The spans may lie in several documents of one project; every document touched has its version bumped and every new version comes back in `X-Document-Versions` (past fifty documents, only their number, in `X-Document-Versions-Omitted`). A `document-version` precondition is accepted only when every entry lies in one document. An unknown id refuses the whole update.
        * @returns {Promise<{count: number}>} How many spans were updated.
        */
       bulkUpdate: (body, auditMessage) =>
@@ -662,7 +826,6 @@ class PlaidClient {
         this._request("PUT", `/api/v1/spans/${spanId}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a span.
@@ -671,18 +834,16 @@ class PlaidClient {
       deleteMetadata: (spanId, auditMessage) =>
         this._request("DELETE", `/api/v1/spans/${spanId}/metadata`, {
           auditMessage,
-          skipResponseTransform: true,
         }),
       /**
-       * Patch (shallow-merge) metadata for a span. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * Edit metadata for a span with a list of ops applied in order, in one operation. `{op: 'set', path, value}` writes value at path, creating missing objects along it; `{op: 'delete', path}` removes the key at path (a no-op when absent). A path is a non-empty array of keys, the first a top-level key. A path through a non-object is refused (400). See metadataOps and applyMetadataOps.
        * @param {string} spanId - The span ID
-       * @param {any} body - The metadata patch
+       * @param {Array<{op: string, path: string[], value?: any}>} body - The metadata ops
        */
       patchMetadata: (spanId, body, auditMessage) =>
         this._request("PATCH", `/api/v1/spans/${spanId}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
     };
 
@@ -698,11 +859,7 @@ class PlaidClient {
        */
       info: () => {
         if (!infoPromise) {
-          // bypassBatch: a read belongs to whoever asked for it, not to
-          // whatever batch happens to be open on this shared client.
-          infoPromise = this._request("GET", "/api/v1/info", {
-            bypassBatch: true,
-          }).catch((err) => {
+          infoPromise = this._request("GET", "/api/v1/info").catch((err) => {
             // A failure must not be cached: a client that starts before the
             // server is up would never see the limits at all.
             infoPromise = null;
@@ -722,18 +879,22 @@ class PlaidClient {
       health: () => PlaidClient.health(this.baseUrl, { timeout: this.timeout }),
     };
 
-    this.batch = {
-      /**
-       * Execute multiple API operations atomically. If any operation fails, all
-       * changes are rolled back.
-       * @param {Array} body - The request body
+    // The signed-in user's sign-ins. Signing in is `PlaidClient.login`, which
+    // makes the client.
+    this.auth = {
+      /**
+       * End every sign-in of this user on every device: each browser tab,
+       * script and service holding one of the user's sign-in tokens is
+       * refused from now on, this client included. Named API tokens are not
+       * affected (revoke one with `apiTokens.revoke`). To sign out of one tab
+       * only, discard its token instead. A signal rather than project data:
+       * made on a batch it still goes out at once, and it never joins an
+       * operation.
+       * @returns {Promise<void>}
        */
-      submit: (body, auditMessage) =>
-        this._request("POST", "/api/v1/batch", {
-          auditMessage,
-          body,
-          noBatch: true,
-        }),
+      logoutEverywhere: async () => {
+        await this._request("POST", "/api/v1/logout", { outOfBand: true });
+      },
     };
 
     this.texts = {
@@ -746,7 +907,6 @@ class PlaidClient {
         this._request("PUT", `/api/v1/texts/${textId}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a text.
@@ -755,18 +915,16 @@ class PlaidClient {
       deleteMetadata: (textId, auditMessage) =>
         this._request("DELETE", `/api/v1/texts/${textId}/metadata`, {
           auditMessage,
-          skipResponseTransform: true,
         }),
       /**
-       * Patch (shallow-merge) metadata for a text. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * Edit metadata for a text with a list of ops applied in order, in one operation. `{op: 'set', path, value}` writes value at path, creating missing objects along it; `{op: 'delete', path}` removes the key at path (a no-op when absent). A path is a non-empty array of keys, the first a top-level key. A path through a non-object is refused (400). See metadataOps and applyMetadataOps.
        * @param {string} textId - The text ID
-       * @param {any} body - The metadata patch
+       * @param {Array<{op: string, path: string[], value?: any}>} body - The metadata ops
        */
       patchMetadata: (textId, body, auditMessage) =>
         this._request("PATCH", `/api/v1/texts/${textId}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Create a new text in a document's text layer. A text is a container for
@@ -789,13 +947,9 @@ class PlaidClient {
       /**
        * Get a text.
        * @param {string} textId - The text ID
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      get: (textId, asOf) =>
-        this._request("GET", `/api/v1/texts/${textId}`, {
-          bypassBatch: true,
-          queryParams: { "as-of": asOf },
-        }),
+      get: (textId) =>
+        this._request("GET", `/api/v1/texts/${textId}`),
       /**
        * Delete a text and all dependent data.
        * @param {string} textId - The text ID
@@ -827,37 +981,34 @@ class PlaidClient {
        * returns the full flat array. Admin-or-maintainer only.
        * @param {object} [opts]
        * @param {string} [opts.q] - Filter to users whose display name or email contains this text (case-insensitive)
-       * @param {string} [opts.asOf] - Temporal query timestamp
        */
-      list: ({ q, asOf } = {}) =>
-        listAll(this, "/api/v1/users", { query: { q, "as-of": asOf } }),
+      list: ({ q } = {}) =>
+        listAll(this, "/api/v1/users", { query: { q } }),
       /**
        * Fetch a single page of users (optionally filtered by `q`).
        * @param {object} [opts]
        * @param {string} [opts.q] - Filter to users whose display name or email contains this text (case-insensitive)
        * @param {number} [opts.limit] - Page size (1..1000; server default 100)
        * @param {string} [opts.cursor] - Opaque cursor from a previous page
-       * @param {string} [opts.asOf] - Temporal query timestamp
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
-      listPage: ({ q, limit, cursor, asOf } = {}) =>
+      listPage: ({ q, limit, cursor } = {}) =>
         listPage(this, "/api/v1/users", {
           limit,
           cursor,
-          query: { q, "as-of": asOf },
+          query: { q },
         }),
       /**
        * Async-iterate users page by page; yields each page's entries array.
        * @param {object} [opts]
        * @param {string} [opts.q] - Filter to users whose display name or email contains this text (case-insensitive)
        * @param {number} [opts.pageSize] - Per-request page size
-       * @param {string} [opts.asOf] - Temporal query timestamp
        * @returns {AsyncGenerator<Array>}
        */
-      iterPages: ({ q, pageSize, asOf } = {}) =>
+      iterPages: ({ q, pageSize } = {}) =>
         iterPages(this, "/api/v1/users", {
           pageSize,
-          query: { q, "as-of": asOf },
+          query: { q },
         }),
       /**
        * Create a new user.
@@ -875,7 +1026,9 @@ class PlaidClient {
             email,
             password,
             "is-admin": isAdmin,
-            "display-name": displayName,
+            // Left out when not given (null too), so core gives the user the
+            // local part of the email. Core refuses a null display name.
+            "display-name": displayName ?? undefined,
           }),
         }),
       /**
@@ -884,18 +1037,16 @@ class PlaidClient {
        * @param {string} userId - The user ID
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
-       * @param {string} [asOf] - Temporal query timestamp
        * @param {string[]|string} [opTypes] - Only return operations of these
        *   types, spelled as in an entry's `op/type` (e.g.
        *   `['span-layer/create', 'span-layer/delete']`). An entry appears when
        *   one of its operations matches, carrying only the ones that did.
        */
-      audit: (userId, startTime, endTime, asOf, opTypes) =>
+      audit: (userId, startTime, endTime, opTypes) =>
         listAll(this, `/api/v1/users/${userId}/audit`, {
           query: {
             "start-time": startTime,
             "end-time": endTime,
-            "as-of": asOf,
             "op-types": opTypesParam(opTypes),
           },
         }),
@@ -903,6 +1054,7 @@ class PlaidClient {
        * One page of the same log, newest-first with `order: "desc"`. Use this
        * rather than audit() wherever the caller wants the recent end of a log
        * that may be long: audit() walks every page before it resolves.
+       * @param {string} userId - The user ID
        * @param {object} [opts]
        * @param {"asc"|"desc"} [opts.order] - "desc" pages newest-first
        * @param {number} [opts.limit] - Page size (1..1000; server default 100)
@@ -911,7 +1063,7 @@ class PlaidClient {
        */
       auditPage: (
         userId,
-        { startTime, endTime, asOf, opTypes, order, limit, cursor } = {},
+        { startTime, endTime, opTypes, order, limit, cursor } = {},
       ) =>
         listPage(this, `/api/v1/users/${userId}/audit`, {
           limit,
@@ -919,7 +1071,6 @@ class PlaidClient {
           query: {
             "start-time": startTime,
             "end-time": endTime,
-            "as-of": asOf,
             "op-types": opTypesParam(opTypes),
             order,
           },
@@ -927,13 +1078,9 @@ class PlaidClient {
       /**
        * Get a user by ID
        * @param {string} id - The resource ID
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      get: (id, asOf) =>
-        this._request("GET", `/api/v1/users/${id}`, {
-          bypassBatch: true,
-          queryParams: { "as-of": asOf },
-        }),
+      get: (id) =>
+        this._request("GET", `/api/v1/users/${id}`),
       /**
        * Deactivate a user. Users are never hard-deleted: deactivation
        * rejects their logins and tokens, strips their project memberships
@@ -1001,7 +1148,6 @@ class PlaidClient {
        */
       getAvatar: (id) =>
         this._request("GET", `/api/v1/users/${id}/avatar`, {
-          bypassBatch: true,
           binaryResponse: true,
         }),
       /**
@@ -1059,13 +1205,6 @@ class PlaidClient {
        * @param {number} [opts.pageSize=100] - Entries per request (1..1000)
        */
       list: (userId, { prefix, pattern, includeValues, pageSize = 100 } = {}) =>
-        // Every page carries bypassBatch (the pagination helpers set it): a
-        // read belongs to whoever asked for it, not to whatever batch happens
-        // to be open on this shared client. The assistant panel is app chrome
-        // in both SPAs, so it reads this store while an import or a bulk edit
-        // holds a batch open. Queued, the read answered `{batched: true}` (the
-        // sidebar then threw on `.map`) and took a slot in the batch's
-        // results, shifting every index the caller counted on.
         listAll(this, `/api/v1/users/${userId}/data`, {
           pageSize,
           query: { prefix, pattern, "include-values": includeValues },
@@ -1113,15 +1252,13 @@ class PlaidClient {
        * @param {string} key
        */
       get: (userId, key) =>
-        // bypassBatch for the same reason as list() above.
         this._request(
           "GET",
           `/api/v1/users/${userId}/data/${encodeURIComponent(key)}`,
-          { bypassBatch: true },
         ),
       /**
        * Create or replace one private data entry. `value` is any JSON (up to
-       * 1 MB), stored as sent. Not audited, not batchable.
+       * 1 MB). Not audited, not batchable.
        *
        * The server stores it verbatim, but this client recases object keys on
        * the way out and back like any other body (`myKey` <-> `my-key`), so a
@@ -1189,7 +1326,7 @@ class PlaidClient {
        * credential and is shown ONLY here — store it immediately. API tokens
        * do not expire and survive password changes / logout; revoke to kill.
        * @param {string} userId - The user ID who will own the token
-       * @param {string} name - A human label, e.g. "Stanza Parser"
+       * @param {string} name - A human label, e.g. "Stanza parser"
        * @returns {Promise<{id: string, name: string, token: string}>}
        */
       create: (userId, name, auditMessage) =>
@@ -1318,8 +1455,7 @@ class PlaidClient {
        * walks the media directory, so open it, do not poll it. Admin only.
        * @returns {Promise<{version: string, jvm: object, database: object, media: object, backup: object, settings: object}>}
        */
-      server: () =>
-        this._request("GET", "/api/v1/admin/server", { bypassBatch: true }),
+      server: () => this._request("GET", "/api/v1/admin/server"),
       /**
        * Take a database backup right now, outside the nightly schedule.
        * Resolves to the backup block with `ok` reporting whether the snapshot
@@ -1327,20 +1463,17 @@ class PlaidClient {
        * people are working. Admin only.
        * @returns {Promise<{ok: boolean, directory: string, backups: Array}>}
        *
-       * Goes over the wire even while a batch is open, as every admin action
-       * on the server itself does: none of them writes project data, and a
-       * backup taken inside somebody's open write transaction is not what the
-       * caller asked for.
+       * outOfBand, as every admin action on the server itself is: none of them
+       * writes project data (see the note at the top of http.js).
        */
       backup: () =>
-        this._request("POST", "/api/v1/admin/backup", { bypassBatch: true }),
+        this._request("POST", "/api/v1/admin/backup", { outOfBand: true }),
       /**
        * Documents currently held by an editing lock, with who holds each and
        * when it expires on its own. Admin only.
        * @returns {Promise<{entries: Array<{documentId: string, userId: string, expiresAt: number}>}>}
        */
-      locks: () =>
-        this._request("GET", "/api/v1/admin/locks", { bypassBatch: true }),
+      locks: () => this._request("GET", "/api/v1/admin/locks"),
       /**
        * Drop the lock on a document whoever holds it. Idempotent. For a client
        * that went away without releasing one. Admin only.
@@ -1348,7 +1481,7 @@ class PlaidClient {
        */
       releaseLock: (documentId) =>
         this._request("DELETE", `/api/v1/admin/locks/${documentId}`, {
-          bypassBatch: true,
+          outOfBand: true,
         }),
       /**
        * Live login and invite rate-limit buckets: the address, the account
@@ -1356,10 +1489,7 @@ class PlaidClient {
        * it is currently blocking. Admin only.
        * @returns {Promise<{windowMs: number, logins: Array, ips: Array, invites: Array}>}
        */
-      rateLimits: () =>
-        this._request("GET", "/api/v1/admin/rate-limits", {
-          bypassBatch: true,
-        }),
+      rateLimits: () => this._request("GET", "/api/v1/admin/rate-limits"),
       /**
        * Forget recorded rate-limit failures. With `ip`, clears that address,
        * narrowed to one account with `userId`. With neither, clears every
@@ -1370,7 +1500,7 @@ class PlaidClient {
        */
       clearRateLimits: ({ ip, userId } = {}) =>
         this._request("DELETE", "/api/v1/admin/rate-limits", {
-          bypassBatch: true,
+          outOfBand: true,
           queryParams: { ip, "user-id": userId },
         }),
       /**
@@ -1394,7 +1524,6 @@ class PlaidClient {
        */
       logs: ({ limit, q, level, status, user, method } = {}) =>
         this._request("GET", "/api/v1/admin/logs", {
-          bypassBatch: true,
           queryParams: { limit, q, level, status, user, method },
         }),
       /**
@@ -1408,7 +1537,6 @@ class PlaidClient {
        */
       logFile: ({ lines } = {}) =>
         this._request("GET", "/api/v1/admin/logs/file", {
-          bypassBatch: true,
           queryParams: { lines },
         }),
       /**
@@ -1536,7 +1664,6 @@ class PlaidClient {
           ? `/api/v1/projects/${projectId}/audit/tally`
           : "/api/v1/audit/tally";
         const result = await this._request("GET", path, {
-          bypassBatch: true,
           queryParams: {
             "start-time": startTime,
             "end-time": endTime,
@@ -1615,13 +1742,9 @@ class PlaidClient {
       /**
        * Get a token layer by ID.
        * @param {string} tokenLayerId - The token layer ID
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      get: (tokenLayerId, asOf) =>
-        this._request("GET", `/api/v1/token-layers/${tokenLayerId}`, {
-          bypassBatch: true,
-          queryParams: { "as-of": asOf },
-        }),
+      get: (tokenLayerId) =>
+        this._request("GET", `/api/v1/token-layers/${tokenLayerId}`),
       /**
        * Delete a token layer.
        * @param {string} tokenLayerId - The token layer ID
@@ -1646,38 +1769,34 @@ class PlaidClient {
       /**
        * Check the lock status of a document.
        * @param {string} documentId - The document ID
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      checkLock: (documentId, asOf) =>
-        this._request("GET", `/api/v1/documents/${documentId}/lock`, {
-          bypassBatch: true,
-          queryParams: { "as-of": asOf },
-        }),
+      checkLock: (documentId) =>
+        this._request("GET", `/api/v1/documents/${documentId}/lock`),
       /**
        * Acquire or refresh a document lock.
        *
-       * Goes over the wire even while a batch is open. The lock is an
-       * out-of-band signal, not project data: a queued acquire is taken only
-       * when the batch submits, which is after every write it was meant to
-       * guard, and until then it answers success to a caller that does not
-       * hold it and cannot see the 423 saying somebody else does.
+       * outOfBand: the lock is a signal, not project data (see the note at
+       * the top of http.js). Queued on a batch it would be taken only at
+       * submit, after every write it was meant to guard, and until then answer
+       * success to a caller that does not hold it and cannot see the 423
+       * saying somebody else does.
        * @param {string} documentId - The document ID
        */
       acquireLock: (documentId, auditMessage) =>
         this._request("POST", `/api/v1/documents/${documentId}/lock`, {
           auditMessage,
-          bypassBatch: true,
+          outOfBand: true,
         }),
       /**
-       * Release a document lock. Goes over the wire even while a batch is
-       * open, for the same reason as acquireLock: queued, the lock is held
-       * until the batch submits, and not released at all if it aborts.
+       * Release a document lock. outOfBand, for the same reason as
+       * acquireLock: queued, the lock would be held until the batch submits,
+       * and not released at all if it aborts.
        * @param {string} documentId - The document ID
        */
       releaseLock: (documentId, auditMessage) =>
         this._request("DELETE", `/api/v1/documents/${documentId}/lock`, {
           auditMessage,
-          bypassBatch: true,
+          outOfBand: true,
         }),
       /**
        * Hold this document's server-enforced lock for the length of `fn`,
@@ -1708,8 +1827,8 @@ class PlaidClient {
        * NOT re-entrant: nesting two `locked()` blocks on one document would
        * release on the inner exit and leave the outer unprotected. Lock at
        * exactly one level per call path. A lost lock is recorded on the
-       * CLIENT, like batch and strict mode, so it stops every write the client
-       * makes and not only the ones this block makes.
+       * CLIENT, like strict mode, so it stops every write the client makes
+       * (on any batch of it too) and not only the ones this block makes.
        * @param {string} documentId - The document ID
        * @param {(lock: DocumentLock) => any} fn - The work to run while holding it
        * @param {object} [options] - `{ keepAlive }`: renew on a timer (default true)
@@ -1724,7 +1843,6 @@ class PlaidClient {
        */
       getMedia: (documentId) =>
         this._request("GET", `/api/v1/documents/${documentId}/media`, {
-          bypassBatch: true,
           binaryResponse: true,
         }),
       /**
@@ -1749,8 +1867,8 @@ class PlaidClient {
        * Delete media file for a document
        * @param {string} documentId - The document ID
        */
-      // No flag: the upload above is multipart and cannot be batched, but a
-      // DELETE carries no blob, so the batch transport takes it. It is a write
+      // The upload above is multipart and cannot be batched, but a DELETE
+      // carries no blob, so the batch transport takes it. It is a write
       // of the document's own data and queues like any other. Note that the
       // file removal happens outside the server's transaction, so a batch that
       // aborts after this op does not bring the file back.
@@ -1767,7 +1885,6 @@ class PlaidClient {
         this._request("PUT", `/api/v1/documents/${documentId}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a document.
@@ -1776,18 +1893,16 @@ class PlaidClient {
       deleteMetadata: (documentId, auditMessage) =>
         this._request("DELETE", `/api/v1/documents/${documentId}/metadata`, {
           auditMessage,
-          skipResponseTransform: true,
         }),
       /**
-       * Patch (shallow-merge) metadata for a document. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * Edit metadata for a document with a list of ops applied in order, in one operation. `{op: 'set', path, value}` writes value at path, creating missing objects along it; `{op: 'delete', path}` removes the key at path (a no-op when absent). A path is a non-empty array of keys, the first a top-level key. A path through a non-object is refused (400). See metadataOps and applyMetadataOps.
        * @param {string} documentId - The document ID
-       * @param {any} body - The metadata patch
+       * @param {Array<{op: string, path: string[], value?: any}>} body - The metadata ops
        */
       patchMetadata: (documentId, body, auditMessage) =>
         this._request("PATCH", `/api/v1/documents/${documentId}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Get audit log for a document. Transparently follows pagination cursors
@@ -1795,18 +1910,16 @@ class PlaidClient {
        * @param {string} documentId - The document ID
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
-       * @param {string} [asOf] - Temporal query timestamp
        * @param {string[]|string} [opTypes] - Only return operations of these
        *   types, spelled as in an entry's `op/type` (e.g.
        *   `['span-layer/create', 'span-layer/delete']`). An entry appears when
        *   one of its operations matches, carrying only the ones that did.
        */
-      audit: (documentId, startTime, endTime, asOf, opTypes) =>
+      audit: (documentId, startTime, endTime, opTypes) =>
         listAll(this, `/api/v1/documents/${documentId}/audit`, {
           query: {
             "start-time": startTime,
             "end-time": endTime,
-            "as-of": asOf,
             "op-types": opTypesParam(opTypes),
           },
         }),
@@ -1814,6 +1927,7 @@ class PlaidClient {
        * One page of the same log, newest-first with `order: "desc"`. Use this
        * rather than audit() wherever the caller wants the recent end of a log
        * that may be long: audit() walks every page before it resolves.
+       * @param {string} documentId - The document ID
        * @param {object} [opts]
        * @param {"asc"|"desc"} [opts.order] - "desc" pages newest-first
        * @param {number} [opts.limit] - Page size (1..1000; server default 100)
@@ -1822,7 +1936,7 @@ class PlaidClient {
        */
       auditPage: (
         documentId,
-        { startTime, endTime, asOf, opTypes, order, limit, cursor } = {},
+        { startTime, endTime, opTypes, order, limit, cursor } = {},
       ) =>
         listPage(this, `/api/v1/documents/${documentId}/audit`, {
           limit,
@@ -1830,7 +1944,6 @@ class PlaidClient {
           query: {
             "start-time": startTime,
             "end-time": endTime,
-            "as-of": asOf,
             "op-types": opTypesParam(opTypes),
             order,
           },
@@ -1874,7 +1987,6 @@ class PlaidClient {
        */
       get: (documentId, includeBody, asOf, layers) =>
         this._request("GET", `/api/v1/documents/${documentId}`, {
-          bypassBatch: true,
           queryParams: {
             "include-body": includeBody,
             "as-of": asOf,
@@ -2019,18 +2131,16 @@ class PlaidClient {
        * @param {string} projectId - The project ID
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
-       * @param {string} [asOf] - Temporal query timestamp
        * @param {string[]|string} [opTypes] - Only return operations of these
        *   types, spelled as in an entry's `op/type` (e.g.
        *   `['span-layer/create', 'span-layer/delete']`). An entry appears when
        *   one of its operations matches, carrying only the ones that did.
        */
-      audit: (projectId, startTime, endTime, asOf, opTypes) =>
+      audit: (projectId, startTime, endTime, opTypes) =>
         listAll(this, `/api/v1/projects/${projectId}/audit`, {
           query: {
             "start-time": startTime,
             "end-time": endTime,
-            "as-of": asOf,
             "op-types": opTypesParam(opTypes),
           },
         }),
@@ -2038,6 +2148,7 @@ class PlaidClient {
        * One page of the same log, newest-first with `order: "desc"`. Use this
        * rather than audit() wherever the caller wants the recent end of a log
        * that may be long: audit() walks every page before it resolves.
+       * @param {string} projectId - The project ID
        * @param {object} [opts]
        * @param {"asc"|"desc"} [opts.order] - "desc" pages newest-first
        * @param {number} [opts.limit] - Page size (1..1000; server default 100)
@@ -2046,7 +2157,7 @@ class PlaidClient {
        */
       auditPage: (
         projectId,
-        { startTime, endTime, asOf, opTypes, order, limit, cursor } = {},
+        { startTime, endTime, opTypes, order, limit, cursor } = {},
       ) =>
         listPage(this, `/api/v1/projects/${projectId}/audit`, {
           limit,
@@ -2054,7 +2165,6 @@ class PlaidClient {
           query: {
             "start-time": startTime,
             "end-time": endTime,
-            "as-of": asOf,
             "op-types": opTypesParam(opTypes),
             order,
           },
@@ -2071,7 +2181,6 @@ class PlaidClient {
        */
       myLastEdits: (projectId) =>
         this._request("GET", `/api/v1/projects/${projectId}/audit/last-edits`, {
-          bypassBatch: true,
           skipResponseTransform: true,
         }),
       /**
@@ -2096,13 +2205,9 @@ class PlaidClient {
        * Get a project by ID. To fetch the project's documents, use
        * listDocuments(id) — the include-documents flag has been removed.
        * @param {string} id - The resource ID
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      get: (id, asOf) =>
-        this._request("GET", `/api/v1/projects/${id}`, {
-          bypassBatch: true,
-          queryParams: { "as-of": asOf },
-        }),
+      get: (id) =>
+        this._request("GET", `/api/v1/projects/${id}`),
       /**
        * List all documents in a project. Transparently follows pagination
        * cursors and returns the full flat array.
@@ -2139,17 +2244,15 @@ class PlaidClient {
       iterDocuments: (id, { pageSize } = {}) =>
         iterPages(this, `/api/v1/projects/${id}/documents`, { pageSize }),
       /**
-       * Delete a project and everything in it. This is irrecoverable.
-       *
-       * For a large project this can take a long time, so the client's
-       * per-request timeout is DISABLED by default. Pass `{ timeout }` to
-       * impose a finite bound.
+       * Delete a project and everything in it. This is irrecoverable. The
+       * project is gone when this returns, and what it holds is removed on
+       * the server afterwards.
        * @param {string} id - The resource ID
        * @param {string} [auditMessage] - Custom audit-log message
        * @param {object} [options]
-       * @param {number} [options.timeout=0] - Per-request timeout in ms (0/null disables)
+       * @param {number} [options.timeout] - Per-request timeout in ms, the client's own by default (0/null disables)
        */
-      delete: (id, auditMessage, { timeout = 0 } = {}) =>
+      delete: (id, auditMessage, { timeout } = {}) =>
         this._request("DELETE", `/api/v1/projects/${id}`, {
           auditMessage,
           timeout,
@@ -2167,35 +2270,29 @@ class PlaidClient {
       /**
        * List all projects accessible to user. Transparently follows pagination
        * cursors and returns the full flat array.
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      list: (asOf) =>
-        listAll(this, "/api/v1/projects", { query: { "as-of": asOf } }),
+      list: () => listAll(this, "/api/v1/projects"),
       /**
        * Fetch a single page of projects.
        * @param {object} [opts]
        * @param {number} [opts.limit] - Page size (1..1000; server default 100)
        * @param {string} [opts.cursor] - Opaque cursor from a previous page
-       * @param {string} [opts.asOf] - Temporal query timestamp
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
-      listPage: ({ limit, cursor, asOf } = {}) =>
+      listPage: ({ limit, cursor } = {}) =>
         listPage(this, "/api/v1/projects", {
           limit,
           cursor,
-          query: { "as-of": asOf },
         }),
       /**
        * Async-iterate projects page by page; yields each page's entries array.
        * @param {object} [opts]
        * @param {number} [opts.pageSize] - Per-request page size
-       * @param {string} [opts.asOf] - Temporal query timestamp
        * @returns {AsyncGenerator<Array>}
        */
-      iterPages: ({ pageSize, asOf } = {}) =>
+      iterPages: ({ pageSize } = {}) =>
         iterPages(this, "/api/v1/projects", {
           pageSize,
-          query: { "as-of": asOf },
         }),
       /**
        * Create a new project. Note: this also registers the user as a maintainer.
@@ -2243,13 +2340,9 @@ class PlaidClient {
       /**
        * Get a text layer by ID.
        * @param {string} textLayerId - The text layer ID
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      get: (textLayerId, asOf) =>
-        this._request("GET", `/api/v1/text-layers/${textLayerId}`, {
-          bypassBatch: true,
-          queryParams: { "as-of": asOf },
-        }),
+      get: (textLayerId) =>
+        this._request("GET", `/api/v1/text-layers/${textLayerId}`),
       /**
        * Delete a text layer.
        * @param {string} textLayerId - The text layer ID
@@ -2300,7 +2393,6 @@ class PlaidClient {
         this._request("PUT", `/api/v1/vocab-items/${id}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a vocab item.
@@ -2309,18 +2401,16 @@ class PlaidClient {
       deleteMetadata: (id, auditMessage) =>
         this._request("DELETE", `/api/v1/vocab-items/${id}/metadata`, {
           auditMessage,
-          skipResponseTransform: true,
         }),
       /**
-       * Patch (shallow-merge) metadata for a vocab item. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * Edit metadata for a vocab item with a list of ops applied in order, in one operation. `{op: 'set', path, value}` writes value at path, creating missing objects along it; `{op: 'delete', path}` removes the key at path (a no-op when absent). A path is a non-empty array of keys, the first a top-level key. A path through a non-object is refused (400). See metadataOps and applyMetadataOps.
        * @param {string} id - The resource ID
-       * @param {any} body - The metadata patch
+       * @param {Array<{op: string, path: string[], value?: any}>} body - The metadata ops
        */
       patchMetadata: (id, body, auditMessage) =>
         this._request("PATCH", `/api/v1/vocab-items/${id}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Create a new vocab item
@@ -2343,9 +2433,23 @@ class PlaidClient {
           auditMessage,
           body,
         }),
+      /**
+       * Update many vocab items in a single operation: set forms and/or patch
+       * metadata.
+       * @param {Array<{id: string, form?: string, metadata?: Array<object>}>} body - `form` is set only when the key is present; `metadata` is a list of metadata ops, as for patchMetadata. The entries may lie in several vocab layers; the user must have write access to each. An unknown id refuses the whole update, and an id may appear only once. Only an entry whose form really changes restates the documents linking it, and a strict-mode client picks up their new versions from the response.
+       * @returns {Promise<{count: number}>} How many vocab items were updated.
+       */
+      bulkUpdate: (body, auditMessage) =>
+        this._request("PATCH", "/api/v1/vocab-items/bulk", {
+          auditMessage,
+          body,
+        }),
       /**
        * Delete multiple vocab items in a single operation. Each item's
        * descendant vocab links are deleted too. Provide an array of IDs.
+       *
+       * Every document holding one of those links has its version bumped, and
+       * a strict-mode client picks up their new versions from the response.
        * @param {string[]} body - The vocab item IDs to delete
        */
       bulkDelete: (body, auditMessage) =>
@@ -2356,21 +2460,22 @@ class PlaidClient {
       /**
        * Get a vocab item by ID
        * @param {string} id - The resource ID
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      get: (id, asOf) =>
-        this._request("GET", `/api/v1/vocab-items/${id}`, {
-          bypassBatch: true,
-          queryParams: { "as-of": asOf },
-        }),
+      get: (id) =>
+        this._request("GET", `/api/v1/vocab-items/${id}`),
       /**
-       * Delete a vocab item
+       * Delete a vocab item, and every link to it. Every document holding one
+       * of those links has its version bumped, and a strict-mode client picks
+       * up their new versions from the response.
        * @param {string} id - The resource ID
        */
       delete: (id, auditMessage) =>
         this._request("DELETE", `/api/v1/vocab-items/${id}`, { auditMessage }),
       /**
-       * Update a vocab item's form
+       * Update a vocab item's form. A document read carries the entry's form on
+       * every link to it, so a rename restates those documents: each has its
+       * version bumped, and a strict-mode client picks up their new versions
+       * from the response.
        * @param {string} id - The resource ID
        * @param {string} form - The vocab item form
        */
@@ -2437,13 +2542,9 @@ class PlaidClient {
       /**
        * Get a relation layer by ID.
        * @param {string} relationLayerId - The relation layer ID
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      get: (relationLayerId, asOf) =>
-        this._request("GET", `/api/v1/relation-layers/${relationLayerId}`, {
-          bypassBatch: true,
-          queryParams: { "as-of": asOf },
-        }),
+      get: (relationLayerId) =>
+        this._request("GET", `/api/v1/relation-layers/${relationLayerId}`),
       /**
        * Delete a relation layer.
        * @param {string} relationLayerId - The relation layer ID
@@ -2506,13 +2607,9 @@ class PlaidClient {
       /**
        * Get a token.
        * @param {string} tokenId - The token ID
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      get: (tokenId, asOf) =>
-        this._request("GET", `/api/v1/tokens/${tokenId}`, {
-          bypassBatch: true,
-          queryParams: { "as-of": asOf },
-        }),
+      get: (tokenId) =>
+        this._request("GET", `/api/v1/tokens/${tokenId}`),
       /**
        * Delete a token and remove it from any spans. If this causes a span to
        * have no remaining tokens, the span will also be deleted.
@@ -2550,7 +2647,7 @@ class PlaidClient {
         this._request("DELETE", "/api/v1/tokens/bulk", { auditMessage, body }),
       /**
        * Update many tokens in a single operation: patch metadata.
-       * @param {Array} body - Objects of the shape `{id, metadata}`. `metadata` is a patch, a null value deleting that key. The tokens may lie in several documents of one project; every document touched has its version bumped and every new version comes back in `X-Document-Versions`. A `document-version` precondition is accepted only when every entry lies in one document. An unknown id refuses the whole update.
+       * @param {Array} body - Objects of the shape `{id, metadata}`. `metadata` is a list of metadata ops, as for patchMetadata. The tokens may lie in several documents of one project; every document touched has its version bumped and every new version comes back in `X-Document-Versions` (past fifty documents, only their number, in `X-Document-Versions-Omitted`). A `document-version` precondition is accepted only when every entry lies in one document. An unknown id refuses the whole update.
        * @returns {Promise<{count: number}>} How many tokens were updated.
        */
       bulkUpdate: (body, auditMessage) =>
@@ -2604,7 +2701,6 @@ class PlaidClient {
         this._request("PUT", `/api/v1/tokens/${tokenId}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a token.
@@ -2613,18 +2709,16 @@ class PlaidClient {
       deleteMetadata: (tokenId, auditMessage) =>
         this._request("DELETE", `/api/v1/tokens/${tokenId}/metadata`, {
           auditMessage,
-          skipResponseTransform: true,
         }),
       /**
-       * Patch (shallow-merge) metadata for a token. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * Edit metadata for a token with a list of ops applied in order, in one operation. `{op: 'set', path, value}` writes value at path, creating missing objects along it; `{op: 'delete', path}` removes the key at path (a no-op when absent). A path is a non-empty array of keys, the first a top-level key. A path through a non-object is refused (400). See metadataOps and applyMetadataOps.
        * @param {string} tokenId - The token ID
-       * @param {any} body - The metadata patch
+       * @param {Array<{op: string, path: string[], value?: any}>} body - The metadata ops
        */
       patchMetadata: (tokenId, body, auditMessage) =>
         this._request("PATCH", `/api/v1/tokens/${tokenId}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
     };
 
@@ -2648,21 +2742,24 @@ class PlaidClient {
        * this a key such as `case-marker` would reach listeners as
        * `caseMarker` in JS and `case_marker` in Python. `listen` restores it
        * verbatim on the way in.
+       *
+       * A message is not saved and writes nothing to History, so it never
+       * joins an open operation (`withOperation`). Made on a batch it still
+       * queues, so a message queued after the writes goes out after them.
        * @param {string} projectId - The UUID of the project to send to
        * @param {any} data - The message data to send
        * @returns {Promise<any>} Response from the send operation
        */
-      sendMessage: (projectId, data, auditMessage) =>
+      sendMessage: (projectId, data) =>
         this._request("POST", `/api/v1/projects/${projectId}/message`, {
-          auditMessage,
+          noOperation: true,
           rawBody: { body: data },
         }),
 
       /**
        * Discover the services seen on a project (synchronous GET). Currently
        * connected services carry `online: true`; previously-seen offline ones
-       * carry `online: false` plus a `lastSeenAt` stamp. Goes over the wire
-       * even while a batch is open on the client.
+       * carry `online: false` plus a `lastSeenAt` stamp.
        * @param {string} projectId - The UUID of the project to query
        * @returns {Promise<Array>} Array of discovered service information
        */
@@ -2688,7 +2785,9 @@ class PlaidClient {
        * @param {function} onServiceRequest - Callback (data, responseHelper)
        * @param {Object} [extras] - Optional additional service metadata
        * @param {function} [onStatus] - Optional callback (event, projectId, detail) for
-       *   connection transitions: 'registered', 'reconnected', 'disconnected'
+       *   connection transitions: 'registered', 'reconnected', 'disconnected',
+       *   and 'stopped' when the server refuses the channel for good, which
+       *   ends the registration
        * @returns {Object} Service registration with .stop(), .isRunning(), .isConnected()
        */
       serve: (projectId, serviceInfo, onServiceRequest, extras, onStatus) =>
@@ -2710,7 +2809,7 @@ class PlaidClient {
        * @param {number} [timeout=10000] - Timeout in ms
        * @param {function} [onProgress] - Called with each progress payload {percent, message}
        * @param {AbortSignal} [signal] - Abort to stop waiting; rejects with an AbortError
-       * @param {Object} [opts] - {requestId, onAccepted}
+       * @param {Object} [opts] - {requestId, onAccepted, projectIds}
        * @returns {Promise<any>} The service's result
        */
       requestService: (
@@ -2808,21 +2907,15 @@ class PlaidClient {
      * @param {Object} body - The query AST ({find, where, scope?, limit?, orderBy?,
      *   return?, bindings?}).
      * @returns {Promise<Object>} For 'ids'/'entities': {columns, results, count, truncated}.
-     *   For 'count': {return: 'count', count}. Entity cells are full entity objects
-     *   (same shape as the GET endpoints).
+     *   For 'count': {return: 'count', count, truncated}, where `truncated` says
+     *   the count stopped at the server's cap. Entity cells are full entity
+     *   objects (same shape as the GET endpoints).
      */
-    // bypassBatch: a query is a read. `client.batched()` flips one flag on the
-    // whole client, so a query issued by unrelated code while a batch is open
-    // (the IGT island fetching precedent while a document reconciles) used to
-    // be queued into it: the caller got `{batched: true}` instead of results,
-    // and the server ran the query against the batch's tx Connection, which
-    // 500s and rolls back every write in that batch.
-    this.query = (body, auditMessage) =>
-      this._request("POST", "/api/v1/query", {
-        auditMessage,
-        body,
-        bypassBatch: true,
-      });
+    // outOfBand: a query is a read that travels as a POST (see the note at
+    // the top of http.js). Made on a batch it goes over the wire like any
+    // read, and it never joins a logical operation.
+    this.query = (body) =>
+      this._request("POST", "/api/v1/query", { body, outOfBand: true });
 
     // Logical-operation groups (audit-log grouping). There is no create: a
     // group row is made lazily by the first write carrying `?group-id=`
@@ -2832,10 +2925,7 @@ class PlaidClient {
        * Get a logical-operation group (its label + creator).
        * @param {string} id - The group id
        */
-      get: (id) =>
-        this._request("GET", `/api/v1/operation-groups/${id}`, {
-          bypassBatch: true,
-        }),
+      get: (id) => this._request("GET", `/api/v1/operation-groups/${id}`),
       /**
        * Relabel a logical-operation group after the fact. Owner or admin only.
        * @param {string} id - The group id
@@ -2876,8 +2966,7 @@ class PlaidClient {
        * Read one comment.
        * @param {string} id - The comment id
        */
-      get: (id) =>
-        this._request("GET", `/api/v1/comments/${id}`, { bypassBatch: true }),
+      get: (id) => this._request("GET", `/api/v1/comments/${id}`),
       /**
        * Edit a comment's body. Only the comment's AUTHOR may do this - not
        * maintainers, not admins. Sets `edited` on the comment.
@@ -2969,7 +3058,6 @@ class PlaidClient {
        */
       counts: (projectId, { documentId, entityType, entityId } = {}) =>
         this._request("GET", `/api/v1/projects/${projectId}/comments/counts`, {
-          bypassBatch: true,
           queryParams: {
             "document-id": documentId,
             "entity-type": entityType,
@@ -3004,6 +3092,20 @@ class PlaidClient {
           cursor,
           query: { "entity-id": entityId },
         }),
+      /**
+       * Async-iterate a vocabulary's comments page by page, oldest first;
+       * yields each page's entries array.
+       * @param {string} vocabId - The vocab layer to read
+       * @param {object} [opts]
+       * @param {string} [opts.entityId] - One entry's thread
+       * @param {number} [opts.pageSize] - Per-request page size
+       * @returns {AsyncGenerator<Array>}
+       */
+      iterInVocabPages: (vocabId, { entityId, pageSize } = {}) =>
+        iterPages(this, `/api/v1/vocab-layers/${vocabId}/comments`, {
+          pageSize,
+          query: { "entity-id": entityId },
+        }),
       /**
        * Comment counts per entry of a vocabulary, as an `{entityId: n}` map.
        * The response is NOT key-transformed: its keys are entry ids.
@@ -3017,12 +3119,111 @@ class PlaidClient {
           "GET",
           `/api/v1/vocab-layers/${vocabId}/comments/counts`,
           {
-            bypassBatch: true,
             queryParams: { "entity-id": entityId },
             skipResponseTransform: true,
           },
         ),
     };
+
+    this.guidelines = {
+      /**
+       * Create a guideline in a project. `title` is the handle an assistant
+       * asks for one by, and the only thing a person has to keep current. It is
+       * NOT required to be unique, so a title already in use is written like
+       * any other: warn about it, do not refuse it. A `pinned` guideline is one
+       * the assistant is given in full on every turn.
+       * @param {string} projectId - The project the guideline belongs to
+       * @param {string} title - The handle an assistant asks for one by (1..100 characters)
+       * @param {object} [opts]
+       * @param {string} [opts.body] - The Markdown text (up to 20000 characters; may be empty)
+       * @param {boolean} [opts.pinned] - Send this one to the assistant in full on every turn
+       */
+      create: (projectId, title, { body, pinned } = {}, auditMessage) =>
+        this._request("POST", `/api/v1/projects/${projectId}/guidelines`, {
+          auditMessage,
+          body: bodyOf({ title, body, pinned }),
+        }),
+      /**
+       * Read one guideline, Markdown body included.
+       * @param {string} id - The guideline id
+       */
+      get: (id) => this._request("GET", `/api/v1/guidelines/${id}`),
+      /**
+       * Update a guideline. Every field is optional and an omitted one is
+       * left alone, so an edit to the body need not restate the title.
+       *
+       * Pass `expectedUpdatedAt` (the `updatedAt` you last read) when a person
+       * has been editing prose: the write then fails with 409 rather than
+       * overwriting somebody who saved in between. Leave it off for a pin
+       * toggle or a script, which have nothing of anyone's to lose.
+       * @param {string} id - The guideline id
+       * @param {object} [changes]
+       * @param {string} [changes.title] - The new handle
+       * @param {string} [changes.body] - The new Markdown text
+       * @param {boolean} [changes.pinned] - Whether the assistant always gets it in full
+       * @param {string} [changes.expectedUpdatedAt] - Write only if this is still the stored updatedAt
+       */
+      update: (
+        id,
+        { title, body, pinned, expectedUpdatedAt } = {},
+        auditMessage,
+      ) =>
+        this._request("PATCH", `/api/v1/guidelines/${id}`, {
+          auditMessage,
+          queryParams: { "updated-at": expectedUpdatedAt },
+          body: bodyOf({ title, body, pinned }),
+        }),
+      /**
+       * Delete a guideline.
+       * @param {string} id - The guideline id
+       */
+      delete: (id, auditMessage) =>
+        this._request("DELETE", `/api/v1/guidelines/${id}`, { auditMessage }),
+      /**
+       * List a project's guidelines, by title. Transparently follows
+       * pagination cursors and returns the full flat array.
+       *
+       * Without `includeBodies` each entry carries `bodyChars`, the length of
+       * its body, so a caller can budget before fetching any. Pinned
+       * guidelines are NOT sorted first: `pinned` is on every entry and
+       * grouping is the caller's.
+       * @param {string} projectId - The project to read
+       * @param {object} [opts]
+       * @param {boolean} [opts.includeBodies] - Return each body instead of its length
+       */
+      list: (projectId, { includeBodies } = {}) =>
+        listAll(this, `/api/v1/projects/${projectId}/guidelines`, {
+          query: { "include-bodies": includeBodies },
+        }),
+      /**
+       * Fetch a single page of a project's guidelines.
+       * @param {string} projectId - The project to read
+       * @param {object} [opts]
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @param {boolean} [opts.includeBodies] - Return each body instead of its length
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      listPage: (projectId, { limit, cursor, includeBodies } = {}) =>
+        listPage(this, `/api/v1/projects/${projectId}/guidelines`, {
+          limit,
+          cursor,
+          query: { "include-bodies": includeBodies },
+        }),
+      /**
+       * Async-iterate a project's guidelines page by page; yields each page's entries array.
+       * @param {string} projectId - The project to read
+       * @param {object} [opts]
+       * @param {number} [opts.pageSize] - Per-request page size
+       * @param {boolean} [opts.includeBodies] - Return each body instead of its length
+       * @returns {AsyncGenerator<Array>}
+       */
+      iterPages: (projectId, { pageSize, includeBodies } = {}) =>
+        iterPages(this, `/api/v1/projects/${projectId}/guidelines`, {
+          pageSize,
+          query: { "include-bodies": includeBodies },
+        }),
+    };
   }
 
   // --- Core methods ---
@@ -3067,8 +3268,8 @@ class PlaidClient {
    * "Every write" is the writes of project data. Reads never join, and neither
    * do the out-of-band signals shaped like a write (a document lock taken or
    * renewed, a stopped service request, a service reporting itself, an admin
-   * control): none of them is audited, so there would be nothing under the
-   * label.
+   * control), and neither does a broadcast message (`messages.sendMessage`):
+   * none of them is audited, so there would be nothing under the label.
    *
    * @param {string} message - Human label for the operation.
    * @param {object} [opts] - Optional `{ id }`: adopt an existing group id instead of minting one (a service joining the requester's operation; `requestService` propagates an open operation to the service automatically).
@@ -3124,7 +3325,7 @@ class PlaidClient {
    * callback to refine the label once the outcome is known.
    *
    *   await client.withOperation('Merge morphemes', async (setMessage) => {
-   *     await client.batched(() => { ... });
+   *     await client.batched(async (b) => { ... });
    *     setMessage(`Merged ${n} morphemes`);
    *   });
    *
@@ -3146,58 +3347,38 @@ class PlaidClient {
   }
 
   /**
-   * Begin a batch of operations. Subsequent WRITES are queued; reads and
-   * out-of-band signals still go over the wire (see `batched`).
+   * Open a batch: a view of this client with the same bundles, on which every
+   * write of project data queues instead of going out. `submit()` sends the
+   * queued operations as ONE atomic request (larger than the server's cap,
+   * as consecutive requests with the results concatenated in queue order,
+   * each atomic on its own, so a failure in a later one leaves the earlier
+   * ones committed, and the error it throws carries `committed`, the count
+   * saved, and `committedResults`, their results) and
+   * resolves to one result per operation; `abort()` drops them. A call made
+   * on the client itself is never touched by an open batch, and a read or an
+   * out-of-band signal made on the batch goes over the wire now (see the note
+   * at the top of `http.js`).
+   *
+   *   const b = client.batch();
+   *   b.tokens.bulkCreate(sentenceOps);
+   *   b.tokens.bulkCreate(wordOps);
+   *   const [sentRes, wordRes] = await b.submit();
+   *
+   * Server-side a batch runs sequentially in one transaction: a child op sees
+   * parents created earlier in the same batch, and any op's failure rolls the
+   * whole batch back. A batch is not nestable. Prefer `batched()`, which
+   * submits or aborts for you.
+   * @returns {PlaidClient} the batch view
    */
-  beginBatch() {
-    this.isBatching = true;
-    this.batchOperations = [];
-    // Strict mode stamps the expected document-version on the FIRST QUEUED
-    // write of the batch only (see _request), so reset the marker per batch.
-    this.batchVersionStamped = false;
+  batch() {
+    return openBatch(this);
   }
 
   /**
-   * Submit all queued batch operations as a single batch request, executed
-   * atomically. If any operation fails, all changes are rolled back.
-   * @returns {Promise<Array>} Array of results corresponding to each operation
+   * POST one batch request (at most MAX_BATCH_OPS operations). Resolves to
+   * one `{ status, headers, body }` per operation, with only the body
+   * recased: the headers keep the server's spelling.
    */
-  async submitBatch() {
-    if (!this.isBatching) {
-      throw new Error("No active batch. Call beginBatch() first.");
-    }
-
-    if (this.batchOperations.length === 0) {
-      this.isBatching = false;
-      return [];
-    }
-
-    try {
-      const url = `${this.baseUrl}/api/v1/batch`;
-      const ops = this.batchOperations.map((op) => ({
-        path: op.path,
-        method: op.method.toUpperCase(),
-        ...(op.body && { body: op.body }),
-      }));
-      // The server caps a batch at MAX_BATCH_OPS so one transaction cannot
-      // hold the write lock without bound. A larger batch goes as consecutive
-      // requests, results concatenated in queue order: it could not have been
-      // one transaction anyway, and a repair or bulk edit over a big document
-      // must not fail on its size alone.
-      const results = [];
-      for (let i = 0; i < ops.length; i += MAX_BATCH_OPS) {
-        results.push(
-          ...(await this._postBatch(url, ops.slice(i, i + MAX_BATCH_OPS))),
-        );
-      }
-      return results;
-    } finally {
-      this.isBatching = false;
-      this.batchOperations = [];
-    }
-  }
-
-  /** POST one batch request (at most MAX_BATCH_OPS operations); resolves to its transformed results. */
   async _postBatch(url, body) {
     const fetchOptions = {
       method: "POST",
@@ -3222,6 +3403,22 @@ class PlaidClient {
           throw makeHttpError(res, await parseErrorBody(res), url, "POST");
         }
         return res;
+      }).catch((error) => {
+        // 401 means the token is missing, expired or invalid: fire the app's
+        // auth-error handler once, exactly as makeRequest does.
+        if (
+          error?.status === 401 &&
+          typeof this.onAuthError === "function" &&
+          !this._authErrorFired
+        ) {
+          this._authErrorFired = true;
+          try {
+            this.onAuthError(error);
+          } catch (_) {
+            /* handler must not mask the original error */
+          }
+        }
+        throw error;
       });
 
       const results = await response.json();
@@ -3249,80 +3446,44 @@ class PlaidClient {
         }
       }
 
-      return results.map((result) => transformResponse(result));
+      return results.map((result) => ({
+        ...result,
+        body: transformResponse(result.body),
+      }));
     } catch (error) {
       if (error.status) throw error;
       throw makeNetworkError(error, url, "POST");
     }
   }
 
-  /** Abort the current batch without executing any operations. */
-  abortBatch() {
-    this.isBatching = false;
-    this.batchOperations = [];
-  }
-
   /**
-   * Check if currently in batch mode.
-   * @returns {boolean}
-   */
-  isBatchMode() {
-    return this.isBatching;
-  }
-
-  /**
-   * Run `fn` with a batch open, then submit all queued ops as ONE atomic
-   * request — or abort the batch if `fn` throws, so a half-open batch can never
-   * silently swallow later non-batch calls. `fn` makes the (queued) client
-   * calls; it must NOT call submitBatch itself. Resolves to the batch results
-   * array (`[]` if `fn` queued nothing).
+   * Run `fn` with a batch, then submit all queued ops as `submit()` does (ONE
+   * atomic request up to MAX_BATCH_OPS operations, consecutive requests past
+   * it), or abort the batch if `fn` throws. `fn` receives the batch and makes its
+   * writes on it; it must NOT call `submit()` itself. Resolves to the batch
+   * results array (`[]` if `fn` queued nothing).
    *
-   *   const [sentRes, wordRes] = await client.batched(async () => {
-   *     client.tokens.bulkCreate(sentenceOps);
-   *     client.tokens.bulkCreate(wordOps);
+   *   const [sentRes, wordRes] = await client.batched(async (b) => {
+   *     b.tokens.bulkCreate(sentenceOps);
+   *     b.tokens.bulkCreate(wordOps);
    *   });
    *
-   * Server-side a batch runs sequentially in one transaction (a child op sees
-   * parents created earlier in the same `fn`; any op's failure rolls the whole
-   * batch back). Not nestable. Named `batched()` because `client.batch` is the
-   * low-level batch resource.
-   *
-   * WRITES are what a batch queues, and batch mode is one flag on the whole
-   * client, so it catches every write made while it is open, including writes
-   * made by code that knows nothing about this batch. READS are never caught:
-   * every read method goes over the wire while a batch is open and is answered
-   * from the state the batch has not committed yet, so a read cannot come back
-   * as a batch marker and cannot take a slot in the results array. Neither are
-   * the calls that signal something out of band rather than write project data:
-   * stopping a service request, a service reporting its progress or result,
-   * taking and dropping a document lock, and the admin actions on the server
-   * itself. See the note at the top of `http.js` for which column a new
-   * endpoint belongs in.
-   * @param {() => (void | Promise<void>)} fn
+   * A write made on `client` inside `fn` is not part of the batch: it goes
+   * over the wire at once, as it would anywhere else. See `batch()`.
+   * @param {(batch: PlaidClient) => (void | Promise<void>)} fn
    * @returns {Promise<Array>}
    */
   async batched(fn) {
-    this.beginBatch();
+    const batch = this.batch();
     try {
-      await fn();
+      await fn(batch);
     } catch (e) {
-      // fn failed: drop the queued ops so the client leaves batch mode and
-      // later plain calls don't queue into a never-submitted batch.
-      if (this.isBatchMode()) this.abortBatch();
+      batch.abort();
       throw e;
     }
-    return this.submitBatch();
+    return batch.submit();
   }
 
-  /**
-   * Authenticate and return a new client instance with token. This is the
-   * single auth entry point — there is no `client.login` resource.
-   * @param {string} baseUrl - The base URL for the API
-   * @param {string} userId - User ID for authentication
-   * @param {string} password - Password for authentication
-   * @param {object} [options] - Client options forwarded to the constructor (e.g. { timeout })
-   * @returns {Promise<PlaidClient>} - Authenticated client instance
-   */
   /**
    * Liveness, version and database size, with NO authentication and no client
    * instance — for a launcher or status page checking whether a server is up
@@ -3417,6 +3578,15 @@ class PlaidClient {
     };
   }
 
+  /**
+   * Authenticate and return a new client instance with token. This is the
+   * single auth entry point — there is no `client.login` resource.
+   * @param {string} baseUrl - The base URL for the API
+   * @param {string} userId - User ID for authentication
+   * @param {string} password - Password for authentication
+   * @param {object} [options] - Client options forwarded to the constructor (e.g. { timeout })
+   * @returns {Promise<PlaidClient>} - Authenticated client instance
+   */
   static async login(baseUrl, userId, password, options = {}) {
     baseUrl = baseUrl.replace(/\/$/, "");
     const url = `${baseUrl}/api/v1/login`;
@@ -3516,7 +3686,6 @@ export {
   needsReview,
   verifyOnEdit,
   contributeOnEdit,
-  mergeMetadata,
   serviceSource,
   userSource,
   REVIEW_KEY,
@@ -3527,4 +3696,15 @@ export {
   withReviewedUser,
   writerPolicy,
 } from "./provenance.js";
+// Metadata ops: the body of a metadata PATCH and of a bulk update entry's
+// `metadata`. See ./metadataOps.js.
+export {
+  metadataOps,
+  applyMetadataOps,
+  mergeMetadata,
+  isReservedMetadataKey,
+} from "./metadataOps.js";
+// The ids a create or bulk create answered with, off the call or its batch
+// result. See ./created.js.
+export { createdId, createdIds } from "./created.js";
 export { MAX_BATCH_OPS };