@larc-iu/plaid-client 0.2.0-alpha.22 → 0.2.0-alpha.26

package/src/index.js

@@ -22,7 +22,7 @@ import {
   DEFAULT_BATCH_TIMEOUT_MS,
   queryTimeout,
 } from "./http.js";
-import { uuidv7 } from "./ids.js";
+import { uuidv4, uuidv7, normalizeUserId } from "./ids.js";
 import { constraintsBody } from "./constraints.js";
 import { listAll, listPage, iterPages } from "./pagination.js";
 import { recorderFor } from "./events.js";
@@ -39,6 +39,294 @@ import {
   cancelServiceRequest,
 } from "./services.js";
 
+// ---- Types --------------------------------------------------------------
+// The shapes the API answers with and takes, for editors and for the
+// declarations `npm run types` generates from this JSDoc (index.d.ts).
+
+/**
+ * @typedef {import("./textEdits.js").TextEditOp} TextEditOp
+ * @typedef {import("./textEdits.js").TextGap} TextGap
+ * @typedef {import("./metadataOps.js").MetadataOp} MetadataOp
+ * @typedef {import("./constraints.js").LayerConstraint} LayerConstraint
+ * @typedef {import("./constraints.js").ConstraintWriteOptions} ConstraintWriteOptions
+ * @typedef {import("./constraints.js").ConstraintViolation} ConstraintViolation
+ * @typedef {import("./requester.js").Requester} Requester
+ * @typedef {import("./batchRef.js").BatchRef} BatchRef
+ * @typedef {import("./serviceSchema.js").ServiceParam} ServiceParam
+ * @typedef {import("./serviceSchema.js").ServiceInfo} ServiceInfo
+ * @typedef {import("./serviceSchema.js").DiscoveredService} DiscoveredService
+ * @typedef {import("./services.js").ResponseHelper} ResponseHelper
+ * @typedef {import("./services.js").ServiceRegistration} ServiceRegistration
+ * @typedef {import("./services.js").ServiceStatusEvent} ServiceStatusEvent
+ * @typedef {PlaidClient["operationGroups"]} OperationGroupsBundle
+ */
+
+/**
+ * A single page of a cursor-paginated collection.
+ * @template [T=any]
+ * @typedef {{entries: T[], nextCursor: string | null}} Page
+ */
+
+/**
+ * Client options.
+ * @typedef {object} PlaidClientOptions
+ * @property {number | null} [timeout] Per-request timeout in ms (default
+ *   30000, 0 or null disables it).
+ * @property {number | null} [batchTimeout] Timeout for batch submissions in
+ *   ms (default 180000, 0 or null disables it). Aborting a batch does NOT
+ *   stop the server, which keeps running the transaction and holding the
+ *   write lock. Defaults to `timeout` when that is given and this is not.
+ * @property {number[]} [retryDelaysMs] Delays in ms before sending a keyed
+ *   write again when its answer was lost (no response, 502 or 504). Default
+ *   [1000, 3000, 9000].
+ * @property {((error: Error) => void) | null} [onAuthError] Fired once when
+ *   a request returns HTTP 401 (missing, expired or invalid token). 403 does
+ *   NOT trigger it.
+ */
+
+/**
+ * What kind of operation a logical-operation group is (`?group-kind=`).
+ * @typedef {"assistant-plan" | "service-run" | "import" | "bulk-edit"
+ *   | "guess-adoption" | "repair" | "review"} OperationKind
+ */
+
+/**
+ * Idempotency-Key seed for an operation run more than once (`client.keySeed()`).
+ * @typedef {{seed: string, stamps: Map<number, number | null>}} KeySeed
+ */
+
+/**
+ * A batch: the client's bundles, on which every write of project data queues
+ * until `submit()`. See `PlaidClient.batch()`. `submit()` resolves to one
+ * result per operation, in order. `ref(opIndex, index)` stands for the id a
+ * queued operation will create, in the body of a later write on this batch.
+ * @typedef {PlaidClient & {
+ *   readonly client: PlaidClient,
+ *   readonly operations: Array<{path: string, method: string, body?: any}>,
+ *   submit(): Promise<any[]>,
+ *   abort(): void,
+ *   ref(opIndex?: number, index?: number): BatchRef,
+ * }} PlaidBatch
+ */
+
+/**
+ * Options for a single page of any audit log. `kinds` keeps only the entries
+ * of operations of these kinds, each whole. `order: "desc"` pages newest
+ * first, and a cursor belongs to the direction that made it. `opsLimit` keeps
+ * only each entry's oldest N operations in `ops` (1..1000), and every entry
+ * has `opCount`. `entryId` reads only that entry rather than a page.
+ * @typedef {object} AuditPageOptions
+ * @property {string} [startTime]
+ * @property {string} [endTime]
+ * @property {string[] | string} [opTypes]
+ * @property {OperationKind[] | string} [kinds]
+ * @property {"asc" | "desc"} [order]
+ * @property {number} [limit]
+ * @property {string} [cursor]
+ * @property {number} [opsLimit]
+ * @property {string} [entryId]
+ */
+
+/**
+ * What `vocabLayers.restoreItem` did, or with `dryRun` would do.
+ * @typedef {object} VocabItemRestoreSummary
+ * @property {boolean} inserted The entry was gone and came back under its old id.
+ * @property {boolean} form A living entry's form was set back.
+ * @property {boolean} metadata A living entry's fields were set back.
+ * @property {number} total 0 when nothing changes.
+ */
+
+/**
+ * One private data entry. `version` is raised by one on every write of the
+ * entry, and a new entry is 1.
+ * @typedef {{key: string, updatedAt: string, version: number, value?: any}} UserDataEntry
+ */
+
+/** @typedef {UserDataEntry & {userId: string}} AdminUserDataEntry */
+
+/**
+ * One user's activity over a scope and window (`audit.tally`).
+ * @typedef {object} ActivityTallyRow
+ * @property {{id: string, displayName?: string}} user
+ * @property {number} operations
+ * @property {number} changes
+ * @property {number} documents
+ * @property {string} firstTs
+ * @property {string} lastTs
+ * @property {Array<{date: string, changes: number}>} [byDay]
+ */
+
+/**
+ * What a constraint repair did in one document.
+ * @typedef {{document: string, constraint: string, deleted: number, joined: number}} ConstraintRepair
+ */
+
+/**
+ * Entities that can carry a comment.
+ * @typedef {"document" | "text" | "token" | "span" | "relation" | "vocab-item"} CommentableType
+ */
+
+/**
+ * One comment. `projectId` and `documentId` are null for a comment on a
+ * vocabulary entry, and `vocabLayerId` is set only for one. `anchorLabel` is
+ * what the comment is about, in words, captured when it was posted: a
+ * comment outlives its anchor. `edited` is true once the body has been
+ * rewritten since it was posted.
+ * @typedef {object} Comment
+ * @property {string} id
+ * @property {string | null} projectId
+ * @property {string | null} documentId
+ * @property {string | null} vocabLayerId
+ * @property {CommentableType} entityType
+ * @property {string} entityId
+ * @property {string | null} anchorLabel
+ * @property {string} authorId
+ * @property {string} body
+ * @property {string} createdAt
+ * @property {string} updatedAt
+ * @property {boolean} edited
+ */
+
+/**
+ * One entry in a project's annotation manual. `body` is present on a single
+ * read and on a list made with `includeBodies`, `bodyChars` on a list made
+ * without. `pinned`: the assistant is given this one in full on every turn.
+ * @typedef {object} Guideline
+ * @property {string} id
+ * @property {string} projectId
+ * @property {string} title
+ * @property {string} [body]
+ * @property {number} [bodyChars]
+ * @property {boolean} pinned
+ * @property {string} createdAt
+ * @property {string} updatedAt
+ */
+
+/**
+ * A research-telemetry event type.
+ * @typedef {"suggestion.shown" | "suggestion.adopted" | "suggestion.dismissed" | "plan.opened"} ClientEventType
+ */
+
+/**
+ * One research-telemetry event as the server stores it.
+ * @typedef {object} ClientEvent
+ * @property {number} id
+ * @property {string} projectId
+ * @property {string | null} documentId
+ * @property {string} userId
+ * @property {ClientEventType} type
+ * @property {string | null} targetId
+ * @property {Record<string, any> | null} data
+ * @property {string | null} clientTs
+ * @property {string} ts
+ */
+
+/**
+ * An invite. `kind` is "signup" or "password-reset", `status` "active",
+ * "used", "expired", "revoked" or "inactive".
+ * @typedef {object} Invite
+ * @property {string} id
+ * @property {string} kind
+ * @property {string} status
+ * @property {string} createdBy
+ * @property {string} createdAt
+ * @property {string} expiresAt
+ * @property {number} maxUses
+ * @property {number} uses
+ * @property {string | null} revokedAt
+ * @property {string | null} note
+ * @property {string | null} targetUserId
+ * @property {boolean} grantAdmin
+ * @property {string | null} projectId
+ * @property {string | null} projectRole
+ */
+
+/**
+ * Server limits, as reported by /api/v1/info. An unset limit is absent.
+ * `passwordMinLength` is the shortest password the server accepts on any
+ * path, `lockExpirationMs` how long a document lock is held before it lapses.
+ * @typedef {object} ServerLimits
+ * @property {number} [mediaFileBytes]
+ * @property {number} [jsonBodyBytes]
+ * @property {number} [batchOperations]
+ * @property {number} [metadataDepth]
+ * @property {number} [metadataKeyCount]
+ * @property {number} [metadataStringLength]
+ * @property {number} [metadataTotalBytes]
+ * @property {number} [userDataValueBytes]
+ * @property {number} [guidelineTitleLength]
+ * @property {number} [guidelineBodyLength]
+ * @property {number} [passwordMinLength]
+ * @property {number} [lockExpirationMs]
+ */
+
+/**
+ * @typedef {object} ServerHealth
+ * @property {boolean} ok
+ * @property {string} version
+ * @property {number} uptimeMs
+ * @property {{dbSizeMb?: number, auditRows?: number, error?: string}} audit
+ */
+
+/**
+ * @typedef {{ip: string, userId?: string, failures: number, limit: number, blocked: boolean}} RateLimitBucket
+ */
+
+/**
+ * @typedef {object} RateLimitSnapshot
+ * @property {number} windowMs
+ * @property {RateLimitBucket[]} logins
+ * @property {RateLimitBucket[]} ips
+ * @property {RateLimitBucket[]} invites
+ */
+
+/**
+ * @typedef {object} BackupStatus
+ * @property {boolean} enabled
+ * @property {string} directory
+ * @property {number} retention
+ * @property {string} time
+ * @property {Array<{name: string, bytes: number, modified: string}>} backups
+ * @property {boolean} [ok]
+ */
+
+/**
+ * @typedef {object} ServerReport
+ * @property {string} version
+ * @property {{uptimeMs: number, startedAt: string, java: string, heapUsed: number, heapMax: number}} jvm
+ * @property {{path: string | null, bytes: number | null, walBytes: number | null,
+ *   slowQueryThresholdMs?: number, journalMode?: string, maxPoolSize?: number,
+ *   tables: Record<string, number | null>}} database
+ * @property {{directory: string, files: number, bytes: number, orphans: number, orphanBytes: number}} media
+ * @property {BackupStatus} backup
+ * @property {Record<string, any>} settings
+ */
+
+/**
+ * The live log. Requests and events are buffered separately, so a burst of
+ * requests cannot evict an error. In each, `matched` is how many passed the
+ * filters (which may exceed what `entries` holds) and `held` how many are
+ * buffered in total. `file` is the configured log file's absolute path, or
+ * null when logging to stdout.
+ * @typedef {object} LiveLog
+ * @property {{entries: object[], matched: number, held: number, capacity: number,
+ *   stats: Record<string, number | null>}} requests
+ * @property {{entries: object[], matched: number, held: number, capacity: number,
+ *   byLevel: Record<string, number>}} events
+ * @property {string | null} file
+ */
+
+/**
+ * An open server-sent-events stream. Once CLOSED, `error` says why: null when
+ * this side closed it. A refused stream's error carries the HTTP `status`,
+ * and one the server ended is named "StreamClosed".
+ * @typedef {object} SSEConnection
+ * @property {() => void} close
+ * @property {() => any} getStats
+ * @property {number} readyState
+ * @property {(Error & {status?: number}) | null} error
+ */
+
 // 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.
