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

package/src/index.js

@@ -5,6 +5,7 @@
 import { transformRequest, transformResponse } from "./transforms.js";
 import {
   makeRequest,
+  queueRequest,
   extractDocumentVersions,
   parseErrorBody,
   makeHttpError,
@@ -15,6 +16,7 @@ import {
   DEFAULT_BATCH_TIMEOUT_MS,
 } from "./http.js";
 import { listAll, listPage, iterPages } from "./pagination.js";
+import { withDocumentLock } from "./documentLock.js";
 import { createSSEConnection } from "./sse.js";
 import {
   discoverServices,
@@ -116,6 +118,55 @@ async function anonymousGet(baseUrl, path, options = {}) {
  */
 const MAX_BATCH_OPS = 1000;
 
+/**
+ * A batch is the client with a different `_request` (see `queueRequest`) and
+ * its own copy of the bundles. Everything else resolves to the client through
+ * the prototype: the token and base URL, strict mode and the document versions
+ * it tracks, the open logical operation.
+ */
+function openBatch(client) {
+  const batch = Object.create(client);
+  batch.client = client;
+  batch.operations = [];
+  batch.open = true;
+  batch._request = (method, path, options = {}) =>
+    queueRequest(batch, method, path, options);
+  batch.batch = () => {
+    throw new Error("A batch is not nestable: queue on the batch you have");
+  };
+  batch.batched = batch.batch;
+  batch.submit = () => submitBatch(batch);
+  batch.abort = () => {
+    batch.operations = [];
+    batch.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;
+  batch.operations = [];
+  if (ops.length === 0) return [];
+  const url = `${batch.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.
+  const results = [];
+  for (let i = 0; i < ops.length; i += MAX_BATCH_OPS) {
+    results.push(
+      ...(await batch.client._postBatch(url, ops.slice(i, i + MAX_BATCH_OPS))),
+    );
+  }
+  return results;
+}
+
 class PlaidClient {
   /**
    * Create a new PlaidClient instance
@@ -141,10 +192,12 @@ class PlaidClient {
         : options.timeout !== undefined
           ? options.timeout
           : DEFAULT_BATCH_TIMEOUT_MS;
-    this.isBatching = false;
-    this.batchOperations = [];
     this.documentVersions = {};
     this.strictModeDocumentId = null;
+    // Set to a DocumentLockLost while a `documents.locked()` block's keep-alive
+    // 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.
@@ -156,8 +209,16 @@ class PlaidClient {
     this.onAuthError = options.onAuthError || null;
     this._authErrorFired = false;
 
-    // --- API Bundles ---
+    this._installResources();
+  }
 
+  /**
+   * The API bundles (`client.documents`, `client.tokens`, ...). Installed on
+   * the client, and again on every batch it opens (see `batch()`): a batch is
+   * a view of the client with its own `_request`, so the same bundles built
+   * on it queue instead of sending.
+   */
+  _installResources() {
     this.vocabLinks = {
       /**
        * Create a new vocab link between tokens and a vocab item.
@@ -294,7 +355,6 @@ class PlaidClient {
       /**
        * 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) =>
@@ -318,7 +378,6 @@ class PlaidClient {
        * @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 } = {}) =>
@@ -477,7 +536,7 @@ class PlaidClient {
         }),
       /**
        * Update many relations in a single operation: set values and/or patch metadata.
-       * @param {Array} body - Objects of the shape `{id, value?, metadata?}`. `value` is set only when the key is present (null sends JSON null); `metadata` is a patch, a null value deleting that key. The relations may lie in several documents of one project; every document touched has its version bumped. An unknown id refuses the whole update.
+       * @param {Array} body - Objects of the shape `{id, value?, metadata?}`. `value` is set only when the key is present (null sends JSON null); `metadata` is a patch, a null value deleting that key. The relations may lie in several documents of one project; every document touched has its version bumped and every new version comes back in `X-Document-Versions`. A `document-version` precondition is accepted only when every entry lies in one document. An unknown id refuses the whole update.
        * @returns {Promise<{count: number}>} How many relations were updated.
        */
       bulkUpdate: (body, auditMessage) =>
@@ -637,7 +696,7 @@ class PlaidClient {
         this._request("DELETE", "/api/v1/spans/bulk", { auditMessage, body }),
       /**
        * Update many spans in a single operation: set values and/or patch metadata.
-       * @param {Array} body - Objects of the shape `{id, value?, metadata?}`. `value` is set only when the key is present (null sends JSON null); `metadata` is a patch, a null value deleting that key. The spans may lie in several documents of one project; every document touched has its version bumped. An unknown id refuses the whole update.
+       * @param {Array} body - Objects of the shape `{id, value?, metadata?}`. `value` is set only when the key is present (null sends JSON null); `metadata` is a patch, a null value deleting that key. The spans may lie in several documents of one project; every document touched has its version bumped and every new version comes back in `X-Document-Versions`. A `document-version` precondition is accepted only when every entry lies in one document. An unknown id refuses the whole update.
        * @returns {Promise<{count: number}>} How many spans were updated.
        */
       bulkUpdate: (body, auditMessage) =>
@@ -690,11 +749,7 @@ class PlaidClient {
        */
       info: () => {
         if (!infoPromise) {
-          // bypassBatch: a read belongs to whoever asked for it, not to
-          // whatever batch happens to be open on this shared client.
-          infoPromise = this._request("GET", "/api/v1/info", {
-            bypassBatch: true,
-          }).catch((err) => {
+          infoPromise = this._request("GET", "/api/v1/info").catch((err) => {
             // A failure must not be cached: a client that starts before the
             // server is up would never see the limits at all.
             infoPromise = null;
@@ -714,20 +769,6 @@ class PlaidClient {
       health: () => PlaidClient.health(this.baseUrl, { timeout: this.timeout }),
     };
 
-    this.batch = {
-      /**
-       * Execute multiple API operations atomically. If any operation fails, all
-       * changes are rolled back.
-       * @param {Array} body - The request body
-       */
-      submit: (body, auditMessage) =>
-        this._request("POST", "/api/v1/batch", {
-          auditMessage,
-          body,
-          noBatch: true,
-        }),
-    };
-
     this.texts = {
       /**
        * Replace all metadata for a text.
@@ -816,7 +857,6 @@ 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 users whose display name or email contains this text (case-insensitive)
        * @param {string} [opts.asOf] - Temporal query timestamp
@@ -844,7 +884,6 @@ class PlaidClient {
        * @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 } = {}) =>
@@ -874,7 +913,6 @@ class PlaidClient {
       /**
        * 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
@@ -994,7 +1032,6 @@ class PlaidClient {
        */
       getAvatar: (id) =>
         this._request("GET", `/api/v1/users/${id}/avatar`, {
-          noBatch: true,
           binaryResponse: true,
         }),
       /**
@@ -1019,32 +1056,79 @@ class PlaidClient {
        * 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.userData = {
       /**
        * List a user's private data entries ({key, updatedAt}, plus value when
-       * includeValues). Owner or admin only.
+       * 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 } = {}) =>
-        this._request("GET", `/api/v1/users/${userId}/data`, {
-          queryParams: { prefix, pattern, "include-values": includeValues },
+      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.
@@ -1098,7 +1182,6 @@ 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`),
@@ -1118,7 +1201,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 } = {}) =>
@@ -1154,7 +1236,6 @@ 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)
@@ -1184,7 +1265,6 @@ class PlaidClient {
        * @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, all, pageSize } = {}) =>
