@larc-iu/plaid-client 0.2.0-alpha.2 → 0.2.0-alpha.20

package/src/index.js

@@ -2,26 +2,48 @@
  * plaid-client - JavaScript client for the Plaid annotation API
  */
 
-import { transformRequest, transformResponse } from './transforms.js';
+import { transformRequest, transformResponse } from "./transforms.js";
 import {
-  makeRequest, extractDocumentVersions, parseErrorBody, makeHttpError,
-  makeNetworkError, timeoutSignal, DEFAULT_TIMEOUT_MS,
-} from './http.js';
-import { listAll, listPage, iterPages } from './pagination.js';
-import { createSSEConnection } from './sse.js';
+  makeRequest,
+  queueRequest,
+  restampDocumentVersion,
+  extractDocumentVersions,
+  parseErrorBody,
+  makeHttpError,
+  makeNetworkError,
+  timeoutSignal,
+  retryWhileBusy,
+  retryUnknown,
+  nextIdempotencyKey,
+  mergeVersions,
+  IDEMPOTENCY_HEADER,
+  REPLAYED_HEADER,
+  DEFAULT_TIMEOUT_MS,
+  DEFAULT_BATCH_TIMEOUT_MS,
+} from "./http.js";
+import { uuidv7 } from "./ids.js";
+import { constraintsBody } from "./constraints.js";
+import { listAll, listPage, iterPages } from "./pagination.js";
+import { recorderFor } from "./events.js";
+import { withDocumentLock } from "./documentLock.js";
+import { createSSEConnection } from "./sse.js";
+import { makeBatchRef, rebaseRefs } from "./batchRef.js";
+import { markReplayed, wasReplayed } from "./replayed.js";
 import {
   discoverServices,
   discardService,
   serve,
   requestService,
-} from './services.js';
+  attachServiceRequest,
+  cancelServiceRequest,
+} from "./services.js";
 
 // Helper: normalize a document-read `layers` filter to the wire's
 // comma-separated form. Accepts an array of layer ids or a ready-made string;
 // anything empty becomes undefined so no `?layers=` is sent at all.
 function layersParam(layers) {
   if (layers === undefined || layers === null) return undefined;
-  const joined = Array.isArray(layers) ? layers.join(',') : String(layers);
+  const joined = Array.isArray(layers) ? layers.join(",") : String(layers);
   return joined.length > 0 ? joined : undefined;
 }
 
