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

package/src/index.js

@@ -161,6 +161,22 @@ import {
  * @typedef {{document: string, constraint: string, deleted: number, joined: number}} ConstraintRepair
  */
 
+/**
+ * A value-set rule as `refusedValues` takes it: the list, the characters a
+ * value is split on, and whether every part (`"all"`, the default) or only
+ * the first must be listed.
+ * @typedef {{values: string[], delimiters?: string, parts?: "all" | "first"}} ValueSetRule
+ */
+
+/**
+ * What a value-set rule would refuse in a layer's stored values: how many,
+ * how many distinct, and the most frequent with the parts not listed.
+ * @typedef {object} RefusedValues
+ * @property {number} count
+ * @property {number} valueCount
+ * @property {Array<{value: any, parts: string[], count: number}>} values
+ */
+
 /**
  * Entities that can carry a comment.
  * @typedef {"document" | "text" | "token" | "span" | "relation" | "vocab-item"} CommentableType
@@ -256,6 +272,7 @@ import {
  * @property {number} [userDataValueBytes]
  * @property {number} [guidelineTitleLength]
  * @property {number} [guidelineBodyLength]
+ * @property {number} [commentBodyLength]
  * @property {number} [passwordMinLength]
  * @property {number} [lockExpirationMs]
  */
@@ -322,11 +339,362 @@ import {
  * and one the server ended is named "StreamClosed".
  * @typedef {object} SSEConnection
  * @property {() => void} close
- * @property {() => any} getStats
+ * @property {() => SSEStats} getStats
  * @property {number} readyState
  * @property {(Error & {status?: number}) | null} error
  */
 
+/**
+ * How an SSE connection has fared so far. `events` counts what arrived by
+ * event type ("audit-log", "message", "heartbeat", "connected", "other").
+ * @typedef {object} SSEStats
+ * @property {number} durationSeconds
+ * @property {boolean} isConnected
+ * @property {boolean} isClosed
+ * @property {string | null} clientId
+ * @property {Record<string, number>} events
+ * @property {number} readyState
+ */
+
+/**
+ * A value a span or relation holds: a JSON scalar.
+ * @typedef {string | number | boolean | null} AtomicValue
+ */
+
+/**
+ * What a create answers: the new record's id.
+ * @typedef {{id: string}} Created
+ */
+
+/**
+ * A project. `textLayers` nests its layers in their display order, each
+ * with the layers built on it, and `vocabs` lists the vocabularies linked to
+ * it.
+ * @typedef {object} Project
+ * @property {string} id
+ * @property {string} name
+ * @property {Record<string, any>} config
+ * @property {string[]} readers
+ * @property {string[]} writers
+ * @property {string[]} maintainers
+ * @property {ProjectTextLayer[]} textLayers
+ * @property {ProjectVocab[]} vocabs
+ */
+
+/**
+ * @typedef {{id: string, name: string, config: Record<string, any>, tokenLayers: ProjectTokenLayer[]}} ProjectTextLayer
+ * @typedef {{id: string, name: string, config: Record<string, any>,
+ *   constraints: Record<string, LayerConstraint[]>, spanLayers: ProjectSpanLayer[]}} ProjectTokenLayer
+ * @typedef {{id: string, name: string, config: Record<string, any>,
+ *   constraints: Record<string, LayerConstraint[]>, relationLayers: ProjectRelationLayer[]}} ProjectSpanLayer
+ * @typedef {{id: string, name: string, config: Record<string, any>,
+ *   constraints: Record<string, LayerConstraint[]>}} ProjectRelationLayer
+ * @typedef {{id: string, name: string, maintainers: string[], config: Record<string, any>}} ProjectVocab
+ */
+
+/**
+ * A document. `version` rises by one on every write to it or its layers.
+ * A read with `includeBody` also carries `textLayers`, the document's
+ * annotation nested under each layer.
+ * @typedef {object} PlaidDocument
+ * @property {string} id
+ * @property {string} name
+ * @property {string} project
+ * @property {number} version
+ * @property {string} timeCreated
+ * @property {string} timeModified
+ * @property {Record<string, any>} [metadata]
+ * @property {DocumentTextLayer[]} [textLayers]
+ */
+
+/**
+ * A text layer as a document read nests it: `text` is null where the
+ * document has no text in this layer.
+ * @typedef {object} DocumentTextLayer
+ * @property {string} id
+ * @property {string} name
+ * @property {Record<string, any>} config
+ * @property {{id: string, document: string, body: string, digest: string,
+ *   metadata?: Record<string, any>} | null} text
+ * @property {DocumentTokenLayer[]} tokenLayers
+ */
+
+/**
+ * @typedef {object} DocumentTokenLayer
+ * @property {string} id
+ * @property {string} name
+ * @property {Record<string, any>} config
+ * @property {Record<string, LayerConstraint[]>} constraints
+ * @property {string} overlapMode
+ * @property {string | null} parentTokenLayer
+ * @property {Array<{id: string, begin: number, end: number, precedence: number | null,
+ *   metadata?: Record<string, any>}>} tokens
+ * @property {DocumentSpanLayer[]} spanLayers
+ * @property {Array<ProjectVocab & {vocabLinks: Array<{id: string, vocabItem: VocabItem,
+ *   tokens: string[], metadata?: Record<string, any>}>}>} vocabs
+ */
+
+/**
+ * @typedef {object} DocumentSpanLayer
+ * @property {string} id
+ * @property {string} name
+ * @property {Record<string, any>} config
+ * @property {Record<string, LayerConstraint[]>} constraints
+ * @property {Array<{id: string, value: AtomicValue, tokens: string[],
+ *   metadata?: Record<string, any>}>} spans
+ * @property {Array<ProjectRelationLayer & {relations: Array<{id: string, source: string,
+ *   target: string, value: AtomicValue, metadata?: Record<string, any>}>}>} relationLayers
+ */
+
+/**
+ * A text: one document's body in one text layer. `digest` names the body,
+ * as an edit's `base`.
+ * @typedef {object} PlaidText
+ * @property {string} id
+ * @property {string} body
+ * @property {string} document
+ * @property {string} layer
+ * @property {string} digest
+ * @property {Record<string, any>} [metadata]
+ */
+
+/**
+ * What a text write changed besides the body: the tokens whose extent
+ * moved (with `layer` and `text` on one the write made), the spans and
+ * vocabulary links whose tokens or value changed, and the ids of what it
+ * deleted.
+ * @typedef {object} TextReshape
+ * @property {Array<{id: string, begin: number, end: number, layer?: string, text?: string}>} tokens
+ * @property {Array<{id: string, tokens?: string[], value?: AtomicValue}>} spans
+ * @property {Array<{id: string, tokens: string[]}>} vocabLinks
+ * @property {{tokens: string[], spans: string[], relations: string[], vocabLinks: string[]}} deleted
+ */
+
+/**
+ * A token. `value` is the text it covers.
+ * @typedef {object} Token
+ * @property {string} id
+ * @property {string} text
+ * @property {number} begin
+ * @property {number} end
+ * @property {string} layer
+ * @property {string} document
+ * @property {number | null} precedence
+ * @property {string} value
+ * @property {Record<string, any>} [metadata]
+ */
+
+/**
+ * @typedef {object} Span
+ * @property {string} id
+ * @property {string} layer
+ * @property {string} document
+ * @property {AtomicValue} value
+ * @property {string[]} tokens
+ * @property {Record<string, any>} [metadata]
+ */
+
+/**
+ * A relation, from the span `source` to the span `target`.
+ * @typedef {object} Relation
+ * @property {string} id
+ * @property {string} layer
+ * @property {string} document
+ * @property {string} source
+ * @property {string} target
+ * @property {AtomicValue} value
+ * @property {Record<string, any>} [metadata]
+ */
+
+/**
+ * @typedef {object} VocabItem
+ * @property {string} id
+ * @property {string} layer
+ * @property {string} form
+ * @property {Record<string, any>} [metadata]
+ */
+
+/**
+ * A link from a vocabulary entry to the tokens of one occurrence.
+ * @typedef {object} VocabLink
+ * @property {string} id
+ * @property {string} vocabItem
+ * @property {string} document
+ * @property {string[]} tokens
+ * @property {Record<string, any>} [metadata]
+ */
+
+/**
+ * A vocabulary. `items` is there on a read made with `includeItems`.
+ * @typedef {object} VocabLayer
+ * @property {string} id
+ * @property {string} name
+ * @property {string} timeCreated
+ * @property {string} timeModified
+ * @property {Record<string, any>} config
+ * @property {string[]} maintainers
+ * @property {VocabItem[]} [items]
+ */
+
+/**
+ * @typedef {{id: string, name: string, project: string, config: Record<string, any>}} TextLayer
+ * @typedef {{id: string, name: string, textLayer: string, project: string, overlapMode: string,
+ *   parentTokenLayer: string | null, config: Record<string, any>,
+ *   constraints: Record<string, LayerConstraint[]>}} TokenLayer
+ * @typedef {{id: string, name: string, tokenLayer: string, project: string, config: Record<string, any>,
+ *   constraints: Record<string, LayerConstraint[]>}} SpanLayer
+ * @typedef {{id: string, name: string, spanLayer: string, project: string, config: Record<string, any>,
+ *   constraints: Record<string, LayerConstraint[]>}} RelationLayer
+ */
+
+/**
+ * The records with metadata, by the path segment of their routes.
+ * @typedef {{documents: PlaidDocument, texts: PlaidText, tokens: Token, spans: Span,
+ *   relations: Relation, "vocab-items": VocabItem, "vocab-links": VocabLink}} MetadataRecords
+ */
+
+/**
+ * The four layer kinds, by the path segment of their routes.
+ * @typedef {{"text-layers": TextLayer, "token-layers": TokenLayer, "span-layers": SpanLayer,
+ *   "relation-layers": RelationLayer}} LayerRecords
+ */
+
+/**
+ * @typedef {object} User
+ * @property {string} id
+ * @property {string} displayName
+ * @property {boolean} isAdmin
+ * @property {string | null} deactivatedAt
+ * @property {string | null} avatarHash
+ */
+
+/**
+ * A project as the project list gives it: the project, with how many
+ * documents it has and when the newest of them last changed.
+ * @typedef {Project & {documentCount: number, lastModified: string | null}} ProjectListEntry
+ */
+
+/**
+ * A document as a project's document list gives it.
+ * @typedef {object} DocumentListEntry
+ * @property {string} id
+ * @property {string} name
+ * @property {number} version
+ * @property {string} timeCreated
+ * @property {string} timeModified
+ */
+
+/**
+ * A named API token, without the signed token itself, which only `create`
+ * returns.
+ * @typedef {object} ApiToken
+ * @property {string} id
+ * @property {string} userId
+ * @property {string} name
+ * @property {string} createdAt
+ * @property {string | null} lastUsedAt
+ * @property {string | null} revokedAt
+ */
+
+/**
+ * Who made an operation, as the audit log names them.
+ * @typedef {{id: string, displayName: string, avatarHash: string | null}} AuditUser
+ */
+
+/**
+ * A project or a document an audit entry names, while it exists.
+ * @typedef {{id: string, name: string}} AuditTarget
+ */
+
+/**
+ * One operation of an audit entry.
+ * @typedef {object} AuditOp
+ * @property {string} id
+ * @property {string} type The kind of write, such as "document/update".
+ * @property {string} description
+ * @property {string} time
+ * @property {string} endTime The time to read at to see the operation done.
+ * @property {AuditUser | null} user
+ * @property {string} [credential]
+ * @property {AuditTarget} [project]
+ * @property {AuditTarget} [document]
+ * @property {string} [batchId]
+ */
+
+/**
+ * One entry of an audit log: a logical operation, an atomic batch or a lone
+ * write, with its operations oldest first (`ops`, cut to `opsLimit` when one
+ * was asked for, while `opCount` counts them all).
+ * @typedef {object} AuditEntry
+ * @property {string} id
+ * @property {string} time
+ * @property {string} endTime
+ * @property {AuditUser | null} user
+ * @property {AuditTarget[]} projects
+ * @property {AuditTarget[]} documents
+ * @property {AuditOp[]} ops
+ * @property {number} opCount
+ * @property {string} [groupId]
+ * @property {string} [message]
+ * @property {OperationKind} [kind]
+ * @property {string} [ref]
+ * @property {string} [batchId]
+ * @property {{id: string, name: string}} [apiToken]
+ * @property {string} [credential]
+ */
+
+/**
+ * A document lock as its holder sees it. `expiresAt` is in epoch
+ * milliseconds.
+ * @typedef {{lockId: string, userId: string, expiresAt: number}} LockGrant
+ */
+
+/**
+ * What `documents.restore` did, or with `dryRun` would do: per kind of
+ * record, how many come back, are set back and are removed (per layer for
+ * the layered kinds), and what could not come back, with why.
+ * @typedef {object} DocumentRestoreSummary
+ * @property {boolean} name
+ * @property {boolean} documentMetadata
+ * @property {RestoreCounts} texts
+ * @property {RestoreCounts & {byLayer: Array<RestoreCounts & {layerId: string}>}} tokens
+ * @property {RestoreCounts & {byLayer: Array<RestoreCounts & {layerId: string}>}} spans
+ * @property {RestoreCounts & {byLayer: Array<RestoreCounts & {layerId: string}>}} relations
+ * @property {RestoreCounts} vocabLinks
+ * @property {Array<{kind: string, count: number, reason: string}>} skipped
+ * @property {{name: string, taken: string}} [nameKept] When the name the
+ *   document had then belongs to another document now: the name it keeps,
+ *   and that other document's name.
+ * @property {number} total 0 when nothing changes.
+ */
+
+/** @typedef {{inserted: number, updated: number, deleted: number}} RestoreCounts */
+
+/**
+ * A logical-operation group: its label, who made it and when, and the kind
+ * and reference of the operation when it has them.
+ * @typedef {object} OperationGroup
+ * @property {string} id
+ * @property {string | null} message
+ * @property {string} user
+ * @property {string} createdAt
+ * @property {string} [kind]
+ * @property {string} [ref]
+ */
+
+/**
+ * A query's answer. For "ids" and "entities", one row of `results` per
+ * match, a cell per `columns` entry: an id, or the entity as its GET
+ * answers it. For "count", only the count. `truncated`: the rows or the
+ * count stopped at the server's cap.
+ * @typedef {object} QueryResult
+ * @property {string} return
+ * @property {number} count
+ * @property {boolean} truncated
+ * @property {string[]} [columns]
+ * @property {any[][]} [results]
+ */
+
 // 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.
@@ -429,9 +797,12 @@ const AVATAR_TOKEN_FRESH_MS = 5 * 1000;
  * the prototype: the token and base URL, strict mode and the document versions
  * it tracks, the open logical operation.
  */
-function openBatch(client) {
+function openBatch(client, { timeout } = {}) {
   const batch = Object.create(client);
   batch.client = client;
+  // This batch's own timeout per request, in place of the client's
+  // `batchTimeout` (undefined: the client's).
+  batch.submitTimeout = timeout;
   batch.operations = [];
   // The document each queued op's strict-mode stamp is for (null for none),
   // and the logical operation it joined (null for none), index for index with
@@ -494,7 +865,15 @@ async function submitBatch(batch) {
   // needs to know. The same holds for `committedResults`.
   const results = [];
   try {
-    await sendChunks(client, url, ops, stamps, results, groups);
+    await sendChunks(
+      client,
+      url,
+      ops,
+      stamps,
+      results,
+      groups,
+      batch.submitTimeout,
+    );
   } catch (error) {
     if (error && typeof error === "object") {
       error.committed = results.length;
@@ -511,7 +890,15 @@ function claimedVersion(path) {
   return v == null ? null : Number(v);
 }
 
-async function sendChunks(client, url, ops, stamps, results, groups = []) {
+async function sendChunks(
+  client,
+  url,
+  ops,
+  stamps,
+  results,
+  groups = [],
+  timeout = undefined,
+) {
   // Every chunk's refs are checked before the first request goes, so a batch
   // whose refs cannot resolve writes nothing.
   const chunks = [];
@@ -549,7 +936,7 @@ async function sendChunks(client, url, ops, stamps, results, groups = []) {
     // its path now carries it.
     const j = stamps.slice(i, i + chunk.length).findIndex(Boolean);
     record(j < 0 ? null : claimedVersion(chunk[j].path));
-    const answered = await client._postBatch(url, chunk, { key });
+    const answered = await client._postBatch(url, chunk, { key, timeout });
     results.push(...answered);
     if (wasReplayed(answered)) markReplayed(results);
     // The server took the chunk, so each operation it joined exists.
@@ -746,6 +1133,7 @@ class PlaidClient {
        * @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)
+       * @returns {Promise<Created>}
        */
       create: (vocabItem, tokens, metadata, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/vocab-links", {
@@ -780,6 +1168,7 @@ class PlaidClient {
       /**
        * Get a vocab link by ID
        * @param {string} id - The resource ID
+       * @returns {Promise<VocabLink>}
        */
       get: (id) =>
         this._request("GET", `/api/v1/vocab-links/${id}`),
@@ -787,6 +1176,7 @@ class PlaidClient {
        * Delete a vocab link
        * @param {string} id - The resource ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       delete: (id, auditMessage) =>
         this._request("DELETE", `/api/v1/vocab-links/${id}`, { auditMessage }),
@@ -801,6 +1191,7 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {boolean} [includeItems] - Include vocab items
        * @param {string} [asOf] - The moment to read at (ISO-8601 instant)
+       * @returns {Promise<VocabLayer>}
        */
       get: (id, includeItems, asOf) =>
         this._request("GET", `/api/v1/vocab-layers/${id}`, {
@@ -813,6 +1204,7 @@ class PlaidClient {
        * @param {string} id - The vocabulary ID
        * @param {string} itemId - The entry ID
        * @param {string} asOf - The moment to read at (ISO-8601 instant)
+       * @returns {Promise<VocabItem>}
        */
       getItemAt: (id, itemId, asOf) =>
         this._request("GET", `/api/v1/vocab-layers/${id}/items/${itemId}`, {
@@ -833,6 +1225,7 @@ class PlaidClient {
        *   each with only its operations that did
        * @param {string[]|string} [kinds] - Only the entries of operations of
        *   these kinds (e.g. `['review', 'guess-adoption']`), each whole
+       * @returns {Promise<AuditEntry[]>}
        */
       audit: (id, startTime, endTime, opTypes, itemId, kinds) =>
         listAll(this, `/api/v1/vocab-layers/${id}/audit`, {
@@ -863,7 +1256,7 @@ class PlaidClient {
        * @param {string} [opts.entryId] - Read only this entry, not a page
        * @param {string} [opts.itemId] - Only the changes that wrote this one
        *   entry, each with only its operations that did
-       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       * @returns {Promise<Page<AuditEntry>>}
        */
       auditPage: (
         id,
@@ -920,6 +1313,7 @@ class PlaidClient {
        * Delete a vocab layer.
        * @param {string} id - The resource ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       delete: (id, auditMessage) =>
         this._request("DELETE", `/api/v1/vocab-layers/${id}`, { auditMessage }),
@@ -928,6 +1322,7 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} name - The name
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<VocabLayer>}
        */
       update: (id, name, auditMessage) =>
         this._request("PATCH", `/api/v1/vocab-layers/${id}`, {
@@ -938,6 +1333,7 @@ class PlaidClient {
       /**
        * List all vocab layers accessible to user. Transparently follows
        * pagination cursors and returns the full flat array.
+       * @returns {Promise<VocabLayer[]>}
        */
       list: () => listAll(this, "/api/v1/vocab-layers"),
       /**
@@ -945,7 +1341,7 @@ class PlaidClient {
        * @param {object} [opts]
        * @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<VocabLayer>>}
        */
       listPage: ({ limit, cursor } = {}) =>
         listPage(this, "/api/v1/vocab-layers", {
@@ -956,7 +1352,7 @@ class PlaidClient {
        * Async-iterate vocab layers page by page; yields each page's entries array.
        * @param {object} [opts]
        * @param {number} [opts.pageSize] - Per-request page size
-       * @returns {AsyncGenerator<Array>}
+       * @returns {AsyncGenerator<VocabLayer[]>}
        */
       iterPages: ({ pageSize } = {}) =>
         iterPages(this, "/api/v1/vocab-layers", {
@@ -968,6 +1364,7 @@ class PlaidClient {
        * @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)
+       * @returns {Promise<Created>}
        */
       create: (name, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/vocab-layers", {
@@ -979,6 +1376,7 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       addMaintainer: (id, userId, auditMessage) =>
         this._request(
@@ -991,6 +1389,7 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       removeMaintainer: (id, userId, auditMessage) =>
         this._request(
@@ -1007,6 +1406,7 @@ class PlaidClient {
        * @param {string} relationId - The relation ID
        * @param {string} spanId - The span ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<Relation>}
        */
       setTarget: (relationId, spanId, auditMessage) =>
         this._request("PUT", `/api/v1/relations/${relationId}/target`, {
@@ -1016,6 +1416,7 @@ class PlaidClient {
       /**
        * Get a relation by ID.
        * @param {string} relationId - The relation ID
+       * @returns {Promise<Relation>}
        */
       get: (relationId) =>
         this._request("GET", `/api/v1/relations/${relationId}`),
@@ -1023,6 +1424,7 @@ class PlaidClient {
        * Delete a relation.
        * @param {string} relationId - The relation ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       delete: (relationId, auditMessage) =>
         this._request("DELETE", `/api/v1/relations/${relationId}`, {
@@ -1033,6 +1435,7 @@ class PlaidClient {
        * @param {string} relationId - The relation ID
        * @param {any} value - The value
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<Relation>}
        */
       update: (relationId, value, auditMessage) =>
         this._request("PATCH", `/api/v1/relations/${relationId}`, {
@@ -1044,6 +1447,7 @@ class PlaidClient {
        * @param {string} relationId - The relation ID
        * @param {string} spanId - The span ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<Relation>}
        */
       setSource: (relationId, spanId, auditMessage) =>
         this._request("PUT", `/api/v1/relations/${relationId}/source`, {
@@ -1054,19 +1458,20 @@ class PlaidClient {
        * Create a new relation. A relation is a directed edge between two spans
        * with a value, useful for expressing phenomena such as syntactic or
        * semantic relations.
-       * @param {string} layerId - The relation layer ID
-       * @param {string} sourceId - The source span ID
-       * @param {string} targetId - The target span ID
+       * @param {string} relationLayerId - The relation layer ID
+       * @param {string} source - The source span ID
+       * @param {string} target - 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)
+       * @returns {Promise<Created>}
        */
       create: (
-        layerId,
-        sourceId,
-        targetId,
+        relationLayerId,
+        source,
+        target,
         value,
         metadata,
         auditMessage,
@@ -1076,9 +1481,9 @@ class PlaidClient {
           auditMessage,
           body: bodyOf({
             id,
-            "layer-id": layerId,
-            "source-id": sourceId,
-            "target-id": targetId,
+            "relation-layer-id": relationLayerId,
+            source,
+            target,
             value,
             metadata,
           }),
@@ -1118,6 +1523,7 @@ class PlaidClient {
     this.spanLayers = {
       ...configMethods(this, "span-layers"),
       ...constraintMethods(this, "span-layers"),
+      ...valueSetMethods(this, "span-layers"),
       ...layerMethods(this, "span-layers"),
       /**
        * Create a new span layer.
@@ -1126,6 +1532,7 @@ class PlaidClient {
        * @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)
+       * @returns {Promise<Created>}
        */
       create: (tokenLayerId, name, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/span-layers", {
@@ -1140,6 +1547,7 @@ class PlaidClient {
        * @param {string} spanId - The span ID
        * @param {Array} tokens - The tokens
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<Span>}
        */
       setTokens: (spanId, tokens, auditMessage) =>
         this._request("PUT", `/api/v1/spans/${spanId}/tokens`, {
@@ -1156,6 +1564,7 @@ class PlaidClient {
        * @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)
+       * @returns {Promise<Created>}
        */
       create: (spanLayerId, tokens, value, metadata, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/spans", {
@@ -1171,6 +1580,7 @@ class PlaidClient {
       /**
        * Get a span by ID.
        * @param {string} spanId - The span ID
+       * @returns {Promise<Span>}
        */
       get: (spanId) =>
         this._request("GET", `/api/v1/spans/${spanId}`),
@@ -1178,6 +1588,7 @@ class PlaidClient {
        * Delete a span.
        * @param {string} spanId - The span ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       delete: (spanId, auditMessage) =>
         this._request("DELETE", `/api/v1/spans/${spanId}`, { auditMessage }),
@@ -1186,6 +1597,7 @@ class PlaidClient {
        * @param {string} spanId - The span ID
        * @param {any} value - The value
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<Span>}
        */
       update: (spanId, value, auditMessage) =>
         this._request("PATCH", `/api/v1/spans/${spanId}`, {
@@ -1316,10 +1728,13 @@ class PlaidClient {
        * @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).
+       * @param {{id?: string, tokenEdges?: number[], tokenizeLayer?: string}} [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).
+       *   `tokenizeLayer`: a word layer of the text, which gets the body's words, cut by the
+       *   server ("Tokenize new text").
+       * @returns {Promise<Created>}
        */
       create: (
         textLayerId,
@@ -1327,7 +1742,7 @@ class PlaidClient {
         body,
         metadata,
         auditMessage,
-        { id, tokenEdges } = {},
+        { id, tokenEdges, tokenizeLayer } = {},
       ) =>
         this._request("POST", "/api/v1/texts", {
           auditMessage,
@@ -1337,12 +1752,14 @@ class PlaidClient {
             "document-id": documentId,
             body,
             "token-edges": tokenEdges,
+            "tokenize-layer": tokenizeLayer,
             metadata,
           }),
         }),
       /**
        * Get a text.
        * @param {string} textId - The text ID
+       * @returns {Promise<PlaidText>}
        */
       get: (textId) =>
         this._request("GET", `/api/v1/texts/${textId}`),
@@ -1350,6 +1767,7 @@ class PlaidClient {
        * Delete a text and all dependent data.
        * @param {string} textId - The text ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       delete: (textId, auditMessage) =>
         this._request("DELETE", `/api/v1/texts/${textId}`, { auditMessage }),
@@ -1371,12 +1789,16 @@ class PlaidClient {
        * @param {string} textId - The text ID
        * @param {any} body - The request body
        * @param {string} [auditMessage]
-       * @param {{base?: string, versioned?: boolean}} [options]
+       * `tokenizeLayer`: a word layer of the text, whose words the server makes for the text the
+       * update types, after it places the old tokens ("Tokenize new text"). They come in the
+       * answer's `reshape`.
+       * @param {{base?: string, versioned?: boolean, tokenizeLayer?: string}} [options]
+       * @returns {Promise<PlaidText & {reshape: TextReshape}>}
        */
-      update: (textId, body, auditMessage, { base, versioned } = {}) =>
+      update: (textId, body, auditMessage, { base, versioned, tokenizeLayer } = {}) =>
         this._request("PATCH", `/api/v1/texts/${textId}`, {
           auditMessage,
-          body: bodyOf({ body, base }),
+          body: bodyOf({ body, base, "tokenize-layer": tokenizeLayer }),
           versioned: versioned ?? (base === undefined || base === null),
         }),
       /**
@@ -1390,16 +1812,17 @@ class PlaidClient {
        * `base`, the digest of the body the edits were made on, the edit
        * applies only to that body and is refused with 409 and `text-changed`
        * otherwise, and strict mode does not stamp it unless `versioned` is
-       * true. See composeTextEdits and gapsToOps.
+       * true. `tokenizeLayer` is as `update` takes it. See composeTextEdits and gapsToOps.
        * @param {string} textId - The text ID
        * @param {Array<object>} edits - The edit directives
        * @param {string} [auditMessage]
-       * @param {{base?: string, versioned?: boolean}} [options]
+       * @param {{base?: string, versioned?: boolean, tokenizeLayer?: string}} [options]
+       * @returns {Promise<PlaidText & {reshape: TextReshape}>}
        */
-      edit: (textId, edits, auditMessage, { base, versioned } = {}) =>
+      edit: (textId, edits, auditMessage, { base, versioned, tokenizeLayer } = {}) =>
         this._request("PATCH", `/api/v1/texts/${textId}`, {
           auditMessage,
-          body: bodyOf({ edits, base }),
+          body: bodyOf({ edits, base, "tokenize-layer": tokenizeLayer }),
           versioned: versioned ?? (base === undefined || base === null),
         }),
     };
@@ -1410,6 +1833,7 @@ class PlaidClient {
        * 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 holds an at sign), case-insensitive
+       * @returns {Promise<User[]>}
        */
       list: ({ q } = {}) =>
         listAll(this, "/api/v1/users", { query: { q } }),
@@ -1419,7 +1843,7 @@ class PlaidClient {
        * @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)}>}
+       * @returns {Promise<Page<User>>}
        */
       listPage: ({ q, limit, cursor } = {}) =>
         listPage(this, "/api/v1/users", {
@@ -1432,7 +1856,7 @@ class PlaidClient {
        * @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 holds an at sign), case-insensitive
        * @param {number} [opts.pageSize] - Per-request page size
-       * @returns {AsyncGenerator<Array>}
+       * @returns {AsyncGenerator<User[]>}
        */
       iterPages: ({ q, pageSize } = {}) =>
         iterPages(this, "/api/v1/users", {
@@ -1449,6 +1873,7 @@ class PlaidClient {
        * @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
+       * @returns {Promise<Created>}
        */
       create: (email, password, isAdmin, displayName, auditMessage) =>
         this._request("POST", "/api/v1/users", {
@@ -1474,6 +1899,7 @@ class PlaidClient {
        *   one of its operations matches, carrying only the ones that did.
        * @param {string[]|string} [kinds] - Only the entries of operations of
        *   these kinds (e.g. `['review', 'guess-adoption']`), each whole
+       * @returns {Promise<AuditEntry[]>}
        */
       audit: (userId, startTime, endTime, opTypes, kinds) =>
         listAll(this, `/api/v1/users/${userId}/audit`, {
@@ -1501,7 +1927,7 @@ class PlaidClient {
        *   operations in `ops` (1..1000). `opCount` on every entry says how
        *   many it has
        * @param {string} [opts.entryId] - Read only this entry, not a page
-       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       * @returns {Promise<Page<AuditEntry>>}
        */
       auditPage: (
         userId,
@@ -1523,6 +1949,7 @@ class PlaidClient {
       /**
        * Get a user by ID
        * @param {string} id - The resource ID
+       * @returns {Promise<User>}
        */
       get: (id) =>
         this._request("GET", `/api/v1/users/${id}`),
@@ -1534,6 +1961,7 @@ class PlaidClient {
        * Reversible via activate(), which restores login only.
        * @param {string} id - The resource ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       delete: (id, auditMessage) =>
         this._request("DELETE", `/api/v1/users/${id}`, { auditMessage }),
@@ -1543,6 +1971,7 @@ class PlaidClient {
        * at deactivation are NOT restored — re-grant them deliberately.
        * @param {string} id - The resource ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<User>}
        */
       activate: (id, auditMessage) =>
         this._request("POST", `/api/v1/users/${id}/activate`, { auditMessage }),
@@ -1559,6 +1988,7 @@ class PlaidClient {
        * @param {string} [displayName] - New display name
        * @param {boolean} [isAdmin] - New admin status
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<User>}
        */
       update: (id, password, displayName, isAdmin, auditMessage) =>
         this._request("PATCH", `/api/v1/users/${id}`, {
@@ -1660,6 +2090,7 @@ class PlaidClient {
        * Fetch a user's profile picture as raw bytes. Most callers want
        * avatarUrl() instead. This one is for non-browser consumers.
        * @param {string} id - The user ID
+       * @returns {Promise<ArrayBuffer>}
        */
       getAvatar: (id) =>
         this._request("GET", `/api/v1/users/${id}/avatar`, {
@@ -1673,6 +2104,7 @@ class PlaidClient {
        * @param {string} id - The user ID
        * @param {File} file - The image to upload
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<User>}
        */
       setAvatar: (id, file, auditMessage) => {
         const fd = new FormData();
@@ -1688,6 +2120,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
+       * @returns {Promise<void>}
        */
       // No flag: the upload beside this one is multipart and cannot be
       // batched, but a DELETE carries no blob, so the batch transport takes
@@ -1827,6 +2260,7 @@ class PlaidClient {
        * Delete one private data entry; 404 if absent.
        * @param {string} userId
        * @param {string} key
+       * @returns {Promise<void>}
        */
       delete: (userId, key) =>
         this._request(
@@ -1844,6 +2278,7 @@ class PlaidClient {
        * string itself — that is only returned once, by create().
        * Transparently follows pagination cursors and returns the full flat array.
        * @param {string} userId - The user ID who owns the tokens
+       * @returns {Promise<ApiToken[]>}
        */
       list: (userId) => listAll(this, `/api/v1/users/${userId}/tokens`),
       /**
@@ -1852,7 +2287,7 @@ class PlaidClient {
        * @param {object} [opts]
        * @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<ApiToken>>}
        */
       listPage: (userId, { limit, cursor } = {}) =>
         listPage(this, `/api/v1/users/${userId}/tokens`, { limit, cursor }),
@@ -1862,7 +2297,7 @@ class PlaidClient {
        * @param {string} userId - The user ID who owns the tokens
        * @param {object} [opts]
        * @param {number} [opts.pageSize] - Per-request page size
-       * @returns {AsyncGenerator<Array>}
+       * @returns {AsyncGenerator<ApiToken[]>}
        */
       iterPages: (userId, { pageSize } = {}) =>
         iterPages(this, `/api/v1/users/${userId}/tokens`, { pageSize }),
@@ -1892,6 +2327,7 @@ class PlaidClient {
        * @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
+       * @returns {Promise<void>}
        */
       revoke: (userId, tokenId, auditMessage) =>
         this._request("DELETE", `/api/v1/users/${userId}/tokens/${tokenId}`, {
@@ -2004,6 +2440,7 @@ class PlaidClient {
        * 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
+       * @returns {Promise<void>}
        */
       revoke: (id, auditMessage) =>
         this._request("DELETE", `/api/v1/invites/${id}`, { auditMessage }),
@@ -2175,6 +2612,7 @@ class PlaidClient {
        *   matches, carrying only the ones that did.
        * @param {string[]|string} [opts.kinds] - Only the entries of operations
        *   of these kinds (e.g. `['review']`), each whole
+       * @returns {Promise<AuditEntry[]>}
        */
       list: ({ startTime, endTime, opTypes, kinds } = {}) =>
         listAll(this, "/api/v1/audit", {
@@ -2200,7 +2638,7 @@ class PlaidClient {
        *   operations in `ops` (1..1000). `opCount` on every entry says how
        *   many it has
        * @param {string} [opts.entryId] - Read only this entry, not a page
-       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       * @returns {Promise<Page<AuditEntry>>}
        */
       listPage: ({ startTime, endTime, opTypes, kinds, order, limit, cursor, opsLimit, entryId } = {}) =>
         listPage(this, "/api/v1/audit", {
@@ -2224,7 +2662,7 @@ class PlaidClient {
        * @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>}
+       * @returns {AsyncGenerator<AuditEntry[]>}
        */
       iterPages: ({ startTime, endTime, opTypes, kinds, pageSize } = {}) =>
         iterPages(this, "/api/v1/audit", {
@@ -2271,6 +2709,24 @@ class PlaidClient {
 
     this.tokenLayers = {
       ...layerMethods(this, "token-layers"),
+      /**
+       * Count, per document, the tokens of each layer whose surface matches a
+       * regex, as a query's `value: {regex}` on a token decides. Each text is
+       * read once, so it stays fast on a long document. Layers you cannot read
+       * are left out.
+       * @param {string[]} layerIds - The token layer ids
+       * @param {{regex: string, flags?: string}} value - The regex spec
+       * @returns {Promise<{results: Array<[string, string, number]>}>} [layerId,
+       *   documentId, count] rows, a document with tokens of the layer and no
+       *   match counting 0.
+       */
+      countMatching: (layerIds, value) =>
+        this._request("POST", "/api/v1/query/token-counts", {
+          body: { layers: layerIds, value },
+          outOfBand: true,
+          timeout: queryTimeout(this),
+          noBusyRetry: true,
+        }),
       /**
        * Create a new token layer.
        * @param {string} textLayerId - The text layer ID
@@ -2280,6 +2736,7 @@ class PlaidClient {
        * @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)
+       * @returns {Promise<Created>}
        */
       create: (
         textLayerId,
@@ -2307,6 +2764,7 @@ class PlaidClient {
       /**
        * Check the lock status of a document.
        * @param {string} documentId - The document ID
+       * @returns {Promise<{userId: string, expiresAt: number} | void>}
        */
       checkLock: (documentId) =>
         this._request("GET", `/api/v1/documents/${documentId}/lock`),
@@ -2331,6 +2789,7 @@ class PlaidClient {
        * @param {string} documentId - The document ID
        * @param {string} [auditMessage]
        * @param {string} [newLockId] - A holder id this client minted
+       * @returns {Promise<LockGrant>}
        */
       acquireLock: (documentId, auditMessage, newLockId) =>
         this._request("POST", `/api/v1/documents/${documentId}/lock`, {
@@ -2348,6 +2807,7 @@ class PlaidClient {
        * @param {string} documentId - The document ID
        * @param {string} lockId - The `lockId` acquireLock answered with
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<LockGrant>}
        */
       renewLock: (documentId, lockId, auditMessage) =>
         this._request("POST", `/api/v1/documents/${documentId}/lock`, {
@@ -2363,6 +2823,7 @@ class PlaidClient {
        * @param {string} documentId - The document ID
        * @param {string} lockId - The `lockId` acquireLock answered with
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       releaseLock: (documentId, lockId, auditMessage) =>
         this._request("DELETE", `/api/v1/documents/${documentId}/lock`, {
@@ -2406,6 +2867,12 @@ 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.
+       *
+       * A core restart drops every lock, and until the next renewal finds it
+       * gone (up to half the lock window) this block's writes still pass, since
+       * writes carry no lock id. When a write must not land past that point,
+       * hold the document in strict mode too (`enterStrictMode`), so such a
+       * write is refused with a 409.
        * @template T
        * @param {string} documentId - The document ID
        * @param {(lock: import("./documentLock.js").DocumentLock) => T | Promise<T>} fn - The work to run while holding it
@@ -2458,6 +2925,7 @@ class PlaidClient {
        * @param {File} file - The file to upload
        * @param {string} [auditMessage] - Custom audit-log message for this write
        * @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.
+       * @returns {Promise<{message: string, extension: string, contentType: string}>}
        */
       uploadMedia: (documentId, file, auditMessage, { onProgress } = {}) => {
         const fd = new FormData();
@@ -2478,12 +2946,13 @@ class PlaidClient {
        *   recording meant, the `?v=` of the document's `mediaUrl`. The delete
        *   is refused with a 409 (`media-changed`, and the current `media-url`)
        *   when the stored recording is another one.
+       * @returns {Promise<void>}
        */
       // The upload above is multipart and cannot be batched, but a DELETE
       // carries no blob, so the batch transport takes it. It is a write
-      // of the document's own data and queues like any other. Note that the
-      // file removal happens outside the server's transaction, so a batch that
-      // aborts after this op does not bring the file back.
+      // of the document's own data and queues like any other. The server
+      // removes the file only after the write commits, so a batch that aborts
+      // after this op leaves the recording in place.
       deleteMedia: (documentId, auditMessage, { mediaVersion } = {}) =>
         this._request("DELETE", `/api/v1/documents/${documentId}/media`, {
           auditMessage,
@@ -2506,6 +2975,7 @@ class PlaidClient {
        *   one of its operations matches, carrying only the ones that did.
        * @param {string[]|string} [kinds] - Only the entries of operations of
        *   these kinds (e.g. `['review', 'guess-adoption']`), each whole
+       * @returns {Promise<AuditEntry[]>}
        */
       audit: (documentId, startTime, endTime, opTypes, kinds) =>
         listAll(this, `/api/v1/documents/${documentId}/audit`, {
@@ -2533,7 +3003,7 @@ class PlaidClient {
        *   operations in `ops` (1..1000). `opCount` on every entry says how
        *   many it has
        * @param {string} [opts.entryId] - Read only this entry, not a page
-       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       * @returns {Promise<Page<AuditEntry>>}
        */
       auditPage: (
         documentId,
@@ -2557,7 +3027,9 @@ class PlaidClient {
        * operation: what was deleted since then comes back under its original
        * id, what was added since is removed, and what changed is set back,
        * across every layer. A layer deleted since then, or a vocabulary entry
-       * that no longer exists, is skipped and reported under `skipped`.
+       * that no longer exists, is skipped and reported under `skipped`. A name
+       * another document holds now stays with it, and the document keeps its
+       * current name, reported under `nameKept` (`{name, taken}`).
        * Resolves to a summary of the changes. Maintainers only.
        * @param {string} documentId - The document ID
        * @param {string} asOf - The moment to go back to (ISO-8601 instant),
@@ -2565,6 +3037,7 @@ class PlaidClient {
        * @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<DocumentRestoreSummary>}
        */
       restore: (documentId, asOf, { dryRun } = {}, auditMessage) =>
         this._request("POST", `/api/v1/documents/${documentId}/restore`, {
@@ -2577,6 +3050,10 @@ class PlaidClient {
       /**
        * Get a document. Set `includeBody` to true to include all data.
        *
+       * A document with a recording has `mediaUrl`, and `mediaDuration`, the
+       * recording's length in seconds, when the server could read it from the
+       * file at upload (WAV, MP4, M4A, MOV, FLAC, MP3).
+       *
        * `layers` narrows a body read to the layers you name (ids of any kind:
        * text, token, span, or relation). A layer comes back when it is named
        * or is an ancestor of a named layer, and carries its own
@@ -2588,6 +3065,7 @@ class PlaidClient {
        * @param {boolean} [includeBody] - Include document body data
        * @param {string} [asOf] - Temporal query timestamp
        * @param {string[]|string} [layers] - Layer ids to restrict a body read to
+       * @returns {Promise<PlaidDocument>}
        */
       get: (documentId, includeBody, asOf, layers) =>
         this._request("GET", `/api/v1/documents/${documentId}`, {
@@ -2601,16 +3079,20 @@ class PlaidClient {
        * Delete a document and all data contained.
        * @param {string} documentId - The document ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       delete: (documentId, auditMessage) =>
         this._request("DELETE", `/api/v1/documents/${documentId}`, {
           auditMessage,
         }),
       /**
-       * Update a document's name.
+       * Update a document's name. A name another document of the project holds,
+       * ignoring case,
+       * is refused with 422 and `name-taken`.
        * @param {string} documentId - The document ID
        * @param {string} name - The name
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<PlaidDocument>}
        */
       update: (documentId, name, auditMessage) =>
         this._request("PATCH", `/api/v1/documents/${documentId}`, {
@@ -2625,11 +3107,21 @@ class PlaidClient {
        * @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)
+       * @param {boolean} [opts.freeName] - A name another document of the project holds, ignoring case, becomes
+       *   the first free "name (2)", "name (3)" and on. Without it such a name is refused with 422
+       *   and `name-taken`.
+       * @returns {Promise<{id: string, name: string}>} The new id and the name stored
        */
-      create: (projectId, name, metadata, auditMessage, { id } = {}) =>
+      create: (projectId, name, metadata, auditMessage, { id, freeName } = {}) =>
         this._request("POST", "/api/v1/documents", {
           auditMessage,
-          body: bodyOf({ id, "project-id": projectId, name, metadata }),
+          body: bodyOf({
+            id,
+            "project-id": projectId,
+            name,
+            metadata,
+            "free-name": freeName || undefined,
+          }),
         }),
       /**
        * Copy a document and everything in it into a new document of the same
@@ -2637,19 +3129,27 @@ class PlaidClient {
        * the vocabulary entries its links name, and holds the source's texts,
        * tokens, spans, relations and vocab links under fresh ids, with their
        * metadata. Comments do not travel. The media file does, unless
-       * `includeMedia` is false. Resolves to `{ id }`, plus `mediaError` when
-       * the source had media the copy could not take with it.
+       * `includeMedia` is false. Resolves to `{ id, name }`, plus `mediaError` when
+       * the source had media the copy could not take with it. A name another
+       * document of the project holds, ignoring case, is refused with 422 and `name-taken`,
+       * unless `freeName`, which takes the first free "name (2)", "name (3)"
+       * and on.
        * @param {string} documentId - The document to copy
        * @param {string} name - The new document's name
-       * @param {{includeMedia?: boolean, id?: string}} [options] - `{ includeMedia }`: false leaves the media
+       * @param {{includeMedia?: boolean, id?: string, freeName?: boolean}} [options] - `{ includeMedia }`: false leaves the media
        *   file behind
        * @param {string} [auditMessage] - Custom audit message for this operation
-       * @returns {Promise<{id: string, mediaError?: string}>}
+       * @returns {Promise<{id: string, name: string, mediaError?: string}>}
        */
-      copy: (documentId, name, { includeMedia, id } = {}, auditMessage) =>
+      copy: (documentId, name, { includeMedia, id, freeName } = {}, auditMessage) =>
         this._request("POST", `/api/v1/documents/${documentId}/copy`, {
           auditMessage,
-          body: bodyOf({ id, name, "include-media": includeMedia }),
+          body: bodyOf({
+            id,
+            name,
+            "include-media": includeMedia,
+            "free-name": freeName || undefined,
+          }),
         }),
     };
 
@@ -2659,6 +3159,7 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       addWriter: (id, userId, auditMessage) =>
         this._request("POST", `/api/v1/projects/${id}/writers/${userId}`, {
@@ -2669,6 +3170,7 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       removeWriter: (id, userId, auditMessage) =>
         this._request("DELETE", `/api/v1/projects/${id}/writers/${userId}`, {
@@ -2679,6 +3181,7 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       addReader: (id, userId, auditMessage) =>
         this._request("POST", `/api/v1/projects/${id}/readers/${userId}`, {
@@ -2689,6 +3192,7 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       removeReader: (id, userId, auditMessage) =>
         this._request("DELETE", `/api/v1/projects/${id}/readers/${userId}`, {
@@ -2700,6 +3204,7 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       addMaintainer: (id, userId, auditMessage) =>
         this._request("POST", `/api/v1/projects/${id}/maintainers/${userId}`, {
@@ -2710,6 +3215,7 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       removeMaintainer: (id, userId, auditMessage) =>
         this._request(
@@ -2733,6 +3239,7 @@ class PlaidClient {
        *   one of its operations matches, carrying only the ones that did.
        * @param {string[]|string} [kinds] - Only the entries of operations of
        *   these kinds (e.g. `['review', 'guess-adoption']`), each whole
+       * @returns {Promise<AuditEntry[]>}
        */
       audit: (projectId, startTime, endTime, opTypes, kinds) =>
         listAll(this, `/api/v1/projects/${projectId}/audit`, {
@@ -2760,7 +3267,7 @@ class PlaidClient {
        *   operations in `ops` (1..1000). `opCount` on every entry says how
        *   many it has
        * @param {string} [opts.entryId] - Read only this entry, not a page
-       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       * @returns {Promise<Page<AuditEntry>>}
        */
       auditPage: (
         projectId,
@@ -2798,6 +3305,7 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} vocabId - The vocab layer ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       linkVocab: (id, vocabId, auditMessage) =>
         this._request("POST", `/api/v1/projects/${id}/vocabs/${vocabId}`, {
@@ -2808,6 +3316,7 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} vocabId - The vocab layer ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       unlinkVocab: (id, vocabId, auditMessage) =>
         this._request("DELETE", `/api/v1/projects/${id}/vocabs/${vocabId}`, {
@@ -2817,6 +3326,7 @@ class PlaidClient {
        * Get a project by ID. To fetch the project's documents, use
        * listDocuments(id) — the include-documents flag has been removed.
        * @param {string} id - The resource ID
+       * @returns {Promise<Project>}
        */
       get: (id) =>
         this._request("GET", `/api/v1/projects/${id}`),
@@ -2827,6 +3337,7 @@ class PlaidClient {
        * Note: this endpoint does not support temporal (`as-of`) queries; the
        * server rejects `?as-of=` on the documents-list route with a 400.
        * @param {string} id - The project ID
+       * @returns {Promise<DocumentListEntry[]>}
        */
       listDocuments: (id) => listAll(this, `/api/v1/projects/${id}/documents`),
       /**
@@ -2838,7 +3349,7 @@ class PlaidClient {
        * @param {object} [opts]
        * @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<DocumentListEntry>>}
        */
       listDocumentsPage: (id, { limit, cursor } = {}) =>
         listPage(this, `/api/v1/projects/${id}/documents`, { limit, cursor }),
@@ -2851,7 +3362,7 @@ class PlaidClient {
        * @param {string} id - The project ID
        * @param {object} [opts]
        * @param {number} [opts.pageSize] - Per-request page size
-       * @returns {AsyncGenerator<Array>}
+       * @returns {AsyncGenerator<DocumentListEntry[]>}
        */
       iterDocuments: (id, { pageSize } = {}) =>
         iterPages(this, `/api/v1/projects/${id}/documents`, { pageSize }),
@@ -2863,6 +3374,7 @@ class PlaidClient {
        * @param {string} [auditMessage] - Custom audit-log message
        * @param {object} [options]
        * @param {number} [options.timeout] - Per-request timeout in ms, the client's own by default (0/null disables)
+       * @returns {Promise<void>}
        */
       delete: (id, auditMessage, { timeout } = {}) =>
         this._request("DELETE", `/api/v1/projects/${id}`, {
@@ -2874,6 +3386,7 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} name - The name
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<Project>}
        */
       update: (id, name, auditMessage) =>
         this._request("PATCH", `/api/v1/projects/${id}`, {
@@ -2883,6 +3396,7 @@ class PlaidClient {
       /**
        * List all projects accessible to user. Transparently follows pagination
        * cursors and returns the full flat array.
+       * @returns {Promise<ProjectListEntry[]>}
        */
       list: () => listAll(this, "/api/v1/projects"),
       /**
@@ -2890,7 +3404,7 @@ class PlaidClient {
        * @param {object} [opts]
        * @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<ProjectListEntry>>}
        */
       listPage: ({ limit, cursor } = {}) =>
         listPage(this, "/api/v1/projects", {
@@ -2901,7 +3415,7 @@ class PlaidClient {
        * Async-iterate projects page by page; yields each page's entries array.
        * @param {object} [opts]
        * @param {number} [opts.pageSize] - Per-request page size
-       * @returns {AsyncGenerator<Array>}
+       * @returns {AsyncGenerator<ProjectListEntry[]>}
        */
       iterPages: ({ pageSize } = {}) =>
         iterPages(this, "/api/v1/projects", {
@@ -2913,6 +3427,7 @@ class PlaidClient {
        * @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)
+       * @returns {Promise<Created>}
        */
       create: (name, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/projects", {
@@ -2931,6 +3446,7 @@ class PlaidClient {
        * @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)
+       * @returns {Promise<Created>}
        */
       create: (projectId, name, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/text-layers", {
@@ -2949,6 +3465,7 @@ class PlaidClient {
        * @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)
+       * @returns {Promise<Created>}
        */
       create: (vocabLayerId, form, metadata, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/vocab-items", {
@@ -2997,6 +3514,7 @@ class PlaidClient {
       /**
        * Get a vocab item by ID
        * @param {string} id - The resource ID
+       * @returns {Promise<VocabItem>}
        */
       get: (id) =>
         this._request("GET", `/api/v1/vocab-items/${id}`),
@@ -3009,6 +3527,7 @@ class PlaidClient {
        * @param {{expectedLinkCount?: number}} [options] - `expectedLinkCount`: the
        *   number of links the caller showed. The delete is refused with a 409 when
        *   the entry has any other number of links by then.
+       * @returns {Promise<void>}
        */
       delete: (id, auditMessage, { expectedLinkCount } = {}) =>
         this._request("DELETE", `/api/v1/vocab-items/${id}`, {
@@ -3046,6 +3565,7 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} form - The vocab item form
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<VocabItem>}
        */
       update: (id, form, auditMessage) =>
         this._request("PATCH", `/api/v1/vocab-items/${id}`, {
@@ -3063,6 +3583,7 @@ class PlaidClient {
        * @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)
+       * @returns {Promise<Created>}
        */
       create: (spanLayerId, name, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/relation-layers", {
@@ -3071,6 +3592,7 @@ class PlaidClient {
         }),
       ...configMethods(this, "relation-layers"),
       ...constraintMethods(this, "relation-layers"),
+      ...valueSetMethods(this, "relation-layers"),
     };
 
     this.tokens = {
@@ -3094,6 +3616,7 @@ class PlaidClient {
        * @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)
+       * @returns {Promise<Created>}
        */
       create: (
         tokenLayerId,
@@ -3120,6 +3643,7 @@ class PlaidClient {
       /**
        * Get a token.
        * @param {string} tokenId - The token ID
+       * @returns {Promise<Token>}
        */
       get: (tokenId) =>
         this._request("GET", `/api/v1/tokens/${tokenId}`),
@@ -3128,6 +3652,7 @@ class PlaidClient {
        * have no remaining tokens, the span will also be deleted.
        * @param {string} tokenId - The token ID
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       delete: (tokenId, auditMessage) =>
         this._request("DELETE", `/api/v1/tokens/${tokenId}`, { auditMessage }),
@@ -3141,6 +3666,7 @@ class PlaidClient {
        *   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
+       * @returns {Promise<Token>}
        */
       update: (tokenId, begin, end, precedence, auditMessage) =>
         this._request("PATCH", `/api/v1/tokens/${tokenId}`, {
@@ -3175,8 +3701,9 @@ class PlaidClient {
           body,
         }),
       /**
-       * Split a token at a Unicode code-point offset. The original token becomes the
-       * left half (keeps its ID, spans, vocab-links); the new right token's ID is returned.
+       * Split a token at a Unicode code-point offset. A new token is made for one
+       * half and its ID is returned. The original token keeps its ID, spans and
+       * vocab-links on the left half, or on the right half with `keep: "right"`.
        * @param {string} tokenId - The token ID
        * @param {number} position - Code-point offset to split at (strictly between begin and end)
        * @param {string} [auditMessage] - Audit message for this write
@@ -3187,6 +3714,7 @@ class PlaidClient {
        *   half. A relation layer whose relations must stay inside one token
        *   of this layer declares a same-ancestor constraint, and the server deletes
        *   the relations the split leaves crossing in the same transaction.
+       * @returns {Promise<Created>}
        */
       split: (
         tokenId,
@@ -3206,6 +3734,7 @@ class PlaidClient {
        * @param {string} tokenId - The anchor token ID
        * @param {string} otherTokenId - The other token to merge in
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<Token>}
        */
       merge: (tokenId, otherTokenId, auditMessage) =>
         this._request("POST", `/api/v1/tokens/${tokenId}/merge`, {
@@ -3220,6 +3749,7 @@ class PlaidClient {
        * @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
+       * @returns {Promise<Token>}
        */
       shift: (tokenId, begin, end, auditMessage) =>
         this._request("POST", `/api/v1/tokens/${tokenId}/shift`, {
@@ -3255,7 +3785,7 @@ class PlaidClient {
        * queues, so a message queued after the writes goes out after them.
        * @param {string} projectId - The UUID of the project to send to
        * @param {any} data - The message data to send
-       * @returns {Promise<any>} Response from the send operation
+       * @returns {Promise<{success: boolean, message: string}>}
        */
       sendMessage: (projectId, data) =>
         this._request("POST", `/api/v1/projects/${projectId}/message`, {
@@ -3382,6 +3912,11 @@ class PlaidClient {
         cancelServiceRequest(this, projectId, requestId),
     };
 
+    // outOfBand: a query is a read that travels as a POST (see the note at
+    // the top of http.js). Made on a batch it goes over the wire like any
+    // read, and it never joins a logical operation. It waits past core's own
+    // query limit, so a query too broad answers with core's 408, and a 503
+    // from core's full queue of large queries is not retried.
     /**
      * Run a query over every project you can read.
      *
@@ -3413,16 +3948,11 @@ class PlaidClient {
      *
      * @param {Object} body - The query AST ({find, where, scope?, limit?, orderBy?,
      *   return?, bindings?}).
-     * @returns {Promise<Object>} For 'ids'/'entities': {columns, results, count, truncated}.
+     * @returns {Promise<QueryResult>} For 'ids'/'entities': {columns, results, count, truncated}.
      *   For 'count': {return: 'count', count, truncated}, where `truncated` says
      *   the count stopped at the server's cap. Entity cells are full entity
      *   objects (same shape as the GET endpoints).
      */
-    // outOfBand: a query is a read that travels as a POST (see the note at
-    // the top of http.js). Made on a batch it goes over the wire like any
-    // read, and it never joins a logical operation. It waits past core's own
-    // query limit, so a query too broad answers with core's 408, and a 503
-    // from core's full queue of large queries is not retried.
     this.query = (body) =>
       this._request("POST", "/api/v1/query", {
         body,
@@ -3438,12 +3968,14 @@ class PlaidClient {
       /**
        * Get a logical-operation group (its label + creator).
        * @param {string} id - The group id
+       * @returns {Promise<OperationGroup>}
        */
       get: (id) => this._request("GET", `/api/v1/operation-groups/${id}`),
       /**
        * Relabel a logical-operation group after the fact. Owner or admin only.
        * @param {string} id - The group id
        * @param {string|null} message - The new label
+       * @returns {Promise<OperationGroup>}
        */
       update: (id, message) =>
         this._request("PATCH", `/api/v1/operation-groups/${id}`, {
@@ -3504,6 +4036,7 @@ class PlaidClient {
        * Delete a comment. The author may delete their own; a project
        * maintainer (or admin) may delete any.
        * @param {string} id - The comment id
+       * @returns {Promise<void>}
        */
       delete: (id) =>
         this._request("DELETE", `/api/v1/comments/${id}`, { noOperation: true }),
@@ -3808,6 +4341,7 @@ class PlaidClient {
        * Delete a guideline.
        * @param {string} id - The guideline id
        * @param {string} [auditMessage] - Audit message for this write
+       * @returns {Promise<void>}
        */
       delete: (id, auditMessage) =>
         this._request("DELETE", `/api/v1/guidelines/${id}`, { auditMessage }),
@@ -4087,10 +4621,15 @@ 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.
+   *
+   * `timeout` (ms, or null for none) is how long each of this batch's
+   * requests may wait for its answer, in place of the client's
+   * `batchTimeout`, for this batch alone.
+   * @param {{timeout?: number | null}} [options]
    * @returns {PlaidBatch} the batch view
    */
-  batch() {
-    return openBatch(this);
+  batch({ timeout } = {}) {
+    return openBatch(this, { timeout });
   }
 
   /**
@@ -4099,9 +4638,10 @@ 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.
+   * `timeout` is this request's, in place of `batchTimeout` when given.
    * @private
    */
-  async _postBatch(url, body, { key = uuidv7() } = {}) {
+  async _postBatch(url, body, { key = uuidv7(), timeout } = {}) {
     const fetchOptions = {
       method: "POST",
       headers: {
@@ -4117,7 +4657,9 @@ class PlaidClient {
       // repeating it is safe. A fresh timeout signal per attempt — an
       // AbortSignal.timeout stays aborted once it fires.
       const attempt = async () => {
-        const signal = timeoutSignal(this.batchTimeout);
+        const signal = timeoutSignal(
+          timeout !== undefined ? timeout : this.batchTimeout,
+        );
         let res;
         try {
           res = await fetch(
@@ -4231,12 +4773,14 @@ 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()`.
+   * over the wire at once, as it would anywhere else. See `batch()`, which
+   * also says what `timeout` does.
    * @param {(batch: PlaidBatch) => (void | Promise<void>)} fn
+   * @param {{timeout?: number | null}} [options]
    * @returns {Promise<any[]>}
    */
-  async batched(fn) {
-    const batch = this.batch();
+  async batched(fn, { timeout } = {}) {
+    const batch = this.batch({ timeout });
     try {
       await fn(batch);
     } catch (e) {
@@ -4381,25 +4925,25 @@ class PlaidClient {
  * neither body is re-cased.
  */
 function configRequest(auditMessage, value, options, isDelete = false) {
+  // The answer is a 204 with no body, so there is nothing to keep un-recased.
   if (!options || !Object.hasOwn(options, "expected")) {
-    return isDelete
-      ? { auditMessage, skipResponseTransform: true }
-      : { auditMessage, rawBody: value, skipResponseTransform: true };
+    return isDelete ? { auditMessage } : { auditMessage, rawBody: value };
   }
   const expected = options.expected === undefined ? null : options.expected;
   return {
     auditMessage,
     queryParams: { "if-unchanged": true },
     rawBody: isDelete ? { expected } : { expected, value },
-    skipResponseTransform: true,
   };
 }
 
 /**
  * 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.
+ * Each answers the entity as its GET does.
+ * @template {keyof MetadataRecords} K
  * @param {PlaidClient} client
- * @param {string} kind
+ * @param {K} kind
  */
 function metadataMethods(client, kind) {
   const path = (id) => `/api/v1/${kind}/${id}/metadata`;
@@ -4409,6 +4953,7 @@ function metadataMethods(client, kind) {
      * @param {string} id - The entity's ID
      * @param {object} body - The new metadata map
      * @param {string} [auditMessage] - Audit message for this write
+     * @returns {Promise<MetadataRecords[K]>}
      */
     setMetadata: (id, body, auditMessage) =>
       client._request("PUT", path(id), { auditMessage, rawBody: body }),
@@ -4416,6 +4961,7 @@ function metadataMethods(client, kind) {
      * Remove all metadata from an entity.
      * @param {string} id - The entity's ID
      * @param {string} [auditMessage] - Audit message for this write
+     * @returns {Promise<MetadataRecords[K]>}
      */
     deleteMetadata: (id, auditMessage) => client._request("DELETE", path(id), { auditMessage }),
     /**
@@ -4423,6 +4969,7 @@ function metadataMethods(client, kind) {
      * @param {string} id - The entity's ID
      * @param {MetadataOp[]} body - The metadata ops
      * @param {string} [auditMessage] - Audit message for this write
+     * @returns {Promise<MetadataRecords[K]>}
      */
     patchMetadata: (id, body, auditMessage) =>
       client._request("PATCH", path(id), { auditMessage, rawBody: body }),
@@ -4446,7 +4993,10 @@ function configMethods(client, kind) {
      * @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.
+     *   was absent). The write is then refused with a 409 when the stored value differs. A value the key
+     *   already holds is not written and leaves no audit row, so the value read, expecting it, states in a
+     *   batch that the key is unchanged.
+     * @returns {Promise<void>}
      */
     setConfig: (id, namespace, configKey, configValue, auditMessage, options) =>
       client._request(
@@ -4460,7 +5010,9 @@ function configMethods(client, kind) {
      * @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.
+     * @param {{expected?: any}} [options] - `expected`, as on setConfig. A key that is absent is not
+     *   written, so expecting null states in a batch that it is still absent.
+     * @returns {Promise<void>}
      */
     deleteConfig: (id, namespace, configKey, auditMessage, options) =>
       client._request(
@@ -4474,8 +5026,9 @@ function configMethods(client, kind) {
 /**
  * The get, delete, update and shift methods of the four layer bundles, on
  * `/api/v1/<kind>/<layerId>`.
+ * @template {keyof LayerRecords} K
  * @param {PlaidClient} client
- * @param {string} kind
+ * @param {K} kind
  */
 function layerMethods(client, kind) {
   const path = (layerId) => `/api/v1/${kind}/${layerId}`;
@@ -4483,12 +5036,14 @@ function layerMethods(client, kind) {
     /**
      * Get a layer by ID.
      * @param {string} layerId - The layer ID
+     * @returns {Promise<LayerRecords[K]>}
      */
     get: (layerId) => client._request("GET", path(layerId)),
     /**
      * Delete a layer.
      * @param {string} layerId - The layer ID
      * @param {string} [auditMessage] - Audit message for this write
+     * @returns {Promise<void>}
      */
     delete: (layerId, auditMessage) => client._request("DELETE", path(layerId), { auditMessage }),
     /**
@@ -4496,6 +5051,7 @@ function layerMethods(client, kind) {
      * @param {string} layerId - The layer ID
      * @param {string} name - The new name
      * @param {string} [auditMessage] - Audit message for this write
+     * @returns {Promise<LayerRecords[K]>}
      */
     update: (layerId, name, auditMessage) =>
       client._request("PATCH", path(layerId), { auditMessage, body: bodyOf({ name }) }),
@@ -4504,6 +5060,7 @@ function layerMethods(client, kind) {
      * @param {string} layerId - The layer ID
      * @param {string} direction - The direction ("up" or "down")
      * @param {string} [auditMessage] - Audit message for this write
+     * @returns {Promise<void>}
      */
     shift: (layerId, direction, auditMessage) =>
       client._request("POST", `${path(layerId)}/shift`, {
@@ -4546,6 +5103,7 @@ function constraintMethods(client, kind) {
      * @param {string} namespace - The declaring app's namespace
      * @param {string} [auditMessage] - Audit message for this write
      * @param {{expected?: Array<object>|null}} [options] - `expected`, as on setConstraints.
+     * @returns {Promise<void>}
      */
     deleteConstraints: (layerId, namespace, auditMessage, options) => {
       const body = constraintsBody(undefined, options);
@@ -4559,10 +5117,16 @@ function constraintMethods(client, kind) {
      * data. Writes nothing.
      * @param {string} layerId - The layer ID
      * @param {LayerConstraint[]} constraints - The list to check
+     * @param {{limit?: number}} [options] - `limit`: how many violations to list (default 100)
      * @returns {Promise<{violations: ConstraintViolation[], violationCount: number}>}
      */
-    checkConstraints: (layerId, constraints) =>
-      client._request("POST", `${base(layerId)}/check`, { body: { constraints } }),
+    checkConstraints: (layerId, constraints, options) =>
+      client._request("POST", `${base(layerId)}/check`, {
+        body: {
+          constraints,
+          ...(options?.limit != null ? { limit: options.limit } : {}),
+        },
+      }),
     /**
      * Apply the remedies of the given constraints' remediable types
      * (coextensive, single-span, single-link, same-ancestor) to every
@@ -4584,6 +5148,38 @@ function constraintMethods(client, kind) {
   };
 }
 
+/**
+ * The value-set read of a span or relation layer bundle, on
+ * `/api/v1/<kind>/<layerId>/constraints/refused-values`.
+ * @param {PlaidClient} client
+ * @param {string} kind
+ */
+function valueSetMethods(client, kind) {
+  return {
+    /**
+     * The stored values of this layer that a value-set rule would refuse,
+     * before it is declared: exactly what a declaration of it would meet,
+     * with the rule's exemptions (an unconfirmed machine value, a value an
+     * import, a document copy or a restore set). Writes nothing, and a
+     * reader may ask.
+     * @param {string} layerId - The layer ID
+     * @param {ValueSetRule} rule - The list as a value-set declaration takes it
+     * @param {{limit?: number}} [options] - `limit`: how many values to list, the most frequent first
+     *   (default 20, at most 100)
+     * @returns {Promise<RefusedValues>}
+     */
+    refusedValues: (layerId, rule, options) =>
+      client._request("POST", `/api/v1/${kind}/${layerId}/constraints/refused-values`, {
+        body: bodyOf({
+          values: rule?.values,
+          delimiters: rule?.delimiters,
+          parts: rule?.parts,
+          limit: options?.limit,
+        }),
+      }),
+  };
+}
+
 export default PlaidClient;
 export { PlaidClient };
 export { valueSetAllows, violationsOf } from "./constraints.js";
@@ -4625,6 +5221,9 @@ export {
 // request, and `critical()` holds that off around writes. See ./services.js
 // and the manual, "Stopping a request".
 export { ServiceCancelled, createCancelScope } from "./services.js";
+// The two messages a write that got no answer is reported with: one the
+// server may have saved, one never sent. See ./services.js.
+export { UNKNOWN_OUTCOME, UNREACHABLE } from "./services.js";
 // Who asked for a service run, named in its History label and in what it
 // stores. See ./requester.js.
 export { REQUESTED_BY, makeRequester, requesterOf } from "./requester.js";