@@ -70,18 +358,22 @@ function bodyOf(obj) {
   return result;
 }
 
-// POST to an endpoint that takes no Authorization header (login, invite lookup
-// 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 = {}) {
+// A request with no Authorization header: login, invite lookup and redemption
+// (POST, with a body), /health and /api/v1/info (GET). Deliberately does not
+// go through PlaidClient._request: these are called before any client exists,
+// which is the whole point.
+async function anonymousRequest(method, baseUrl, path, body, options = {}) {
   const base = baseUrl.replace(/\/$/, "");
   const url = `${base}${path}`;
   try {
-    const fetchOptions = {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(body),
-    };
+    const fetchOptions =
+      method === "GET"
+        ? { method }
+        : {
+            method,
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+          };
     const signal = timeoutSignal(
       options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS,
     );
@@ -89,42 +381,12 @@ async function anonymousPost(baseUrl, path, body, options = {}) {
 
     const response = await fetch(url, fetchOptions);
     if (!response.ok) {
-      throw makeHttpError(
-        response,
-        await parseErrorBody(response),
-        url,
-        "POST",
-      );
+      throw makeHttpError(response, await parseErrorBody(response), url, method);
     }
     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, "GET");
-    }
-    return transformResponse(await response.json());
-  } catch (error) {
-    if (error.status) throw error;
-    throw makeNetworkError(error, url, "GET");
+    throw makeNetworkError(error, url, method);
   }
 }
 