@@ -30,10 +52,14 @@ function layersParam(layers) {
 // becomes undefined so no `?op-types=` is sent at all.
 function opTypesParam(opTypes) {
   if (opTypes === undefined || opTypes === null) return undefined;
-  const joined = Array.isArray(opTypes) ? opTypes.join(',') : String(opTypes);
+  const joined = Array.isArray(opTypes) ? opTypes.join(",") : String(opTypes);
   return joined.length > 0 ? joined : undefined;
 }
 
+// The same for an audit `kinds` filter (`?kinds=`): operation kinds, such as
+// "review", in a list or a ready-made string.
+const kindsParam = opTypesParam;
+
 // Helper: build body object, filtering out undefined values
 function bodyOf(obj) {
   const result = {};
@@ -47,26 +73,220 @@ function bodyOf(obj) {
 // and redemption). Deliberately does not go through PlaidClient._request: these
 // are called before any client exists, which is the whole point.
 async function anonymousPost(baseUrl, path, body, options = {}) {
-  const base = baseUrl.replace(/\/$/, '');
+  const base = baseUrl.replace(/\/$/, "");
   const url = `${base}${path}`;
   try {
     const fetchOptions = {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
       body: JSON.stringify(body),
     };
-    const signal = timeoutSignal(options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS);
+    const signal = timeoutSignal(
+      options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS,
+    );
+    if (signal) fetchOptions.signal = signal;
+
+    const response = await fetch(url, fetchOptions);
+    if (!response.ok) {
+      throw makeHttpError(
+        response,
+        await parseErrorBody(response),
+        url,
+        "POST",
+      );
+    }
+    return transformResponse(await response.json());
+  } catch (error) {
+    if (error.status) throw error;
+    throw makeNetworkError(error, url, "POST");
+  }
+}
+
+/**
+ * GET a path with no authentication, for the two endpoints a client may need
+ * before it has a session: /health and /api/v1/info.
+ */
+async function anonymousGet(baseUrl, path, options = {}) {
+  const base = baseUrl.replace(/\/$/, "");
+  const url = `${base}${path}`;
+  try {
+    const fetchOptions = { method: "GET" };
+    const signal = timeoutSignal(
+      options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS,
+    );
     if (signal) fetchOptions.signal = signal;
 
     const response = await fetch(url, fetchOptions);
     if (!response.ok) {
-      throw makeHttpError(response, await parseErrorBody(response), url, 'POST');
+      throw makeHttpError(response, await parseErrorBody(response), url, "GET");
     }
     return transformResponse(await response.json());
   } catch (error) {
     if (error.status) throw error;
-    throw makeNetworkError(error, url, 'POST');
+    throw makeNetworkError(error, url, "GET");
+  }
+}
+
+/**
+ * The server's cap on operations per batch request (plaid.rest-api.v1.batch).
+ * A batch queued past it is submitted as consecutive requests.
+ */
+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),
+  // and the logical operation it joined (null for none), index for index with
+  // `operations`.
+  batch.stampedDocuments = [];
+  batch.stampedGroups = [];
+  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;
+  // A stand-in for the id op n will create, for a later op's body (see
+  // batchRef.js). The server fills it in inside the batch's transaction.
+  batch.ref = (opIndex = -1, index) => makeBatchRef(batch, opIndex, index);
+  batch.submit = () => submitBatch(batch);
+  batch.abort = () => {
+    batch.operations = [];
+    batch.stampedDocuments = [];
+    batch.stampedGroups = [];
+    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;
+  const groups = batch.stampedGroups;
+  batch.operations = [];
+  batch.stampedDocuments = [];
+  batch.stampedGroups = [];
+  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.
+  //
+  // Each request's results are marked replayed when that request was (see
+  // replayed.js), and the combined results when any request was: then some of
+  // the batch stored nothing new, which is what a caller reading the mark
+  // needs to know. The same holds for `committedResults`.
+  const results = [];
+  try {
+    await sendChunks(client, url, ops, stamps, results, groups);
+  } catch (error) {
+    if (error && typeof error === "object") {
+      error.committed = results.length;
+      error.committedResults = results;
+    }
+    throw error;
   }
+  return results;
+}
+
+/** The document-version an op's path claims, as a number, or null. */
+function claimedVersion(path) {
+  const v = new URLSearchParams(path.split("?")[1] ?? "").get("document-version");
+  return v == null ? null : Number(v);
+}
+
+async function sendChunks(client, url, ops, stamps, results, groups = []) {
+  // Every chunk's refs are checked before the first request goes, so a batch
+  // whose refs cannot resolve writes nothing.
+  const chunks = [];
+  for (let i = 0; i < ops.length; i += MAX_BATCH_OPS) {
+    chunks.push(
+      ops
+        .slice(i, i + MAX_BATCH_OPS)
+        .map((op) =>
+          i > 0 && op.refs ? { ...op, refs: rebaseRefs(op.refs, i) } : op,
+        ),
+    );
+  }
+  for (let c = 0; c < chunks.length; c++) {
+    const i = c * MAX_BATCH_OPS;
+    let chunk = chunks[c];
+    // One Idempotency-Key per request, minted as the request is formed, so a
+    // resend of this chunk is answered from its first send when that landed.
+    // Inside an operation opened with keys, a chunk whose ops joined it takes
+    // the operation's next key and claims the version its first run claimed.
+    const joins = groups
+      .slice(i, i + chunk.length)
+      .some((g) => g && g === client.operationGroup);
+    const { key, pin, record } = nextIdempotencyKey(client, joins);
+    const claim = (docId) =>
+      pin !== undefined ? pin : client.documentVersions[docId];
+    if (i > 0 || pin !== undefined) {
+      chunk = chunk.map((op, j) => {
+        const docId = stamps[i + j];
+        if (!docId) return op;
+        const path = restampDocumentVersion(op.path, claim(docId));
+        return { ...op, path };
+      });
+    }
+    // Pin what the chunk actually claims: the first stamped op's version as
+    // its path now carries it.
+    const j = stamps.slice(i, i + chunk.length).findIndex(Boolean);
+    record(j < 0 ? null : claimedVersion(chunk[j].path));
+    const answered = await client._postBatch(url, chunk, { key });
+    results.push(...answered);
+    if (wasReplayed(answered)) markReplayed(results);
+    // The server took the chunk, so each operation it joined exists.
+    for (let j = i; j < i + chunk.length; j++) {
+      if (groups[j]) groups[j].written = true;
+    }
+  }
+}
+
+/**
+ * End the key frame `frame` of `group`, wherever it is among the frames open:
+ * the frame under it, or the one open over it, numbers from then on. A plain
+ * function, so a caller that borrows withOperation onto another object
+ * (test doubles do) keeps it.
+ */
+function dropFrame(group, frame) {
+  if (!group || !frame || group.frames[0] === frame) return;
+  group.frames = group.frames.filter((f) => f !== frame);
+}
+
+/** 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 {
@@ -76,19 +296,41 @@ class PlaidClient {
    * @param {string} token - The authentication token
    * @param {object} [options] - Client options
    * @param {number} [options.timeout=30000] - Per-request timeout in ms (0 or null disables it)
+   * @param {number} [options.batchTimeout=180000] - Timeout for batch submissions in ms (0 or null disables it)
    */
   constructor(baseUrl, token, options = {}) {
-    this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.baseUrl = baseUrl.replace(/\/$/, "");
     this.token = token;
-    this.timeout = options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS;
-    this.isBatching = false;
-    this.batchOperations = [];
+    this.timeout =
+      options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS;
+    // Batch submissions get a longer budget than a single request. Aborting a
+    // batch does NOT stop the server: it keeps running the transaction and
+    // holding the single SQLite write lock, so a client that gives up early
+    // just adds a retry on top of a write that is still in progress. Falls
+    // back to an explicit `timeout` when one was given.
+    this.batchTimeout =
+      options.batchTimeout !== undefined
+        ? options.batchTimeout
+        : options.timeout !== undefined
+          ? options.timeout
+          : DEFAULT_BATCH_TIMEOUT_MS;
+    // Delays (ms) before sending a keyed write again when its answer was lost
+    // (no response, 502, 504). See the Idempotency-Key note in http.js.
+    this.retryDelaysMs = options.retryDelaysMs;
     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
+    // documentLock.js.
+    this.documentLockLost = null;
     // The open logical operation (audit-log group), or null. While set, every
     // write is stamped with `?group-id=` (+ `group-message`) so the audit log
     // folds them into ONE expandable entry. See beginOperation / withOperation.
-    // Shape: { id, message, depth, written, refined }.
+    // Shape: { id, message, depth, written, refined, frames }, where each of
+    // `frames` is { keys, count, minted, depth, owned } and the last numbers.
     this.operationGroup = null;
     // Optional callback fired once (per client) when any request returns HTTP
     // 401 — i.e. the token is missing/expired/invalid. Apps use it to discard
@@ -96,8 +338,27 @@ class PlaidClient {
     this.onAuthError = options.onAuthError || null;
     this._authErrorFired = false;
 
-    // --- API Bundles ---
+    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
+   * 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.
@@ -105,9 +366,10 @@ class PlaidClient {
        * @param {Array} tokens - The tokens to link
        * @param {any} [metadata] - Metadata for the link. Omit to leave unset; pass null to send JSON null.
        */
-      create: (vocabItem, tokens, metadata, auditMessage) =>
-        this._request('POST', '/api/v1/vocab-links', { auditMessage,
-          body: bodyOf({ 'vocab-item': vocabItem, tokens, metadata }),
+      create: (vocabItem, tokens, metadata, auditMessage, { id } = {}) =>
+        this._request("POST", "/api/v1/vocab-links", {
+          auditMessage,
+          body: bodyOf({ id, "vocab-item": vocabItem, tokens, metadata }),
         }),
       /**
        * Create multiple vocab links in a single operation. Entries may
@@ -117,80 +379,188 @@ class PlaidClient {
        * @returns {Promise<{ids: string[]}>} The created entity IDs, in input order. (bulkDelete resolves to no value.)
        */
       bulkCreate: (body, auditMessage) =>
-        this._request('POST', '/api/v1/vocab-links/bulk', { auditMessage, body }),
+        this._request("POST", "/api/v1/vocab-links/bulk", {
+          auditMessage,
+          body,
+        }),
       /**
        * Delete multiple vocab links in a single operation. Provide an array of IDs.
        * @param {string[]} body - The vocab link IDs to delete
        */
       bulkDelete: (body, auditMessage) =>
-        this._request('DELETE', '/api/v1/vocab-links/bulk', { auditMessage, body }),
+        this._request("DELETE", "/api/v1/vocab-links/bulk", {
+          auditMessage,
+          body,
+        }),
       /**
        * Replace all metadata for a vocab link. The entire metadata map is replaced - existing metadata keys not included in the request will be removed.
        * @param {string} id - The resource ID
        * @param {any} body - The request body
        */
       setMetadata: (id, body, auditMessage) =>
-        this._request('PUT', `/api/v1/vocab-links/${id}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        this._request("PUT", `/api/v1/vocab-links/${id}/metadata`, {
+          auditMessage,
+          rawBody: body,
         }),
       /**
        * Remove all metadata from a vocab link.
        * @param {string} id - The resource ID
        */
       deleteMetadata: (id, auditMessage) =>
-        this._request('DELETE', `/api/v1/vocab-links/${id}/metadata`, { auditMessage,
-          skipResponseTransform: true,
+        this._request("DELETE", `/api/v1/vocab-links/${id}/metadata`, {
+          auditMessage,
         }),
       /**
-       * 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,
+        this._request("PATCH", `/api/v1/vocab-links/${id}/metadata`, {
+          auditMessage,
+          rawBody: body,
         }),
       /**
        * 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
        */
       delete: (id, auditMessage) =>
-        this._request('DELETE', `/api/v1/vocab-links/${id}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/vocab-links/${id}`, { auditMessage }),
     };
 
     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 },
+        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
+       * @param {string[]|string} [kinds] - Only the entries of operations of
+       *   these kinds (e.g. `['review', 'guess-adoption']`), each whole
+       */
+      audit: (id, startTime, endTime, opTypes, itemId, kinds) =>
+        listAll(this, `/api/v1/vocab-layers/${id}/audit`, {
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+            "item-id": itemId,
+            kinds: kindsParam(kinds),
+          },
+        }),
+      /**
+       * 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, kinds, 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),
+            kinds: kindsParam(kinds),
+            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
        */
       delete: (id, auditMessage) =>
-        this._request('DELETE', `/api/v1/vocab-layers/${id}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/vocab-layers/${id}`, { auditMessage }),
       /**
        * Update a vocab layer's name.
        * @param {string} id - The resource ID
        * @param {string} name - The name
        */
       update: (id, name, auditMessage) =>
-        this._request('PATCH', `/api/v1/vocab-layers/${id}`, { auditMessage,
+        this._request("PATCH", `/api/v1/vocab-layers/${id}`, {
+          auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -199,56 +569,65 @@ class PlaidClient {
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`: the value read for this key (null or undefined when it
+       *   was absent). The write is then refused with a 409 when the stored value differs.
        */
-      setConfig: (id, namespace, configKey, configValue, auditMessage) =>
-        this._request('PUT', `/api/v1/vocab-layers/${id}/config/${namespace}/${configKey}`, { auditMessage,
-          rawBody: configValue, skipResponseTransform: true,
-        }),
+      setConfig: (id, namespace, configKey, configValue, auditMessage, options) =>
+        this._request(
+          "PUT",
+          `/api/v1/vocab-layers/${id}/config/${namespace}/${configKey}`,
+          configRequest(auditMessage, configValue, options),
+        ),
       /**
        * Remove a configuration value for a layer.
        * @param {string} id - The resource ID
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`, as on setConfig.
        */
-      deleteConfig: (id, namespace, configKey, auditMessage) =>
-        this._request('DELETE', `/api/v1/vocab-layers/${id}/config/${namespace}/${configKey}`, { auditMessage,
-          skipResponseTransform: true,
-        }),
+      deleteConfig: (id, namespace, configKey, auditMessage, options) =>
+        this._request(
+          "DELETE",
+          `/api/v1/vocab-layers/${id}/config/${namespace}/${configKey}`,
+          configRequest(auditMessage, undefined, options, true),
+        ),
       /**
        * List all vocab layers accessible to user. Transparently follows
        * pagination cursors and returns the full flat array.
-       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use listPage() for a single page in a batch.
-       * @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(this, '/api/v1/vocab-layers', { limit, cursor, query: { 'as-of': asOf } }),
+      listPage: ({ limit, cursor } = {}) =>
+        listPage(this, "/api/v1/vocab-layers", {
+          limit,
+          cursor,
+        }),
       /**
        * 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
-       * Cannot be used inside a batch (auto-paginates across requests); throws on first iteration if called while batching — use listPage() for a single page in a batch.
        * @returns {AsyncGenerator<Array>}
        */
-      iterPages: ({ pageSize, asOf } = {}) =>
-        iterPages(this, '/api/v1/vocab-layers', { pageSize, query: { 'as-of': asOf } }),
+      iterPages: ({ pageSize } = {}) =>
+        iterPages(this, "/api/v1/vocab-layers", {
+          pageSize,
+        }),
       /**
        * Create a new vocab layer. Note: this also registers the user as a maintainer.
        * @param {string} name - The name
        */
-      create: (name, auditMessage) =>
-        this._request('POST', '/api/v1/vocab-layers', { auditMessage,
-          body: bodyOf({ name }),
+      create: (name, auditMessage, { id } = {}) =>
+        this._request("POST", "/api/v1/vocab-layers", {
+          auditMessage,
+          body: bodyOf({ id, name }),
         }),
       /**
        * Assign a user as a maintainer for this vocab layer.
@@ -256,14 +635,22 @@ class PlaidClient {
        * @param {string} userId - The user ID
        */
       addMaintainer: (id, userId, auditMessage) =>
-        this._request('POST', `/api/v1/vocab-layers/${id}/maintainers/${userId}`, { auditMessage }),
+        this._request(
+          "POST",
+          `/api/v1/vocab-layers/${id}/maintainers/${userId}`,
+          { auditMessage },
+        ),
       /**
        * Remove a user's maintainer privileges for this vocab layer.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        */
       removeMaintainer: (id, userId, auditMessage) =>
-        this._request('DELETE', `/api/v1/vocab-layers/${id}/maintainers/${userId}`, { auditMessage }),
+        this._request(
+          "DELETE",
+          `/api/v1/vocab-layers/${id}/maintainers/${userId}`,
+          { auditMessage },
+        ),
     };
 
     this.relations = {
@@ -273,25 +660,27 @@ class PlaidClient {
        * @param {any} body - The request body
        */
       setMetadata: (relationId, body, auditMessage) =>
-        this._request('PUT', `/api/v1/relations/${relationId}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        this._request("PUT", `/api/v1/relations/${relationId}/metadata`, {
+          auditMessage,
+          rawBody: body,
         }),
       /**
        * Remove all metadata from a relation.
        * @param {string} relationId - The relation ID
        */
       deleteMetadata: (relationId, auditMessage) =>
-        this._request('DELETE', `/api/v1/relations/${relationId}/metadata`, { auditMessage,
-          skipResponseTransform: true,
+        this._request("DELETE", `/api/v1/relations/${relationId}/metadata`, {
+          auditMessage,
         }),
       /**
-       * 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,
+        this._request("PATCH", `/api/v1/relations/${relationId}/metadata`, {
+          auditMessage,
+          rawBody: body,
         }),
       /**
        * Update the target span of a relation.
@@ -299,31 +688,32 @@ class PlaidClient {
        * @param {string} spanId - The span ID
        */
       setTarget: (relationId, spanId, auditMessage) =>
-        this._request('PUT', `/api/v1/relations/${relationId}/target`, { auditMessage,
-          body: bodyOf({ 'span-id': spanId }),
+        this._request("PUT", `/api/v1/relations/${relationId}/target`, {
+          auditMessage,
+          body: bodyOf({ "span-id": spanId }),
         }),
       /**
        * 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
        */
       delete: (relationId, auditMessage) =>
-        this._request('DELETE', `/api/v1/relations/${relationId}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/relations/${relationId}`, {
+          auditMessage,
+        }),
       /**
        * Update a relation's value.
        * @param {string} relationId - The relation ID
        * @param {any} value - The value
        */
       update: (relationId, value, auditMessage) =>
-        this._request('PATCH', `/api/v1/relations/${relationId}`, { auditMessage,
+        this._request("PATCH", `/api/v1/relations/${relationId}`, {
+          auditMessage,
           body: bodyOf({ value }),
         }),
       /**
@@ -332,8 +722,9 @@ class PlaidClient {
        * @param {string} spanId - The span ID
        */
       setSource: (relationId, spanId, auditMessage) =>
-        this._request('PUT', `/api/v1/relations/${relationId}/source`, { auditMessage,
-          body: bodyOf({ 'span-id': spanId }),
+        this._request("PUT", `/api/v1/relations/${relationId}/source`, {
+          auditMessage,
+          body: bodyOf({ "span-id": spanId }),
         }),
       /**
        * Create a new relation. A relation is a directed edge between two spans
@@ -345,9 +736,25 @@ class PlaidClient {
        * @param {any} value - The value
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (layerId, sourceId, targetId, value, metadata, auditMessage) =>
-        this._request('POST', '/api/v1/relations', { auditMessage,
-          body: bodyOf({ 'layer-id': layerId, 'source-id': sourceId, 'target-id': targetId, value, metadata }),
+      create: (
+        layerId,
+        sourceId,
+        targetId,
+        value,
+        metadata,
+        auditMessage,
+        { id } = {},
+      ) =>
+        this._request("POST", "/api/v1/relations", {
+          auditMessage,
+          body: bodyOf({
+            id,
+            "layer-id": layerId,
+            "source-id": sourceId,
+            "target-id": targetId,
+            value,
+            metadata,
+          }),
         }),
       /**
        * Create multiple relations in a single operation.
@@ -355,13 +762,26 @@ class PlaidClient {
        * @returns {Promise<{ids: string[]}>} The created entity IDs, in input order. (bulkDelete resolves to no value.)
        */
       bulkCreate: (body, auditMessage) =>
-        this._request('POST', '/api/v1/relations/bulk', { auditMessage, body }),
+        this._request("POST", "/api/v1/relations/bulk", { auditMessage, body }),
       /**
        * Delete multiple relations in a single operation. Provide an array of IDs.
        * @param {Array} body - The request body
        */
       bulkDelete: (body, auditMessage) =>
-        this._request('DELETE', '/api/v1/relations/bulk', { auditMessage, body }),
+        this._request("DELETE", "/api/v1/relations/bulk", {
+          auditMessage,
+          body,
+        }),
+      /**
+       * 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 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) =>
+        this._request("PATCH", "/api/v1/relations/bulk", {
+          auditMessage,
+          body,
+        }),
     };
 
     this.spanLayers = {
@@ -371,43 +791,53 @@ class PlaidClient {
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`: the value read for this key (null or undefined when it
+       *   was absent). The write is then refused with a 409 when the stored value differs.
        */
-      setConfig: (spanLayerId, namespace, configKey, configValue, auditMessage) =>
-        this._request('PUT', `/api/v1/span-layers/${spanLayerId}/config/${namespace}/${configKey}`, { auditMessage,
-          rawBody: configValue, skipResponseTransform: true,
-        }),
+      setConfig: (spanLayerId, namespace, configKey, configValue, auditMessage, options) =>
+        this._request(
+          "PUT",
+          `/api/v1/span-layers/${spanLayerId}/config/${namespace}/${configKey}`,
+          configRequest(auditMessage, configValue, options),
+        ),
       /**
        * Remove a configuration value for a layer.
        * @param {string} spanLayerId - The span layer ID
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`, as on setConfig.
        */
-      deleteConfig: (spanLayerId, namespace, configKey, auditMessage) =>
-        this._request('DELETE', `/api/v1/span-layers/${spanLayerId}/config/${namespace}/${configKey}`, { auditMessage,
-          skipResponseTransform: true,
-        }),
+      deleteConfig: (spanLayerId, namespace, configKey, auditMessage, options) =>
+        this._request(
+          "DELETE",
+          `/api/v1/span-layers/${spanLayerId}/config/${namespace}/${configKey}`,
+          configRequest(auditMessage, undefined, options, true),
+        ),
+      ...constraintMethods(this, "span-layers"),
       /**
        * 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
        */
       delete: (spanLayerId, auditMessage) =>
-        this._request('DELETE', `/api/v1/span-layers/${spanLayerId}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/span-layers/${spanLayerId}`, {
+          auditMessage,
+        }),
       /**
        * Update a span layer's name.
        * @param {string} spanLayerId - The span layer ID
        * @param {string} name - The name
        */
       update: (spanLayerId, name, auditMessage) =>
-        this._request('PATCH', `/api/v1/span-layers/${spanLayerId}`, { auditMessage,
+        this._request("PATCH", `/api/v1/span-layers/${spanLayerId}`, {
+          auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -415,9 +845,10 @@ class PlaidClient {
        * @param {string} tokenLayerId - The token layer ID
        * @param {string} name - The name
        */
-      create: (tokenLayerId, name, auditMessage) =>
-        this._request('POST', '/api/v1/span-layers', { auditMessage,
-          body: bodyOf({ 'token-layer-id': tokenLayerId, name }),
+      create: (tokenLayerId, name, auditMessage, { id } = {}) =>
+        this._request("POST", "/api/v1/span-layers", {
+          auditMessage,
+          body: bodyOf({ id, "token-layer-id": tokenLayerId, name }),
         }),
       /**
        * Shift a span layer's display order.
@@ -425,7 +856,8 @@ class PlaidClient {
        * @param {string} direction - The direction ("up" or "down")
        */
       shift: (spanLayerId, direction, auditMessage) =>
-        this._request('POST', `/api/v1/span-layers/${spanLayerId}/shift`, { auditMessage,
+        this._request("POST", `/api/v1/span-layers/${spanLayerId}/shift`, {
+          auditMessage,
           body: bodyOf({ direction }),
         }),
     };
@@ -437,7 +869,8 @@ class PlaidClient {
        * @param {Array} tokens - The tokens
        */
       setTokens: (spanId, tokens, auditMessage) =>
-        this._request('PUT', `/api/v1/spans/${spanId}/tokens`, { auditMessage,
+        this._request("PUT", `/api/v1/spans/${spanId}/tokens`, {
+          auditMessage,
           body: bodyOf({ tokens }),
         }),
       /**
@@ -448,32 +881,37 @@ class PlaidClient {
        * @param {any} value - The value
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (spanLayerId, tokens, value, metadata, auditMessage) =>
-        this._request('POST', '/api/v1/spans', { auditMessage,
-          body: bodyOf({ 'span-layer-id': spanLayerId, tokens, value, metadata }),
+      create: (spanLayerId, tokens, value, metadata, auditMessage, { id } = {}) =>
+        this._request("POST", "/api/v1/spans", {
+          auditMessage,
+          body: bodyOf({
+            id,
+            "span-layer-id": spanLayerId,
+            tokens,
+            value,
+            metadata,
+          }),
         }),
       /**
        * 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
        */
       delete: (spanId, auditMessage) =>
-        this._request('DELETE', `/api/v1/spans/${spanId}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/spans/${spanId}`, { auditMessage }),
       /**
        * Update a span's value.
        * @param {string} spanId - The span ID
        * @param {any} value - The value
        */
       update: (spanId, value, auditMessage) =>
-        this._request('PATCH', `/api/v1/spans/${spanId}`, { auditMessage,
+        this._request("PATCH", `/api/v1/spans/${spanId}`, {
+          auditMessage,
           body: bodyOf({ value }),
         }),
       /**
@@ -482,51 +920,101 @@ class PlaidClient {
        * @returns {Promise<{ids: string[]}>} The created entity IDs, in input order. (bulkDelete resolves to no value.)
        */
       bulkCreate: (body, auditMessage) =>
-        this._request('POST', '/api/v1/spans/bulk', { auditMessage, body }),
+        this._request("POST", "/api/v1/spans/bulk", { auditMessage, body }),
       /**
        * Delete multiple spans in a single operation. Provide an array of IDs.
        * @param {Array} body - The request body
        */
       bulkDelete: (body, auditMessage) =>
-        this._request('DELETE', '/api/v1/spans/bulk', { auditMessage, body }),
+        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 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) =>
+        this._request("PATCH", "/api/v1/spans/bulk", {
+          auditMessage,
+          body,
+        }),
       /**
        * Replace all metadata for a span.
        * @param {string} spanId - The span ID
        * @param {any} body - The request body
        */
       setMetadata: (spanId, body, auditMessage) =>
-        this._request('PUT', `/api/v1/spans/${spanId}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        this._request("PUT", `/api/v1/spans/${spanId}/metadata`, {
+          auditMessage,
+          rawBody: body,
         }),
       /**
        * Remove all metadata from a span.
        * @param {string} spanId - The span ID
        */
       deleteMetadata: (spanId, auditMessage) =>
-        this._request('DELETE', `/api/v1/spans/${spanId}/metadata`, { auditMessage,
-          skipResponseTransform: true,
+        this._request("DELETE", `/api/v1/spans/${spanId}/metadata`, {
+          auditMessage,
         }),
       /**
-       * 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,
+        this._request("PATCH", `/api/v1/spans/${spanId}/metadata`, {
+          auditMessage,
+          rawBody: body,
         }),
     };
 
-    this.batch = {
+    // Server-level facts. Fetched at most once: the limits cannot change while
+    // the server is up, and a caller asking "will this file be accepted" should
+    // not pay a round trip to find out.
+    let infoPromise = null;
+    this.server = {
+      /**
+       * This server's version and the limits it enforces, e.g.
+       * `{ limits: { mediaFileBytes, jsonBodyBytes, batchOperations, … } }`.
+       * Sizes are in bytes. Unauthenticated.
+       */
+      info: () => {
+        if (!infoPromise) {
+          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;
+            throw err;
+          });
+        }
+        return infoPromise;
+      },
+      /** Just the limits, which is what a caller almost always wants. */
+      limits: async () => (await this.server.info()).limits,
       /**
-       * Execute multiple API operations atomically. If any operation fails, all
-       * changes are rolled back.
-       * @param {Array} body - The request body
+       * Liveness, version and database size. Unauthenticated, and served
+       * outside the REST router at /health, so it answers even while the API
+       * is refusing requests. Never cached — the point is that it is current.
+       * @returns {Promise<{ok: boolean, version: string, uptimeMs: number, audit: object}>}
        */
-      submit: (body, auditMessage) =>
-        this._request('POST', '/api/v1/batch', { auditMessage,
-          body, noBatch: true,
-        }),
+      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 = {
@@ -536,25 +1024,27 @@ class PlaidClient {
        * @param {any} body - The request body
        */
       setMetadata: (textId, body, auditMessage) =>
-        this._request('PUT', `/api/v1/texts/${textId}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        this._request("PUT", `/api/v1/texts/${textId}/metadata`, {
+          auditMessage,
+          rawBody: body,
         }),
       /**
        * Remove all metadata from a text.
        * @param {string} textId - The text ID
        */
       deleteMetadata: (textId, auditMessage) =>
-        this._request('DELETE', `/api/v1/texts/${textId}/metadata`, { auditMessage,
-          skipResponseTransform: true,
+        this._request("DELETE", `/api/v1/texts/${textId}/metadata`, {
+          auditMessage,
         }),
       /**
-       * 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,
+        this._request("PATCH", `/api/v1/texts/${textId}/metadata`, {
+          auditMessage,
+          rawBody: body,
         }),
       /**
        * Create a new text in a document's text layer. A text is a container for
@@ -564,35 +1054,84 @@ class PlaidClient {
        * @param {string} body - The request body
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (textLayerId, documentId, body, metadata, auditMessage) =>
-        this._request('POST', '/api/v1/texts', { auditMessage,
-          body: bodyOf({ 'text-layer-id': textLayerId, 'document-id': documentId, body, metadata }),
+      create: (
+        textLayerId,
+        documentId,
+        body,
+        metadata,
+        auditMessage,
+        { id } = {},
+      ) =>
+        this._request("POST", "/api/v1/texts", {
+          auditMessage,
+          body: bodyOf({
+            id,
+            "text-layer-id": textLayerId,
+            "document-id": documentId,
+            body,
+            metadata,
+          }),
         }),
       /**
        * 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
        */
       delete: (textId, auditMessage) =>
-        this._request('DELETE', `/api/v1/texts/${textId}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/texts/${textId}`, { auditMessage }),
       /**
        * Update a text's body. A diff is computed and token indices are updated
        * so that tokens remain intact. Alternatively, `body` can be a list of
-       * edit directives.
+       * edit directives (code-point indices, applied in order):
+       *   {type: 'delete', index, value: count}
+       *   {type: 'insert', index, value: string}
+       *   {type: 'replace', index, length, value: string} — unlike
+       *     delete+insert, a token covering the whole range is resized to keep
+       *     it (respell a word in place without losing its annotations).
+       * A list is applied exactly as sent. With `base` (the `digest` of the
+       * body the update was made on, as every read of a text gives it) the
+       * update applies only to that body, and is refused with 409 and
+       * `text-changed` otherwise. Strict mode then does not stamp it, unless
+       * `versioned` is true (a batch whose later writes are stamped needs its
+       * first write stamped too).
        * @param {string} textId - The text ID
        * @param {any} body - The request body
-       */
-      update: (textId, body, auditMessage) =>
-        this._request('PATCH', `/api/v1/texts/${textId}`, { auditMessage,
-          body: bodyOf({ body }),
+       * @param {string} [auditMessage]
+       * @param {{base?: string, versioned?: boolean}} [options]
+       */
+      update: (textId, body, auditMessage, { base, versioned } = {}) =>
+        this._request("PATCH", `/api/v1/texts/${textId}`, {
+          auditMessage,
+          body: bodyOf({ body, base }),
+          versioned: versioned ?? (base === undefined || base === null),
+        }),
+      /**
+       * Change a text's body by the edits made at the caret: a list of edit
+       * directives as `update` takes them (code-point indices, applied in
+       * order, each index in the body the ones before it left). Only their
+       * net change counts. An insert or a delete stays where it was made, and
+       * a stretch deleted and typed over is read as a whole new body is. The
+       * answer is the text with its new `digest` and `reshape` (the tokens
+       * moved, the spans and vocab links trimmed, the rows deleted). With
+       * `base`, the digest of the body the edits were made on, the edit
+       * applies only to that body and is refused with 409 and `text-changed`
+       * otherwise, and strict mode does not stamp it unless `versioned` is
+       * true. See composeTextEdits and gapsToOps.
+       * @param {string} textId - The text ID
+       * @param {Array<object>} edits - The edit directives
+       * @param {string} [auditMessage]
+       * @param {{base?: string, versioned?: boolean}} [options]
+       */
+      edit: (textId, edits, auditMessage, { base, versioned } = {}) =>
+        this._request("PATCH", `/api/v1/texts/${textId}`, {
+          auditMessage,
+          body: bodyOf({ edits, base }),
+          versioned: versioned ?? (base === undefined || base === null),
         }),
     };
 
@@ -600,76 +1139,112 @@ class PlaidClient {
       /**
        * List (or search) users. Transparently follows pagination cursors and
        * returns the full flat array. Admin-or-maintainer only.
-       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use listPage() for a single page in a batch.
        * @param {object} [opts]
-       * @param {string} [opts.q] - Filter to usernames containing this text (case-insensitive)
-       * @param {string} [opts.asOf] - Temporal query timestamp
+       * @param {string} [opts.q] - Filter to users whose display name or email contains this text (case-insensitive)
        */
-      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 usernames containing this text (case-insensitive)
+       * @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(this, '/api/v1/users', { limit, cursor, query: { q, 'as-of': asOf } }),
+      listPage: ({ q, limit, cursor } = {}) =>
+        listPage(this, "/api/v1/users", {
+          limit,
+          cursor,
+          query: { q },
+        }),
       /**
        * Async-iterate users page by page; yields each page's entries array.
        * @param {object} [opts]
-       * @param {string} [opts.q] - Filter to usernames containing this text (case-insensitive)
+       * @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
-       * Cannot be used inside a batch (auto-paginates across requests); throws on first iteration if called while batching — use listPage() for a single page in a batch.
        * @returns {AsyncGenerator<Array>}
        */
-      iterPages: ({ q, pageSize, asOf } = {}) =>
-        iterPages(this, '/api/v1/users', { pageSize, query: { q, 'as-of': asOf } }),
+      iterPages: ({ q, pageSize } = {}) =>
+        iterPages(this, "/api/v1/users", {
+          pageSize,
+          query: { q },
+        }),
       /**
-       * Create a new user
-       * @param {string} username - The username
+       * Create a new user.
+       * @param {string} email - The account's email address. It becomes the
+       *   user's id and is what they log in with; it can never be changed.
        * @param {string} password - The password
        * @param {boolean} isAdmin - Whether the user is an admin
+       * @param {string} [displayName] - How the user is shown in the UI.
+       *   Defaults to the local part of the email.
        */
-      create: (username, password, isAdmin, auditMessage) =>
-        this._request('POST', '/api/v1/users', { auditMessage,
-          body: bodyOf({ username, password, 'is-admin': isAdmin }),
+      create: (email, password, isAdmin, displayName, auditMessage) =>
+        this._request("POST", "/api/v1/users", {
+          auditMessage,
+          body: bodyOf({
+            email,
+            password,
+            "is-admin": isAdmin,
+            // 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,
+          }),
         }),
       /**
        * Get audit log for a user's actions. Transparently follows pagination
        * cursors and returns the full flat array.
-       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use listPage() for a single page in a batch.
        * @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.
+       * @param {string[]|string} [kinds] - Only the entries of operations of
+       *   these kinds (e.g. `['review', 'guess-adoption']`), each whole
        */
-      audit: (userId, startTime, endTime, asOf, opTypes) =>
+      audit: (userId, startTime, endTime, opTypes, kinds) =>
         listAll(this, `/api/v1/users/${userId}/audit`, {
           query: {
-            'start-time': startTime,
-            'end-time': endTime,
-            'as-of': asOf,
-            'op-types': opTypesParam(opTypes),
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
+          },
+        }),
+      /**
+       * 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)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      auditPage: (
+        userId,
+        { startTime, endTime, opTypes, kinds, order, limit, cursor } = {},
+      ) =>
+        listPage(this, `/api/v1/users/${userId}/audit`, {
+          limit,
+          cursor,
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
+            order,
           },
         }),
       /**
        * 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
@@ -679,7 +1254,7 @@ class PlaidClient {
        * @param {string} id - The resource ID
        */
       delete: (id, auditMessage) =>
-        this._request('DELETE', `/api/v1/users/${id}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/users/${id}`, { auditMessage }),
       /**
        * Reactivate a deactivated user, restoring their ability to log in.
        * Project memberships, vocab maintainerships, and API tokens removed
@@ -687,19 +1262,27 @@ class PlaidClient {
        * @param {string} id - The resource ID
        */
       activate: (id, auditMessage) =>
-        this._request('POST', `/api/v1/users/${id}/activate`, { auditMessage }),
+        this._request("POST", `/api/v1/users/${id}/activate`, { auditMessage }),
       /**
-       * Modify a user. Admins may change the username, password, and admin
-       * status of any user. All other users may only modify their own username
-       * or password.
-       * @param {string} id - The resource ID
+       * Modify a user. Admins may change the display name, password, and admin
+       * status of any user. All other users may only modify their own display
+       * name or password.
+       *
+       * A user's id is their email address and is fixed for the life of the
+       * account — it is what they log in with, so nothing can change it.
+       * @param {string} id - The resource ID (the user's email address)
        * @param {string} [password] - New password
-       * @param {string} [username] - New username
+       * @param {string} [displayName] - New display name
        * @param {boolean} [isAdmin] - New admin status
        */
-      update: (id, password, username, isAdmin, auditMessage) =>
-        this._request('PATCH', `/api/v1/users/${id}`, { auditMessage,
-          body: bodyOf({ password, username, 'is-admin': isAdmin }),
+      update: (id, password, displayName, isAdmin, auditMessage) =>
+        this._request("PATCH", `/api/v1/users/${id}`, {
+          auditMessage,
+          body: bodyOf({
+            password,
+            "display-name": displayName,
+            "is-admin": isAdmin,
+          }),
         }),
       /**
        * Build a URL for a user's profile picture, suitable for use directly as
@@ -719,7 +1302,7 @@ class PlaidClient {
       avatarUrl: (id, avatarHash) => {
         if (avatarHash === null) return null;
         const params = new URLSearchParams({ token: this.token });
-        if (avatarHash) params.set('v', avatarHash);
+        if (avatarHash) params.set("v", avatarHash);
         return `${this.baseUrl}/api/v1/users/${id}/avatar?${params}`;
       },
       /**
@@ -728,8 +1311,7 @@ class PlaidClient {
        * @param {string} id - The user ID
        */
       getAvatar: (id) =>
-        this._request('GET', `/api/v1/users/${id}/avatar`, {
-          noBatch: true,
+        this._request("GET", `/api/v1/users/${id}/avatar`, {
           binaryResponse: true,
         }),
       /**
@@ -742,19 +1324,137 @@ class PlaidClient {
        */
       setAvatar: (id, file, auditMessage) => {
         const fd = new FormData();
-        fd.append('file', file);
-        return this._request('PUT', `/api/v1/users/${id}/avatar`, { auditMessage,
-          body: fd, formData: true, noBatch: true,
+        fd.append("file", file);
+        return this._request("PUT", `/api/v1/users/${id}/avatar`, {
+          auditMessage,
+          body: fd,
+          formData: true,
+          noBatch: true,
         });
       },
       /**
        * Remove a profile picture. Your own, or anyone's if you are an admin.
        * @param {string} id - The user ID
        */
+      // No flag: the upload beside this one is multipart and cannot be
+      // batched, but a DELETE carries no blob, so the batch transport takes
+      // it. It is an ordinary audited write and queues like any other.
       deleteAvatar: (id, auditMessage) =>
-        this._request('DELETE', `/api/v1/users/${id}/avatar`, { auditMessage,
-          noBatch: true,
+        this._request("DELETE", `/api/v1/users/${id}/avatar`, {
+          auditMessage,
+        }),
+    };
+
+    this.userData = {
+      /**
+       * List a user's private data entries ({key, updatedAt}, plus value when
+       * includeValues), ordered by key. Owner or admin only. Transparently
+       * follows pagination cursors and returns the full flat array.
+       *
+       * Narrow with `prefix` (the literal head of a key) and/or `pattern`, a
+       * GLOB over the whole key (`*` any run, `?` one character) — the way to
+       * ask for a key convention identified by a segment in the middle, e.g.
+       * `igt:assistant:*:meta:*` for every conversation's sidebar entry across
+       * every project without dragging down the transcripts beside them.
+       *
+       * `pageSize` is exposed here, and defaults lower than elsewhere, because
+       * one value runs to 1 MB: a page of them with `includeValues` is the
+       * largest response this API can be asked for. Raise it when the listing
+       * is keys, or the values are known to be small.
+       * @param {string} userId
+       * @param {object} [opts]
+       * @param {string} [opts.prefix] - Only keys starting with this prefix
+       * @param {string} [opts.pattern] - Only keys matching this GLOB
+       * @param {boolean} [opts.includeValues] - Also return each entry's value
+       * @param {number} [opts.pageSize=100] - Entries per request (1..1000)
+       */
+      list: (userId, { prefix, pattern, includeValues, pageSize = 100 } = {}) =>
+        listAll(this, `/api/v1/users/${userId}/data`, {
+          pageSize,
+          query: { prefix, pattern, "include-values": includeValues },
+        }),
+      /**
+       * One page of a user's private data entries, ordered by key.
+       * @param {string} userId
+       * @param {object} [opts]
+       * @param {string} [opts.prefix] - Only keys starting with this prefix
+       * @param {string} [opts.pattern] - Only keys matching this GLOB
+       * @param {boolean} [opts.includeValues] - Also return each entry's value
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      listPage: (
+        userId,
+        { prefix, pattern, includeValues, limit, cursor } = {},
+      ) =>
+        listPage(this, `/api/v1/users/${userId}/data`, {
+          limit,
+          cursor,
+          query: { prefix, pattern, "include-values": includeValues },
+        }),
+      /**
+       * Async generator over a user's private data entries, one page at a time.
+       * @param {string} userId
+       * @param {object} [opts]
+       * @param {string} [opts.prefix] - Only keys starting with this prefix
+       * @param {string} [opts.pattern] - Only keys matching this GLOB
+       * @param {boolean} [opts.includeValues] - Also return each entry's value
+       * @param {number} [opts.pageSize=100] - Entries per request (1..1000)
+       */
+      iterPages: (
+        userId,
+        { prefix, pattern, includeValues, pageSize = 100 } = {},
+      ) =>
+        iterPages(this, `/api/v1/users/${userId}/data`, {
+          pageSize,
+          query: { prefix, pattern, "include-values": includeValues },
         }),
+      /**
+       * Read one private data entry ({key, updatedAt, value}); 404 if absent.
+       * @param {string} userId
+       * @param {string} key
+       */
+      get: (userId, key) =>
+        this._request(
+          "GET",
+          `/api/v1/users/${userId}/data/${encodeURIComponent(key)}`,
+        ),
+      /**
+       * Create or replace one private data entry. `value` is any JSON (up to
+       * 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
+       * value whose keys are camelCase round-trips unchanged while one keyed
+       * by arbitrary strings does not. Put such a map under a `metadata` key,
+       * which both clients pass through untouched.
+       * @param {string} userId
+       * @param {string} key
+       * @param {*} value
+       */
+      put: (userId, key, value) =>
+        this._request(
+          "PUT",
+          `/api/v1/users/${userId}/data/${encodeURIComponent(key)}`,
+          {
+            body: value,
+            noBatch: true,
+          },
+        ),
+      /**
+       * Delete one private data entry; 404 if absent.
+       * @param {string} userId
+       * @param {string} key
+       */
+      delete: (userId, key) =>
+        this._request(
+          "DELETE",
+          `/api/v1/users/${userId}/data/${encodeURIComponent(key)}`,
+          {
+            noBatch: true,
+          },
+        ),
     };
 
     this.apiTokens = {
@@ -762,11 +1462,9 @@ class PlaidClient {
        * List a user's named API tokens. Never includes the signed token
        * string itself — that is only returned once, by create().
        * Transparently follows pagination cursors and returns the full flat array.
-       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use listPage() for a single page in a batch.
        * @param {string} userId - The user ID who owns the tokens
        */
-      list: (userId) =>
-        listAll(this, `/api/v1/users/${userId}/tokens`),
+      list: (userId) => listAll(this, `/api/v1/users/${userId}/tokens`),
       /**
        * Fetch a single page of a user's named API tokens.
        * @param {string} userId - The user ID who owns the tokens
@@ -783,7 +1481,6 @@ class PlaidClient {
        * @param {string} userId - The user ID who owns the tokens
        * @param {object} [opts]
        * @param {number} [opts.pageSize] - Per-request page size
-       * Cannot be used inside a batch (auto-paginates across requests); throws on first iteration if called while batching — use listPage() for a single page in a batch.
        * @returns {AsyncGenerator<Array>}
        */
       iterPages: (userId, { pageSize } = {}) =>
@@ -793,12 +1490,15 @@ 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) =>
-        this._request('POST', `/api/v1/users/${userId}/tokens`, { auditMessage,
+        this._request("POST", `/api/v1/users/${userId}/tokens`, {
+          auditMessage,
           body: bodyOf({ name }),
+          // The answer is the secret, which the server never keeps.
+          noIdempotency: true,
         }),
       /**
        * Revoke a named API token (soft-revoke; idempotent).
@@ -806,7 +1506,9 @@ class PlaidClient {
        * @param {string} tokenId - The token ID to revoke
        */
       revoke: (userId, tokenId, auditMessage) =>
-        this._request('DELETE', `/api/v1/users/${userId}/tokens/${tokenId}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/users/${userId}/tokens/${tokenId}`, {
+          auditMessage,
+        }),
     };
 
     this.invites = {
@@ -816,32 +1518,42 @@ class PlaidClient {
        * maintainer or admin on it. Never includes invite codes — the code is
        * returned once, by create(), and is not recoverable afterward.
        * Transparently follows pagination cursors and returns the full flat array.
-       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use listPage() for a single page in a batch.
        * @param {object} [opts]
        * @param {string} [opts.projectId] - List this project's invites instead of your own
+       * @param {boolean} [opts.all] - List every invite on the server (admin only)
        */
-      list: ({ projectId } = {}) =>
-        listAll(this, '/api/v1/invites', { query: { 'project-id': projectId } }),
+      list: ({ projectId, all } = {}) =>
+        listAll(this, "/api/v1/invites", {
+          query: { "project-id": projectId, all },
+        }),
       /**
        * Fetch a single page of invites.
        * @param {object} [opts]
        * @param {string} [opts.projectId] - List this project's invites instead of your own
+       * @param {boolean} [opts.all] - List every invite on the server (admin only)
        * @param {number} [opts.limit] - Page size (1..1000; server default 100)
        * @param {string} [opts.cursor] - Opaque cursor from a previous page
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
-      listPage: ({ projectId, limit, cursor } = {}) =>
-        listPage(this, '/api/v1/invites', { limit, cursor, query: { 'project-id': projectId } }),
+      listPage: ({ projectId, all, limit, cursor } = {}) =>
+        listPage(this, "/api/v1/invites", {
+          limit,
+          cursor,
+          query: { "project-id": projectId, all },
+        }),
       /**
        * Async-iterate invites page by page; yields each page's entries array.
        * @param {object} [opts]
        * @param {string} [opts.projectId] - List this project's invites instead of your own
+       * @param {boolean} [opts.all] - List every invite on the server (admin only)
        * @param {number} [opts.pageSize] - Per-request page size
-       * Cannot be used inside a batch (auto-paginates across requests); throws on first iteration if called while batching — use listPage() for a single page in a batch.
        * @returns {AsyncGenerator<Array>}
        */
-      iterPages: ({ projectId, pageSize } = {}) =>
-        iterPages(this, '/api/v1/invites', { pageSize, query: { 'project-id': projectId } }),
+      iterPages: ({ projectId, all, pageSize } = {}) =>
+        iterPages(this, "/api/v1/invites", {
+          pageSize,
+          query: { "project-id": projectId, all },
+        }),
       /**
        * Mint an invite. The returned `code` is shown ONLY here — it is never
        * stored and cannot be recovered, so build and hand off the link now.
@@ -849,23 +1561,48 @@ class PlaidClient {
        *
        * Admins may mint anything. A project maintainer may mint role grants on
        * projects they maintain, and nothing else: no admin grant, no grantless
-       * invite, no password resets.
-       * @param {object} opts
-       * @param {string} [opts.projectId] - Project the redeemer joins (with projectRole)
-       * @param {string} [opts.projectRole] - "reader" | "writer" | "maintainer"
+       * invite, no password resets — so for a non-admin, projectId/projectRole
+       * are required in practice (403 without them).
+       *
+       * EVERY option is optional; `create()` with no arguments mints a
+       * single-use signup link granting nothing but an account. Two pairing
+       * rules the server enforces with a 400: projectId and projectRole must be
+       * given TOGETHER, and targetUserId may not be combined with projectId,
+       * grantAdmin, or a maxUses above 1.
+       * @param {object} [opts]
+       * @param {string} [opts.projectId] - Project the redeemer joins (requires projectRole)
+       * @param {string} [opts.projectRole] - "reader" | "writer" | "maintainer" (requires projectId)
        * @param {boolean} [opts.grantAdmin] - Make the new account a global admin (admin only)
-       * @param {string} [opts.targetUserId] - Make this a password reset for that user (admin only)
+       * @param {string} [opts.targetUserId] - Password reset for that user instead of a signup; admin only, single-use, grants nothing
        * @param {number} [opts.maxUses] - How many accounts this link may create (default 1)
        * @param {number} [opts.ttlDays] - Days until it expires (default 14, max 365)
        * @param {string} [opts.note] - Human label shown in your invite list
        * @returns {Promise<{id: string, code: string, kind: string, status: string}>}
        */
-      create: ({ projectId, projectRole, grantAdmin, targetUserId, maxUses, ttlDays, note } = {}, auditMessage) =>
-        this._request('POST', '/api/v1/invites', { auditMessage,
+      create: (
+        {
+          projectId,
+          projectRole,
+          grantAdmin,
+          targetUserId,
+          maxUses,
+          ttlDays,
+          note,
+        } = {},
+        auditMessage,
+      ) =>
+        this._request("POST", "/api/v1/invites", {
+          auditMessage,
+          // The answer is the code, which the server never keeps.
+          noIdempotency: true,
           body: bodyOf({
-            'project-id': projectId, 'project-role': projectRole,
-            'grant-admin': grantAdmin, 'target-user-id': targetUserId,
-            'max-uses': maxUses, 'ttl-days': ttlDays, note,
+            "project-id": projectId,
+            "project-role": projectRole,
+            "grant-admin": grantAdmin,
+            "target-user-id": targetUserId,
+            "max-uses": maxUses,
+            "ttl-days": ttlDays,
+            note,
           }),
         }),
       /**
@@ -874,129 +1611,482 @@ class PlaidClient {
        * @param {string} id - The invite ID
        */
       revoke: (id, auditMessage) =>
-        this._request('DELETE', `/api/v1/invites/${id}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/invites/${id}`, { auditMessage }),
     };
 
-    this.tokenLayers = {
+    this.admin = {
+      /**
+       * Everything about the server in one read: version and JVM uptime,
+       * database size and per-table row counts, media directory usage, backup
+       * configuration and the backups on disk, and the settings an operator
+       * gets asked to confirm. Carries no secrets. Runs a count per table and
+       * 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"),
+      /**
+       * Take a database backup right now, outside the nightly schedule.
+       * Resolves to the backup block with `ok` reporting whether the snapshot
+       * succeeded. Uses VACUUM INTO, which only reads, so it is safe while
+       * people are working. Admin only.
+       * @returns {Promise<{ok: boolean, directory: string, backups: Array}>}
+       *
+       * 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", { outOfBand: true }),
       /**
-       * Shift a token layer's display order.
-       * @param {string} tokenLayerId - The token layer ID
-       * @param {string} direction - The direction ("up" or "down")
+       * 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}>}>}
        */
-      shift: (tokenLayerId, direction, auditMessage) =>
-        this._request('POST', `/api/v1/token-layers/${tokenLayerId}/shift`, { auditMessage,
-          body: bodyOf({ direction }),
-        }),
+      locks: () => this._request("GET", "/api/v1/admin/locks"),
       /**
-       * Create a new token layer.
-       * @param {string} textLayerId - The text layer ID
-       * @param {string} name - The name
-       * @param {string} [overlapMode] - Per-layer, immutable token invariant: "any" (default), "non-overlapping", or "partitioning". On partitioning layers, single token create/update/delete are rejected; use bulkCreate plus split/merge/shift.
-       * @param {string} [parentTokenLayerId] - Optional immutable parent token layer. Tokens in this layer must nest within a parent-layer token; the parent layer must be in the same text layer and be "non-overlapping" or "partitioning" (an "any" parent is rejected). A nested layer may be "any" or "non-overlapping" but not "partitioning" (partitioning is only for root layers), e.g. words (non-overlapping, parent=sentences) within sentences (partitioning).
+       * Drop the lock on a document whoever holds it. Idempotent. For a client
+       * that went away without releasing one. Admin only.
+       * @param {string} documentId - The document ID
        */
-      create: (textLayerId, name, overlapMode, parentTokenLayerId, auditMessage) =>
-        this._request('POST', '/api/v1/token-layers', { auditMessage,
-          body: bodyOf({ 'text-layer-id': textLayerId, name, 'overlap-mode': overlapMode, 'parent-token-layer-id': parentTokenLayerId }),
+      releaseLock: (documentId) =>
+        this._request("DELETE", `/api/v1/admin/locks/${documentId}`, {
+          outOfBand: true,
         }),
       /**
-       * Set a configuration value for a layer in an editor namespace.
-       * @param {string} tokenLayerId - The token layer ID
-       * @param {string} namespace - The config namespace
-       * @param {string} configKey - The config key
-       * @param {any} configValue - Configuration value to set
+       * Live login and invite rate-limit buckets: the address, the account
+       * where there is one, failures inside the window, the limit, and whether
+       * it is currently blocking. Admin only.
+       * @returns {Promise<{windowMs: number, logins: Array, ips: Array, invites: Array}>}
        */
-      setConfig: (tokenLayerId, namespace, configKey, configValue, auditMessage) =>
-        this._request('PUT', `/api/v1/token-layers/${tokenLayerId}/config/${namespace}/${configKey}`, { auditMessage,
-          rawBody: configValue, skipResponseTransform: true,
-        }),
+      rateLimits: () => this._request("GET", "/api/v1/admin/rate-limits"),
       /**
-       * Remove a configuration value for a layer.
-       * @param {string} tokenLayerId - The token layer ID
-       * @param {string} namespace - The config namespace
-       * @param {string} configKey - The config key
+       * Forget recorded rate-limit failures. With `ip`, clears that address,
+       * narrowed to one account with `userId`. With neither, clears every
+       * bucket. Only ever unblocks. Admin only.
+       * @param {object} [opts]
+       * @param {string} [opts.ip] - Clear only this address
+       * @param {string} [opts.userId] - Narrow to one account on that address
        */
-      deleteConfig: (tokenLayerId, namespace, configKey, auditMessage) =>
-        this._request('DELETE', `/api/v1/token-layers/${tokenLayerId}/config/${namespace}/${configKey}`, { auditMessage,
-          skipResponseTransform: true,
+      clearRateLimits: ({ ip, userId } = {}) =>
+        this._request("DELETE", "/api/v1/admin/rate-limits", {
+          outOfBand: true,
+          queryParams: { ip, "user-id": userId },
         }),
       /**
-       * Get a token layer by ID.
-       * @param {string} tokenLayerId - The token layer ID
-       * @param {string} [asOf] - Temporal query timestamp
+       * What the server has logged, structured and filtered, from an in-memory
+       * buffer kept whether or not a log file is configured. `requests` is one
+       * entry per HTTP request (method, path, status, duration, and who made
+       * it), `events` is everything else, with a stack trace where there was
+       * one. They are buffered separately so a burst of requests cannot evict
+       * an error. Both come newest first, `matched` counts what passed the
+       * filters, and request `stats` describe the filtered set. Covers Plaid's
+       * own log stream since the last restart: for library messages and older
+       * history, see `logFile`. Admin only.
+       * @param {object} [opts]
+       * @param {number} [opts.limit] - Max entries per kind (default 200, max 2000)
+       * @param {string} [opts.q] - Substring of any field, case-insensitive
+       * @param {string} [opts.level] - Minimum level for events, e.g. "warn"
+       * @param {string} [opts.status] - "2xx".."5xx", an exact code, or "failures"
+       * @param {string} [opts.user] - Only requests made by this account
+       * @param {string} [opts.method] - Only requests with this HTTP method
+       * @returns {Promise<{requests: object, events: object, file: (string|null)}>}
+       */
+      logs: ({ limit, q, level, status, user, method } = {}) =>
+        this._request("GET", "/api/v1/admin/logs", {
+          queryParams: { limit, q, level, status, user, method },
+        }),
+      /**
+       * The tail of the configured log file, as text lines. The only place
+       * third-party library messages and anything from before the last restart
+       * can be read. Resolves with an `error` string instead of lines when no
+       * log file is configured or it does not exist yet. Admin only.
+       * @param {object} [opts]
+       * @param {number} [opts.lines] - How many lines (default 200, max 2000)
+       * @returns {Promise<{file: (string|null), lines: string[], error?: string}>}
        */
-      get: (tokenLayerId, asOf) =>
-        this._request('GET', `/api/v1/token-layers/${tokenLayerId}`, {
-          queryParams: { 'as-of': asOf },
+      logFile: ({ lines } = {}) =>
+        this._request("GET", "/api/v1/admin/logs/file", {
+          queryParams: { lines },
         }),
       /**
-       * Delete a token layer.
-       * @param {string} tokenLayerId - The token layer ID
+       * Private user-data entries across every account, each carrying its
+       * `userId`. `/users/:userId/data` has always been owner-or-admin; this
+       * is the same reach across accounts at once. Transparently follows
+       * pagination cursors and returns the full flat array. Admin only.
+       *
+       * Narrow with `prefix` (the literal head of a key) and/or `pattern`, a
+       * GLOB over the whole key (`*` any run, `?` one character) — the way to
+       * ask for a key convention identified by a segment in the middle, e.g.
+       * `igt:assistant:*:meta:*`. Values come only with `includeValues`, and
+       * are recased like any other body (see `userData.put`).
+       * @param {object} [opts]
+       * @param {string} [opts.prefix] - Only keys starting with this
+       * @param {string} [opts.pattern] - Only keys matching this GLOB
+       * @param {boolean} [opts.includeValues] - Also return each entry's value
+       * @returns {Promise<Array<{userId: string, key: string, updatedAt: string, value?: *}>>}
        */
-      delete: (tokenLayerId, auditMessage) =>
-        this._request('DELETE', `/api/v1/token-layers/${tokenLayerId}`, { auditMessage }),
+      userData: ({ prefix, pattern, includeValues } = {}) =>
+        listAll(this, "/api/v1/admin/user-data", {
+          query: {
+            prefix,
+            pattern,
+            "include-values": includeValues,
+          },
+        }),
       /**
-       * Update a token layer's name.
-       * @param {string} tokenLayerId - The token layer ID
-       * @param {string} name - The name
+       * One page of private user-data entries across accounts, ordered by
+       * (user, key). Admin only.
+       * @param {object} [opts]
+       * @param {string} [opts.prefix] - Only keys starting with this
+       * @param {string} [opts.pattern] - Only keys matching this GLOB
+       * @param {boolean} [opts.includeValues] - Also return each entry's value
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
-      update: (tokenLayerId, name, auditMessage) =>
-        this._request('PATCH', `/api/v1/token-layers/${tokenLayerId}`, { auditMessage,
-          body: bodyOf({ name }),
+      userDataPage: ({ prefix, pattern, includeValues, limit, cursor } = {}) =>
+        listPage(this, "/api/v1/admin/user-data", {
+          limit,
+          cursor,
+          query: {
+            prefix,
+            pattern,
+            "include-values": includeValues,
+          },
         }),
     };
 
-    this.documents = {
+    this.audit = {
       /**
-       * 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 },
+       * The audit log across every project, oldest first. Same fold, window
+       * and op-type filter as the per-project read, with the entity scope
+       * dropped. Admin only. Transparently follows pagination cursors and
+       * returns the full flat array.
+       * @param {object} [opts]
+       * @param {string} [opts.startTime] - Only operations at or after this instant
+       * @param {string} [opts.endTime] - Only operations at or before this instant
+       * @param {string[]|string} [opts.opTypes] - Only these op types (e.g.
+       *   `['span-layer/create']`). An entry appears when one of its operations
+       *   matches, carrying only the ones that did.
+       * @param {string[]|string} [opts.kinds] - Only the entries of operations
+       *   of these kinds (e.g. `['review']`), each whole
+       */
+      list: ({ startTime, endTime, opTypes, kinds } = {}) =>
+        listAll(this, "/api/v1/audit", {
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
+          },
         }),
       /**
-       * Acquire or refresh a document lock
-       * @param {string} documentId - The document ID
+       * Fetch a single page of the instance-wide audit log. Admin only.
+       * @param {object} [opts]
+       * @param {"asc"|"desc"} [opts.order] - "desc" pages newest-first, which
+       *   is what a feed wants. A cursor belongs to the direction that made it.
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
-      acquireLock: (documentId, auditMessage) =>
-        this._request('POST', `/api/v1/documents/${documentId}/lock`, { auditMessage }),
+      listPage: ({ startTime, endTime, opTypes, kinds, order, limit, cursor } = {}) =>
+        listPage(this, "/api/v1/audit", {
+          limit,
+          cursor,
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
+            order,
+          },
+        }),
       /**
-       * Release a document lock
-       * @param {string} documentId - The document ID
+       * Async-iterate the instance-wide audit log page by page. Admin only.
+       * @returns {AsyncGenerator<Array>}
+       */
+      iterPages: ({ startTime, endTime, opTypes, kinds, pageSize } = {}) =>
+        iterPages(this, "/api/v1/audit", {
+          pageSize,
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
+          },
+        }),
+      /**
+       * Per-user activity counts. `changes` is the number of logical actions,
+       * folded the way the audit feed folds them, so one "Confirm word
+       * analysis" counts once however many rows it wrote; `operations` is the
+       * unfolded row count. Only users who did something appear — subtract
+       * from the roster you already hold to find the ones who did not.
+       *
+       * With `projectId`, scoped to that project and open to its maintainers.
+       * Without one, instance-wide and admin only.
+       * @param {object} [opts]
+       * @param {string} [opts.projectId] - Scope to one project
+       * @param {string} [opts.startTime] - Only count at or after this instant
+       * @param {string} [opts.endTime] - Only count at or before this instant
+       * @param {boolean} [opts.daily] - Also return `byDay`, a list of
+       *   `{date, changes}` per user, oldest first, at the cost of a second
+       *   grouped scan
+       * @returns {Promise<Array<{user: object, operations: number, changes: number, documents: number, firstTs: string, lastTs: string, byDay?: object}>>}
+       */
+      tally: async ({ projectId, startTime, endTime, daily } = {}) => {
+        const path = projectId
+          ? `/api/v1/projects/${projectId}/audit/tally`
+          : "/api/v1/audit/tally";
+        const result = await this._request("GET", path, {
+          queryParams: {
+            "start-time": startTime,
+            "end-time": endTime,
+            daily,
+          },
+        });
+        return result.entries;
+      },
+    };
+
+    this.tokenLayers = {
+      /**
+       * Shift a token layer's display order.
+       * @param {string} tokenLayerId - The token layer ID
+       * @param {string} direction - The direction ("up" or "down")
+       */
+      shift: (tokenLayerId, direction, auditMessage) =>
+        this._request("POST", `/api/v1/token-layers/${tokenLayerId}/shift`, {
+          auditMessage,
+          body: bodyOf({ direction }),
+        }),
+      /**
+       * Create a new token layer.
+       * @param {string} textLayerId - The text layer ID
+       * @param {string} name - The name
+       * @param {string} [overlapMode] - Per-layer, immutable token invariant: "any" (default), "non-overlapping", or "partitioning". On partitioning layers, single token create/update/delete are rejected; use bulkCreate plus split/merge/shift.
+       * @param {string} [parentTokenLayerId] - Optional immutable parent token layer. Tokens in this layer must nest within a parent-layer token; the parent layer must be in the same text layer and be "non-overlapping" or "partitioning" (an "any" parent is rejected). A nested layer may be "any" or "non-overlapping" but not "partitioning" (partitioning is only for root layers), e.g. words (non-overlapping, parent=sentences) within sentences (partitioning).
+       */
+      create: (
+        textLayerId,
+        name,
+        overlapMode,
+        parentTokenLayerId,
+        auditMessage,
+        { id } = {},
+      ) =>
+        this._request("POST", "/api/v1/token-layers", {
+          auditMessage,
+          body: bodyOf({
+            id,
+            "text-layer-id": textLayerId,
+            name,
+            "overlap-mode": overlapMode,
+            "parent-token-layer-id": parentTokenLayerId,
+          }),
+        }),
+      /**
+       * Set a configuration value for a layer in an editor namespace.
+       * @param {string} tokenLayerId - The token layer ID
+       * @param {string} namespace - The config namespace
+       * @param {string} configKey - The config key
+       * @param {any} configValue - Configuration value to set
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`: the value read for this key (null or undefined when it
+       *   was absent). The write is then refused with a 409 when the stored value differs.
+       */
+      setConfig: (tokenLayerId, namespace, configKey, configValue, auditMessage, options) =>
+        this._request(
+          "PUT",
+          `/api/v1/token-layers/${tokenLayerId}/config/${namespace}/${configKey}`,
+          configRequest(auditMessage, configValue, options),
+        ),
+      /**
+       * Remove a configuration value for a layer.
+       * @param {string} tokenLayerId - The token layer ID
+       * @param {string} namespace - The config namespace
+       * @param {string} configKey - The config key
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`, as on setConfig.
+       */
+      deleteConfig: (tokenLayerId, namespace, configKey, auditMessage, options) =>
+        this._request(
+          "DELETE",
+          `/api/v1/token-layers/${tokenLayerId}/config/${namespace}/${configKey}`,
+          configRequest(auditMessage, undefined, options, true),
+        ),
+      ...constraintMethods(this, "token-layers"),
+      /**
+       * Get a token layer by ID.
+       * @param {string} tokenLayerId - The token layer ID
+       */
+      get: (tokenLayerId) =>
+        this._request("GET", `/api/v1/token-layers/${tokenLayerId}`),
+      /**
+       * Delete a token layer.
+       * @param {string} tokenLayerId - The token layer ID
+       */
+      delete: (tokenLayerId, auditMessage) =>
+        this._request("DELETE", `/api/v1/token-layers/${tokenLayerId}`, {
+          auditMessage,
+        }),
+      /**
+       * Update a token layer's name.
+       * @param {string} tokenLayerId - The token layer ID
+       * @param {string} name - The name
+       */
+      update: (tokenLayerId, name, auditMessage) =>
+        this._request("PATCH", `/api/v1/token-layers/${tokenLayerId}`, {
+          auditMessage,
+          body: bodyOf({ name }),
+        }),
+    };
+
+    this.documents = {
+      /**
+       * Check the lock status of a document.
+       * @param {string} documentId - The document ID
        */
-      releaseLock: (documentId, auditMessage) =>
-        this._request('DELETE', `/api/v1/documents/${documentId}/lock`, { auditMessage }),
+      checkLock: (documentId) =>
+        this._request("GET", `/api/v1/documents/${documentId}/lock`),
       /**
-       * Get media file for a document
+       * 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.
+       *
+       * `newLockId` names the holder from the client's side (a fresh UUID). An
+       * acquire whose answer never arrived can then be sent again, which
+       * answers 200 while that holder has the lock, or released. Without it
+       * the server mints the id, and a lost answer leaves a lock nobody can
+       * release until it expires.
+       *
+       * 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
-       * @param {string} [asOf] - Temporal query timestamp
+       * @param {string} [auditMessage]
+       * @param {string} [newLockId] - A holder id this client minted
+       */
+      acquireLock: (documentId, auditMessage, newLockId) =>
+        this._request("POST", `/api/v1/documents/${documentId}/lock`, {
+          ...(newLockId !== undefined && newLockId !== null
+            ? { queryParams: { "new-lock-id": newLockId } }
+            : {}),
+          auditMessage,
+          outOfBand: true,
+        }),
+      /**
+       * 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
        */
-      getMedia: (documentId, asOf) =>
-        this._request('GET', `/api/v1/documents/${documentId}/media`, {
-          queryParams: { 'as-of': asOf },
-          noBatch: true,
+      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, lockId, auditMessage) =>
+        this._request("DELETE", `/api/v1/documents/${documentId}/lock`, {
+          queryParams: { "lock-id": lockId },
+          auditMessage,
+          outOfBand: true,
+        }),
+      /**
+       * Hold this document's server-enforced lock for the length of `fn`,
+       * releasing it on the way out (including on error). Resolves to what
+       * `fn` returned.
+       *
+       *   await client.documents.locked(docId, async () => {
+       *     // delete + recreate tokens
+       *   });
+       *
+       * Wrap any multi-step, server-side mutation of a document that must not
+       * interleave with a human editor or another service, e.g. a parser or
+       * 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 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
+       * only for its first minute. If a renewal fails the lock is gone: every
+       * later write from this client throws `DocumentLockLost`, and a block
+       * that got to the end anyway ends with that error rather than reporting
+       * success. `fn` receives a lock handle and may read `lock.lost` (or call
+       * `lock.raiseIfLost()`) to give up sooner.
+       *
+       * 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.
+       * The block mints its holder id and sends it with the acquire, so an
+       * acquire whose answer was lost is sent again (up to three tries) and,
+       * if none is answered, released rather than left to expire. 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)
+       */
+      locked: (documentId, fn, options) =>
+        withDocumentLock(this, documentId, fn, options),
+      /**
+       * Get the media file for a document. Media is not versioned, so there is
+       * no as-of form: the route refuses the parameter. Prefer the document's
+       * own `mediaUrl`, which carries the file's version for caching.
+       * @param {string} documentId - The document ID
+       */
+      getMedia: (documentId) =>
+        this._request("GET", `/api/v1/documents/${documentId}/media`, {
           binaryResponse: true,
         }),
       /**
        * Upload a media file for a document. Uses Apache Tika for content validation.
        * @param {string} documentId - The document ID
        * @param {File} file - The file to upload
+       * @param {string} [auditMessage] - Custom audit-log message for this write
+       * @param {object} [options] - `{ onProgress }`: called with `{ loaded, total }` (bytes) as the file goes up. In a browser the upload then travels by XMLHttpRequest, and the request timeout only fires when the upload stalls, not on total time.
        */
-      uploadMedia: (documentId, file, auditMessage) => {
+      uploadMedia: (documentId, file, auditMessage, { onProgress } = {}) => {
         const fd = new FormData();
-        fd.append('file', file);
-        return this._request('PUT', `/api/v1/documents/${documentId}/media`, { auditMessage,
-          body: fd, formData: true, noBatch: true,
+        fd.append("file", file);
+        return this._request("PUT", `/api/v1/documents/${documentId}/media`, {
+          auditMessage,
+          body: fd,
+          formData: true,
+          noBatch: true,
+          onUploadProgress: onProgress,
         });
       },
       /**
        * Delete media file for a document
        * @param {string} documentId - The document ID
        */
+      // 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.
       deleteMedia: (documentId, auditMessage) =>
-        this._request('DELETE', `/api/v1/documents/${documentId}/media`, { auditMessage,
-          noBatch: true,
+        this._request("DELETE", `/api/v1/documents/${documentId}/media`, {
+          auditMessage,
         }),
       /**
        * Replace all metadata for a document.
@@ -1004,48 +2094,98 @@ class PlaidClient {
        * @param {any} body - The request body
        */
       setMetadata: (documentId, body, auditMessage) =>
-        this._request('PUT', `/api/v1/documents/${documentId}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        this._request("PUT", `/api/v1/documents/${documentId}/metadata`, {
+          auditMessage,
+          rawBody: body,
         }),
       /**
        * Remove all metadata from a document.
        * @param {string} documentId - The document ID
        */
       deleteMetadata: (documentId, auditMessage) =>
-        this._request('DELETE', `/api/v1/documents/${documentId}/metadata`, { auditMessage,
-          skipResponseTransform: true,
+        this._request("DELETE", `/api/v1/documents/${documentId}/metadata`, {
+          auditMessage,
         }),
       /**
-       * 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,
+        this._request("PATCH", `/api/v1/documents/${documentId}/metadata`, {
+          auditMessage,
+          rawBody: body,
         }),
       /**
        * Get audit log for a document. Transparently follows pagination cursors
        * and returns the full flat array.
-       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use listPage() for a single page in a batch.
        * @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.
+       * @param {string[]|string} [kinds] - Only the entries of operations of
+       *   these kinds (e.g. `['review', 'guess-adoption']`), each whole
        */
-      audit: (documentId, startTime, endTime, asOf, opTypes) =>
+      audit: (documentId, startTime, endTime, opTypes, kinds) =>
         listAll(this, `/api/v1/documents/${documentId}/audit`, {
           query: {
-            'start-time': startTime,
-            'end-time': endTime,
-            'as-of': asOf,
-            'op-types': opTypesParam(opTypes),
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
           },
         }),
+      /**
+       * 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)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      auditPage: (
+        documentId,
+        { startTime, endTime, opTypes, kinds, order, limit, cursor } = {},
+      ) =>
+        listPage(this, `/api/v1/documents/${documentId}/audit`, {
+          limit,
+          cursor,
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
+            order,
+          },
+        }),
+      /**
+       * Restore a document to its state at an earlier time, as one
+       * operation: what was deleted since then comes back under its original
+       * id, what was added since is removed, and what changed is set back,
+       * across every layer. A layer deleted since then, or a vocabulary entry
+       * that no longer exists, is skipped and reported under `skipped`.
+       * Resolves to a summary of the changes. Maintainers only.
+       * @param {string} documentId - The document 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
+       */
+      restore: (documentId, asOf, { dryRun } = {}, auditMessage) =>
+        this._request("POST", `/api/v1/documents/${documentId}/restore`, {
+          queryParams: {
+            "as-of": asOf,
+            "dry-run": dryRun ? "true" : undefined,
+          },
+          auditMessage,
+        }),
       /**
        * Get a document. Set `includeBody` to true to include all data.
        *
@@ -1062,10 +2202,10 @@ class PlaidClient {
        * @param {string[]|string} [layers] - Layer ids to restrict a body read to
        */
       get: (documentId, includeBody, asOf, layers) =>
-        this._request('GET', `/api/v1/documents/${documentId}`, {
+        this._request("GET", `/api/v1/documents/${documentId}`, {
           queryParams: {
-            'include-body': includeBody,
-            'as-of': asOf,
+            "include-body": includeBody,
+            "as-of": asOf,
             layers: layersParam(layers),
           },
         }),
@@ -1074,14 +2214,17 @@ class PlaidClient {
        * @param {string} documentId - The document ID
        */
       delete: (documentId, auditMessage) =>
-        this._request('DELETE', `/api/v1/documents/${documentId}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/documents/${documentId}`, {
+          auditMessage,
+        }),
       /**
        * Update a document's name.
        * @param {string} documentId - The document ID
        * @param {string} name - The name
        */
       update: (documentId, name, auditMessage) =>
-        this._request('PATCH', `/api/v1/documents/${documentId}`, { auditMessage,
+        this._request("PATCH", `/api/v1/documents/${documentId}`, {
+          auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -1090,9 +2233,29 @@ class PlaidClient {
        * @param {string} name - The name
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (projectId, name, metadata, auditMessage) =>
-        this._request('POST', '/api/v1/documents', { auditMessage,
-          body: bodyOf({ 'project-id': projectId, name, metadata }),
+      create: (projectId, name, metadata, auditMessage, { id } = {}) =>
+        this._request("POST", "/api/v1/documents", {
+          auditMessage,
+          body: bodyOf({ id, "project-id": projectId, name, metadata }),
+        }),
+      /**
+       * Copy a document and everything in it into a new document of the same
+       * project, as one operation. The copy shares the source's layers and
+       * the vocabulary entries its links name, and holds the source's texts,
+       * tokens, spans, relations and vocab links under fresh ids, with their
+       * metadata. Comments do not travel. The media file does, unless
+       * `includeMedia` is false. Resolves to `{ id }`, plus `mediaError` when
+       * the source had media the copy could not take with it.
+       * @param {string} documentId - The document to copy
+       * @param {string} name - The new document's name
+       * @param {object} [options] - `{ includeMedia }`: false leaves the media
+       *   file behind
+       * @param {string} [auditMessage] - Custom audit message for this operation
+       */
+      copy: (documentId, name, { includeMedia, id } = {}, auditMessage) =>
+        this._request("POST", `/api/v1/documents/${documentId}/copy`, {
+          auditMessage,
+          body: bodyOf({ id, name, "include-media": includeMedia }),
         }),
     };
 
@@ -1103,120 +2266,182 @@ class PlaidClient {
        * @param {string} userId - The user ID
        */
       addWriter: (id, userId, auditMessage) =>
-        this._request('POST', `/api/v1/projects/${id}/writers/${userId}`, { auditMessage }),
+        this._request("POST", `/api/v1/projects/${id}/writers/${userId}`, {
+          auditMessage,
+        }),
       /**
        * Remove a user's writer privileges for this project.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        */
       removeWriter: (id, userId, auditMessage) =>
-        this._request('DELETE', `/api/v1/projects/${id}/writers/${userId}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/projects/${id}/writers/${userId}`, {
+          auditMessage,
+        }),
       /**
        * Set a user's access level to read-only for this project.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        */
       addReader: (id, userId, auditMessage) =>
-        this._request('POST', `/api/v1/projects/${id}/readers/${userId}`, { auditMessage }),
+        this._request("POST", `/api/v1/projects/${id}/readers/${userId}`, {
+          auditMessage,
+        }),
       /**
        * Remove a user's reader privileges for this project.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        */
       removeReader: (id, userId, auditMessage) =>
-        this._request('DELETE', `/api/v1/projects/${id}/readers/${userId}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/projects/${id}/readers/${userId}`, {
+          auditMessage,
+        }),
       /**
        * Set a configuration value for a project in an editor namespace.
        * @param {string} id - The resource ID
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`: the value read for this key (null or undefined when it
+       *   was absent). The write is then refused with a 409 when the stored value differs.
        */
-      setConfig: (id, namespace, configKey, configValue, auditMessage) =>
-        this._request('PUT', `/api/v1/projects/${id}/config/${namespace}/${configKey}`, { auditMessage,
-          rawBody: configValue, skipResponseTransform: true,
-        }),
+      setConfig: (id, namespace, configKey, configValue, auditMessage, options) =>
+        this._request(
+          "PUT",
+          `/api/v1/projects/${id}/config/${namespace}/${configKey}`,
+          configRequest(auditMessage, configValue, options),
+        ),
       /**
        * Remove a configuration value for a project.
        * @param {string} id - The resource ID
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`, as on setConfig.
        */
-      deleteConfig: (id, namespace, configKey, auditMessage) =>
-        this._request('DELETE', `/api/v1/projects/${id}/config/${namespace}/${configKey}`, { auditMessage,
-          skipResponseTransform: true,
-        }),
+      deleteConfig: (id, namespace, configKey, auditMessage, options) =>
+        this._request(
+          "DELETE",
+          `/api/v1/projects/${id}/config/${namespace}/${configKey}`,
+          configRequest(auditMessage, undefined, options, true),
+        ),
       /**
        * Assign a user as a maintainer for this project.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        */
       addMaintainer: (id, userId, auditMessage) =>
-        this._request('POST', `/api/v1/projects/${id}/maintainers/${userId}`, { auditMessage }),
+        this._request("POST", `/api/v1/projects/${id}/maintainers/${userId}`, {
+          auditMessage,
+        }),
       /**
        * Remove a user's maintainer privileges for this project.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        */
       removeMaintainer: (id, userId, auditMessage) =>
-        this._request('DELETE', `/api/v1/projects/${id}/maintainers/${userId}`, { auditMessage }),
+        this._request(
+          "DELETE",
+          `/api/v1/projects/${id}/maintainers/${userId}`,
+          { auditMessage },
+        ),
       /**
        * Get audit log for a project. Transparently follows pagination cursors
        * and returns the full flat array.
-       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use listPage() for a single page in a batch.
        * @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.
+       * @param {string[]|string} [kinds] - Only the entries of operations of
+       *   these kinds (e.g. `['review', 'guess-adoption']`), each whole
        */
-      audit: (projectId, startTime, endTime, asOf, opTypes) =>
+      audit: (projectId, startTime, endTime, opTypes, kinds) =>
         listAll(this, `/api/v1/projects/${projectId}/audit`, {
           query: {
-            'start-time': startTime,
-            'end-time': endTime,
-            'as-of': asOf,
-            'op-types': opTypesParam(opTypes),
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
+          },
+        }),
+      /**
+       * 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)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      auditPage: (
+        projectId,
+        { startTime, endTime, opTypes, kinds, order, limit, cursor } = {},
+      ) =>
+        listPage(this, `/api/v1/projects/${projectId}/audit`, {
+          limit,
+          cursor,
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
+            order,
           },
         }),
+      /**
+       * When the calling user last wrote to each document in a project, as a
+       * `{documentId: timestamp}` map. Documents they have never written to
+       * are absent. One request covers a whole document list.
+       *
+       * The response is NOT key-transformed: its keys are document ids, and
+       * camelCasing would mangle the hyphens in a UUID.
+       * @param {string} projectId - The project ID
+       * @returns {Promise<Object<string, string>>}
+       */
+      myLastEdits: (projectId) =>
+        this._request("GET", `/api/v1/projects/${projectId}/audit/last-edits`, {
+          skipResponseTransform: true,
+        }),
       /**
        * Link a vocabulary to a project.
        * @param {string} id - The resource ID
        * @param {string} vocabId - The vocab layer ID
        */
       linkVocab: (id, vocabId, auditMessage) =>
-        this._request('POST', `/api/v1/projects/${id}/vocabs/${vocabId}`, { auditMessage }),
+        this._request("POST", `/api/v1/projects/${id}/vocabs/${vocabId}`, {
+          auditMessage,
+        }),
       /**
        * Unlink a vocabulary from a project.
        * @param {string} id - The resource ID
        * @param {string} vocabId - The vocab layer ID
        */
       unlinkVocab: (id, vocabId, auditMessage) =>
-        this._request('DELETE', `/api/v1/projects/${id}/vocabs/${vocabId}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/projects/${id}/vocabs/${vocabId}`, {
+          auditMessage,
+        }),
       /**
        * 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.
-       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use listPage() for a single page in a batch.
        *
        * Note: this endpoint does not support temporal (`as-of`) queries; the
        * server rejects `?as-of=` on the documents-list route with a 400.
        * @param {string} id - The project ID
        */
-      listDocuments: (id) =>
-        listAll(this, `/api/v1/projects/${id}/documents`),
+      listDocuments: (id) => listAll(this, `/api/v1/projects/${id}/documents`),
       /**
        * Fetch a single page of a project's documents.
        *
@@ -1239,68 +2464,69 @@ class PlaidClient {
        * @param {string} id - The project ID
        * @param {object} [opts]
        * @param {number} [opts.pageSize] - Per-request page size
-       * Cannot be used inside a batch (auto-paginates across requests); throws on first iteration if called while batching — use listPage() for a single page in a batch.
        * @returns {AsyncGenerator<Array>}
        */
       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 } = {}) =>
-        this._request('DELETE', `/api/v1/projects/${id}`, { auditMessage, timeout }),
+      delete: (id, auditMessage, { timeout } = {}) =>
+        this._request("DELETE", `/api/v1/projects/${id}`, {
+          auditMessage,
+          timeout,
+        }),
       /**
        * Update a project's name.
        * @param {string} id - The resource ID
        * @param {string} name - The name
        */
       update: (id, name, auditMessage) =>
-        this._request('PATCH', `/api/v1/projects/${id}`, { auditMessage,
+        this._request("PATCH", `/api/v1/projects/${id}`, {
+          auditMessage,
           body: bodyOf({ name }),
         }),
       /**
        * List all projects accessible to user. Transparently follows pagination
        * cursors and returns the full flat array.
-       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use listPage() for a single page in a batch.
-       * @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(this, '/api/v1/projects', { limit, cursor, query: { 'as-of': asOf } }),
+      listPage: ({ limit, cursor } = {}) =>
+        listPage(this, "/api/v1/projects", {
+          limit,
+          cursor,
+        }),
       /**
        * 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
-       * Cannot be used inside a batch (auto-paginates across requests); throws on first iteration if called while batching — use listPage() for a single page in a batch.
        * @returns {AsyncGenerator<Array>}
        */
-      iterPages: ({ pageSize, asOf } = {}) =>
-        iterPages(this, '/api/v1/projects', { pageSize, query: { 'as-of': asOf } }),
+      iterPages: ({ pageSize } = {}) =>
+        iterPages(this, "/api/v1/projects", {
+          pageSize,
+        }),
       /**
        * Create a new project. Note: this also registers the user as a maintainer.
        * @param {string} name - The name
        */
-      create: (name, auditMessage) =>
-        this._request('POST', '/api/v1/projects', { auditMessage,
-          body: bodyOf({ name }),
+      create: (name, auditMessage, { id } = {}) =>
+        this._request("POST", "/api/v1/projects", {
+          auditMessage,
+          body: bodyOf({ id, name }),
         }),
     };
 
@@ -1311,43 +2537,52 @@ class PlaidClient {
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`: the value read for this key (null or undefined when it
+       *   was absent). The write is then refused with a 409 when the stored value differs.
        */
-      setConfig: (textLayerId, namespace, configKey, configValue, auditMessage) =>
-        this._request('PUT', `/api/v1/text-layers/${textLayerId}/config/${namespace}/${configKey}`, { auditMessage,
-          rawBody: configValue, skipResponseTransform: true,
-        }),
+      setConfig: (textLayerId, namespace, configKey, configValue, auditMessage, options) =>
+        this._request(
+          "PUT",
+          `/api/v1/text-layers/${textLayerId}/config/${namespace}/${configKey}`,
+          configRequest(auditMessage, configValue, options),
+        ),
       /**
        * Remove a configuration value for a layer.
        * @param {string} textLayerId - The text layer ID
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`, as on setConfig.
        */
-      deleteConfig: (textLayerId, namespace, configKey, auditMessage) =>
-        this._request('DELETE', `/api/v1/text-layers/${textLayerId}/config/${namespace}/${configKey}`, { auditMessage,
-          skipResponseTransform: true,
-        }),
+      deleteConfig: (textLayerId, namespace, configKey, auditMessage, options) =>
+        this._request(
+          "DELETE",
+          `/api/v1/text-layers/${textLayerId}/config/${namespace}/${configKey}`,
+          configRequest(auditMessage, undefined, options, true),
+        ),
       /**
        * 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
        */
       delete: (textLayerId, auditMessage) =>
-        this._request('DELETE', `/api/v1/text-layers/${textLayerId}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/text-layers/${textLayerId}`, {
+          auditMessage,
+        }),
       /**
        * Update a text layer's name.
        * @param {string} textLayerId - The text layer ID
        * @param {string} name - The name
        */
       update: (textLayerId, name, auditMessage) =>
-        this._request('PATCH', `/api/v1/text-layers/${textLayerId}`, { auditMessage,
+        this._request("PATCH", `/api/v1/text-layers/${textLayerId}`, {
+          auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -1356,7 +2591,8 @@ class PlaidClient {
        * @param {string} direction - The direction ("up" or "down")
        */
       shift: (textLayerId, direction, auditMessage) =>
-        this._request('POST', `/api/v1/text-layers/${textLayerId}/shift`, { auditMessage,
+        this._request("POST", `/api/v1/text-layers/${textLayerId}/shift`, {
+          auditMessage,
           body: bodyOf({ direction }),
         }),
       /**
@@ -1364,9 +2600,10 @@ class PlaidClient {
        * @param {string} projectId - The project ID
        * @param {string} name - The name
        */
-      create: (projectId, name, auditMessage) =>
-        this._request('POST', '/api/v1/text-layers', { auditMessage,
-          body: bodyOf({ 'project-id': projectId, name }),
+      create: (projectId, name, auditMessage, { id } = {}) =>
+        this._request("POST", "/api/v1/text-layers", {
+          auditMessage,
+          body: bodyOf({ id, "project-id": projectId, name }),
         }),
     };
 
@@ -1377,25 +2614,27 @@ class PlaidClient {
        * @param {any} body - The request body
        */
       setMetadata: (id, body, auditMessage) =>
-        this._request('PUT', `/api/v1/vocab-items/${id}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        this._request("PUT", `/api/v1/vocab-items/${id}/metadata`, {
+          auditMessage,
+          rawBody: body,
         }),
       /**
        * Remove all metadata from a vocab item.
        * @param {string} id - The resource ID
        */
       deleteMetadata: (id, auditMessage) =>
-        this._request('DELETE', `/api/v1/vocab-items/${id}/metadata`, { auditMessage,
-          skipResponseTransform: true,
+        this._request("DELETE", `/api/v1/vocab-items/${id}/metadata`, {
+          auditMessage,
         }),
       /**
-       * 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,
+        this._request("PATCH", `/api/v1/vocab-items/${id}/metadata`, {
+          auditMessage,
+          rawBody: body,
         }),
       /**
        * Create a new vocab item
@@ -1403,9 +2642,10 @@ class PlaidClient {
        * @param {string} form - The vocab item form
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (vocabLayerId, form, metadata, auditMessage) =>
-        this._request('POST', '/api/v1/vocab-items', { auditMessage,
-          body: bodyOf({ 'vocab-layer-id': vocabLayerId, form, metadata }),
+      create: (vocabLayerId, form, metadata, auditMessage, { id } = {}) =>
+        this._request("POST", "/api/v1/vocab-items", {
+          auditMessage,
+          body: bodyOf({ id, "vocab-layer-id": vocabLayerId, form, metadata }),
         }),
       /**
        * Create multiple vocab items in a single operation. Entries may target
@@ -1413,36 +2653,85 @@ class PlaidClient {
        * @param {Array<{vocabLayerId: string, form: string, metadata?: any}>} body - The vocab items to create
        */
       bulkCreate: (body, auditMessage) =>
-        this._request('POST', '/api/v1/vocab-items/bulk', { auditMessage, body }),
+        this._request("POST", "/api/v1/vocab-items/bulk", {
+          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) =>
-        this._request('DELETE', '/api/v1/vocab-items/bulk', { auditMessage, body }),
+        this._request("DELETE", "/api/v1/vocab-items/bulk", {
+          auditMessage,
+          body,
+        }),
       /**
        * 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
+       * 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 }),
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expectedLinkCount?: number}} [options] - `expectedLinkCount`: the
+       *   number of links the caller showed. The delete is refused with a 409 when
+       *   the entry has any other number of links by then.
+       */
+      delete: (id, auditMessage, { expectedLinkCount } = {}) =>
+        this._request("DELETE", `/api/v1/vocab-items/${id}`, {
+          auditMessage,
+          queryParams: { "expected-link-count": expectedLinkCount },
+        }),
+      /**
+       * Merge entries into this one, in one operation. Every link to a loser
+       * moves to the survivor (keeping its id and metadata), except a link on
+       * words the survivor is already linked to, which is deleted, and then the
+       * losers are deleted. Links are read when the merge runs, so one made
+       * after the caller looked moves too. Every loser must be in the
+       * survivor's vocabulary, and a loser that is already gone is skipped, so
+       * a repeated merge changes nothing. References to a loser in other
+       * entries' metadata are the caller's to rewrite, in the same batch.
+       * Needs maintainer rights on the vocabulary.
+       * @param {string} survivorId - The entry that stays
+       * @param {string[]} loserIds - The entries merged into it
+       * @returns {Promise<{moved: number, duplicates: number, removed: string[]}>}
+       */
+      merge: (survivorId, loserIds, auditMessage) =>
+        this._request("POST", `/api/v1/vocab-items/${survivorId}/merge`, {
+          auditMessage,
+          body: { losers: loserIds },
+        }),
       /**
-       * 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
        */
       update: (id, form, auditMessage) =>
-        this._request('PATCH', `/api/v1/vocab-items/${id}`, { auditMessage,
+        this._request("PATCH", `/api/v1/vocab-items/${id}`, {
+          auditMessage,
           body: bodyOf({ form }),
         }),
     };
@@ -1454,17 +2743,20 @@ class PlaidClient {
        * @param {string} direction - The direction ("up" or "down")
        */
       shift: (relationLayerId, direction, auditMessage) =>
-        this._request('POST', `/api/v1/relation-layers/${relationLayerId}/shift`, { auditMessage,
-          body: bodyOf({ direction }),
-        }),
+        this._request(
+          "POST",
+          `/api/v1/relation-layers/${relationLayerId}/shift`,
+          { auditMessage, body: bodyOf({ direction }) },
+        ),
       /**
        * Create a new relation layer.
        * @param {string} spanLayerId - The span layer ID
        * @param {string} name - The name
        */
-      create: (spanLayerId, name, auditMessage) =>
-        this._request('POST', '/api/v1/relation-layers', { auditMessage,
-          body: bodyOf({ 'span-layer-id': spanLayerId, name }),
+      create: (spanLayerId, name, auditMessage, { id } = {}) =>
+        this._request("POST", "/api/v1/relation-layers", {
+          auditMessage,
+          body: bodyOf({ id, "span-layer-id": spanLayerId, name }),
         }),
       /**
        * Set a configuration value for a layer in an editor namespace.
@@ -1472,43 +2764,53 @@ class PlaidClient {
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`: the value read for this key (null or undefined when it
+       *   was absent). The write is then refused with a 409 when the stored value differs.
        */
-      setConfig: (relationLayerId, namespace, configKey, configValue, auditMessage) =>
-        this._request('PUT', `/api/v1/relation-layers/${relationLayerId}/config/${namespace}/${configKey}`, { auditMessage,
-          rawBody: configValue, skipResponseTransform: true,
-        }),
+      setConfig: (relationLayerId, namespace, configKey, configValue, auditMessage, options) =>
+        this._request(
+          "PUT",
+          `/api/v1/relation-layers/${relationLayerId}/config/${namespace}/${configKey}`,
+          configRequest(auditMessage, configValue, options),
+        ),
       /**
        * Remove a configuration value for a layer.
        * @param {string} relationLayerId - The relation layer ID
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`, as on setConfig.
        */
-      deleteConfig: (relationLayerId, namespace, configKey, auditMessage) =>
-        this._request('DELETE', `/api/v1/relation-layers/${relationLayerId}/config/${namespace}/${configKey}`, { auditMessage,
-          skipResponseTransform: true,
-        }),
+      deleteConfig: (relationLayerId, namespace, configKey, auditMessage, options) =>
+        this._request(
+          "DELETE",
+          `/api/v1/relation-layers/${relationLayerId}/config/${namespace}/${configKey}`,
+          configRequest(auditMessage, undefined, options, true),
+        ),
+      ...constraintMethods(this, "relation-layers"),
       /**
        * 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
        */
       delete: (relationLayerId, auditMessage) =>
-        this._request('DELETE', `/api/v1/relation-layers/${relationLayerId}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/relation-layers/${relationLayerId}`, {
+          auditMessage,
+        }),
       /**
        * Update a relation layer's name.
        * @param {string} relationLayerId - The relation layer ID
        * @param {string} name - The name
        */
       update: (relationLayerId, name, auditMessage) =>
-        this._request('PATCH', `/api/v1/relation-layers/${relationLayerId}`, { auditMessage,
+        this._request("PATCH", `/api/v1/relation-layers/${relationLayerId}`, {
+          auditMessage,
           body: bodyOf({ name }),
         }),
     };
@@ -1532,26 +2834,41 @@ class PlaidClient {
        * @param {number} [precedence] - Ordering precedence
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (tokenLayerId, text, begin, end, precedence, metadata, auditMessage) =>
-        this._request('POST', '/api/v1/tokens', { auditMessage,
-          body: bodyOf({ 'token-layer-id': tokenLayerId, text, begin, end, precedence, metadata }),
+      create: (
+        tokenLayerId,
+        text,
+        begin,
+        end,
+        precedence,
+        metadata,
+        auditMessage,
+        { id } = {},
+      ) =>
+        this._request("POST", "/api/v1/tokens", {
+          auditMessage,
+          body: bodyOf({
+            id,
+            "token-layer-id": tokenLayerId,
+            text,
+            begin,
+            end,
+            precedence,
+            metadata,
+          }),
         }),
       /**
        * 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.
        * @param {string} tokenId - The token ID
        */
       delete: (tokenId, auditMessage) =>
-        this._request('DELETE', `/api/v1/tokens/${tokenId}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/tokens/${tokenId}`, { auditMessage }),
       /**
        * Update a token.
        * @param {string} tokenId - The token ID
@@ -1563,7 +2880,8 @@ class PlaidClient {
        *   drops undefined, so the three cases map correctly to the server.
        */
       update: (tokenId, begin, end, precedence, auditMessage) =>
-        this._request('PATCH', `/api/v1/tokens/${tokenId}`, { auditMessage,
+        this._request("PATCH", `/api/v1/tokens/${tokenId}`, {
+          auditMessage,
           body: bodyOf({ begin, end, precedence }),
         }),
       /**
@@ -1572,22 +2890,43 @@ class PlaidClient {
        * @returns {Promise<{ids: string[]}>} The created entity IDs, in input order. (bulkDelete resolves to no value.)
        */
       bulkCreate: (body, auditMessage) =>
-        this._request('POST', '/api/v1/tokens/bulk', { auditMessage, body }),
+        this._request("POST", "/api/v1/tokens/bulk", { auditMessage, body }),
       /**
        * Delete multiple tokens in a single operation. Provide an array of IDs.
        * @param {Array} body - The request body
        */
       bulkDelete: (body, auditMessage) =>
-        this._request('DELETE', '/api/v1/tokens/bulk', { auditMessage, body }),
+        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 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) =>
+        this._request("PATCH", "/api/v1/tokens/bulk", {
+          auditMessage,
+          body,
+        }),
       /**
        * Split a token at a Unicode code-point offset. The original token becomes the
        * left half (keeps its ID, spans, vocab-links); the new right token's ID is returned.
        * @param {string} tokenId - The token ID
        * @param {number} position - Code-point offset to split at (strictly between begin and end)
-       */
-      split: (tokenId, position, auditMessage) =>
-        this._request('POST', `/api/v1/tokens/${tokenId}/split`, { auditMessage,
-          body: bodyOf({ position }),
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{id?: string}} [options] - `id`: the right half's id, a UUIDv7 this
+       *   client minted. A relation layer whose relations must stay inside one token
+       *   of this layer declares a same-ancestor constraint, and the server deletes
+       *   the relations the split leaves crossing in the same transaction.
+       */
+      split: (
+        tokenId,
+        position,
+        auditMessage,
+        { id } = {},
+      ) =>
+        this._request("POST", `/api/v1/tokens/${tokenId}/split`, {
+          auditMessage,
+          body: bodyOf({ id, position }),
         }),
       /**
        * Merge two tokens. The left token (smaller begin) survives with the combined
@@ -1598,8 +2937,9 @@ class PlaidClient {
        * @param {string} otherTokenId - The other token to merge in
        */
       merge: (tokenId, otherTokenId, auditMessage) =>
-        this._request('POST', `/api/v1/tokens/${tokenId}/merge`, { auditMessage,
-          body: bodyOf({ 'other-token-id': otherTokenId }),
+        this._request("POST", `/api/v1/tokens/${tokenId}/merge`, {
+          auditMessage,
+          body: bodyOf({ "other-token-id": otherTokenId }),
         }),
       /**
        * Shift a token's boundary. On partitioning layers the adjacent token is
@@ -1610,7 +2950,8 @@ class PlaidClient {
        * @param {number} [end] - New end offset, exclusive (Unicode code points)
        */
       shift: (tokenId, begin, end, auditMessage) =>
-        this._request('POST', `/api/v1/tokens/${tokenId}/shift`, { auditMessage,
+        this._request("POST", `/api/v1/tokens/${tokenId}/shift`, {
+          auditMessage,
           body: bodyOf({ begin, end }),
         }),
       /**
@@ -1619,25 +2960,27 @@ class PlaidClient {
        * @param {any} body - The request body
        */
       setMetadata: (tokenId, body, auditMessage) =>
-        this._request('PUT', `/api/v1/tokens/${tokenId}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        this._request("PUT", `/api/v1/tokens/${tokenId}/metadata`, {
+          auditMessage,
+          rawBody: body,
         }),
       /**
        * Remove all metadata from a token.
        * @param {string} tokenId - The token ID
        */
       deleteMetadata: (tokenId, auditMessage) =>
-        this._request('DELETE', `/api/v1/tokens/${tokenId}/metadata`, { auditMessage,
-          skipResponseTransform: true,
+        this._request("DELETE", `/api/v1/tokens/${tokenId}/metadata`, {
+          auditMessage,
         }),
       /**
-       * 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,
+        this._request("PATCH", `/api/v1/tokens/${tokenId}/metadata`, {
+          auditMessage,
+          rawBody: body,
         }),
     };
 
@@ -1661,12 +3004,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) =>
-        this._request('POST', `/api/v1/projects/${projectId}/message`, { auditMessage,
+      sendMessage: (projectId, data) =>
+        this._request("POST", `/api/v1/projects/${projectId}/message`, {
+          noOperation: true,
           rawBody: { body: data },
         }),
 
@@ -1677,8 +3025,7 @@ class PlaidClient {
        * @param {string} projectId - The UUID of the project to query
        * @returns {Promise<Array>} Array of discovered service information
        */
-      discoverServices: (projectId) =>
-        discoverServices(this, projectId),
+      discoverServices: (projectId) => discoverServices(this, projectId),
 
       /**
        * Forget a previously-seen (offline) service. Maintainer-only; 409 if
@@ -1692,26 +3039,102 @@ class PlaidClient {
 
       /**
        * Register as a service and handle incoming work requests.
+       *
+       * The registration reopens its channel whenever it drops, so a server
+       * restart needs no service restart.
        * @param {string} projectId - The UUID of the project to serve
        * @param {Object} serviceInfo - Service information {serviceId, serviceName, description}
        * @param {function} onServiceRequest - Callback (data, responseHelper)
        * @param {Object} [extras] - Optional additional service metadata
-       * @returns {Object} Service registration object with .stop() method
-       */
-      serve: (projectId, serviceInfo, onServiceRequest, extras) =>
-        serve(this, projectId, serviceInfo, onServiceRequest, extras),
+       * @param {function} [onStatus] - Optional callback (event, projectId, detail) for
+       *   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) =>
+        serve(this, projectId, serviceInfo, onServiceRequest, extras, onStatus),
 
       /**
        * Request a service to perform work and await its result.
+       *
+       * The request outlives this call: after a timeout, an abort, or a
+       * dropped connection the service goes on, and `attachServiceRequest`
+       * collects the result given the request id, which `opts.onAccepted`
+       * receives as soon as the server has taken the request. Pass
+       * `opts.requestId` (a UUID you mint) to know the id before submitting;
+       * submitting an id that names a request you already made rejoins it
+       * instead of starting another.
        * @param {string} projectId - The UUID of the project
        * @param {string} serviceId - The ID of the service to request
        * @param {any} data - The request data
-       * @param {number} [timeout] - Timeout in milliseconds (default: 10000)
+       * @param {number} [timeout=10000] - Timeout in ms
        * @param {function} [onProgress] - Called with each progress payload {percent, message}
-       * @returns {Promise<any>} Service response
+       * @param {AbortSignal} [signal] - Abort to stop waiting; rejects with an AbortError
+       * @param {Object} [opts] - {requestId, onAccepted, projectIds, noOperation}
+       * @returns {Promise<any>} The service's result
+       */
+      requestService: (
+        projectId,
+        serviceId,
+        data,
+        timeout,
+        onProgress,
+        signal,
+        opts,
+      ) =>
+        requestService(
+          this,
+          projectId,
+          serviceId,
+          data,
+          timeout,
+          onProgress,
+          signal,
+          opts,
+        ),
+
+      /**
+       * Rejoin a service request made earlier and await its result: the
+       * latest progress is replayed, then the result comes, or at once if the
+       * request already finished. Only the user who submitted it (or an
+       * admin). Rejects with an error whose `status` is 404 when the request
+       * is unknown or expired (a finished request's result is kept for a
+       * while, not forever).
+       * @param {string} projectId - The UUID of the project
+       * @param {string} requestId - The request id
+       * @param {number} [timeout=10000] - Timeout in ms
+       * @param {function} [onProgress] - Called with each progress payload
+       * @param {AbortSignal} [signal] - Abort to stop waiting
+       * @returns {Promise<any>} The service's result
+       */
+      attachServiceRequest: (
+        projectId,
+        requestId,
+        timeout,
+        onProgress,
+        signal,
+      ) =>
+        attachServiceRequest(
+          this,
+          projectId,
+          requestId,
+          timeout,
+          onProgress,
+          signal,
+        ),
+
+      /**
+       * Ask the service to stop a request made earlier. The request still
+       * ends with whatever the service then reports, on the stream of whoever
+       * is awaiting it. Rejects with 404 if unknown or expired, 409 once
+       * finished.
+       * @param {string} projectId - The UUID of the project
+       * @param {string} requestId - The request id
+       * @returns {Promise<void>}
        */
-      requestService: (projectId, serviceId, data, timeout, onProgress) =>
-        requestService(this, projectId, serviceId, data, timeout, onProgress),
+      cancelServiceRequest: (projectId, requestId) =>
+        cancelServiceRequest(this, projectId, requestId),
     };
 
     /**
@@ -1746,11 +3169,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).
      */
-    this.query = (body, auditMessage) =>
-      this._request('POST', '/api/v1/query', { auditMessage, body });
+    // 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=`
@@ -1760,15 +3187,406 @@ 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}`),
+      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
        * @param {string|null} message - The new label
        */
       update: (id, message) =>
-        this._request('PATCH', `/api/v1/operation-groups/${id}`, { body: { message } }),
+        this._request("PATCH", `/api/v1/operation-groups/${id}`, {
+          body: { message },
+        }),
+    };
+
+    this.comments = {
+      /**
+       * Post a comment on an entity. Requires write access to the entity's
+       * project, or to the vocabulary for a vocab-item; the author is the
+       * authenticated caller. Comments are not audited and do not bump the
+       * document version.
+       *
+       * A comment outlives its anchor: deleting the entity does not delete
+       * the comment. `anchorLabel` is the caption shown once that happens
+       * ("Gloss of ktab, sentence 4"), so pass what the comment is about.
+       * @param {'document'|'text'|'token'|'span'|'relation'|'vocab-item'} entityType - What kind of thing is being commented on
+       * @param {string} entityId - The commented entity's id
+       * @param {string} body - The comment text (1..10000 characters)
+       * @param {object} [opts]
+       * @param {string} [opts.anchorLabel] - What the comment is about, in words (at most 200 characters)
+       */
+      create: (entityType, entityId, body, { anchorLabel, id } = {}) =>
+        this._request("POST", "/api/v1/comments", {
+          // A comment is not audited, so it never joins an open operation,
+          // and never takes a number from an edit's Idempotency-Key seed.
+          noOperation: true,
+          body: bodyOf({
+            id,
+            "entity-type": entityType,
+            "entity-id": entityId,
+            body,
+            "anchor-label": anchorLabel,
+          }),
+        }),
+      /**
+       * Read one comment.
+       * @param {string} id - The comment id
+       */
+      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.
+       * @param {string} id - The comment id
+       * @param {string} body - The replacement text
+       */
+      update: (id, body) =>
+        this._request("PATCH", `/api/v1/comments/${id}`, {
+          body: { body },
+          noOperation: true,
+        }),
+      /**
+       * Delete a comment. The author may delete their own; a project
+       * maintainer (or admin) may delete any.
+       * @param {string} id - The comment id
+       */
+      delete: (id) =>
+        this._request("DELETE", `/api/v1/comments/${id}`, { noOperation: true }),
+      /**
+       * List comments in a project, oldest first. Transparently follows
+       * pagination cursors and returns the full flat array.
+       * @param {string} projectId - The project to read
+       * @param {object} [filters] - Narrow the scope
+       * @param {string} [filters.documentId] - Every comment anywhere in one document
+       * @param {string} [filters.entityType] - With entityId, one entity's thread
+       * @param {string} [filters.entityId] - With entityType, one entity's thread
+       */
+      list: (projectId, { documentId, entityType, entityId } = {}) =>
+        listAll(this, `/api/v1/projects/${projectId}/comments`, {
+          query: {
+            "document-id": documentId,
+            "entity-type": entityType,
+            "entity-id": entityId,
+          },
+        }),
+      /**
+       * Fetch a single page of a project's comments.
+       * @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} [opts.documentId] - Every comment anywhere in one document
+       * @param {string} [opts.entityType] - With entityId, one entity's thread
+       * @param {string} [opts.entityId] - With entityType, one entity's thread
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      listPage: (
+        projectId,
+        { limit, cursor, documentId, entityType, entityId } = {},
+      ) =>
+        listPage(this, `/api/v1/projects/${projectId}/comments`, {
+          limit,
+          cursor,
+          query: {
+            "document-id": documentId,
+            "entity-type": entityType,
+            "entity-id": entityId,
+          },
+        }),
+      /**
+       * Async-iterate a project's comments 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} [opts.documentId] - Every comment anywhere in one document
+       * @param {string} [opts.entityType] - With entityId, one entity's thread
+       * @param {string} [opts.entityId] - With entityType, one entity's thread
+       * @returns {AsyncGenerator<Array>}
+       */
+      iterPages: (
+        projectId,
+        { pageSize, documentId, entityType, entityId } = {},
+      ) =>
+        iterPages(this, `/api/v1/projects/${projectId}/comments`, {
+          pageSize,
+          query: {
+            "document-id": documentId,
+            "entity-type": entityType,
+            "entity-id": entityId,
+          },
+        }),
+      /**
+       * Comment counts per entity, as an `{entityId: n}` map, over the same
+       * scope and filters as `list`. One cheap request paints a comment
+       * indicator on every annotated item in a document without paging
+       * through the bodies.
+       *
+       * The response is NOT key-transformed: its keys are entity ids, and
+       * camelCasing would mangle the hyphens in a UUID.
+       * @param {string} projectId - The project to read
+       * @param {object} [filters] - Same filters as list()
+       * @returns {Promise<Object<string, number>>}
+       */
+      counts: (projectId, { documentId, entityType, entityId } = {}) =>
+        this._request("GET", `/api/v1/projects/${projectId}/comments/counts`, {
+          queryParams: {
+            "document-id": documentId,
+            "entity-type": entityType,
+            "entity-id": entityId,
+          },
+          skipResponseTransform: true,
+        }),
+      /**
+       * List the comments on a vocabulary's entries, oldest first. Requires
+       * read access to the vocabulary. Transparently follows pagination
+       * cursors and returns the full flat array.
+       * @param {string} vocabId - The vocab layer to read
+       * @param {object} [filters]
+       * @param {string} [filters.entityId] - One entry's thread
+       */
+      listInVocab: (vocabId, { entityId } = {}) =>
+        listAll(this, `/api/v1/vocab-layers/${vocabId}/comments`, {
+          query: { "entity-id": entityId },
+        }),
+      /**
+       * Fetch a single page of a vocabulary's comments.
+       * @param {string} vocabId - The vocab layer 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} [opts.entityId] - One entry's thread
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      listInVocabPage: (vocabId, { limit, cursor, entityId } = {}) =>
+        listPage(this, `/api/v1/vocab-layers/${vocabId}/comments`, {
+          limit,
+          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.
+       * @param {string} vocabId - The vocab layer to read
+       * @param {object} [filters]
+       * @param {string} [filters.entityId] - One entry only
+       * @returns {Promise<Object<string, number>>}
+       */
+      countsInVocab: (vocabId, { entityId } = {}) =>
+        this._request(
+          "GET",
+          `/api/v1/vocab-layers/${vocabId}/comments/counts`,
+          {
+            queryParams: { "entity-id": entityId },
+            skipResponseTransform: true,
+          },
+        ),
+    };
+
+    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
+       * 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, id } = {}, auditMessage) =>
+        this._request("POST", `/api/v1/projects/${projectId}/guidelines`, {
+          auditMessage,
+          body: bodyOf({ id, 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 },
+        }),
     };
   }
 
@@ -1811,25 +3629,80 @@ class PlaidClient {
    * write, so an operation that is never ended (crash, closed tab) is still
    * labeled in the log.
    *
+   * "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), 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`, `repair` or `review` (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.
+   *
+   * `keys` (from `keySeed()`) makes a run of the operation send the same
+   * requests as an earlier run with the same keys: the nth keyed request that
+   * joins it takes the Idempotency-Key `<seed>.<n>` and the document-version
+   * its first run claimed, so a request that landed is answered from its
+   * first send and writes nothing again. The count starts at 0 at each
+   * outermost begin. A nested operation joins the outer one's keys, unless it
+   * brings its own: then it numbers from 0 under its own seed until its
+   * matching end, and the outer numbering resumes after it.
+   *
    * @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, keys }`. `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`, `ref` and `keys` are described above.
    * @returns {string} The operation's group id.
    */
-  beginOperation(message, { id } = {}) {
-    if (this.operationGroup) {
-      this.operationGroup.depth += 1;
-      return this.operationGroup.id;
+  beginOperation(message, { id, kind, ref, keys, minted } = {}) {
+    const frame = {
+      keys: keys || null,
+      count: 0,
+      // Any iterable of ids (a Set, an array).
+      minted: minted ? new Set(minted) : null,
+      depth: 1,
+    };
+    const open = this.operationGroup;
+    this._openedFrame = null;
+    if (open) {
+      // A nested operation joins the outer one. When it brings its own key
+      // seed or ids (a queued edit run inside a longer operation), it numbers
+      // the keys in a frame of its own until it ends, then the frame under it
+      // numbers again.
+      open.depth += 1;
+      if (keys || minted) {
+        frame.depth = open.depth;
+        open.frames.push(frame);
+        this._openedFrame = frame;
+      }
+      return open.id;
     }
     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,
+      frames: [frame],
     };
+    this._openedFrame = frame;
     return this.operationGroup.id;
   }
 
+  /**
+   * A seed for the Idempotency-Keys of a logical operation that may be run
+   * again from the top (see beginOperation's `keys`). Keep it with the work
+   * it belongs to and pass it to every run.
+   * @returns {{seed: string, stamps: Map<number, number|null>}}
+   */
+  keySeed() {
+    return { seed: uuidv7(), stamps: new Map() };
+  }
+
   /**
    * End the current logical operation. With no argument this is purely local
    * (no request). Pass a refined `message` to relabel the group now that the
@@ -1843,6 +3716,12 @@ class PlaidClient {
     const group = this.operationGroup;
     if (!group) return;
     if (group.depth > 1) {
+      // A frame begun at this depth by hand (beginOperation) ends here. One
+      // begun by withOperation is ended by that call itself (_dropFrame).
+      const top = group.frames.at(-1);
+      if (group.frames.length > 1 && !top.owned && top.depth === group.depth) {
+        group.frames.pop();
+      }
       group.depth -= 1;
       return;
     }
@@ -1865,157 +3744,227 @@ 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`);
    *   });
    *
+   * 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, id, keys }`, as for beginOperation.
    * @returns {Promise<any>} Whatever `fn` resolves to.
    */
-  async withOperation(message, fn) {
-    this.beginOperation(message);
+  async withOperation(message, fn, { kind, ref, id, keys, minted } = {}) {
+    this.beginOperation(message, { kind, ref, id, keys, minted });
     const group = this.operationGroup;
-    const setMessage = (msg) => { if (group.depth === 1) group.refined = msg; };
+    // The key frame this call opened is ended by this call, whatever else
+    // began or ended meanwhile, not by whichever end comes at its depth.
+    const frame = this._openedFrame;
+    if (frame) frame.owned = true;
+    const setMessage = (msg) => {
+      if (group.depth === 1) group.refined = msg;
+    };
+    let result;
     try {
-      return await fn(setMessage);
-    } finally {
-      await this.endOperation();
+      result = await fn(setMessage);
+    } catch (e) {
+      // A relabel the server refuses (a token scoped to projects may not
+      // relabel a group, which names none) must not take the place of the
+      // error `fn` threw: the caller answers for that one.
+      dropFrame(group, frame);
+      try {
+        await this.endOperation();
+      } catch (relabel) {
+        console.warn('The operation was not relabelled:', relabel);
+      }
+      throw e;
     }
+    dropFrame(group, frame);
+    await this.endOperation();
+    return result;
   }
 
-  /** Begin a batch of operations. Subsequent API calls will be queued. */
-  beginBatch() {
-    this.isBatching = true;
-    this.batchOperations = [];
-    // Strict mode stamps the expected document-version on the FIRST write of
-    // the batch only (see _request) — reset the marker per batch.
-    this.batchVersionStamped = false;
-  }
 
   /**
-   * 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
+   * 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
    */
-  async submitBatch() {
-    if (!this.isBatching) {
-      throw new Error('No active batch. Call beginBatch() first.');
-    }
+  batch() {
+    return openBatch(this);
+  }
 
-    if (this.batchOperations.length === 0) {
-      this.isBatching = false;
-      return [];
-    }
+  /**
+   * 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. `key` is the request's
+   * Idempotency-Key: a batch whose answer is lost (no response, 502, 504) is
+   * sent again under it, and answered from the first send if that landed.
+   */
+  async _postBatch(url, body, { key = uuidv7() } = {}) {
+    const fetchOptions = {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        "Content-Type": "application/json",
+        [IDEMPOTENCY_HEADER]: key,
+      },
+      body: JSON.stringify(body),
+    };
 
     try {
-      let url = `${this.baseUrl}/api/v1/batch`;
-      const body = this.batchOperations.map(op => ({
-        path: op.path,
-        method: op.method.toUpperCase(),
-        ...(op.body && { body: op.body }),
-      }));
-
-      const fetchOptions = {
-        method: 'POST',
-        headers: {
-          'Authorization': `Bearer ${this.token}`,
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify(body),
+      // Retry a 503: the batch is atomic, so a refused one wrote nothing and
+      // repeating it is safe. A fresh timeout signal per attempt — an
+      // AbortSignal.timeout stays aborted once it fires.
+      const attempt = async () => {
+        const signal = timeoutSignal(this.batchTimeout);
+        let res;
+        try {
+          res = await fetch(
+            url,
+            signal ? { ...fetchOptions, signal } : fetchOptions,
+          );
+        } catch (e) {
+          throw makeNetworkError(e, url, "POST");
+        }
+        if (!res.ok) {
+          throw makeHttpError(res, await parseErrorBody(res), url, "POST");
+        }
+        return res;
       };
-      const signal = timeoutSignal(this.timeout);
-      if (signal) fetchOptions.signal = signal;
-
-      try {
-        const response = await fetch(url, fetchOptions);
-        if (!response.ok) {
-          throw makeHttpError(response, await parseErrorBody(response), url, 'POST');
+      const response = await retryUnknown(() => retryWhileBusy(attempt), {
+        delaysMs: this.retryDelaysMs,
+      }).catch((error) => {
+        error.idempotencyKey = key;
+        // 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();
+      // A replayed batch carries the versions right after its first send.
+      const replayed = response.headers?.get?.(REPLAYED_HEADER) === "true";
 
-        const results = await response.json();
-
-        // Extract document versions from each batch response
-        for (const result of results) {
-          if (result.headers && result.headers['X-Document-Versions']) {
-            try {
-              const versionsMap = JSON.parse(result.headers['X-Document-Versions']);
-              if (typeof versionsMap === 'object' && versionsMap !== null) {
-                // Clone once per response, then merge — not once per entry.
-                this.documentVersions = { ...this.documentVersions, ...versionsMap };
-              }
-            } catch (e) {
-              console.warn('Failed to parse document versions header from batch response:', e);
+      // Extract document versions from each batch response
+      for (const result of results) {
+        if (result.headers && result.headers["X-Document-Versions"]) {
+          try {
+            const versionsMap = JSON.parse(
+              result.headers["X-Document-Versions"],
+            );
+            if (typeof versionsMap === "object" && versionsMap !== null) {
+              // Clone once per response, then merge — not once per entry.
+              this.documentVersions = mergeVersions(
+                this.documentVersions,
+                versionsMap,
+                replayed,
+              );
             }
+          } catch (e) {
+            console.warn(
+              "Failed to parse document versions header from batch response:",
+              e,
+            );
           }
         }
-
-        return results.map(result => transformResponse(result));
-      } catch (error) {
-        if (error.status) throw error;
-        throw makeNetworkError(error, url, 'POST');
       }
-    } finally {
-      this.isBatching = false;
-      this.batchOperations = [];
-    }
-  }
-
-  /** 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;
+      const out = results.map((result) => ({
+        ...result,
+        body: transformResponse(result.body),
+      }));
+      return replayed ? markReplayed(out) : out;
+    } catch (error) {
+      if (error.status !== undefined) throw error;
+      throw Object.assign(makeNetworkError(error, url, "POST"), {
+        idempotencyKey: key,
+      });
+    }
   }
 
   /**
-   * 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.
-   * @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
+   * before anyone logs in.
+   * @param {string} baseUrl - The API base URL
+   * @param {object} [options]
+   */
+  static async health(baseUrl, options = {}) {
+    return anonymousGet(baseUrl, "/health", options);
+  }
+
+  /**
+   * The limits this server enforces, with NO authentication and no client
+   * instance. See the instance method for the shape.
+   * @param {string} baseUrl - The API base URL
+   * @param {object} [options]
    */
+  static async info(baseUrl, options = {}) {
+    return anonymousGet(baseUrl, "/api/v1/info", options);
+  }
+
   /**
    * Build the link to hand someone for an invite code. The server never sees
    * an app URL, so the app that minted the invite is the one that names it.
@@ -2026,7 +3975,7 @@ class PlaidClient {
    * @returns {string}
    */
   static inviteUrl(appUrl, code) {
-    return `${appUrl.replace(/#.*$/, '').replace(/\/$/, '')}/#/invite/${encodeURIComponent(code)}`;
+    return `${appUrl.replace(/#.*$/, "").replace(/\/$/, "")}/#/invite/${encodeURIComponent(code)}`;
   }
 
   /**
@@ -2040,74 +3989,216 @@ class PlaidClient {
    * @param {string} baseUrl - The API base URL
    * @param {string} code - The invite code
    * @param {object} [options]
-   * @returns {Promise<{kind: string, status: string, expiresAt: string, projectName?: string, projectRole?: string, username?: string, grantAdmin: boolean}>}
+   * @returns {Promise<{kind: string, status: string, expiresAt: string, projectName?: string, projectRole?: string, email?: string, grantAdmin: boolean}>}
    */
   static async lookupInvite(baseUrl, code, options = {}) {
-    return anonymousPost(baseUrl, '/api/v1/invite-codes/lookup', { code }, options);
+    return anonymousPost(baseUrl, "/api/v1/invites/lookup", { code }, options);
   }
 
   /**
    * Redeem an invite code, with NO authentication.
    *
-   * For a signup invite, pass `username` and `password` to create the account;
-   * the invite's grants are applied in the same transaction. For a password
-   * reset link, pass `password` only. Resolves to a logged-in client, exactly
-   * like login() — the redeemer just chose these credentials, so there is no
-   * reason to send them to a login form to retype them.
+   * For a signup invite, pass `email` and `password` to create the account
+   * (and optionally `displayName`); the invite's grants are applied in the
+   * same transaction. For a password reset link, pass `password` only.
+   * Resolves to a logged-in client, exactly like login() — the redeemer just
+   * chose these credentials, so there is no reason to send them to a login
+   * form to retype them.
    * @param {string} baseUrl - The API base URL
    * @param {string} code - The invite code
    * @param {object} credentials
-   * @param {string} [credentials.username] - Desired username (signup only)
+   * @param {string} [credentials.email] - The new account's email address,
+   *   which becomes its id and login (signup only)
+   * @param {string} [credentials.displayName] - How the new user is shown in
+   *   the UI; defaults to the local part of the email (signup only)
    * @param {string} credentials.password - Desired password (min 8 characters)
    * @param {object} [options]
    * @returns {Promise<{client: PlaidClient, userId: string, kind: string}>}
    */
-  static async redeemInvite(baseUrl, code, { username, password } = {}, options = {}) {
+  static async redeemInvite(
+    baseUrl,
+    code,
+    { email, password, displayName } = {},
+    options = {},
+  ) {
     const data = await anonymousPost(
-      baseUrl, '/api/v1/invite-codes/redeem',
-      bodyOf({ code, username, password }), options,
+      baseUrl,
+      "/api/v1/invites/redeem",
+      bodyOf({ code, email, password, "display-name": displayName }),
+      options,
     );
     return {
-      client: new PlaidClient(baseUrl.replace(/\/$/, ''), data.token || '', options),
+      client: new PlaidClient(
+        baseUrl.replace(/\/$/, ""),
+        data.token || "",
+        options,
+      ),
       userId: data.userId,
       kind: data.kind,
     };
   }
 
+  /**
+   * 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(/\/$/, '');
+    baseUrl = baseUrl.replace(/\/$/, "");
     const url = `${baseUrl}/api/v1/login`;
     try {
       const fetchOptions = {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ 'user-id': userId, password }),
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ "user-id": userId, password }),
       };
-      const signal = timeoutSignal(options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS);
+      const signal = timeoutSignal(
+        options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS,
+      );
       if (signal) fetchOptions.signal = signal;
 
       const response = await fetch(url, fetchOptions);
       if (!response.ok) {
-        throw makeHttpError(response, await parseErrorBody(response), url, 'POST');
+        throw makeHttpError(
+          response,
+          await parseErrorBody(response),
+          url,
+          "POST",
+        );
       }
 
       const data = await response.json();
-      const token = data.token || '';
+      const token = data.token || "";
       return new PlaidClient(baseUrl, token, options);
     } catch (error) {
       if (error.status) throw error;
-      throw makeNetworkError(error, url, 'POST');
+      throw makeNetworkError(error, url, "POST");
     }
   }
 }
 
+
+/**
+ * The request options of a config write. With `options.expected` present
+ * (even as undefined, which means the key was absent) the write is a
+ * compare-and-set: `?if-unchanged=true` and the body `{expected, value}`,
+ * which the server refuses with a 409 when the stored value is no longer
+ * `expected`. Without it the body is the value itself. Config is opaque, so
+ * neither body is re-cased.
+ */
+function configRequest(auditMessage, value, options, isDelete = false) {
+  if (!options || !Object.hasOwn(options, "expected")) {
+    return isDelete
+      ? { auditMessage, skipResponseTransform: true }
+      : { auditMessage, rawBody: value, skipResponseTransform: true };
+  }
+  const expected = options.expected === undefined ? null : options.expected;
+  return {
+    auditMessage,
+    queryParams: { "if-unchanged": true },
+    rawBody: isDelete ? { expected } : { expected, value },
+    skipResponseTransform: true,
+  };
+}
+
+/**
+ * The four layer-constraint methods of a layer bundle, on `/api/v1/<kind>`.
+ * See constraints.js and the core manual, "Layer constraints".
+ */
+function constraintMethods(client, kind) {
+  const base = (layerId) => `/api/v1/${kind}/${layerId}/constraints`;
+  return {
+    /**
+     * Declare an app namespace's constraints on this layer, replacing that
+     * namespace's list. Refused with 422 and the violations when the layer's
+     * stored data breaks them (see violationsOf).
+     * @param {string} layerId - The layer ID
+     * @param {string} namespace - The declaring app's namespace, e.g. "igt"
+     * @param {Array<object>} constraints - e.g. [{type: "single-span"}, {type: "value-set", values: ["N"]}]
+     * @param {string} [auditMessage] - Audit message for this write
+     * @param {{expected?: Array<object>|null}} [options] - `expected`: the list read for this
+     *   namespace (null when it was absent). The write is then refused with a 409 when the stored
+     *   list differs.
+     * @returns {Promise<{constraints: object}>} the layer's whole constraint map
+     */
+    setConstraints: (layerId, namespace, constraints, auditMessage, options) =>
+      client._request("PUT", `${base(layerId)}/${namespace}`, {
+        auditMessage,
+        body: constraintsBody(constraints, options),
+      }),
+    /**
+     * Remove an app namespace's constraints from this layer.
+     * @param {string} layerId - The layer ID
+     * @param {string} namespace - The declaring app's namespace
+     * @param {string} [auditMessage] - Audit message for this write
+     * @param {{expected?: Array<object>|null}} [options] - `expected`, as on setConstraints.
+     */
+    deleteConstraints: (layerId, namespace, auditMessage, options) => {
+      const body = constraintsBody(undefined, options);
+      return client._request("DELETE", `${base(layerId)}/${namespace}`, {
+        auditMessage,
+        ...(Object.keys(body).length ? { body } : {}),
+      });
+    },
+    /**
+     * The violations the given constraints would meet in this layer's stored
+     * data. Writes nothing.
+     * @param {string} layerId - The layer ID
+     * @param {Array<object>} constraints - The list to check
+     * @returns {Promise<{violations: Array<object>, violationCount: number}>}
+     */
+    checkConstraints: (layerId, constraints) =>
+      client._request("POST", `${base(layerId)}/check`, { body: { constraints } }),
+    /**
+     * Apply the remedies of the given constraints' remediable types
+     * (coextensive, single-span, single-link, same-ancestor) to every
+     * violation in this layer's stored data, one operation per document.
+     * With `document`, only that document is repaired, and a writer may
+     * ask. A document another user holds the lock on is left as it is and
+     * listed under `locked`.
+     * @param {string} layerId - The layer ID
+     * @param {Array<object>} constraints - The list to repair for
+     * @param {string} [auditMessage] - Audit message for this write
+     * @param {{document?: string}} [options]
+     * @returns {Promise<{repaired: Array<object>, locked: Array<{document: string, lockedBy: string}>, violations: Array<object>, violationCount: number}>}
+     */
+    repairConstraints: (layerId, constraints, auditMessage, options) =>
+      client._request("POST", `${base(layerId)}/repair`, {
+        auditMessage,
+        body: options?.document ? { constraints, document: options.document } : { constraints },
+      }),
+  };
+}
+
 export default PlaidClient;
 export { PlaidClient };
+export { CONSTRAINT_TYPES, valueSetAllows, violationsOf } from "./constraints.js";
 
 // Unicode code-point helpers for text offsets (token begin/end are code-point
 // indices). See ./codepoint.js.
-export { cpLength, cpSlice, cpSlicer, utf16ToCp, cpToUtf16, cpIndexOf } from './codepoint.js';
-export { PLAID_NAMESPACE, ROLE_KEY, ROLES, readRole, findByRole } from './roles.js';
+export {
+  cpLength,
+  cpSlice,
+  cpSlicer,
+  utf16ToCp,
+  cpToUtf16,
+  cpIndexOf,
+} from "./codepoint.js";
+export { composeTextEdits, gapsToOps, applyTextOps } from "./textEdits.js";
+export {
+  PLAID_NAMESPACE,
+  ROLE_KEY,
+  PRESERVE_ON_SPLIT_KEY,
+  PLAIN_EDITS_KEY,
+  SPLIT_ON_SPACE_KEY,
+  ROLES,
+  readRole,
+  findByRole,
+} from "./roles.js";
 // Service self-description helpers: filter discovered services by task, read a
 // service's parameter schema/summary, and build/coerce form values. See
 // ./serviceSchema.js.
@@ -2119,20 +4210,65 @@ export {
   getServiceSummary,
   buildDefaultValues,
   coerceParamValues,
-} from './serviceSchema.js';
-// Provenance: the cross-app convention for machine-provided vs human-labeled
-// information (flat prov/provSource/provConfirmed metadata; absence = human),
-// plus the machine-writer contract. See ./provenance.js and the manual,
-// "Provenance".
+} from "./serviceSchema.js";
+// Cooperative cancellation for a service AUTHORED in JS: `progress()` is a
+// checkpoint that throws ServiceCancelled once the requester stops the
+// 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.
+export {
+  DOCUMENT_LOCK_TTL_MS,
+  DocumentLock,
+  DocumentLockLost,
+} from "./documentLock.js";
+// Provenance: the cross-app convention for who made an annotation (flat
+// prov/provSource/provConfirmed metadata; absence = a verifier; 'inferred' =
+// a machine; 'contributed' = a person whose work is reviewed), plus the
+// machine-writer contract. See ./provenance.js and the manual, "Provenance".
 export {
   PROV,
   PROV_STATES,
   PROV_CONFIRMED,
+  PROVENANCE_KEYS,
   stampInferred,
   confirmedInferred,
+  stampContributed,
   provState,
+  provOrigin,
   isMachine,
   isProtected,
+  needsReview,
   verifyOnEdit,
+  contributeOnEdit,
   serviceSource,
-} from './provenance.js';
+  userSource,
+  REVIEW_KEY,
+  PROJECT_ROLES,
+  readReview,
+  projectRole,
+  isReviewed,
+  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";
+// UUIDv7 ids for what a client creates. See ./ids.js and the manual,
+// "Retrying a write".
+export { uuidv7 } from "./ids.js";
+export { wasReplayed } from "./replayed.js";
+export { MAX_BATCH_OPS };