@larc-iu/plaid-client 0.2.0-alpha.16 → 0.2.0-alpha.18

package/src/index.js

@@ -6,6 +6,7 @@ import { transformRequest, transformResponse } from "./transforms.js";
 import {
   makeRequest,
   queueRequest,
+  restampDocumentVersion,
   extractDocumentVersions,
   parseErrorBody,
   makeHttpError,
@@ -16,6 +17,7 @@ import {
   DEFAULT_BATCH_TIMEOUT_MS,
 } from "./http.js";
 import { listAll, listPage, iterPages } from "./pagination.js";
+import { recorderFor } from "./events.js";
 import { withDocumentLock } from "./documentLock.js";
 import { createSSEConnection } from "./sse.js";
 import {
@@ -128,6 +130,9 @@ 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);
@@ -138,6 +143,7 @@ function openBatch(client) {
   batch.submit = () => submitBatch(batch);
   batch.abort = () => {
     batch.operations = [];
+    batch.stampedDocuments = [];
     batch.open = false;
   };
   batch._installResources();
@@ -150,23 +156,66 @@ async function submitBatch(batch) {
   }
   batch.open = false;
   const ops = batch.operations;
+  const stamps = batch.stampedDocuments;
   batch.operations = [];
+  batch.stampedDocuments = [];
   if (ops.length === 0) return [];
-  const url = `${batch.client.baseUrl}/api/v1/batch`;
+  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.
+  // 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 = [];
-  for (let i = 0; i < ops.length; i += MAX_BATCH_OPS) {
-    results.push(
-      ...(await batch.client._postBatch(url, ops.slice(i, i + MAX_BATCH_OPS))),
-    );
+  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)));
+  }
+}
+
+/** The query of an events read: `types` as the wire's comma-separated list. */
+function eventQuery(types, startTime, endTime) {
+  return {
+    types: Array.isArray(types) ? types.join(",") || undefined : types,
+    "start-time": startTime,
+    "end-time": endTime,
+  };
+}
+
 class PlaidClient {
   /**
    * Create a new PlaidClient instance
@@ -193,6 +242,9 @@ class PlaidClient {
           ? options.timeout
           : DEFAULT_BATCH_TIMEOUT_MS;
     this.documentVersions = {};
+    // The server's clock minus this machine's, in ms, from the last response
+    // with a Date header (null before one). See serverNow().
+    this.serverClockOffsetMs = null;
     this.strictModeDocumentId = null;
     // Set to a DocumentLockLost while a `documents.locked()` block's keep-alive
     // has failed. Every write throws it until the block exits; see
@@ -212,6 +264,17 @@ class PlaidClient {
     this._installResources();
   }
 
+  /**
+   * The server's time now, as its last response's Date header put it (to the
+   * second), else this machine's. Judge a time the server stamped, such as an
+   * audit entry's `ts`, against this rather than `Date.now()`: a browser
+   * clock can be minutes off.
+   * @returns {Date}
+   */
+  serverNow() {
+    return new Date(Date.now() + (this.serverClockOffsetMs ?? 0));
+  }
+
   /**
    * The API bundles (`client.documents`, `client.tokens`, ...). Installed on
    * the client, and again on every batch it opens (see `batch()`): a batch is
@@ -261,7 +324,6 @@ class PlaidClient {
         this._request("PUT", `/api/v1/vocab-links/${id}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a vocab link.
@@ -270,28 +332,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}`, {
-          queryParams: { "as-of": asOf },
-        }),
+      get: (id) =>
+        this._request("GET", `/api/v1/vocab-links/${id}`),
       /**
        * Delete a vocab link
        * @param {string} id - The resource ID
@@ -302,15 +359,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}`, {
           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
@@ -355,35 +510,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.
@@ -428,7 +577,6 @@ class PlaidClient {
         this._request("PUT", `/api/v1/relations/${relationId}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a relation.
@@ -437,18 +585,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.
@@ -463,12 +609,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}`, {
-          queryParams: { "as-of": asOf },
-        }),
+      get: (relationId) =>
+        this._request("GET", `/api/v1/relations/${relationId}`),
       /**
        * Delete a relation.
        * @param {string} relationId - The relation ID
@@ -536,7 +679,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) =>
@@ -581,12 +724,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}`, {
-          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
@@ -659,12 +799,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}`, {
-          queryParams: { "as-of": asOf },
-        }),
+      get: (spanId) =>
+        this._request("GET", `/api/v1/spans/${spanId}`),
       /**
        * Delete a span.
        * @param {string} spanId - The span ID
@@ -696,7 +833,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) =>
@@ -713,7 +850,6 @@ class PlaidClient {
         this._request("PUT", `/api/v1/spans/${spanId}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a span.
@@ -722,18 +858,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,
         }),
     };
 
@@ -769,6 +903,24 @@ class PlaidClient {
       health: () => PlaidClient.health(this.baseUrl, { timeout: this.timeout }),
     };
 
+    // 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>}
+       */
+      logoutEverywhere: async () => {
+        await this._request("POST", "/api/v1/logout", { outOfBand: true });
+      },
+    };
+
     this.texts = {
       /**
        * Replace all metadata for a text.
@@ -779,7 +931,6 @@ class PlaidClient {
         this._request("PUT", `/api/v1/texts/${textId}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a text.
@@ -788,18 +939,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
@@ -822,12 +971,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}`, {
-          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
@@ -859,37 +1005,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.
@@ -907,7 +1050,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,
           }),
         }),
       /**
@@ -916,18 +1061,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),
           },
         }),
@@ -935,6 +1078,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)
@@ -943,7 +1087,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,
@@ -951,7 +1095,6 @@ class PlaidClient {
           query: {
             "start-time": startTime,
             "end-time": endTime,
-            "as-of": asOf,
             "op-types": opTypesParam(opTypes),
             order,
           },
@@ -959,12 +1102,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}`, {
-          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
@@ -1142,7 +1282,7 @@ class PlaidClient {
         ),
       /**
        * 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
@@ -1210,7 +1350,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) =>
@@ -1626,12 +1766,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}`, {
-          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
@@ -1656,14 +1793,15 @@ 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`, {
-          queryParams: { "as-of": asOf },
-        }),
+      checkLock: (documentId) =>
+        this._request("GET", `/api/v1/documents/${documentId}/lock`),
       /**
-       * Acquire or refresh a document lock.
+       * Acquire a document lock as a new holder.
+       *
+       * The answer's `lockId` names the holder: `renewLock` and `releaseLock`
+       * take it. While the lock is held, a second acquire is refused with
+       * HTTP 423, whoever makes it, this user included.
        *
        * 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
@@ -1678,13 +1816,30 @@ class PlaidClient {
           outOfBand: true,
         }),
       /**
-       * Release a document lock. outOfBand, for the same reason as
+       * Renew the lock `lockId` holds while it is live. HTTP 423 if another
+       * holder has it, and also once it has expired or been dropped, even when
+       * nobody holds the document now: a renewal never takes a free document.
+       * outOfBand, for the same reason as acquireLock.
+       * @param {string} documentId - The document ID
+       * @param {string} lockId - The `lockId` acquireLock answered with
+       */
+      renewLock: (documentId, lockId, auditMessage) =>
+        this._request("POST", `/api/v1/documents/${documentId}/lock`, {
+          queryParams: { "lock-id": lockId },
+          auditMessage,
+          outOfBand: true,
+        }),
+      /**
+       * Release the lock `lockId` holds. Idempotent: a lock that holder no
+       * longer has is left alone. 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
+       * @param {string} lockId - The `lockId` acquireLock answered with
        */
-      releaseLock: (documentId, auditMessage) =>
+      releaseLock: (documentId, lockId, auditMessage) =>
         this._request("DELETE", `/api/v1/documents/${documentId}/lock`, {
+          queryParams: { "lock-id": lockId },
           auditMessage,
           outOfBand: true,
         }),
@@ -1702,9 +1857,9 @@ class PlaidClient {
        * tokenizer that deletes and recreates a document's tokens, spans and
        * relations. A single atomic call does not need it. While the lock is
        * held, writes to the document by ANOTHER user are refused with HTTP
-       * 423; the holder's own writes pass and renew it. If another user
-       * already holds it this rejects with a readable 423 and `fn` does not
-       * run.
+       * 423; the holder's own writes pass and renew it. If anyone already
+       * holds it, another block of this same user included, this rejects with
+       * a readable 423 and `fn` does not run.
        *
        * The lock is renewed for as long as `fn` runs, so work that computes
        * for minutes before it writes holds the lock the whole time rather than
@@ -1714,11 +1869,13 @@ class PlaidClient {
        * success. `fn` receives a lock handle and may read `lock.lost` (or call
        * `lock.raiseIfLost()`) to give up sooner.
        *
-       * 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.
+       * The lock is per HOLDER: each block is its own, named by
+       * `lock.lockId`, and only that id renews or releases it. NOT
+       * re-entrant: a nested `locked()` block on one document is a second
+       * holder and gets the 423. Lock at exactly one level per call path. A
+       * lost lock is recorded on the 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)
@@ -1775,7 +1932,6 @@ class PlaidClient {
         this._request("PUT", `/api/v1/documents/${documentId}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a document.
@@ -1784,18 +1940,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
@@ -1803,18 +1957,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),
           },
         }),
@@ -1822,6 +1974,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)
@@ -1830,7 +1983,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,
@@ -1838,7 +1991,6 @@ class PlaidClient {
           query: {
             "start-time": startTime,
             "end-time": endTime,
-            "as-of": asOf,
             "op-types": opTypesParam(opTypes),
             order,
           },
@@ -2026,18 +2178,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),
           },
         }),
@@ -2045,6 +2195,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)
@@ -2053,7 +2204,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,
@@ -2061,7 +2212,6 @@ class PlaidClient {
           query: {
             "start-time": startTime,
             "end-time": endTime,
-            "as-of": asOf,
             "op-types": opTypesParam(opTypes),
             order,
           },
@@ -2102,12 +2252,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}`, {
-          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.
@@ -2144,17 +2291,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,
@@ -2172,35 +2317,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.
@@ -2248,12 +2387,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}`, {
-          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
@@ -2304,7 +2440,6 @@ class PlaidClient {
         this._request("PUT", `/api/v1/vocab-items/${id}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a vocab item.
@@ -2313,18 +2448,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
@@ -2350,7 +2483,7 @@ class PlaidClient {
       /**
        * Update many vocab items in a single operation: set forms and/or patch
        * metadata.
-       * @param {Array<{id: string, form?: string, metadata?: any}>} body - `form` is set only when the key is present; `metadata` is a patch, a null value deleting that key. 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.
+       * @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) =>
@@ -2374,12 +2507,9 @@ 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}`, {
-          queryParams: { "as-of": asOf },
-        }),
+      get: (id) =>
+        this._request("GET", `/api/v1/vocab-items/${id}`),
       /**
        * 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
@@ -2459,12 +2589,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}`, {
-          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
@@ -2527,12 +2654,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}`, {
-          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.
@@ -2570,7 +2694,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) =>
@@ -2624,7 +2748,6 @@ class PlaidClient {
         this._request("PUT", `/api/v1/tokens/${tokenId}/metadata`, {
           auditMessage,
           rawBody: body,
-          skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a token.
@@ -2633,18 +2756,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,
         }),
     };
 
@@ -2668,13 +2789,17 @@ 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 },
         }),
 
@@ -2707,7 +2832,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) =>
@@ -2729,7 +2856,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, noOperation}
        * @returns {Promise<any>} The service's result
        */
       requestService: (
@@ -2827,18 +2954,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).
      */
     // 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, auditMessage) =>
-      this._request("POST", "/api/v1/query", {
-        auditMessage,
-        body,
-        outOfBand: true,
-      });
+    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=`
@@ -3015,6 +3139,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.
@@ -3034,6 +3172,100 @@ class PlaidClient {
         ),
     };
 
+    this.events = {
+      /**
+       * Record one research-telemetry event (core manual, "Research
+       * telemetry"). Fire and forget: the event is buffered and sent with
+       * others every ten seconds, at fifty events, and when the page is
+       * hidden. A batch that fails is dropped, nothing is retried, and
+       * nothing is ever thrown. Sends nothing for a project whose switch
+       * (`config.plaid.research.telemetry`) is off, which it reads from the
+       * project itself. `suggestion.shown` is recorded once per target,
+       * field and value in a page session.
+       * @param {'suggestion.shown'|'suggestion.adopted'|'suggestion.dismissed'|'plan.opened'} type - The event type
+       * @param {object} fields
+       * @param {string} fields.projectId - The project it happened in
+       * @param {string} [fields.documentId] - The document it happened in
+       * @param {string} [fields.targetId] - What it is about: a token, a plan
+       * @param {object} [fields.data] - Its details, keyed by single lowercase words (`value`, `source`, `field`, `written`, `conversation`)
+       * @returns {boolean} Whether the event was buffered
+       */
+      record: (type, fields) => recorderFor(this).record(this, type, fields),
+      /**
+       * Send what the recorder holds now, rather than at its next interval.
+       */
+      flush: () => recorderFor(this).flush(),
+      /**
+       * Tell the recorder a project's switch at once, e.g. right after a
+       * maintainer changed it. Turning it off drops what is buffered.
+       * @param {string} projectId - The project
+       * @param {boolean} on - Whether telemetry is on
+       */
+      setEnabled: (projectId, on) => recorderFor(this).setEnabled(projectId, on),
+      /**
+       * Record events directly, with no buffering. Requires write access, and
+       * the server refuses with a 403 while the project's switch is off. All
+       * or nothing: one bad event refuses the request with a 400 naming it.
+       * @param {string} projectId - The project the events happened in
+       * @param {Array<{type: string, documentId?: string, targetId?: string, data?: object, clientTs?: string}>} events - At most 500 events
+       * @returns {Promise<{count: number}>}
+       */
+      create: (projectId, events) =>
+        this._request("POST", `/api/v1/projects/${projectId}/events`, {
+          body: events,
+          outOfBand: true,
+        }),
+      /**
+       * A project's events in arrival order. Maintainer or admin only.
+       * Transparently follows pagination cursors and returns the full flat
+       * array.
+       * @param {string} projectId - The project to read
+       * @param {object} [filters]
+       * @param {string|string[]} [filters.types] - Only these types
+       * @param {string} [filters.startTime] - Only events the server stamped at or after this instant
+       * @param {string} [filters.endTime] - Only events the server stamped at or before this instant
+       */
+      list: (projectId, { types, startTime, endTime } = {}) =>
+        listAll(this, `/api/v1/projects/${projectId}/events`, {
+          query: eventQuery(types, startTime, endTime),
+        }),
+      /**
+       * One page of a project's events. Maintainer or admin only.
+       * @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 {string|string[]} [opts.types] - Only these types
+       * @param {string} [opts.startTime] - Only events at or after this instant
+       * @param {string} [opts.endTime] - Only events at or before this instant
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      listPage: (
+        projectId,
+        { limit, cursor, types, startTime, endTime } = {},
+      ) =>
+        listPage(this, `/api/v1/projects/${projectId}/events`, {
+          limit,
+          cursor,
+          query: eventQuery(types, startTime, endTime),
+        }),
+      /**
+       * Async-iterate a project's events 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 {string|string[]} [opts.types] - Only these types
+       * @param {string} [opts.startTime] - Only events at or after this instant
+       * @param {string} [opts.endTime] - Only events at or before this instant
+       * @returns {AsyncGenerator<Array>}
+       */
+      iterPages: (projectId, { pageSize, types, startTime, endTime } = {}) =>
+        iterPages(this, `/api/v1/projects/${projectId}/events`, {
+          pageSize,
+          query: eventQuery(types, startTime, endTime),
+        }),
+    };
+
     this.guidelines = {
       /**
        * Create a guideline in a project. `title` is the handle an assistant
@@ -3177,14 +3409,22 @@ 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.
+   *
+   * `kind` says what kind of operation this is, for a program reading the
+   * log: one of `assistant-plan`, `service-run`, `import`, `bulk-edit`,
+   * `guess-adoption` or `repair` (the server refuses any other). `ref` is a
+   * short string naming what the operation came from, in the shape its kind
+   * documents (the core manual, "Kinds of operation"). Both are recorded from
+   * the first write like the label, and a nested operation keeps the outer
+   * one's.
    *
    * @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).
+   * @param {object} [opts] - Optional `{ id, kind, ref }`. `id` adopts an existing group id instead of minting one (a service joining the requester's operation; `requestService` propagates an open operation to the service automatically). `kind` and `ref` are described above.
    * @returns {string} The operation's group id.
    */
-  beginOperation(message, { id } = {}) {
+  beginOperation(message, { id, kind, ref } = {}) {
     if (this.operationGroup) {
       this.operationGroup.depth += 1;
       return this.operationGroup.id;
@@ -3192,6 +3432,8 @@ class PlaidClient {
     this.operationGroup = {
       id: id || crypto.randomUUID(),
       message: message == null ? null : String(message),
+      kind: kind == null ? null : String(kind),
+      ref: ref == null ? null : String(ref),
       depth: 1,
       written: false,
       refined: undefined,
@@ -3238,12 +3480,17 @@ class PlaidClient {
    *     setMessage(`Merged ${n} morphemes`);
    *   });
    *
+   * The kind and reference (see beginOperation) come after `fn`:
+   *
+   *   await client.withOperation('Import ELAN corpus', run, { kind: 'import', ref: 'format:elan' });
+   *
    * @param {string} message - Human label for the operation.
    * @param {function} fn - The work to run; receives `setMessage(msg)` to refine the label once the outcome is known.
+   * @param {object} [opts] - Optional `{ kind, ref }`, as for beginOperation.
    * @returns {Promise<any>} Whatever `fn` resolves to.
    */
-  async withOperation(message, fn) {
-    this.beginOperation(message);
+  async withOperation(message, fn, { kind, ref } = {}) {
+    this.beginOperation(message, { kind, ref });
     const group = this.operationGroup;
     const setMessage = (msg) => {
       if (group.depth === 1) group.refined = msg;
@@ -3259,7 +3506,10 @@ class PlaidClient {
    * 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) and
+   * 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
@@ -3280,7 +3530,11 @@ class PlaidClient {
     return openBatch(this);
   }
 
-  /** POST one batch request (at most MAX_BATCH_OPS operations); resolves to its transformed results. */
+  /**
+   * 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 _postBatch(url, body) {
     const fetchOptions = {
       method: "POST",
@@ -3305,6 +3559,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();
@@ -3332,7 +3602,10 @@ 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");
@@ -3340,8 +3613,9 @@ class PlaidClient {
   }
 
   /**
-   * Run `fn` with a batch, then submit all queued ops as ONE atomic request,
-   * or abort the batch if `fn` throws. `fn` receives the batch and makes its
+   * 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).
    *
@@ -3366,15 +3640,6 @@ class PlaidClient {
     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
@@ -3469,6 +3734,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`;
@@ -3541,6 +3815,9 @@ export {
 // request, and `critical()` holds that off around writes. See ./services.js
 // and the manual, "Stopping a request".
 export { ServiceCancelled, createCancelScope } from "./services.js";
+// Who asked for a service run, named in its History label and in what it
+// stores. See ./requester.js.
+export { REQUESTED_BY, makeRequester, requesterOf } from "./requester.js";
 // Document locks: `client.documents.locked()` holds one for a block of work and
 // renews it while the block runs. DocumentLockLost is what a write throws once
 // a renewal has failed. See ./documentLock.js.
@@ -3568,7 +3845,6 @@ export {
   needsReview,
   verifyOnEdit,
   contributeOnEdit,
-  mergeMetadata,
   serviceSource,
   userSource,
   REVIEW_KEY,
@@ -3579,4 +3855,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 };