@@ -1266,8 +1346,12 @@ class PlaidClient {
        * 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"),
+      backup: () =>
+        this._request("POST", "/api/v1/admin/backup", { outOfBand: true }),
       /**
        * Documents currently held by an editing lock, with who holds each and
        * when it expires on its own. Admin only.
@@ -1280,7 +1364,9 @@ class PlaidClient {
        * @param {string} documentId - The document ID
        */
       releaseLock: (documentId) =>
-        this._request("DELETE", `/api/v1/admin/locks/${documentId}`),
+        this._request("DELETE", `/api/v1/admin/locks/${documentId}`, {
+          outOfBand: true,
+        }),
       /**
        * Live login and invite rate-limit buckets: the address, the account
        * where there is one, failures inside the window, the limit, and whether
@@ -1298,18 +1384,43 @@ class PlaidClient {
        */
       clearRateLimits: ({ ip, userId } = {}) =>
         this._request("DELETE", "/api/v1/admin/rate-limits", {
+          outOfBand: true,
           queryParams: { ip, "user-id": userId },
         }),
       /**
-       * The tail of the configured log file. Resolves with an `error` string
-       * instead of lines when no log file is configured or it does not exist
-       * yet. Admin only.
+       * 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}>}
        */
-      logs: ({ lines } = {}) =>
-        this._request("GET", "/api/v1/admin/logs", {
+      logFile: ({ lines } = {}) =>
+        this._request("GET", "/api/v1/admin/logs/file", {
           queryParams: { lines },
         }),
       /**
@@ -1323,7 +1434,6 @@ class PlaidClient {
        * 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`).
-       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use userDataPage() for a single page in a batch.
        * @param {object} [opts]
        * @param {string} [opts.prefix] - Only keys starting with this
        * @param {string} [opts.pattern] - Only keys matching this GLOB
@@ -1367,7 +1477,6 @@ class PlaidClient {
        * 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.
-       * 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.startTime] - Only operations at or after this instant
        * @param {string} [opts.endTime] - Only operations at or before this instant
@@ -1405,7 +1514,6 @@ class PlaidClient {
         }),
       /**
        * Async-iterate the instance-wide audit log page by page. Admin only.
-       * 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: ({ startTime, endTime, opTypes, pageSize } = {}) =>
@@ -1555,21 +1663,68 @@ class PlaidClient {
           queryParams: { "as-of": asOf },
         }),
       /**
-       * Acquire or refresh a document lock
+       * Acquire or refresh a document lock.
+       *
+       * outOfBand: the lock is a signal, not project data (see the note at
+       * the top of http.js). Queued on a batch it would be taken only at
+       * submit, after every write it was meant to guard, and until then answer
+       * success to a caller that does not hold it and cannot see the 423
+       * saying somebody else does.
        * @param {string} documentId - The document ID
        */
       acquireLock: (documentId, auditMessage) =>
         this._request("POST", `/api/v1/documents/${documentId}/lock`, {
           auditMessage,
+          outOfBand: true,
         }),
       /**
-       * Release a document lock
+       * Release a document lock. outOfBand, for the same reason as
+       * acquireLock: queued, the lock would be held until the batch submits,
+       * and not released at all if it aborts.
        * @param {string} documentId - The document ID
        */
       releaseLock: (documentId, auditMessage) =>
         this._request("DELETE", `/api/v1/documents/${documentId}/lock`, {
           auditMessage,
+          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 another user
+       * already holds it 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.
+       *
+       * NOT re-entrant: nesting two `locked()` blocks on one document would
+       * release on the inner exit and leave the outer unprotected. Lock at
+       * exactly one level per call path. A lost lock is recorded on the
+       * CLIENT, like batch and strict mode, so it stops every write the client
+       * makes and not only the ones this block makes.
+       * @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
@@ -1578,7 +1733,6 @@ class PlaidClient {
        */
       getMedia: (documentId) =>
         this._request("GET", `/api/v1/documents/${documentId}/media`, {
-          noBatch: true,
           binaryResponse: true,
         }),
       /**
@@ -1603,10 +1757,14 @@ class PlaidClient {
        * 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,
         }),
       /**
        * Replace all metadata for a document.
@@ -1642,7 +1800,6 @@ class PlaidClient {
       /**
        * 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
@@ -1866,7 +2023,6 @@ class PlaidClient {
       /**
        * 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
@@ -1955,7 +2111,6 @@ class PlaidClient {
       /**
        * 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.
@@ -1984,7 +2139,6 @@ 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 } = {}) =>
@@ -2018,7 +2172,6 @@ class PlaidClient {
       /**
        * 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) =>
@@ -2042,7 +2195,6 @@ class PlaidClient {
        * @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 } = {}) =>
@@ -2195,9 +2347,23 @@ class PlaidClient {
           auditMessage,
           body,
         }),
+      /**
+       * Update many vocab items in a single operation: set forms and/or patch
+       * metadata.
+       * @param {Array<{id: string, form?: string, metadata?: any}>} body - `form` is set only when the key is present; `metadata` is a patch, a null value deleting that key. The entries may lie in several vocab layers; the user must have write access to each. An unknown id refuses the whole update, and an id may appear only once. Only an entry whose form really changes restates the documents linking it, and a strict-mode client picks up their new versions from the response.
+       * @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) =>
@@ -2215,13 +2381,18 @@ class PlaidClient {
           queryParams: { "as-of": asOf },
         }),
       /**
-       * Delete a vocab item
+       * Delete a vocab item, and every link to it. Every document holding one
+       * of those links has its version bumped, and a strict-mode client picks
+       * up their new versions from the response.
        * @param {string} id - The resource ID
        */
       delete: (id, auditMessage) =>
         this._request("DELETE", `/api/v1/vocab-items/${id}`, { auditMessage }),
       /**
-       * Update a vocab item's form
+       * Update a vocab item's form. A document read carries the entry's form on
+       * every link to it, so a rename restates those documents: each has its
+       * version bumped, and a strict-mode client picks up their new versions
+       * from the response.
        * @param {string} id - The resource ID
        * @param {string} form - The vocab item form
        */
@@ -2399,7 +2570,7 @@ class PlaidClient {
         this._request("DELETE", "/api/v1/tokens/bulk", { auditMessage, body }),
       /**
        * Update many tokens in a single operation: patch metadata.
-       * @param {Array} body - Objects of the shape `{id, metadata}`. `metadata` is a patch, a null value deleting that key. The tokens may lie in several documents of one project; every document touched has its version bumped. An unknown id refuses the whole update.
+       * @param {Array} body - Objects of the shape `{id, metadata}`. `metadata` is a patch, a null value deleting that key. The tokens may lie in several documents of one project; every document touched has its version bumped and every new version comes back in `X-Document-Versions`. A `document-version` precondition is accepted only when every entry lies in one document. An unknown id refuses the whole update.
        * @returns {Promise<{count: number}>} How many tokens were updated.
        */
       bulkUpdate: (body, auditMessage) =>
@@ -2659,17 +2830,14 @@ class PlaidClient {
      *   For 'count': {return: 'count', count}. Entity cells are full entity objects
      *   (same shape as the GET endpoints).
      */
-    // bypassBatch: a query is a read. `client.batched()` flips one flag on the
-    // whole client, so a query issued by unrelated code while a batch is open
-    // (the IGT island fetching precedent while a document reconciles) used to
-    // be queued into it: the caller got `{batched: true}` instead of results,
-    // and the server ran the query against the batch's tx Connection, which
-    // 500s and rolls back every write in that batch.
+    // outOfBand: a query is a read that travels as a POST (see the note at
+    // the top of http.js). Made on a batch it goes over the wire like any
+    // read, and it never joins a logical operation.
     this.query = (body, auditMessage) =>
       this._request("POST", "/api/v1/query", {
         auditMessage,
         body,
-        bypassBatch: true,
+        outOfBand: true,
       });
 
     // Logical-operation groups (audit-log grouping). There is no create: a
@@ -2739,7 +2907,6 @@ class PlaidClient {
       /**
        * List comments in a project, oldest first. 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 to read
        * @param {object} [filters] - Narrow the scope
        * @param {string} [filters.documentId] - Every comment anywhere in one document
@@ -2780,7 +2947,6 @@ class PlaidClient {
         }),
       /**
        * Async-iterate a project's comments page by page; yields each page's entries array.
-       * 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.
        * @param {string} projectId - The project to read
        * @param {object} [opts]
        * @param {number} [opts.pageSize] - Per-request page size
@@ -2826,7 +2992,6 @@ class PlaidClient {
        * 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.
-       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching - use listInVocabPage() for a single page in a batch.
        * @param {string} vocabId - The vocab layer to read
        * @param {object} [filters]
        * @param {string} [filters.entityId] - One entry's thread
@@ -2868,6 +3033,106 @@ class PlaidClient {
           },
         ),
     };
+
+    this.guidelines = {
+      /**
+       * Create a guideline in a project. `title` is the handle an assistant
+       * asks for one by, and the only thing a person has to keep current. It is
+       * NOT required to be unique, so a title already in use is written like
+       * any other: warn about it, do not refuse it. A `pinned` guideline is one
+       * the assistant is given in full on every turn.
+       * @param {string} projectId - The project the guideline belongs to
+       * @param {string} title - The handle an assistant asks for one by (1..100 characters)
+       * @param {object} [opts]
+       * @param {string} [opts.body] - The Markdown text (up to 20000 characters; may be empty)
+       * @param {boolean} [opts.pinned] - Send this one to the assistant in full on every turn
+       */
+      create: (projectId, title, { body, pinned } = {}, auditMessage) =>
+        this._request("POST", `/api/v1/projects/${projectId}/guidelines`, {
+          auditMessage,
+          body: bodyOf({ title, body, pinned }),
+        }),
+      /**
+       * Read one guideline, Markdown body included.
+       * @param {string} id - The guideline id
+       */
+      get: (id) => this._request("GET", `/api/v1/guidelines/${id}`),
+      /**
+       * Update a guideline. Every field is optional and an omitted one is
+       * left alone, so an edit to the body need not restate the title.
+       *
+       * Pass `expectedUpdatedAt` (the `updatedAt` you last read) when a person
+       * has been editing prose: the write then fails with 409 rather than
+       * overwriting somebody who saved in between. Leave it off for a pin
+       * toggle or a script, which have nothing of anyone's to lose.
+       * @param {string} id - The guideline id
+       * @param {object} [changes]
+       * @param {string} [changes.title] - The new handle
+       * @param {string} [changes.body] - The new Markdown text
+       * @param {boolean} [changes.pinned] - Whether the assistant always gets it in full
+       * @param {string} [changes.expectedUpdatedAt] - Write only if this is still the stored updatedAt
+       */
+      update: (
+        id,
+        { title, body, pinned, expectedUpdatedAt } = {},
+        auditMessage,
+      ) =>
+        this._request("PATCH", `/api/v1/guidelines/${id}`, {
+          auditMessage,
+          queryParams: { "updated-at": expectedUpdatedAt },
+          body: bodyOf({ title, body, pinned }),
+        }),
+      /**
+       * Delete a guideline.
+       * @param {string} id - The guideline id
+       */
+      delete: (id, auditMessage) =>
+        this._request("DELETE", `/api/v1/guidelines/${id}`, { auditMessage }),
+      /**
+       * List a project's guidelines, by title. Transparently follows
+       * pagination cursors and returns the full flat array.
+       *
+       * Without `includeBodies` each entry carries `bodyChars`, the length of
+       * its body, so a caller can budget before fetching any. Pinned
+       * guidelines are NOT sorted first: `pinned` is on every entry and
+       * grouping is the caller's.
+       * @param {string} projectId - The project to read
+       * @param {object} [opts]
+       * @param {boolean} [opts.includeBodies] - Return each body instead of its length
+       */
+      list: (projectId, { includeBodies } = {}) =>
+        listAll(this, `/api/v1/projects/${projectId}/guidelines`, {
+          query: { "include-bodies": includeBodies },
+        }),
+      /**
+       * Fetch a single page of a project's guidelines.
+       * @param {string} projectId - The project to read
+       * @param {object} [opts]
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @param {boolean} [opts.includeBodies] - Return each body instead of its length
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      listPage: (projectId, { limit, cursor, includeBodies } = {}) =>
+        listPage(this, `/api/v1/projects/${projectId}/guidelines`, {
+          limit,
+          cursor,
+          query: { "include-bodies": includeBodies },
+        }),
+      /**
+       * Async-iterate a project's guidelines page by page; yields each page's entries array.
+       * @param {string} projectId - The project to read
+       * @param {object} [opts]
+       * @param {number} [opts.pageSize] - Per-request page size
+       * @param {boolean} [opts.includeBodies] - Return each body instead of its length
+       * @returns {AsyncGenerator<Array>}
+       */
+      iterPages: (projectId, { pageSize, includeBodies } = {}) =>
+        iterPages(this, `/api/v1/projects/${projectId}/guidelines`, {
+          pageSize,
+          query: { "include-bodies": includeBodies },
+        }),
+    };
   }
 
   // --- Core methods ---
@@ -2909,6 +3174,12 @@ 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): none of them is audited, so there would be nothing under the
+   * label.
+   *
    * @param {string} message - Human label for the operation.
    * @param {object} [opts] - Optional `{ id }`: adopt an existing group id instead of minting one (a service joining the requester's operation; `requestService` propagates an open operation to the service automatically).
    * @returns {string} The operation's group id.
@@ -2963,7 +3234,7 @@ class PlaidClient {
    * callback to refine the label once the outcome is known.
    *
    *   await client.withOperation('Merge morphemes', async (setMessage) => {
-   *     await client.batched(() => { ... });
+   *     await client.batched(async (b) => { ... });
    *     setMessage(`Merged ${n} morphemes`);
    *   });
    *
@@ -2984,53 +3255,29 @@ class PlaidClient {
     }
   }
 
-  /** 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) 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.");
-    }
-
-    if (this.batchOperations.length === 0) {
-      this.isBatching = false;
-      return [];
-    }
-
-    try {
-      const url = `${this.baseUrl}/api/v1/batch`;
-      const ops = this.batchOperations.map((op) => ({
-        path: op.path,
-        method: op.method.toUpperCase(),
-        ...(op.body && { body: op.body }),
-      }));
-      // The server caps a batch at MAX_BATCH_OPS so one transaction cannot
-      // hold the write lock without bound. A larger batch goes as consecutive
-      // requests, results concatenated in queue order: it could not have been
-      // one transaction anyway, and a repair or bulk edit over a big document
-      // must not fail on its size alone.
-      const results = [];
-      for (let i = 0; i < ops.length; i += MAX_BATCH_OPS) {
-        results.push(
-          ...(await this._postBatch(url, ops.slice(i, i + MAX_BATCH_OPS))),
-        );
-      }
-      return results;
-    } finally {
-      this.isBatching = false;
-      this.batchOperations = [];
-    }
+  batch() {
+    return openBatch(this);
   }
 
   /** POST one batch request (at most MAX_BATCH_OPS operations); resolves to its transformed results. */
@@ -3092,50 +3339,31 @@ class PlaidClient {
     }
   }
 
-  /** Abort the current batch without executing any operations. */
-  abortBatch() {
-    this.isBatching = false;
-    this.batchOperations = [];
-  }
-
-  /**
-   * Check if currently in batch mode.
-   * @returns {boolean}
-   */
-  isBatchMode() {
-    return this.isBatching;
-  }
-
   /**
-   * Run `fn` with a batch open, then submit all queued ops as ONE atomic
-   * request — or abort the batch if `fn` throws, so a half-open batch can never
-   * silently swallow later non-batch calls. `fn` makes the (queued) client
-   * calls; it must NOT call submitBatch itself. Resolves to the batch results
-   * array (`[]` if `fn` queued nothing).
+   * Run `fn` with a batch, then submit all queued ops as ONE atomic request,
+   * 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();
   }
 
   /**
@@ -3313,6 +3541,14 @@ export {
 // request, and `critical()` holds that off around writes. See ./services.js
 // and the manual, "Stopping a request".
 export { ServiceCancelled, createCancelScope } from "./services.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