@@ -155,6 +417,12 @@ const OPERATION_KINDS = [
  */
 export const BACKUP_TIMEOUT_MS = 30 * 60 * 1000;
 
+/** An avatar token is minted again once less than this is left of it. */
+const AVATAR_TOKEN_RENEW_MS = 10 * 60 * 1000;
+// An avatar token minted this recently is the renewal a caller asking for one
+// wanted.
+const AVATAR_TOKEN_FRESH_MS = 5 * 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
@@ -316,13 +584,12 @@ class PlaidClient {
    * Create a new PlaidClient instance
    * @param {string} baseUrl - The base URL for the API
    * @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)
+   * @param {PlaidClientOptions} [options] - Client options
    */
   constructor(baseUrl, token, options = {}) {
     this.baseUrl = baseUrl.replace(/\/$/, "");
     this.token = token;
+    /** @type {number | null} */
     this.timeout =
       options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS;
     // Batch submissions get a longer budget than a single request. Aborting a
@@ -330,6 +597,7 @@ class PlaidClient {
     // 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.
+    /** @type {number | null} */
     this.batchTimeout =
       options.batchTimeout !== undefined
         ? options.batchTimeout
@@ -338,33 +606,90 @@ class PlaidClient {
           : 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.
+    /** @type {number[] | undefined} */
     this.retryDelaysMs = options.retryDelaysMs;
+    /**
+     * The latest version seen for each document written through this client,
+     * keyed by document id.
+     * @type {Record<string, number>}
+     */
     this.documentVersions = {};
+    /**
+     * True once a response left its version list out
+     * (X-Document-Versions-Omitted, past fifty documents). Every version held
+     * was then forgotten, and the strict-mode document's is read again before
+     * the next write.
+     * @type {boolean | undefined}
+     */
+    this.documentVersionsOmitted = undefined;
     // The server's clock minus this machine's, in ms, from the last response
     // with a Date header (null before one). See serverNow().
+    /** @type {number | null} */
     this.serverClockOffsetMs = null;
+    /**
+     * The document strict mode is entered for, or null.
+     * @type {string | 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.
+    /** @type {import("./documentLock.js").DocumentLockLost | null} */
     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, frames }, where each of
     // `frames` is { keys, count, minted, depth, owned } and the last numbers.
+    /**
+     * @type {{id: string, message: string | null, kind: OperationKind | null,
+     *   ref: string | null, depth: number, written: boolean, refined: any,
+     *   frames: object[]} | null}
+     */
     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
     // the stored token and route back to login. See makeRequest in http.js.
+    /** @type {((error: Error) => void) | null} */
     this.onAuthError = options.onAuthError || null;
+    /** @private */
     this._authErrorFired = false;
     // Who hears that a request is being sent again (onRetry).
+    /** @private */
     this._retryListeners = new Set();
+    // GET /info as last read (`server.info()`), and whether a stream of this
+    // client dropped since.
+    /** @private */
+    this._serverFacts = { info: null, stale: false };
+    // The key frame the last beginOperation opened, or null (withOperation).
+    /** @private @type {object | null} */
+    this._openedFrame = null;
 
     this._installResources();
   }
 
+  /**
+   * A stream of this client ended without being closed here: the server may
+   * have restarted, with other limits.
+   * @private
+   */
+  _noteStreamDropped() {
+    this._serverFacts.stale = true;
+  }
+
+  /**
+   * A stream of this client is open. After a drop the limits are read again,
+   * once however many streams reopen.
+   * @private
+   */
+  _noteStreamOpened() {
+    if (!this._serverFacts.stale) return;
+    this.server.refresh().catch(() => {
+      // The figures known before stand, and the next open asks again.
+      this._serverFacts.stale = true;
+    });
+  }
+
   /**
    * Hear every time a request is sent again: after a 503 (the database was
    * busy), or for a keyed write after its answer was lost (no response, 502,
@@ -379,7 +704,10 @@ class PlaidClient {
     return () => this._retryListeners.delete(listener);
   }
 
-  /** Tell every `onRetry` listener. A listener that throws is passed over. */
+  /**
+   * Tell every `onRetry` listener. A listener that throws is passed over.
+   * @private
+   */
   _noteRetry(info) {
     for (const listener of this._retryListeners) {
       try {
@@ -406,6 +734,7 @@ class PlaidClient {
    * 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.
+   * @private
    */
   _installResources() {
     this.vocabLinks = {
@@ -414,6 +743,9 @@ class PlaidClient {
        * @param {string} vocabItem - The vocab item to link
        * @param {Array} tokens - The tokens to link
        * @param {any} [metadata] - Metadata for the link. Omit to leave unset; pass null to send JSON null.
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {object} [opts]
+       * @param {string} [opts.id] - The new entity's id, minted by the caller (see uuidv7)
        */
       create: (vocabItem, tokens, metadata, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/vocab-links", {
@@ -425,6 +757,7 @@ class PlaidClient {
        * reference different vocab items, but all tokens across the call must
        * belong to one document.
        * @param {Array<{vocabItem: string, tokens: string[], metadata?: any}>} body - The vocab links to create
+       * @param {string} [auditMessage] - Audit message for this write
        * @returns {Promise<{ids: string[]}>} The created entity IDs, in input order. (bulkDelete resolves to no value.)
        */
       bulkCreate: (body, auditMessage) =>
@@ -435,40 +768,15 @@ class PlaidClient {
       /**
        * Delete multiple vocab links in a single operation. Provide an array of IDs.
        * @param {string[]} body - The vocab link IDs to delete
+       * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       bulkDelete: (body, auditMessage) =>
         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,
-        }),
-      /**
-       * 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,
-        }),
-      /**
-       * 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 {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,
-        }),
+      ...metadataMethods(this, "vocab-links"),
       /**
        * Get a vocab link by ID
        * @param {string} id - The resource ID
@@ -478,6 +786,7 @@ class PlaidClient {
       /**
        * Delete a vocab link
        * @param {string} id - The resource ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       delete: (id, auditMessage) =>
         this._request("DELETE", `/api/v1/vocab-links/${id}`, { auditMessage }),
@@ -541,6 +850,10 @@ class PlaidClient {
        * that may be long: audit() walks every page before it resolves.
        * @param {string} id - The vocabulary ID
        * @param {object} [opts]
+       * @param {string} [opts.startTime] - Only entries at or after this instant
+       * @param {string} [opts.endTime] - Only entries at or before this instant
+       * @param {string[]|string} [opts.opTypes] - Only these op types
+       * @param {OperationKind[]|string} [opts.kinds] - Only the entries of operations of these kinds, each whole
        * @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
@@ -586,9 +899,10 @@ class PlaidClient {
        * @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
+       * @param {{dryRun?: boolean}} [options] - `{ dryRun }`: with `dryRun` true nothing
        *   is written and the summary says what would change
        * @param {string} [auditMessage] - Custom audit message for this operation
+       * @returns {Promise<VocabItemRestoreSummary>}
        */
       restoreItem: (id, itemId, asOf, { dryRun } = {}, auditMessage) =>
         this._request(
@@ -605,6 +919,7 @@ class PlaidClient {
       /**
        * Delete a vocab layer.
        * @param {string} id - The resource ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       delete: (id, auditMessage) =>
         this._request("DELETE", `/api/v1/vocab-layers/${id}`, { auditMessage }),
@@ -612,42 +927,14 @@ class PlaidClient {
        * Update a vocab layer's name.
        * @param {string} id - The resource ID
        * @param {string} name - The name
+       * @param {string} [auditMessage] - Audit message for this write
        */
       update: (id, name, auditMessage) =>
         this._request("PATCH", `/api/v1/vocab-layers/${id}`, {
           auditMessage,
           body: bodyOf({ name }),
         }),
-      /**
-       * Set a configuration value for a layer 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, 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, options) =>
-        this._request(
-          "DELETE",
-          `/api/v1/vocab-layers/${id}/config/${namespace}/${configKey}`,
-          configRequest(auditMessage, undefined, options, true),
-        ),
+      ...configMethods(this, "vocab-layers"),
       /**
        * List all vocab layers accessible to user. Transparently follows
        * pagination cursors and returns the full flat array.
@@ -678,6 +965,9 @@ class PlaidClient {
       /**
        * Create a new vocab layer. Note: this also registers the user as a maintainer.
        * @param {string} name - The name
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {object} [opts]
+       * @param {string} [opts.id] - The new entity's id, minted by the caller (see uuidv7)
        */
       create: (name, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/vocab-layers", {
@@ -688,6 +978,7 @@ class PlaidClient {
        * Assign a user as a maintainer for this vocab layer.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       addMaintainer: (id, userId, auditMessage) =>
         this._request(
@@ -699,6 +990,7 @@ class PlaidClient {
        * Remove a user's maintainer privileges for this vocab layer.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       removeMaintainer: (id, userId, auditMessage) =>
         this._request(
@@ -709,38 +1001,12 @@ class PlaidClient {
     };
 
     this.relations = {
-      /**
-       * Replace all metadata for a relation.
-       * @param {string} relationId - The relation ID
-       * @param {any} body - The request body
-       */
-      setMetadata: (relationId, body, auditMessage) =>
-        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,
-        }),
-      /**
-       * 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 {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,
-        }),
+      ...metadataMethods(this, "relations"),
       /**
        * Update the target span of a relation.
        * @param {string} relationId - The relation ID
        * @param {string} spanId - The span ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       setTarget: (relationId, spanId, auditMessage) =>
         this._request("PUT", `/api/v1/relations/${relationId}/target`, {
@@ -756,6 +1022,7 @@ class PlaidClient {
       /**
        * Delete a relation.
        * @param {string} relationId - The relation ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       delete: (relationId, auditMessage) =>
         this._request("DELETE", `/api/v1/relations/${relationId}`, {
@@ -765,6 +1032,7 @@ class PlaidClient {
        * Update a relation's value.
        * @param {string} relationId - The relation ID
        * @param {any} value - The value
+       * @param {string} [auditMessage] - Audit message for this write
        */
       update: (relationId, value, auditMessage) =>
         this._request("PATCH", `/api/v1/relations/${relationId}`, {
@@ -775,6 +1043,7 @@ class PlaidClient {
        * Update the source span of a relation.
        * @param {string} relationId - The relation ID
        * @param {string} spanId - The span ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       setSource: (relationId, spanId, auditMessage) =>
         this._request("PUT", `/api/v1/relations/${relationId}/source`, {
@@ -790,6 +1059,9 @@ class PlaidClient {
        * @param {string} targetId - The target span ID
        * @param {any} value - The value
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {object} [opts]
+       * @param {string} [opts.id] - The new entity's id, minted by the caller (see uuidv7)
        */
       create: (
         layerId,
@@ -814,6 +1086,7 @@ class PlaidClient {
       /**
        * Create multiple relations in a single operation.
        * @param {Array} body - The request body
+       * @param {string} [auditMessage] - Audit message for this write
        * @returns {Promise<{ids: string[]}>} The created entity IDs, in input order. (bulkDelete resolves to no value.)
        */
       bulkCreate: (body, auditMessage) =>
@@ -821,6 +1094,8 @@ class PlaidClient {
       /**
        * Delete multiple relations in a single operation. Provide an array of IDs.
        * @param {Array} body - The request body
+       * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       bulkDelete: (body, auditMessage) =>
         this._request("DELETE", "/api/v1/relations/bulk", {
@@ -830,6 +1105,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 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.
+       * @param {string} [auditMessage] - Audit message for this write
        * @returns {Promise<{count: number}>} How many relations were updated.
        */
       bulkUpdate: (body, auditMessage) =>
@@ -840,81 +1116,22 @@ class PlaidClient {
     };
 
     this.spanLayers = {
-      /**
-       * Set a configuration value for a layer in an editor namespace.
-       * @param {string} spanLayerId - The span 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: (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, options) =>
-        this._request(
-          "DELETE",
-          `/api/v1/span-layers/${spanLayerId}/config/${namespace}/${configKey}`,
-          configRequest(auditMessage, undefined, options, true),
-        ),
+      ...configMethods(this, "span-layers"),
       ...constraintMethods(this, "span-layers"),
-      /**
-       * Get a span layer by ID.
-       * @param {string} spanLayerId - The span layer ID
-       */
-      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,
-        }),
-      /**
-       * 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,
-          body: bodyOf({ name }),
-        }),
+      ...layerMethods(this, "span-layers"),
       /**
        * Create a new span layer.
        * @param {string} tokenLayerId - The token layer ID
        * @param {string} name - The name
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {object} [opts]
+       * @param {string} [opts.id] - The new entity's id, minted by the caller (see uuidv7)
        */
       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.
-       * @param {string} spanLayerId - The span layer ID
-       * @param {string} direction - The direction ("up" or "down")
-       */
-      shift: (spanLayerId, direction, auditMessage) =>
-        this._request("POST", `/api/v1/span-layers/${spanLayerId}/shift`, {
-          auditMessage,
-          body: bodyOf({ direction }),
-        }),
     };
 
     this.spans = {
@@ -922,6 +1139,7 @@ class PlaidClient {
        * Replace tokens for a span.
        * @param {string} spanId - The span ID
        * @param {Array} tokens - The tokens
+       * @param {string} [auditMessage] - Audit message for this write
        */
       setTokens: (spanId, tokens, auditMessage) =>
         this._request("PUT", `/api/v1/spans/${spanId}/tokens`, {
@@ -935,6 +1153,9 @@ class PlaidClient {
        * @param {Array} tokens - The tokens
        * @param {any} value - The value
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {object} [opts]
+       * @param {string} [opts.id] - The new entity's id, minted by the caller (see uuidv7)
        */
       create: (spanLayerId, tokens, value, metadata, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/spans", {
@@ -956,6 +1177,7 @@ class PlaidClient {
       /**
        * Delete a span.
        * @param {string} spanId - The span ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       delete: (spanId, auditMessage) =>
         this._request("DELETE", `/api/v1/spans/${spanId}`, { auditMessage }),
@@ -963,6 +1185,7 @@ class PlaidClient {
        * Update a span's value.
        * @param {string} spanId - The span ID
        * @param {any} value - The value
+       * @param {string} [auditMessage] - Audit message for this write
        */
       update: (spanId, value, auditMessage) =>
         this._request("PATCH", `/api/v1/spans/${spanId}`, {
@@ -972,6 +1195,7 @@ class PlaidClient {
       /**
        * Create multiple spans in a single operation.
        * @param {Array} body - The request body
+       * @param {string} [auditMessage] - Audit message for this write
        * @returns {Promise<{ids: string[]}>} The created entity IDs, in input order. (bulkDelete resolves to no value.)
        */
       bulkCreate: (body, auditMessage) =>
@@ -979,12 +1203,15 @@ class PlaidClient {
       /**
        * Delete multiple spans in a single operation. Provide an array of IDs.
        * @param {Array} body - The request body
+       * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       bulkDelete: (body, auditMessage) =>
         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.
+       * @param {string} [auditMessage] - Audit message for this write
        * @returns {Promise<{count: number}>} How many spans were updated.
        */
       bulkUpdate: (body, auditMessage) =>
@@ -992,64 +1219,71 @@ class PlaidClient {
           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,
-        }),
-      /**
-       * Remove all metadata from a span.
-       * @param {string} spanId - The span ID
-       */
-      deleteMetadata: (spanId, auditMessage) =>
-        this._request("DELETE", `/api/v1/spans/${spanId}/metadata`, {
-          auditMessage,
-        }),
-      /**
-       * 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 {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,
-        }),
+      ...metadataMethods(this, "spans"),
     };
 
-    // 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;
+    // Server-level facts. Read once, and again only when they may have
+    // changed: after this client's connection to the server was lost and came
+    // back (a restart, the only way the limits change, always drops it), or
+    // after the server refused a private data write as too large. A caller
+    // asking "will this file be accepted" does not pay a round trip to find
+    // out. The facts live on the client (`_serverFacts`), so a batch opened
+    // on it reads the same.
     this.server = {
       /**
        * This server's version and the limits it enforces, e.g.
        * `{ limits: { mediaFileBytes, jsonBodyBytes, batchOperations, … } }`.
        * Sizes are in bytes. Unauthenticated.
+       * @returns {Promise<{limits: ServerLimits}>}
        */
       info: () => {
-        if (!infoPromise) {
-          infoPromise = this._request("GET", "/api/v1/info").catch((err) => {
-            // A failure must not be cached: a client that starts before the
+        const facts = this._serverFacts;
+        if (!facts.info) {
+          const asked = this._request("GET", "/api/v1/info").catch((err) => {
+            // A failure must not be kept: a client that starts before the
             // server is up would never see the limits at all.
-            infoPromise = null;
+            if (facts.info === asked) facts.info = null;
             throw err;
           });
+          facts.info = asked;
         }
-        return infoPromise;
+        return facts.info;
+      },
+      /**
+       * Read `GET /info` again and resolve to it. Until it answers, a reader
+       * waits for it. The facts known before are kept when the server does
+       * not answer, and the error is thrown.
+       * @returns {Promise<{limits: ServerLimits}>}
+       */
+      refresh: () => {
+        const facts = this._serverFacts;
+        const before = facts.info;
+        facts.stale = false;
+        const fresh = this._request("GET", "/api/v1/info");
+        const held = fresh.catch((err) => {
+          if (facts.info === held) facts.info = before;
+          if (before) return before;
+          throw err;
+        });
+        held.catch(() => {});
+        facts.info = held;
+        return fresh;
+      },
+      /**
+       * Just the limits, which is what a caller almost always wants.
+       * @returns {Promise<ServerLimits>}
+       */
+      limits: async () => {
+        // Through `self`: tsc types a bundle that names itself as
+        // `this.server` in its own methods `any` in the declarations.
+        const self = this;
+        return (await self.server.info()).limits;
       },
-      /** Just the limits, which is what a caller almost always wants. */
-      limits: async () => (await this.server.info()).limits,
       /**
        * 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}>}
+       * @returns {Promise<ServerHealth>}
        */
       health: () => PlaidClient.health(this.baseUrl, { timeout: this.timeout }),
     };
@@ -1073,34 +1307,7 @@ class PlaidClient {
     };
 
     this.texts = {
-      /**
-       * Replace all metadata for a text.
-       * @param {string} textId - The text ID
-       * @param {any} body - The request body
-       */
-      setMetadata: (textId, body, auditMessage) =>
-        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,
-        }),
-      /**
-       * 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 {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,
-        }),
+      ...metadataMethods(this, "texts"),
       /**
        * Create a new text in a document's text layer. A text is a container for
        * one long string in `body` for a given layer.
@@ -1108,6 +1315,11 @@ class PlaidClient {
        * @param {string} documentId - The document ID
        * @param {string} body - The request body
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
+       * @param {string} [auditMessage]
+       * @param {{id?: string, tokenEdges?: number[]}} [options] - `id`: the new text's id, a UUIDv7
+       *   this client minted. `tokenEdges`: the code-point offsets where the tokens made next on
+       *   this text begin and end. The body is stored composed, except a character one of them
+       *   falls inside, which stays as sent (see composeText).
        */
       create: (
         textLayerId,
@@ -1115,7 +1327,7 @@ class PlaidClient {
         body,
         metadata,
         auditMessage,
-        { id } = {},
+        { id, tokenEdges } = {},
       ) =>
         this._request("POST", "/api/v1/texts", {
           auditMessage,
@@ -1124,6 +1336,7 @@ class PlaidClient {
             "text-layer-id": textLayerId,
             "document-id": documentId,
             body,
+            "token-edges": tokenEdges,
             metadata,
           }),
         }),
@@ -1136,6 +1349,7 @@ class PlaidClient {
       /**
        * Delete a text and all dependent data.
        * @param {string} textId - The text ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       delete: (textId, auditMessage) =>
         this._request("DELETE", `/api/v1/texts/${textId}`, { auditMessage }),
@@ -1195,14 +1409,14 @@ class PlaidClient {
        * List (or search) users. Transparently follows pagination cursors and
        * returns the full flat array. Admin-or-maintainer only.
        * @param {object} [opts]
-       * @param {string} [opts.q] - Filter to users whose display name contains this text, or whose email starts with it (contains it, when the text has an @), case-insensitive
+       * @param {string} [opts.q] - Filter to users whose display name contains this text, or whose email starts with it (contains it, when the text holds an at sign), case-insensitive
        */
       list: ({ q } = {}) =>
         listAll(this, "/api/v1/users", { query: { q } }),
       /**
        * Fetch a single page of users (optionally filtered by `q`).
        * @param {object} [opts]
-       * @param {string} [opts.q] - Filter to users whose display name contains this text, or whose email starts with it (contains it, when the text has an @), case-insensitive
+       * @param {string} [opts.q] - Filter to users whose display name contains this text, or whose email starts with it (contains it, when the text holds an at sign), case-insensitive
        * @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)}>}
@@ -1216,7 +1430,7 @@ class PlaidClient {
       /**
        * Async-iterate users page by page; yields each page's entries array.
        * @param {object} [opts]
-       * @param {string} [opts.q] - Filter to users whose display name contains this text, or whose email starts with it (contains it, when the text has an @), case-insensitive
+       * @param {string} [opts.q] - Filter to users whose display name contains this text, or whose email starts with it (contains it, when the text holds an at sign), case-insensitive
        * @param {number} [opts.pageSize] - Per-request page size
        * @returns {AsyncGenerator<Array>}
        */
@@ -1234,12 +1448,13 @@ class PlaidClient {
        * @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.
+       * @param {string} [auditMessage] - Audit message for this write
        */
       create: (email, password, isAdmin, displayName, auditMessage) =>
         this._request("POST", "/api/v1/users", {
           auditMessage,
           body: bodyOf({
-            email,
+            email: normalizeUserId(email),
             password,
             "is-admin": isAdmin,
             // Left out when not given (null too), so core gives the user the
@@ -1275,6 +1490,10 @@ class PlaidClient {
        * that may be long: audit() walks every page before it resolves.
        * @param {string} userId - The user ID
        * @param {object} [opts]
+       * @param {string} [opts.startTime] - Only entries at or after this instant
+       * @param {string} [opts.endTime] - Only entries at or before this instant
+       * @param {string[]|string} [opts.opTypes] - Only these op types
+       * @param {OperationKind[]|string} [opts.kinds] - Only the entries of operations of these kinds, each whole
        * @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
@@ -1314,6 +1533,7 @@ class PlaidClient {
        * stays visible in listings with a deactivated-at timestamp.
        * Reversible via activate(), which restores login only.
        * @param {string} id - The resource ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       delete: (id, auditMessage) =>
         this._request("DELETE", `/api/v1/users/${id}`, { auditMessage }),
@@ -1322,6 +1542,7 @@ class PlaidClient {
        * Project memberships, vocab maintainerships, and API tokens removed
        * at deactivation are NOT restored — re-grant them deliberately.
        * @param {string} id - The resource ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       activate: (id, auditMessage) =>
         this._request("POST", `/api/v1/users/${id}/activate`, { auditMessage }),
@@ -1337,6 +1558,7 @@ class PlaidClient {
        * @param {string} [password] - New password
        * @param {string} [displayName] - New display name
        * @param {boolean} [isAdmin] - New admin status
+       * @param {string} [auditMessage] - Audit message for this write
        */
       update: (id, password, displayName, isAdmin, auditMessage) =>
         this._request("PATCH", `/api/v1/users/${id}`, {
@@ -1348,23 +1570,89 @@ class PlaidClient {
           }),
         }),
       /**
-       * Build a URL for a user's profile picture, suitable for use directly as
-       * an `<img>` src. An image element cannot send an Authorization header,
-       * so the session token rides in the query string, the same way document
-       * media does.
+       * A token that shows any user's profile picture without an
+       * Authorization header, for an `<img>`, which cannot send one. Resolves
+       * to `{ token, expiresAt }` (`expiresAt` an ISO-8601 instant, a day on by
+       * default). The server refuses it on every route but the picture, and
+       * it stops working when the user signs out or changes password.
+       *
+       * One token serves the whole client: it is kept and handed out again
+       * until under ten minutes of it remain (half its life, for one minted
+       * near the end of a login), calls made while one is being minted share
+       * that request, and it is dropped when the client's token changes.
+       * avatarUrl() uses it.
+       * @param {{renew?: boolean}} [options] - `renew`: mint a new one
+       *   whatever is kept, unless one was minted in the last few seconds
+       *   (or is being minted), which is shared
+       * @returns {Promise<{token: string, expiresAt: string}>}
+       */
+      avatarToken: ({ renew = false } = {}) => {
+        // A batch is a view of its client and shares the client's token.
+        const owner = this.client ?? this;
+        const cached = owner._avatarToken;
+        if (cached && cached.forToken === owner.token) {
+          if (cached.pending) return cached.pending;
+          const now = owner.serverNow().getTime();
+          // A renewal shares one minted a moment ago: every picture on a page
+          // fails together when a token dies, and each asks.
+          if (renew && now - cached.mintedAt < AVATAR_TOKEN_FRESH_MS) {
+            return Promise.resolve(cached.link);
+          }
+          const expires = Date.parse(cached.link.expiresAt);
+          // Renewed ten minutes before it runs out, or at half its life when
+          // it was minted for less than twenty: the server caps it at the
+          // login's own expiry, and near the end of a login every token it
+          // mints runs out at that same moment, so a fixed ten minutes asked
+          // for a new one on every call.
+          const renewAt = Math.min(AVATAR_TOKEN_RENEW_MS, (expires - cached.mintedAt) / 2);
+          if (!renew && expires - now > renewAt) return Promise.resolve(cached.link);
+        }
+        const entry = {
+          forToken: owner.token,
+          pending: null,
+          link: null,
+          mintedAt: owner.serverNow().getTime(),
+        };
+        entry.pending = owner
+          ._request("POST", "/api/v1/avatar-link", { outOfBand: true })
+          .then(
+            (link) => {
+              entry.pending = null;
+              entry.link = link;
+              return link;
+            },
+            (e) => {
+              if (owner._avatarToken === entry) owner._avatarToken = null;
+              throw e;
+            },
+          );
+        owner._avatarToken = entry;
+        return entry.pending;
+      },
+      /**
+       * Build a URL for a user's profile picture, for an `<img>` src. The
+       * URL carries the client's avatar token (see avatarToken()), never the
+       * login token.
        *
        * Pass the user record's `avatarHash` as the second argument whenever you
        * have it: the URL then addresses that exact picture, so the browser can
        * cache it indefinitely and still pick up a replacement the moment the
-       * user changes it. Returns null when the user has no picture, so callers
-       * can fall back to initials without a wasted request.
+       * user changes it. Resolves to null when `avatarHash` is null (the user
+       * has no picture), so callers can fall back to initials without a
+       * wasted request.
        * @param {string} id - The user ID
-       * @param {string} [avatarHash] - The user record's `avatarHash`
-       * @returns {string|null}
+       * @param {string|null} [avatarHash] - The user record's `avatarHash`
+       * @param {{renew?: boolean}} [options] - `renew`: mint a new avatar
+       *   token first, for a picture its URL failed to load (the token
+       *   stops working when the login it was minted under ends)
+       * @returns {Promise<string|null>}
        */
-      avatarUrl: (id, avatarHash) => {
+      avatarUrl: async (id, avatarHash, { renew = false } = {}) => {
         if (avatarHash === null) return null;
-        const params = new URLSearchParams({ token: this.token });
+        // Through `self`, as in server.limits.
+        const self = this;
+        const { token } = await self.users.avatarToken({ renew });
+        const params = new URLSearchParams({ "avatar-token": token });
         if (avatarHash) params.set("v", avatarHash);
         return `${this.baseUrl}/api/v1/users/${id}/avatar?${params}`;
       },
@@ -1384,6 +1672,7 @@ class PlaidClient {
        * PNG, JPEG, WebP, and GIF. Resolves to the updated user record.
        * @param {string} id - The user ID
        * @param {File} file - The image to upload
+       * @param {string} [auditMessage] - Audit message for this write
        */
       setAvatar: (id, file, auditMessage) => {
         const fd = new FormData();
@@ -1398,6 +1687,7 @@ class PlaidClient {
       /**
        * Remove a profile picture. Your own, or anyone's if you are an admin.
        * @param {string} id - The user ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       // No flag: the upload beside this one is multipart and cannot be
       // batched, but a DELETE carries no blob, so the batch transport takes
@@ -1421,7 +1711,8 @@ class PlaidClient {
        * 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
+       * one value runs to megabytes (`userDataValueBytes` in
+       * `server.limits()`): 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
@@ -1430,6 +1721,7 @@ class PlaidClient {
        * @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)
+       * @returns {Promise<UserDataEntry[]>}
        */
       list: (userId, { prefix, pattern, includeValues, pageSize = 100 } = {}) =>
         listAll(this, `/api/v1/users/${userId}/data`, {
@@ -1445,7 +1737,7 @@ class PlaidClient {
        * @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)}>}
+       * @returns {Promise<Page<UserDataEntry>>}
        */
       listPage: (
         userId,
@@ -1464,6 +1756,7 @@ class PlaidClient {
        * @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)
+       * @returns {AsyncGenerator<UserDataEntry[]>}
        */
       iterPages: (
         userId,
@@ -1474,9 +1767,10 @@ class PlaidClient {
           query: { prefix, pattern, "include-values": includeValues },
         }),
       /**
-       * Read one private data entry ({key, updatedAt, value}); 404 if absent.
+       * Read one private data entry ({key, updatedAt, version, value}); 404 if absent.
        * @param {string} userId
        * @param {string} key
+       * @returns {Promise<UserDataEntry & {value: any}>}
        */
       get: (userId, key) =>
         this._request(
@@ -1484,27 +1778,51 @@ class PlaidClient {
           `/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.
+       * Create or replace one private data entry. `value` is any JSON, up to
+       * the server's `userDataValueBytes` (`server.limits()`, 5 MB by
+       * default), and is refused with 413 over it, after which
+       * `server.limits()` answers the figure the server has now. 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.
+       *
+       * Every write raises the entry's `version` by one, and reads answer it.
+       * With `version`, the write lands only when the entry is still at that
+       * version (0: only when there is no entry), and is otherwise refused with
+       * 409, `error: "version-mismatch"`, and the stored `version` and
+       * `updatedAt` on the error's `responseData`: read it again and make the
+       * change on what is there.
        * @param {string} userId
        * @param {string} key
        * @param {*} value
+       * @param {object} [opts]
+       * @param {number} [opts.version] - The version this write was made from
+       * @returns {Promise<{key: string, updatedAt: string, version: number}>}
        */
-      put: (userId, key, value) =>
-        this._request(
-          "PUT",
-          `/api/v1/users/${userId}/data/${encodeURIComponent(key)}`,
-          {
-            body: value,
-            noBatch: true,
-          },
-        ),
+      put: async (userId, key, value, { version } = {}) => {
+        try {
+          return await this._request(
+            "PUT",
+            `/api/v1/users/${userId}/data/${encodeURIComponent(key)}`,
+            {
+              body: value,
+              noBatch: true,
+              queryParams: { version },
+            },
+          );
+        } catch (err) {
+          if (err?.status === 413) {
+            // The cap may have changed since it was read: the caller deciding
+            // what to do next reads the server's figure now.
+            await this.server.refresh().catch(() => {});
+          }
+          throw err;
+        }
+      },
       /**
        * Delete one private data entry; 404 if absent.
        * @param {string} userId
@@ -1556,6 +1874,7 @@ class PlaidClient {
        * needs a sign-in token.
        * @param {string} userId - The user ID who will own the token
        * @param {string} name - A human label, e.g. "Stanza parser"
+       * @param {string} [auditMessage] - Audit message for this write
        * @returns {Promise<{id: string, name: string, token: string}>}
        */
       create: (userId, name, auditMessage) =>
@@ -1572,6 +1891,7 @@ class PlaidClient {
        * needs a sign-in token.
        * @param {string} userId - The user ID who owns the token
        * @param {string} tokenId - The token ID to revoke
+       * @param {string} [auditMessage] - Audit message for this write
        */
       revoke: (userId, tokenId, auditMessage) =>
         this._request("DELETE", `/api/v1/users/${userId}/tokens/${tokenId}`, {
@@ -1589,6 +1909,7 @@ class PlaidClient {
        * @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)
+       * @returns {Promise<Invite[]>}
        */
       list: ({ projectId, all } = {}) =>
         listAll(this, "/api/v1/invites", {
@@ -1601,7 +1922,7 @@ class PlaidClient {
        * @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)}>}
+       * @returns {Promise<Page<Invite>>}
        */
       listPage: ({ projectId, all, limit, cursor } = {}) =>
         listPage(this, "/api/v1/invites", {
@@ -1615,7 +1936,7 @@ 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
-       * @returns {AsyncGenerator<Array>}
+       * @returns {AsyncGenerator<Invite[]>}
        */
       iterPages: ({ projectId, all, pageSize } = {}) =>
         iterPages(this, "/api/v1/invites", {
@@ -1648,7 +1969,8 @@ class PlaidClient {
        * @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}>}
+       * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<Invite & {code: string}>}
        */
       create: (
         {
@@ -1681,6 +2003,7 @@ class PlaidClient {
        * Revoke an invite, killing the link immediately. Idempotent. Allowed for
        * the creator, an admin, or a maintainer of the invite's project.
        * @param {string} id - The invite ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       revoke: (id, auditMessage) =>
         this._request("DELETE", `/api/v1/invites/${id}`, { auditMessage }),
@@ -1693,7 +2016,7 @@ class PlaidClient {
        * 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}>}
+       * @returns {Promise<ServerReport>}
        */
       server: () => this._request("GET", "/api/v1/admin/server"),
       /**
@@ -1707,7 +2030,7 @@ class PlaidClient {
        * rather than the client's usual timeout. A proxy in front of the server
        * may still give up first (a 504): the backup goes on, and its file
        * shows in `server().backup.backups` once it is written.
-       * @returns {Promise<{ok: boolean, directory: string, backups: Array}>}
+       * @returns {Promise<BackupStatus>}
        *
        * 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).
@@ -1727,6 +2050,7 @@ class PlaidClient {
        * 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
+       * @returns {Promise<{result: string}>}
        */
       releaseLock: (documentId) =>
         this._request("DELETE", `/api/v1/admin/locks/${documentId}`, {
@@ -1736,7 +2060,7 @@ class PlaidClient {
        * 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}>}
+       * @returns {Promise<RateLimitSnapshot>}
        */
       rateLimits: () => this._request("GET", "/api/v1/admin/rate-limits"),
       /**
@@ -1746,6 +2070,7 @@ class PlaidClient {
        * @param {object} [opts]
        * @param {string} [opts.ip] - Clear only this address
        * @param {string} [opts.userId] - Narrow to one account on that address
+       * @returns {Promise<{result: string}>}
        */
       clearRateLimits: ({ ip, userId } = {}) =>
         this._request("DELETE", "/api/v1/admin/rate-limits", {
@@ -1769,7 +2094,7 @@ class PlaidClient {
        * @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)}>}
+       * @returns {Promise<LiveLog>}
        */
       logs: ({ limit, q, level, status, user, method } = {}) =>
         this._request("GET", "/api/v1/admin/logs", {
@@ -1803,7 +2128,7 @@ class PlaidClient {
        * @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?: *}>>}
+       * @returns {Promise<AdminUserDataEntry[]>}
        */
       userData: ({ prefix, pattern, includeValues } = {}) =>
         listAll(this, "/api/v1/admin/user-data", {
@@ -1822,7 +2147,7 @@ class PlaidClient {
        * @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)}>}
+       * @returns {Promise<Page<AdminUserDataEntry>>}
        */
       userDataPage: ({ prefix, pattern, includeValues, limit, cursor } = {}) =>
         listPage(this, "/api/v1/admin/user-data", {
@@ -1863,6 +2188,10 @@ class PlaidClient {
       /**
        * Fetch a single page of the instance-wide audit log. Admin only.
        * @param {object} [opts]
+       * @param {string} [opts.startTime] - Only entries at or after this instant
+       * @param {string} [opts.endTime] - Only entries at or before this instant
+       * @param {string[]|string} [opts.opTypes] - Only these op types
+       * @param {OperationKind[]|string} [opts.kinds] - Only the entries of operations of these kinds, each whole
        * @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)
@@ -1889,6 +2218,12 @@ class PlaidClient {
         }),
       /**
        * Async-iterate the instance-wide audit log page by page. Admin only.
+       * @param {object} [opts]
+       * @param {string} [opts.startTime] - Only entries at or after this instant
+       * @param {string} [opts.endTime] - Only entries at or before this instant
+       * @param {string[]|string} [opts.opTypes] - Only these op types
+       * @param {OperationKind[]|string} [opts.kinds] - Only the entries of operations of these kinds, each whole
+       * @param {number} [opts.pageSize] - Per-request page size
        * @returns {AsyncGenerator<Array>}
        */
       iterPages: ({ startTime, endTime, opTypes, kinds, pageSize } = {}) =>
@@ -1917,7 +2252,7 @@ class PlaidClient {
        * @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}>>}
+       * @returns {Promise<ActivityTallyRow[]>}
        */
       tally: async ({ projectId, startTime, endTime, daily } = {}) => {
         const path = projectId
@@ -1935,22 +2270,16 @@ class PlaidClient {
     };
 
     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 }),
-        }),
+      ...layerMethods(this, "token-layers"),
       /**
        * 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).
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {object} [opts]
+       * @param {string} [opts.id] - The new entity's id, minted by the caller (see uuidv7)
        */
       create: (
         textLayerId,
@@ -1960,71 +2289,18 @@ class PlaidClient {
         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}`, {
+        this._request("POST", "/api/v1/token-layers", {
           auditMessage,
-          body: bodyOf({ name }),
+          body: bodyOf({
+            id,
+            "text-layer-id": textLayerId,
+            name,
+            "overlap-mode": overlapMode,
+            "parent-token-layer-id": parentTokenLayerId,
+          }),
         }),
+      ...configMethods(this, "token-layers"),
+      ...constraintMethods(this, "token-layers"),
     };
 
     this.documents = {
@@ -2071,6 +2347,7 @@ class PlaidClient {
        * outOfBand, for the same reason as acquireLock.
        * @param {string} documentId - The document ID
        * @param {string} lockId - The `lockId` acquireLock answered with
+       * @param {string} [auditMessage] - Audit message for this write
        */
       renewLock: (documentId, lockId, auditMessage) =>
         this._request("POST", `/api/v1/documents/${documentId}/lock`, {
@@ -2085,6 +2362,7 @@ class PlaidClient {
        * and not released at all if it aborts.
        * @param {string} documentId - The document ID
        * @param {string} lockId - The `lockId` acquireLock answered with
+       * @param {string} [auditMessage] - Audit message for this write
        */
       releaseLock: (documentId, lockId, auditMessage) =>
         this._request("DELETE", `/api/v1/documents/${documentId}/lock`, {
@@ -2128,9 +2406,11 @@ class PlaidClient {
        * 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.
+       * @template T
        * @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)
+       * @param {(lock: import("./documentLock.js").DocumentLock) => T | Promise<T>} fn - The work to run while holding it
+       * @param {{keepAlive?: boolean}} [options] - `{ keepAlive }`: renew on a timer (default true)
+       * @returns {Promise<T>}
        */
       locked: (documentId, fn, options) =>
         withDocumentLock(this, documentId, fn, options),
@@ -2139,22 +2419,45 @@ class PlaidClient {
        * 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
+       * @returns {Promise<ArrayBuffer>}
        */
       getMedia: (documentId) =>
         this._request("GET", `/api/v1/documents/${documentId}/media`, {
           binaryResponse: true,
         }),
+      /**
+       * Get a link that plays the document's recording without an
+       * Authorization header, for an audio or video element's `src`, which
+       * cannot send one. `url` is the document's media URL with a
+       * `media-token` added, resolved against the client's base URL. The token
+       * opens only this recording, for this user, and the server refuses it on
+       * every other route. It expires at `expiresAt` (an ISO-8601 instant, six
+       * hours on by default), and sooner when the user signs out, changes
+       * password or loses access to the project: ask for a new link then. A
+       * document with no recording is a 404. Writes nothing, so it takes no
+       * Idempotency-Key and goes over the wire when made on a batch.
+       * @param {string} documentId - The document ID
+       * @returns {Promise<{url: string, expiresAt: string}>}
+       */
+      mediaLink: async (documentId) => {
+        const link = await this._request(
+          "POST",
+          `/api/v1/documents/${documentId}/media/link`,
+          { outOfBand: true },
+        );
+        return { ...link, url: `${this.baseUrl}${link.url}` };
+      },
       /**
        * Upload a media file for a document. Uses Apache Tika for content validation.
        * A document that already has a recording refuses it with a 409
        * (`media-exists`, and the current `media-url`): delete that one first.
-       * A WAV whose samples are not PCM or float (IMA or MS ADPCM, GSM, A-law
-       * and the rest), which browsers cannot play, is refused with a 415
-       * whose `error` names its coding.
+       * A WAV whose samples are not PCM, 32-bit float, A-law or mu-law (IMA or
+       * MS ADPCM, GSM, 64-bit float and the rest), which browsers cannot play,
+       * is refused with a 415 whose `error` names its coding.
        * @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.
+       * @param {{onProgress?: (progress: {loaded: number, total: number | null}) => void}} [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, { onProgress } = {}) => {
         const fd = new FormData();
@@ -2186,37 +2489,14 @@ class PlaidClient {
           auditMessage,
           queryParams: { "media-version": mediaVersion },
         }),
-      /**
-       * Replace all metadata for a document.
-       * @param {string} documentId - The document ID
-       * @param {any} body - The request body
-       */
-      setMetadata: (documentId, body, auditMessage) =>
-        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,
-        }),
-      /**
-       * 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 {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,
-        }),
+      ...metadataMethods(this, "documents"),
       /**
        * Get audit log for a document. Transparently follows pagination cursors
-       * and returns the full flat array.
+       * and returns the full flat array. Each entry, and each of its `ops`,
+       * says what kind of credential made it as `credential`: `login`,
+       * `named-token` or `delegated` (absent on older operations, `service`
+       * on some from 2026-10-06 to 2026-10-08),
+       * beside `apiToken` (the named token's id and name) when there was one.
        * @param {string} documentId - The document ID
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
@@ -2242,6 +2522,10 @@ class PlaidClient {
        * that may be long: audit() walks every page before it resolves.
        * @param {string} documentId - The document ID
        * @param {object} [opts]
+       * @param {string} [opts.startTime] - Only entries at or after this instant
+       * @param {string} [opts.endTime] - Only entries at or before this instant
+       * @param {string[]|string} [opts.opTypes] - Only these op types
+       * @param {OperationKind[]|string} [opts.kinds] - Only the entries of operations of these kinds, each whole
        * @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
@@ -2278,7 +2562,7 @@ class PlaidClient {
        * @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
+       * @param {{dryRun?: boolean}} [options] - `{ dryRun }`: with `dryRun` true nothing
        *   is written and the summary says what would change
        * @param {string} [auditMessage] - Custom audit message for this operation
        */
@@ -2316,6 +2600,7 @@ class PlaidClient {
       /**
        * Delete a document and all data contained.
        * @param {string} documentId - The document ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       delete: (documentId, auditMessage) =>
         this._request("DELETE", `/api/v1/documents/${documentId}`, {
@@ -2325,6 +2610,7 @@ class PlaidClient {
        * Update a document's name.
        * @param {string} documentId - The document ID
        * @param {string} name - The name
+       * @param {string} [auditMessage] - Audit message for this write
        */
       update: (documentId, name, auditMessage) =>
         this._request("PATCH", `/api/v1/documents/${documentId}`, {
@@ -2336,6 +2622,9 @@ class PlaidClient {
        * @param {string} projectId - The project ID
        * @param {string} name - The name
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {object} [opts]
+       * @param {string} [opts.id] - The new entity's id, minted by the caller (see uuidv7)
        */
       create: (projectId, name, metadata, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/documents", {
@@ -2352,9 +2641,10 @@ class PlaidClient {
        * 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
+       * @param {{includeMedia?: boolean, id?: string}} [options] - `{ includeMedia }`: false leaves the media
        *   file behind
        * @param {string} [auditMessage] - Custom audit message for this operation
+       * @returns {Promise<{id: string, mediaError?: string}>}
        */
       copy: (documentId, name, { includeMedia, id } = {}, auditMessage) =>
         this._request("POST", `/api/v1/documents/${documentId}/copy`, {
@@ -2368,6 +2658,7 @@ class PlaidClient {
        * Set a user's access level to read and write for this project.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       addWriter: (id, userId, auditMessage) =>
         this._request("POST", `/api/v1/projects/${id}/writers/${userId}`, {
@@ -2377,6 +2668,7 @@ class PlaidClient {
        * Remove a user's writer privileges for this project.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       removeWriter: (id, userId, auditMessage) =>
         this._request("DELETE", `/api/v1/projects/${id}/writers/${userId}`, {
@@ -2386,6 +2678,7 @@ class PlaidClient {
        * Set a user's access level to read-only for this project.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       addReader: (id, userId, auditMessage) =>
         this._request("POST", `/api/v1/projects/${id}/readers/${userId}`, {
@@ -2395,45 +2688,18 @@ class PlaidClient {
        * Remove a user's reader privileges for this project.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       removeReader: (id, 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, 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, options) =>
-        this._request(
-          "DELETE",
-          `/api/v1/projects/${id}/config/${namespace}/${configKey}`,
-          configRequest(auditMessage, undefined, options, true),
-        ),
+      ...configMethods(this, "projects"),
       /**
        * Assign a user as a maintainer for this project.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       addMaintainer: (id, userId, auditMessage) =>
         this._request("POST", `/api/v1/projects/${id}/maintainers/${userId}`, {
@@ -2443,6 +2709,7 @@ class PlaidClient {
        * Remove a user's maintainer privileges for this project.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       removeMaintainer: (id, userId, auditMessage) =>
         this._request(
@@ -2452,7 +2719,11 @@ class PlaidClient {
         ),
       /**
        * Get audit log for a project. Transparently follows pagination cursors
-       * and returns the full flat array.
+       * and returns the full flat array. Each entry, and each of its `ops`,
+       * says what kind of credential made it as `credential`: `login`,
+       * `named-token` or `delegated` (absent on older operations, `service`
+       * on some from 2026-10-06 to 2026-10-08),
+       * beside `apiToken` (the named token's id and name) when there was one.
        * @param {string} projectId - The project ID
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
@@ -2478,6 +2749,10 @@ class PlaidClient {
        * that may be long: audit() walks every page before it resolves.
        * @param {string} projectId - The project ID
        * @param {object} [opts]
+       * @param {string} [opts.startTime] - Only entries at or after this instant
+       * @param {string} [opts.endTime] - Only entries at or before this instant
+       * @param {string[]|string} [opts.opTypes] - Only these op types
+       * @param {OperationKind[]|string} [opts.kinds] - Only the entries of operations of these kinds, each whole
        * @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
@@ -2522,6 +2797,7 @@ class PlaidClient {
        * Link a vocabulary to a project.
        * @param {string} id - The resource ID
        * @param {string} vocabId - The vocab layer ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       linkVocab: (id, vocabId, auditMessage) =>
         this._request("POST", `/api/v1/projects/${id}/vocabs/${vocabId}`, {
@@ -2531,6 +2807,7 @@ class PlaidClient {
        * Unlink a vocabulary from a project.
        * @param {string} id - The resource ID
        * @param {string} vocabId - The vocab layer ID
+       * @param {string} [auditMessage] - Audit message for this write
        */
       unlinkVocab: (id, vocabId, auditMessage) =>
         this._request("DELETE", `/api/v1/projects/${id}/vocabs/${vocabId}`, {
@@ -2596,6 +2873,7 @@ class PlaidClient {
        * Update a project's name.
        * @param {string} id - The resource ID
        * @param {string} name - The name
+       * @param {string} [auditMessage] - Audit message for this write
        */
       update: (id, name, auditMessage) =>
         this._request("PATCH", `/api/v1/projects/${id}`, {
@@ -2632,6 +2910,9 @@ class PlaidClient {
       /**
        * Create a new project. Note: this also registers the user as a maintainer.
        * @param {string} name - The name
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {object} [opts]
+       * @param {string} [opts.id] - The new entity's id, minted by the caller (see uuidv7)
        */
       create: (name, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/projects", {
@@ -2641,74 +2922,15 @@ class PlaidClient {
     };
 
     this.textLayers = {
-      /**
-       * Set a configuration value for a layer in an editor namespace.
-       * @param {string} textLayerId - The text 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: (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, 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
-       */
-      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,
-        }),
-      /**
-       * 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,
-          body: bodyOf({ name }),
-        }),
-      /**
-       * Shift a text layer's display order within the project.
-       * @param {string} textLayerId - The text layer ID
-       * @param {string} direction - The direction ("up" or "down")
-       */
-      shift: (textLayerId, direction, auditMessage) =>
-        this._request("POST", `/api/v1/text-layers/${textLayerId}/shift`, {
-          auditMessage,
-          body: bodyOf({ direction }),
-        }),
+      ...configMethods(this, "text-layers"),
+      ...layerMethods(this, "text-layers"),
       /**
        * Create a new text layer for a project.
        * @param {string} projectId - The project ID
        * @param {string} name - The name
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {object} [opts]
+       * @param {string} [opts.id] - The new entity's id, minted by the caller (see uuidv7)
        */
       create: (projectId, name, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/text-layers", {
@@ -2718,39 +2940,15 @@ class PlaidClient {
     };
 
     this.vocabItems = {
-      /**
-       * Replace all metadata for a vocab item.
-       * @param {string} id - The resource ID
-       * @param {any} body - The request body
-       */
-      setMetadata: (id, body, auditMessage) =>
-        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,
-        }),
-      /**
-       * 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 {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,
-        }),
+      ...metadataMethods(this, "vocab-items"),
       /**
        * Create a new vocab item
        * @param {string} vocabLayerId - The vocab layer ID
        * @param {string} form - The vocab item form
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {object} [opts]
+       * @param {string} [opts.id] - The new entity's id, minted by the caller (see uuidv7)
        */
       create: (vocabLayerId, form, metadata, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/vocab-items", {
@@ -2761,6 +2959,8 @@ class PlaidClient {
        * Create multiple vocab items in a single operation. Entries may target
        * different vocab layers; the user must have write access to each.
        * @param {Array<{vocabLayerId: string, form: string, metadata?: any}>} body - The vocab items to create
+       * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<{ids: string[]}>}
        */
       bulkCreate: (body, auditMessage) =>
         this._request("POST", "/api/v1/vocab-items/bulk", {
@@ -2771,6 +2971,7 @@ class PlaidClient {
        * 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.
+       * @param {string} [auditMessage] - Audit message for this write
        * @returns {Promise<{count: number}>} How many vocab items were updated.
        */
       bulkUpdate: (body, auditMessage) =>
@@ -2785,6 +2986,8 @@ class PlaidClient {
        * 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
+       * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       bulkDelete: (body, auditMessage) =>
         this._request("DELETE", "/api/v1/vocab-items/bulk", {
@@ -2827,6 +3030,7 @@ class PlaidClient {
        * Needs maintainer rights on the vocabulary.
        * @param {string} survivorId - The entry that stays
        * @param {string[]} loserIds - The entries merged into it
+       * @param {string} [auditMessage] - Audit message for this write
        * @returns {Promise<{moved: number, duplicates: number, removed: string[]}>}
        */
       merge: (survivorId, loserIds, auditMessage) =>
@@ -2841,6 +3045,7 @@ class PlaidClient {
        * from the response.
        * @param {string} id - The resource ID
        * @param {string} form - The vocab item form
+       * @param {string} [auditMessage] - Audit message for this write
        */
       update: (id, form, auditMessage) =>
         this._request("PATCH", `/api/v1/vocab-items/${id}`, {
@@ -2850,82 +3055,22 @@ class PlaidClient {
     };
 
     this.relationLayers = {
-      /**
-       * Shift a relation layer's display order.
-       * @param {string} relationLayerId - The relation layer ID
-       * @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 }) },
-        ),
+      ...layerMethods(this, "relation-layers"),
       /**
        * Create a new relation layer.
        * @param {string} spanLayerId - The span layer ID
        * @param {string} name - The name
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {object} [opts]
+       * @param {string} [opts.id] - The new entity's id, minted by the caller (see uuidv7)
        */
       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.
-       * @param {string} relationLayerId - The relation 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: (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, options) =>
-        this._request(
-          "DELETE",
-          `/api/v1/relation-layers/${relationLayerId}/config/${namespace}/${configKey}`,
-          configRequest(auditMessage, undefined, options, true),
-        ),
+      ...configMethods(this, "relation-layers"),
       ...constraintMethods(this, "relation-layers"),
-      /**
-       * Get a relation layer by ID.
-       * @param {string} relationLayerId - The relation layer ID
-       */
-      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,
-        }),
-      /**
-       * 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,
-          body: bodyOf({ name }),
-        }),
     };
 
     this.tokens = {
@@ -2946,6 +3091,9 @@ class PlaidClient {
        * @param {number} end - End offset, exclusive (Unicode code points)
        * @param {number} [precedence] - Ordering precedence
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {object} [opts]
+       * @param {string} [opts.id] - The new entity's id, minted by the caller (see uuidv7)
        */
       create: (
         tokenLayerId,
@@ -2979,6 +3127,7 @@ class PlaidClient {
        * 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
+       * @param {string} [auditMessage] - Audit message for this write
        */
       delete: (tokenId, auditMessage) =>
         this._request("DELETE", `/api/v1/tokens/${tokenId}`, { auditMessage }),
@@ -2991,6 +3140,7 @@ class PlaidClient {
        *   to leave unchanged; pass a number to set; pass null explicitly to
        *   CLEAR it (revert to no explicit ordering). bodyOf keeps null but
        *   drops undefined, so the three cases map correctly to the server.
+       * @param {string} [auditMessage] - Audit message for this write
        */
       update: (tokenId, begin, end, precedence, auditMessage) =>
         this._request("PATCH", `/api/v1/tokens/${tokenId}`, {
@@ -3000,6 +3150,7 @@ class PlaidClient {
       /**
        * Create multiple tokens in a single operation.
        * @param {Array} body - The request body
+       * @param {string} [auditMessage] - Audit message for this write
        * @returns {Promise<{ids: string[]}>} The created entity IDs, in input order. (bulkDelete resolves to no value.)
        */
       bulkCreate: (body, auditMessage) =>
@@ -3007,12 +3158,15 @@ class PlaidClient {
       /**
        * Delete multiple tokens in a single operation. Provide an array of IDs.
        * @param {Array} body - The request body
+       * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       bulkDelete: (body, auditMessage) =>
         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.
+       * @param {string} [auditMessage] - Audit message for this write
        * @returns {Promise<{count: number}>} How many tokens were updated.
        */
       bulkUpdate: (body, auditMessage) =>
@@ -3051,6 +3205,7 @@ class PlaidClient {
        * merged extent must not engulf a third token.
        * @param {string} tokenId - The anchor token ID
        * @param {string} otherTokenId - The other token to merge in
+       * @param {string} [auditMessage] - Audit message for this write
        */
       merge: (tokenId, otherTokenId, auditMessage) =>
         this._request("POST", `/api/v1/tokens/${tokenId}/merge`, {
@@ -3064,49 +3219,23 @@ class PlaidClient {
        * @param {string} tokenId - The token ID
        * @param {number} [begin] - New start offset, inclusive (Unicode code points)
        * @param {number} [end] - New end offset, exclusive (Unicode code points)
+       * @param {string} [auditMessage] - Audit message for this write
        */
       shift: (tokenId, begin, end, auditMessage) =>
         this._request("POST", `/api/v1/tokens/${tokenId}/shift`, {
           auditMessage,
           body: bodyOf({ begin, end }),
         }),
-      /**
-       * Replace all metadata for a token.
-       * @param {string} tokenId - The token ID
-       * @param {any} body - The request body
-       */
-      setMetadata: (tokenId, body, auditMessage) =>
-        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,
-        }),
-      /**
-       * 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 {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,
-        }),
+      ...metadataMethods(this, "tokens"),
     };
 
     this.messages = {
       /**
        * Open a Server-Sent Events stream for a project.
        * @param {string} projectId - The UUID of the project to listen to
-       * @param {function} onEvent - Callback function that receives (eventType, data). If it returns true, listening will stop.
+       * @param {(eventType: string, data: any) => void | boolean} onEvent - Callback function that receives (eventType, data). If it returns true, listening will stop.
        * @param {string} [path] - Stream path under baseUrl (defaults to the project /listen bus; service channels pass their own).
-       * @returns {Object} SSE connection object with .close() and .getStats() methods
+       * @returns {SSEConnection} SSE connection object with .close() and .getStats() methods
        */
       listen: (projectId, onEvent, path) =>
         createSSEConnection(this, projectId, onEvent, path),
@@ -3139,7 +3268,7 @@ class PlaidClient {
        * connected services carry `online: true`; previously-seen offline ones
        * carry `online: false` plus a `lastSeenAt` stamp.
        * @param {string} projectId - The UUID of the project to query
-       * @returns {Promise<Array>} Array of discovered service information
+       * @returns {Promise<DiscoveredService[]>} Array of discovered service information
        */
       discoverServices: (projectId) => discoverServices(this, projectId),
 
@@ -3159,14 +3288,14 @@ class PlaidClient {
        * 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 {ServiceInfo} serviceInfo - Service information {serviceId, serviceName, description}
+       * @param {(data: any, responseHelper: ResponseHelper) => void} onServiceRequest - Callback (data, responseHelper)
        * @param {Object} [extras] - Optional additional service metadata
-       * @param {function} [onStatus] - Optional callback (event, projectId, detail) for
+       * @param {(event: ServiceStatusEvent, projectId: string, detail?: string) => void} [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()
+       * @returns {ServiceRegistration} Service registration with .stop(), .isRunning(), .isConnected()
        */
       serve: (projectId, serviceInfo, onServiceRequest, extras, onStatus) =>
         serve(this, projectId, serviceInfo, onServiceRequest, extras, onStatus),
@@ -3187,7 +3316,7 @@ class PlaidClient {
        * @param {number} [timeout=10000] - Timeout in ms
        * @param {function} [onProgress] - Called with each progress payload {percent, message}
        * @param {AbortSignal} [signal] - Abort to stop waiting; rejects with an AbortError
-       * @param {Object} [opts] - {requestId, onAccepted, projectIds, noOperation}
+       * @param {{requestId?: string, onAccepted?: (requestId: string) => void, projectIds?: string[], noOperation?: boolean}} [opts] - {requestId, onAccepted, projectIds, noOperation}
        * @returns {Promise<any>} The service's result
        */
       requestService: (
@@ -3332,11 +3461,13 @@ class PlaidClient {
        * 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 {CommentableType} 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)
+       * @param {string} [opts.id] - The new comment's id, minted by the caller (see uuidv7)
+       * @returns {Promise<Comment>}
        */
       create: (entityType, entityId, body, { anchorLabel, id } = {}) =>
         this._request("POST", "/api/v1/comments", {
@@ -3354,6 +3485,7 @@ class PlaidClient {
       /**
        * Read one comment.
        * @param {string} id - The comment id
+       * @returns {Promise<Comment>}
        */
       get: (id) => this._request("GET", `/api/v1/comments/${id}`),
       /**
@@ -3361,6 +3493,7 @@ class PlaidClient {
        * maintainers, not admins. Sets `edited` on the comment.
        * @param {string} id - The comment id
        * @param {string} body - The replacement text
+       * @returns {Promise<Comment>}
        */
       update: (id, body) =>
         this._request("PATCH", `/api/v1/comments/${id}`, {
@@ -3382,6 +3515,7 @@ class PlaidClient {
        * @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
+       * @returns {Promise<Comment[]>}
        */
       list: (projectId, { documentId, entityType, entityId } = {}) =>
         listAll(this, `/api/v1/projects/${projectId}/comments`, {
@@ -3400,7 +3534,7 @@ class PlaidClient {
        * @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)}>}
+       * @returns {Promise<Page<Comment>>}
        */
       listPage: (
         projectId,
@@ -3423,7 +3557,7 @@ class PlaidClient {
        * @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>}
+       * @returns {AsyncGenerator<Comment[]>}
        */
       iterPages: (
         projectId,
@@ -3446,7 +3580,7 @@ class PlaidClient {
        * 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()
+       * @param {{documentId?: string, entityType?: CommentableType, entityId?: string}} [filters] - Same filters as list()
        * @returns {Promise<Object<string, number>>}
        */
       counts: (projectId, { documentId, entityType, entityId } = {}) =>
@@ -3465,6 +3599,7 @@ class PlaidClient {
        * @param {string} vocabId - The vocab layer to read
        * @param {object} [filters]
        * @param {string} [filters.entityId] - One entry's thread
+       * @returns {Promise<Comment[]>}
        */
       listInVocab: (vocabId, { entityId } = {}) =>
         listAll(this, `/api/v1/vocab-layers/${vocabId}/comments`, {
@@ -3477,7 +3612,7 @@ class PlaidClient {
        * @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)}>}
+       * @returns {Promise<Page<Comment>>}
        */
       listInVocabPage: (vocabId, { limit, cursor, entityId } = {}) =>
         listPage(this, `/api/v1/vocab-layers/${vocabId}/comments`, {
@@ -3492,7 +3627,7 @@ class PlaidClient {
        * @param {object} [opts]
        * @param {string} [opts.entityId] - One entry's thread
        * @param {number} [opts.pageSize] - Per-request page size
-       * @returns {AsyncGenerator<Array>}
+       * @returns {AsyncGenerator<Comment[]>}
        */
       iterInVocabPages: (vocabId, { entityId, pageSize } = {}) =>
         iterPages(this, `/api/v1/vocab-layers/${vocabId}/comments`, {
@@ -3520,15 +3655,15 @@ class PlaidClient {
 
     this.events = {
       /**
-       * Record one research-telemetry event (core manual, "Research
-       * telemetry"). Fire and forget: the event is buffered and sent with
+       * Record one research-telemetry event (plaid-core sql/client_event.clj).
+       * 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 {ClientEventType} 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
@@ -3539,6 +3674,7 @@ class PlaidClient {
       record: (type, fields) => recorderFor(this).record(this, type, fields),
       /**
        * Send what the recorder holds now, rather than at its next interval.
+       * @returns {void}
        */
       flush: () => recorderFor(this).flush(),
       /**
@@ -3546,6 +3682,7 @@ class PlaidClient {
        * maintainer changed it. Turning it off drops what is buffered.
        * @param {string} projectId - The project
        * @param {boolean} on - Whether telemetry is on
+       * @returns {void}
        */
       setEnabled: (projectId, on) => recorderFor(this).setEnabled(projectId, on),
       /**
@@ -3570,6 +3707,7 @@ class PlaidClient {
        * @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
+       * @returns {Promise<ClientEvent[]>}
        */
       list: (projectId, { types, startTime, endTime } = {}) =>
         listAll(this, `/api/v1/projects/${projectId}/events`, {
@@ -3584,7 +3722,7 @@ class PlaidClient {
        * @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)}>}
+       * @returns {Promise<Page<ClientEvent>>}
        */
       listPage: (
         projectId,
@@ -3603,7 +3741,7 @@ class PlaidClient {
        * @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>}
+       * @returns {AsyncGenerator<ClientEvent[]>}
        */
       iterPages: (projectId, { pageSize, types, startTime, endTime } = {}) =>
         iterPages(this, `/api/v1/projects/${projectId}/events`, {
@@ -3624,6 +3762,9 @@ class PlaidClient {
        * @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
+       * @param {string} [opts.id] - The new guideline's id, minted by the caller (see uuidv7)
+       * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<{id: string}>}
        */
       create: (projectId, title, { body, pinned, id } = {}, auditMessage) =>
         this._request("POST", `/api/v1/projects/${projectId}/guidelines`, {
@@ -3633,6 +3774,7 @@ class PlaidClient {
       /**
        * Read one guideline, Markdown body included.
        * @param {string} id - The guideline id
+       * @returns {Promise<Guideline>}
        */
       get: (id) => this._request("GET", `/api/v1/guidelines/${id}`),
       /**
@@ -3649,6 +3791,8 @@ class PlaidClient {
        * @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
+       * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<Guideline>}
        */
       update: (
         id,
@@ -3663,6 +3807,7 @@ class PlaidClient {
       /**
        * Delete a guideline.
        * @param {string} id - The guideline id
+       * @param {string} [auditMessage] - Audit message for this write
        */
       delete: (id, auditMessage) =>
         this._request("DELETE", `/api/v1/guidelines/${id}`, { auditMessage }),
@@ -3677,6 +3822,7 @@ class PlaidClient {
        * @param {string} projectId - The project to read
        * @param {object} [opts]
        * @param {boolean} [opts.includeBodies] - Return each body instead of its length
+       * @returns {Promise<Guideline[]>}
        */
       list: (projectId, { includeBodies } = {}) =>
         listAll(this, `/api/v1/projects/${projectId}/guidelines`, {
@@ -3689,7 +3835,7 @@ class PlaidClient {
        * @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)}>}
+       * @returns {Promise<Page<Guideline>>}
        */
       listPage: (projectId, { limit, cursor, includeBodies } = {}) =>
         listPage(this, `/api/v1/projects/${projectId}/guidelines`, {
@@ -3703,7 +3849,7 @@ class PlaidClient {
        * @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>}
+       * @returns {AsyncGenerator<Guideline[]>}
        */
       iterPages: (projectId, { pageSize, includeBodies } = {}) =>
         iterPages(this, `/api/v1/projects/${projectId}/guidelines`, {
@@ -3715,6 +3861,7 @@ class PlaidClient {
 
   // --- Core methods ---
 
+  /** @private */
   async _request(method, path, options = {}) {
     return makeRequest(this, method, path, options);
   }
@@ -3777,7 +3924,7 @@ class PlaidClient {
    * matching end, and the outer numbering resumes after it.
    *
    * @param {string} message - Human label for the operation.
-   * @param {object} [opts] - Optional `{ groupId, kind, ref, keys, minted }`. `groupId` 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). Python's is `group_id`. `kind`, `ref` and `keys` are described above. `minted` is the ids the operation mints for what it creates: a create refused 409 id-taken for one of them was made by an earlier send of the operation, and answers as made.
+   * @param {{groupId?: string, kind?: OperationKind, ref?: string, keys?: KeySeed, minted?: Iterable<string>}} [opts] - Optional `{ groupId, kind, ref, keys, minted }`. `groupId` 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). Python's is `group_id`. `kind`, `ref` and `keys` are described above. `minted` is the ids the operation mints for what it creates: a create refused 409 id-taken for one of them was made by an earlier send of the operation, and answers as made.
    * @returns {string} The operation's group id.
    */
   beginOperation(message, { groupId, kind, ref, keys, minted } = {}) {
@@ -3809,7 +3956,7 @@ class PlaidClient {
       return open.id;
     }
     this.operationGroup = {
-      id: groupId ? String(groupId) : crypto.randomUUID(),
+      id: groupId ? String(groupId) : uuidv4(),
       message: message == null ? null : String(message),
       kind: kind == null ? null : String(kind),
       ref: ref == null ? null : String(ref),
@@ -3826,7 +3973,7 @@ class PlaidClient {
    * 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>}}
+   * @returns {KeySeed}
    */
   keySeed() {
     return { seed: uuidv7(), stamps: new Map() };
@@ -3881,10 +4028,11 @@ class PlaidClient {
    *
    *   await client.withOperation('Import ELAN corpus', run, { kind: 'import', ref: 'format:elan' });
    *
+   * @template T
    * @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, groupId, keys, minted }`, as for beginOperation. `kind` is one of `assistant-plan`, `service-run`, `import`, `bulk-edit`, `guess-adoption`, `repair` or `review`, and any other throws before `fn` runs.
-   * @returns {Promise<any>} Whatever `fn` resolves to.
+   * @param {(setMessage: (msg: string) => void) => T | Promise<T>} fn - The work to run; receives `setMessage(msg)` to refine the label once the outcome is known.
+   * @param {{kind?: OperationKind, ref?: string, groupId?: string, keys?: KeySeed, minted?: Iterable<string>}} [opts] - Optional `{ kind, ref, groupId, keys, minted }`, as for beginOperation. `kind` is one of `assistant-plan`, `service-run`, `import`, `bulk-edit`, `guess-adoption`, `repair` or `review`, and any other throws before `fn` runs.
+   * @returns {Promise<T>} Whatever `fn` resolves to.
    */
   async withOperation(message, fn, { kind, ref, groupId, keys, minted } = {}) {
     this.beginOperation(message, { kind, ref, groupId, keys, minted });
@@ -3939,7 +4087,7 @@ class PlaidClient {
    * 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
+   * @returns {PlaidBatch} the batch view
    */
   batch() {
     return openBatch(this);
@@ -3951,6 +4099,7 @@ class PlaidClient {
    * 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.
+   * @private
    */
   async _postBatch(url, body, { key = uuidv7() } = {}) {
     const fetchOptions = {
@@ -4083,8 +4232,8 @@ class PlaidClient {
    *
    * 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>}
+   * @param {(batch: PlaidBatch) => (void | Promise<void>)} fn
+   * @returns {Promise<any[]>}
    */
   async batched(fn) {
     const batch = this.batch();
@@ -4102,20 +4251,22 @@ class PlaidClient {
    * 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]
+   * @param {{timeout?: number | null}} [options]
+   * @returns {Promise<ServerHealth>}
    */
   static async health(baseUrl, options = {}) {
-    return anonymousGet(baseUrl, "/health", options);
+    return anonymousRequest("GET", baseUrl, "/health", undefined, 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]
+   * @param {{timeout?: number | null}} [options]
+   * @returns {Promise<{limits: ServerLimits}>}
    */
   static async info(baseUrl, options = {}) {
-    return anonymousGet(baseUrl, "/api/v1/info", options);
+    return anonymousRequest("GET", baseUrl, "/api/v1/info", undefined, options);
   }
 
   /**
@@ -4146,7 +4297,7 @@ class PlaidClient {
    * @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/invites/lookup", { code }, options);
+    return anonymousRequest("POST", baseUrl, "/api/v1/invites/lookup", { code }, options);
   }
 
   /**
@@ -4175,10 +4326,16 @@ class PlaidClient {
     { email, password, displayName } = {},
     options = {},
   ) {
-    const data = await anonymousPost(
+    const data = await anonymousRequest(
+      "POST",
       baseUrl,
       "/api/v1/invites/redeem",
-      bodyOf({ code, email, password, "display-name": displayName }),
+      bodyOf({
+        code,
+        email: normalizeUserId(email),
+        password,
+        "display-name": displayName,
+      }),
       options,
     );
     return {
@@ -4203,35 +4360,14 @@ class PlaidClient {
    */
   static async login(baseUrl, userId, password, options = {}) {
     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 }),
-      };
-      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",
-        );
-      }
-
-      const data = await response.json();
-      const token = data.token || "";
-      return new PlaidClient(baseUrl, token, options);
-    } catch (error) {
-      if (error.status) throw error;
-      throw makeNetworkError(error, url, "POST");
-    }
+    const data = await anonymousRequest(
+      "POST",
+      baseUrl,
+      "/api/v1/login",
+      { "user-id": normalizeUserId(userId), password },
+      options,
+    );
+    return new PlaidClient(baseUrl, data.token || "", options);
   }
 }
 
@@ -4259,9 +4395,129 @@ function configRequest(auditMessage, value, options, isDelete = false) {
   };
 }
 
+/**
+ * The three metadata methods of a bundle whose entities carry metadata, on
+ * `/api/v1/<kind>/<id>/metadata`. Metadata is opaque, so no body is re-cased.
+ * @param {PlaidClient} client
+ * @param {string} kind
+ */
+function metadataMethods(client, kind) {
+  const path = (id) => `/api/v1/${kind}/${id}/metadata`;
+  return {
+    /**
+     * Replace all metadata of an entity. Keys left out of the new map are removed.
+     * @param {string} id - The entity's ID
+     * @param {object} body - The new metadata map
+     * @param {string} [auditMessage] - Audit message for this write
+     */
+    setMetadata: (id, body, auditMessage) =>
+      client._request("PUT", path(id), { auditMessage, rawBody: body }),
+    /**
+     * Remove all metadata from an entity.
+     * @param {string} id - The entity's ID
+     * @param {string} [auditMessage] - Audit message for this write
+     */
+    deleteMetadata: (id, auditMessage) => client._request("DELETE", path(id), { auditMessage }),
+    /**
+     * Edit an entity's metadata 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 entity's ID
+     * @param {MetadataOp[]} body - The metadata ops
+     * @param {string} [auditMessage] - Audit message for this write
+     */
+    patchMetadata: (id, body, auditMessage) =>
+      client._request("PATCH", path(id), { auditMessage, rawBody: body }),
+  };
+}
+
+/**
+ * The two config methods of a bundle whose records carry editor config, on
+ * `/api/v1/<kind>/<id>/config/<namespace>/<key>`.
+ * @param {PlaidClient} client
+ * @param {string} kind
+ */
+function configMethods(client, kind) {
+  const path = (id, namespace, configKey) => `/api/v1/${kind}/${id}/config/${namespace}/${configKey}`;
+  return {
+    /**
+     * Set a configuration value in an editor namespace.
+     * @param {string} id - The record's 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, options) =>
+      client._request(
+        "PUT",
+        path(id, namespace, configKey),
+        configRequest(auditMessage, configValue, options),
+      ),
+    /**
+     * Remove a configuration value.
+     * @param {string} id - The record's 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, options) =>
+      client._request(
+        "DELETE",
+        path(id, namespace, configKey),
+        configRequest(auditMessage, undefined, options, true),
+      ),
+  };
+}
+
+/**
+ * The get, delete, update and shift methods of the four layer bundles, on
+ * `/api/v1/<kind>/<layerId>`.
+ * @param {PlaidClient} client
+ * @param {string} kind
+ */
+function layerMethods(client, kind) {
+  const path = (layerId) => `/api/v1/${kind}/${layerId}`;
+  return {
+    /**
+     * Get a layer by ID.
+     * @param {string} layerId - The layer ID
+     */
+    get: (layerId) => client._request("GET", path(layerId)),
+    /**
+     * Delete a layer.
+     * @param {string} layerId - The layer ID
+     * @param {string} [auditMessage] - Audit message for this write
+     */
+    delete: (layerId, auditMessage) => client._request("DELETE", path(layerId), { auditMessage }),
+    /**
+     * Rename a layer.
+     * @param {string} layerId - The layer ID
+     * @param {string} name - The new name
+     * @param {string} [auditMessage] - Audit message for this write
+     */
+    update: (layerId, name, auditMessage) =>
+      client._request("PATCH", path(layerId), { auditMessage, body: bodyOf({ name }) }),
+    /**
+     * Move a layer one place in its display order.
+     * @param {string} layerId - The layer ID
+     * @param {string} direction - The direction ("up" or "down")
+     * @param {string} [auditMessage] - Audit message for this write
+     */
+    shift: (layerId, direction, auditMessage) =>
+      client._request("POST", `${path(layerId)}/shift`, {
+        auditMessage,
+        body: bodyOf({ direction }),
+      }),
+  };
+}
+
 /**
  * The four layer-constraint methods of a layer bundle, on `/api/v1/<kind>`.
  * See constraints.js and the core manual, "Layer constraints".
+ * @param {PlaidClient} client
+ * @param {string} kind
  */
 function constraintMethods(client, kind) {
   const base = (layerId) => `/api/v1/${kind}/${layerId}/constraints`;
@@ -4272,12 +4528,12 @@ function constraintMethods(client, kind) {
      * 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 {LayerConstraint[]} 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
+     * @returns {Promise<{constraints: Record<string, LayerConstraint[]>}>} the layer's whole constraint map
      */
     setConstraints: (layerId, namespace, constraints, auditMessage, options) =>
       client._request("PUT", `${base(layerId)}/${namespace}`, {
@@ -4302,8 +4558,8 @@ function constraintMethods(client, kind) {
      * 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}>}
+     * @param {LayerConstraint[]} constraints - The list to check
+     * @returns {Promise<{violations: ConstraintViolation[], violationCount: number}>}
      */
     checkConstraints: (layerId, constraints) =>
       client._request("POST", `${base(layerId)}/check`, { body: { constraints } }),
@@ -4315,10 +4571,10 @@ function constraintMethods(client, kind) {
      * 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 {LayerConstraint[]} 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}>}
+     * @returns {Promise<{repaired: ConstraintRepair[], locked: Array<{document: string, lockedBy: string}>, violations: ConstraintViolation[], violationCount: number}>}
      */
     repairConstraints: (layerId, constraints, auditMessage, options) =>
       client._request("POST", `${base(layerId)}/repair`, {
@@ -4340,6 +4596,7 @@ export {
   cpSlicer,
   utf16ToCp,
   cpIndexOf,
+  composeText,
 } from "./codepoint.js";
 export { composeTextEdits, gapsToOps, applyTextOps } from "./textEdits.js";
 export {
@@ -4412,7 +4669,8 @@ export {
 // 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";
+// "Retrying a write". uuidv4 works where crypto.randomUUID does not (a page
+// served over plain HTTP from any host but localhost).
+export { uuidv4, uuidv7, normalizeUserId } from "./ids.js";
 export { wasReplayed } from "./replayed.js";
 export { MAX_BATCH_OPS };