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

package/src/index.js

@@ -22,7 +22,7 @@ import {
   DEFAULT_BATCH_TIMEOUT_MS,
   queryTimeout,
 } from "./http.js";
-import { uuidv4, 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,662 @@ 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
+ */
+
+/**
+ * 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
+ */
+
+/**
+ * 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} [commentBodyLength]
+ * @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 {() => 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.
@@ -70,48 +726,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 = {}) {
-  const base = baseUrl.replace(/\/$/, "");
-  const url = `${base}${path}`;
-  try {
-    const fetchOptions = {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(body),
-    };
-    const signal = timeoutSignal(
-      options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS,
-    );
-    if (signal) fetchOptions.signal = signal;
-
-    const response = await fetch(url, fetchOptions);
-    if (!response.ok) {
-      throw makeHttpError(
-        response,
-        await parseErrorBody(response),
-        url,
-        "POST",
-      );
-    }
-    return transformResponse(await response.json());
-  } catch (error) {
-    if (error.status) throw error;
-    throw makeNetworkError(error, url, "POST");
-  }
-}
-
-/**
- * GET a path with no authentication, for the two endpoints a client may need
- * before it has a session: /health and /api/v1/info.
- */
-async function anonymousGet(baseUrl, path, options = {}) {
+// 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: "GET" };
+    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,
     );
@@ -119,12 +749,12 @@ async function anonymousGet(baseUrl, path, options = {}) {
 
     const response = await fetch(url, fetchOptions);
     if (!response.ok) {
-      throw makeHttpError(response, await parseErrorBody(response), url, "GET");
+      throw makeHttpError(response, await parseErrorBody(response), url, method);
     }
     return transformResponse(await response.json());
   } catch (error) {
     if (error.status) throw error;
-    throw makeNetworkError(error, url, "GET");
+    throw makeNetworkError(error, url, method);
   }
 }
 
@@ -155,15 +785,24 @@ 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
  * 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
@@ -226,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;
@@ -243,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 = [];
@@ -281,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.
@@ -316,13 +971,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 +984,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 +993,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 +1091,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 +1121,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 +1130,10 @@ 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)
+       * @returns {Promise<Created>}
        */
       create: (vocabItem, tokens, metadata, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/vocab-links", {
@@ -425,6 +1145,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,49 +1156,27 @@ 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
+       * @returns {Promise<VocabLink>}
        */
       get: (id) =>
         this._request("GET", `/api/v1/vocab-links/${id}`),
       /**
        * 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 }),
@@ -492,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}`, {
@@ -504,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}`, {
@@ -524,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`, {
@@ -541,6 +1243,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
@@ -550,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,
@@ -586,9 +1292,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 +1312,8 @@ 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 }),
@@ -612,45 +1321,19 @@ 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
+       * @returns {Promise<VocabLayer>}
        */
       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.
+       * @returns {Promise<VocabLayer[]>}
        */
       list: () => listAll(this, "/api/v1/vocab-layers"),
       /**
@@ -658,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", {
@@ -669,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", {
@@ -678,6 +1361,10 @@ 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)
+       * @returns {Promise<Created>}
        */
       create: (name, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/vocab-layers", {
@@ -688,6 +1375,8 @@ 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
+       * @returns {Promise<void>}
        */
       addMaintainer: (id, userId, auditMessage) =>
         this._request(
@@ -699,6 +1388,8 @@ 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
+       * @returns {Promise<void>}
        */
       removeMaintainer: (id, userId, auditMessage) =>
         this._request(
@@ -709,38 +1400,13 @@ 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
+       * @returns {Promise<Relation>}
        */
       setTarget: (relationId, spanId, auditMessage) =>
         this._request("PUT", `/api/v1/relations/${relationId}/target`, {
@@ -750,12 +1416,15 @@ 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}`),
       /**
        * 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}`, {
@@ -765,6 +1434,8 @@ 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
+       * @returns {Promise<Relation>}
        */
       update: (relationId, value, auditMessage) =>
         this._request("PATCH", `/api/v1/relations/${relationId}`, {
@@ -775,6 +1446,8 @@ 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
+       * @returns {Promise<Relation>}
        */
       setSource: (relationId, spanId, auditMessage) =>
         this._request("PUT", `/api/v1/relations/${relationId}/source`, {
@@ -785,16 +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,
@@ -804,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,
           }),
@@ -814,6 +1491,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 +1499,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 +1510,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 +1521,24 @@ 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 }),
-        }),
+      ...valueSetMethods(this, "span-layers"),
+      ...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)
+       * @returns {Promise<Created>}
        */
       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 +1546,8 @@ 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
+       * @returns {Promise<Span>}
        */
       setTokens: (spanId, tokens, auditMessage) =>
         this._request("PUT", `/api/v1/spans/${spanId}/tokens`, {
@@ -935,6 +1561,10 @@ 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)
+       * @returns {Promise<Created>}
        */
       create: (spanLayerId, tokens, value, metadata, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/spans", {
@@ -950,12 +1580,15 @@ 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}`),
       /**
        * 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 }),
@@ -963,6 +1596,8 @@ 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
+       * @returns {Promise<Span>}
        */
       update: (spanId, value, auditMessage) =>
         this._request("PATCH", `/api/v1/spans/${spanId}`, {
@@ -972,6 +1607,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 +1615,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 +1631,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 +1719,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 +1727,14 @@ 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[], 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,
@@ -1115,7 +1742,7 @@ class PlaidClient {
         body,
         metadata,
         auditMessage,
-        { id } = {},
+        { id, tokenEdges, tokenizeLayer } = {},
       ) =>
         this._request("POST", "/api/v1/texts", {
           auditMessage,
@@ -1124,18 +1751,23 @@ class PlaidClient {
             "text-layer-id": textLayerId,
             "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}`),
       /**
        * 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 }),
@@ -1157,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),
         }),
       /**
@@ -1176,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),
         }),
     };
@@ -1195,17 +1832,18 @@ 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
+       * @returns {Promise<User[]>}
        */
       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)}>}
+       * @returns {Promise<Page<User>>}
        */
       listPage: ({ q, limit, cursor } = {}) =>
         listPage(this, "/api/v1/users", {
@@ -1216,9 +1854,9 @@ 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>}
+       * @returns {AsyncGenerator<User[]>}
        */
       iterPages: ({ q, pageSize } = {}) =>
         iterPages(this, "/api/v1/users", {
@@ -1234,12 +1872,14 @@ 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
+       * @returns {Promise<Created>}
        */
       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
@@ -1259,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`, {
@@ -1275,6 +1916,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
@@ -1282,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,
@@ -1304,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}`),
@@ -1314,6 +1960,8 @@ 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
+       * @returns {Promise<void>}
        */
       delete: (id, auditMessage) =>
         this._request("DELETE", `/api/v1/users/${id}`, { auditMessage }),
@@ -1322,6 +1970,8 @@ 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
+       * @returns {Promise<User>}
        */
       activate: (id, auditMessage) =>
         this._request("POST", `/api/v1/users/${id}/activate`, { auditMessage }),
@@ -1337,6 +1987,8 @@ 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
+       * @returns {Promise<User>}
        */
       update: (id, password, displayName, isAdmin, auditMessage) =>
         this._request("PATCH", `/api/v1/users/${id}`, {
@@ -1348,23 +2000,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}`;
       },
@@ -1372,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`, {
@@ -1384,6 +2103,8 @@ 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
+       * @returns {Promise<User>}
        */
       setAvatar: (id, file, auditMessage) => {
         const fd = new FormData();
@@ -1398,6 +2119,8 @@ 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
@@ -1421,7 +2144,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 +2154,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 +2170,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 +2189,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,
@@ -1477,6 +2203,7 @@ class PlaidClient {
        * 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,8 +2211,11 @@ 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
@@ -1506,20 +2236,31 @@ class PlaidClient {
        * @param {number} [opts.version] - The version this write was made from
        * @returns {Promise<{key: string, updatedAt: string, version: number}>}
        */
-      put: (userId, key, value, { version } = {}) =>
-        this._request(
-          "PUT",
-          `/api/v1/users/${userId}/data/${encodeURIComponent(key)}`,
-          {
-            body: value,
-            noBatch: true,
-            queryParams: { version },
-          },
-        ),
+      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
        * @param {string} key
+       * @returns {Promise<void>}
        */
       delete: (userId, key) =>
         this._request(
@@ -1537,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`),
       /**
@@ -1545,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 }),
@@ -1555,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 }),
@@ -1567,6 +2309,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) =>
@@ -1583,6 +2326,8 @@ 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
+       * @returns {Promise<void>}
        */
       revoke: (userId, tokenId, auditMessage) =>
         this._request("DELETE", `/api/v1/users/${userId}/tokens/${tokenId}`, {
@@ -1600,6 +2345,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", {
@@ -1612,7 +2358,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", {
@@ -1626,7 +2372,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", {
@@ -1659,7 +2405,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: (
         {
@@ -1692,6 +2439,8 @@ 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
+       * @returns {Promise<void>}
        */
       revoke: (id, auditMessage) =>
         this._request("DELETE", `/api/v1/invites/${id}`, { auditMessage }),
@@ -1704,7 +2453,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"),
       /**
@@ -1718,7 +2467,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).
@@ -1738,6 +2487,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}`, {
@@ -1747,7 +2497,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"),
       /**
@@ -1757,6 +2507,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", {
@@ -1780,7 +2531,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", {
@@ -1814,7 +2565,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", {
@@ -1833,7 +2584,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", {
@@ -1861,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", {
@@ -1874,6 +2626,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)
@@ -1882,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", {
@@ -1900,7 +2656,13 @@ class PlaidClient {
         }),
       /**
        * Async-iterate the instance-wide audit log page by page. Admin only.
-       * @returns {AsyncGenerator<Array>}
+       * @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<AuditEntry[]>}
        */
       iterPages: ({ startTime, endTime, opTypes, kinds, pageSize } = {}) =>
         iterPages(this, "/api/v1/audit", {
@@ -1928,7 +2690,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
@@ -1946,15 +2708,24 @@ 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"),
+      /**
+       * 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.
@@ -1962,6 +2733,10 @@ class PlaidClient {
        * @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)
+       * @returns {Promise<Created>}
        */
       create: (
         textLayerId,
@@ -1981,67 +2756,15 @@ class PlaidClient {
             "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),
-        ),
+      ...configMethods(this, "token-layers"),
       ...constraintMethods(this, "token-layers"),
-      /**
-       * Get a token layer by ID.
-       * @param {string} tokenLayerId - The token layer ID
-       */
-      get: (tokenLayerId) =>
-        this._request("GET", `/api/v1/token-layers/${tokenLayerId}`),
-      /**
-       * Delete a token layer.
-       * @param {string} tokenLayerId - The token layer ID
-       */
-      delete: (tokenLayerId, auditMessage) =>
-        this._request("DELETE", `/api/v1/token-layers/${tokenLayerId}`, {
-          auditMessage,
-        }),
-      /**
-       * Update a token layer's name.
-       * @param {string} tokenLayerId - The token layer ID
-       * @param {string} name - The name
-       */
-      update: (tokenLayerId, name, auditMessage) =>
-        this._request("PATCH", `/api/v1/token-layers/${tokenLayerId}`, {
-          auditMessage,
-          body: bodyOf({ name }),
-        }),
     };
 
     this.documents = {
       /**
        * Check the lock status of a document.
        * @param {string} documentId - The document ID
+       * @returns {Promise<{userId: string, expiresAt: number} | void>}
        */
       checkLock: (documentId) =>
         this._request("GET", `/api/v1/documents/${documentId}/lock`),
@@ -2066,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`, {
@@ -2082,6 +2806,8 @@ 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
+       * @returns {Promise<LockGrant>}
        */
       renewLock: (documentId, lockId, auditMessage) =>
         this._request("POST", `/api/v1/documents/${documentId}/lock`, {
@@ -2096,6 +2822,8 @@ 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
+       * @returns {Promise<void>}
        */
       releaseLock: (documentId, lockId, auditMessage) =>
         this._request("DELETE", `/api/v1/documents/${documentId}/lock`, {
@@ -2139,9 +2867,17 @@ 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: 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),
@@ -2150,11 +2886,34 @@ 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
@@ -2165,7 +2924,8 @@ class PlaidClient {
        * @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.
+       * @returns {Promise<{message: string, extension: string, contentType: string}>}
        */
       uploadMedia: (documentId, file, auditMessage, { onProgress } = {}) => {
         const fd = new FormData();
@@ -2186,50 +2946,25 @@ 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,
           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. Each entry, and each of its `ops`,
        * says what kind of credential made it as `credential`: `login`,
-       * `named-token`, `service` or `delegated` (absent on older operations),
+       * `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
@@ -2240,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`, {
@@ -2256,6 +2992,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
@@ -2263,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,
@@ -2287,14 +3027,17 @@ 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),
        *   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<DocumentRestoreSummary>}
        */
       restore: (documentId, asOf, { dryRun } = {}, auditMessage) =>
         this._request("POST", `/api/v1/documents/${documentId}/restore`, {
@@ -2307,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
@@ -2318,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}`, {
@@ -2330,15 +3078,21 @@ 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}`, {
@@ -2350,11 +3104,24 @@ 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)
+       * @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
@@ -2362,18 +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 {object} [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, 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,
+          }),
         }),
     };
 
@@ -2382,6 +3158,8 @@ 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
+       * @returns {Promise<void>}
        */
       addWriter: (id, userId, auditMessage) =>
         this._request("POST", `/api/v1/projects/${id}/writers/${userId}`, {
@@ -2391,6 +3169,8 @@ 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
+       * @returns {Promise<void>}
        */
       removeWriter: (id, userId, auditMessage) =>
         this._request("DELETE", `/api/v1/projects/${id}/writers/${userId}`, {
@@ -2400,6 +3180,8 @@ 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
+       * @returns {Promise<void>}
        */
       addReader: (id, userId, auditMessage) =>
         this._request("POST", `/api/v1/projects/${id}/readers/${userId}`, {
@@ -2409,45 +3191,20 @@ 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
+       * @returns {Promise<void>}
        */
       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
+       * @returns {Promise<void>}
        */
       addMaintainer: (id, userId, auditMessage) =>
         this._request("POST", `/api/v1/projects/${id}/maintainers/${userId}`, {
@@ -2457,6 +3214,8 @@ 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
+       * @returns {Promise<void>}
        */
       removeMaintainer: (id, userId, auditMessage) =>
         this._request(
@@ -2468,7 +3227,8 @@ class PlaidClient {
        * Get audit log for a project. Transparently follows pagination cursors
        * 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`, `service` or `delegated` (absent on older operations),
+       * `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
@@ -2479,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`, {
@@ -2495,6 +3256,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
@@ -2502,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,
@@ -2539,6 +3304,8 @@ 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
+       * @returns {Promise<void>}
        */
       linkVocab: (id, vocabId, auditMessage) =>
         this._request("POST", `/api/v1/projects/${id}/vocabs/${vocabId}`, {
@@ -2548,6 +3315,8 @@ 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
+       * @returns {Promise<void>}
        */
       unlinkVocab: (id, vocabId, auditMessage) =>
         this._request("DELETE", `/api/v1/projects/${id}/vocabs/${vocabId}`, {
@@ -2557,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}`),
@@ -2567,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`),
       /**
@@ -2578,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 }),
@@ -2591,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 }),
@@ -2603,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}`, {
@@ -2613,6 +3385,8 @@ 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
+       * @returns {Promise<Project>}
        */
       update: (id, name, auditMessage) =>
         this._request("PATCH", `/api/v1/projects/${id}`, {
@@ -2622,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"),
       /**
@@ -2629,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", {
@@ -2640,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", {
@@ -2649,6 +3424,10 @@ 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)
+       * @returns {Promise<Created>}
        */
       create: (name, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/projects", {
@@ -2658,74 +3437,16 @@ 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)
+       * @returns {Promise<Created>}
        */
       create: (projectId, name, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/text-layers", {
@@ -2735,39 +3456,16 @@ 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)
+       * @returns {Promise<Created>}
        */
       create: (vocabLayerId, form, metadata, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/vocab-items", {
@@ -2778,6 +3476,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", {
@@ -2788,6 +3488,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) =>
@@ -2802,6 +3503,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", {
@@ -2811,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}`),
@@ -2823,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}`, {
@@ -2844,6 +3549,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) =>
@@ -2858,6 +3564,8 @@ 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
+       * @returns {Promise<VocabItem>}
        */
       update: (id, form, auditMessage) =>
         this._request("PATCH", `/api/v1/vocab-items/${id}`, {
@@ -2867,82 +3575,24 @@ 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)
+       * @returns {Promise<Created>}
        */
       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 }),
-        }),
+      ...valueSetMethods(this, "relation-layers"),
     };
 
     this.tokens = {
@@ -2963,6 +3613,10 @@ 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)
+       * @returns {Promise<Created>}
        */
       create: (
         tokenLayerId,
@@ -2989,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}`),
@@ -2996,6 +3651,8 @@ 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
+       * @returns {Promise<void>}
        */
       delete: (tokenId, auditMessage) =>
         this._request("DELETE", `/api/v1/tokens/${tokenId}`, { auditMessage }),
@@ -3008,6 +3665,8 @@ 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
+       * @returns {Promise<Token>}
        */
       update: (tokenId, begin, end, precedence, auditMessage) =>
         this._request("PATCH", `/api/v1/tokens/${tokenId}`, {
@@ -3017,6 +3676,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) =>
@@ -3024,12 +3684,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) =>
@@ -3038,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
@@ -3050,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,
@@ -3068,6 +3733,8 @@ 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
+       * @returns {Promise<Token>}
        */
       merge: (tokenId, otherTokenId, auditMessage) =>
         this._request("POST", `/api/v1/tokens/${tokenId}/merge`, {
@@ -3081,49 +3748,24 @@ 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
+       * @returns {Promise<Token>}
        */
       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),
@@ -3143,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`, {
@@ -3156,7 +3798,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),
 
@@ -3176,14 +3818,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),
@@ -3204,7 +3846,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: (
@@ -3270,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.
      *
@@ -3301,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,
@@ -3326,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}`, {
@@ -3349,11 +3993,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", {
@@ -3371,6 +4017,7 @@ class PlaidClient {
       /**
        * Read one comment.
        * @param {string} id - The comment id
+       * @returns {Promise<Comment>}
        */
       get: (id) => this._request("GET", `/api/v1/comments/${id}`),
       /**
@@ -3378,6 +4025,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}`, {
@@ -3388,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 }),
@@ -3399,6 +4048,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`, {
@@ -3417,7 +4067,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,
@@ -3440,7 +4090,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,
@@ -3463,7 +4113,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 } = {}) =>
@@ -3482,6 +4132,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`, {
@@ -3494,7 +4145,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`, {
@@ -3509,7 +4160,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`, {
@@ -3537,15 +4188,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
@@ -3556,6 +4207,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(),
       /**
@@ -3563,6 +4215,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),
       /**
@@ -3587,6 +4240,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`, {
@@ -3601,7 +4255,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,
@@ -3620,7 +4274,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`, {
@@ -3641,6 +4295,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`, {
@@ -3650,6 +4307,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}`),
       /**
@@ -3666,6 +4324,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,
@@ -3680,6 +4340,8 @@ 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 }),
@@ -3694,6 +4356,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`, {
@@ -3706,7 +4369,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`, {
@@ -3720,7 +4383,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`, {
@@ -3732,6 +4395,7 @@ class PlaidClient {
 
   // --- Core methods ---
 
+  /** @private */
   async _request(method, path, options = {}) {
     return makeRequest(this, method, path, options);
   }
@@ -3794,7 +4458,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 } = {}) {
@@ -3843,7 +4507,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() };
@@ -3898,10 +4562,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 });
@@ -3956,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.
-   * @returns {PlaidClient} the batch view
+   *
+   * `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 });
   }
 
   /**
@@ -3968,8 +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: {
@@ -3985,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(
@@ -4099,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()`.
-   * @param {(batch: PlaidClient) => (void | Promise<void>)} fn
-   * @returns {Promise<Array>}
+   * 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) {
@@ -4119,20 +4795,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);
   }
 
   /**
@@ -4163,7 +4841,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);
   }
 
   /**
@@ -4192,10 +4870,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 {
@@ -4220,35 +4904,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);
   }
 }
 
@@ -4262,23 +4925,156 @@ 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 {K} 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
+     * @returns {Promise<MetadataRecords[K]>}
+     */
+    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
+     * @returns {Promise<MetadataRecords[K]>}
+     */
+    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
+     * @returns {Promise<MetadataRecords[K]>}
+     */
+    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. 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(
+        "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. 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(
+        "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>`.
+ * @template {keyof LayerRecords} K
+ * @param {PlaidClient} client
+ * @param {K} kind
+ */
+function layerMethods(client, kind) {
+  const path = (layerId) => `/api/v1/${kind}/${layerId}`;
+  return {
+    /**
+     * 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 }),
+    /**
+     * Rename a layer.
+     * @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 }) }),
+    /**
+     * 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
+     * @returns {Promise<void>}
+     */
+    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`;
@@ -4289,12 +5085,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}`, {
@@ -4307,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);
@@ -4319,11 +5116,17 @@ 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
+     * @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
@@ -4332,10 +5135,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`, {
@@ -4345,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";
@@ -4357,6 +5192,7 @@ export {
   cpSlicer,
   utf16ToCp,
   cpIndexOf,
+  composeText,
 } from "./codepoint.js";
 export { composeTextEdits, gapsToOps, applyTextOps } from "./textEdits.js";
 export {
@@ -4385,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";
@@ -4431,6 +5270,6 @@ export { createdId, createdIds } from "./created.js";
 // UUIDv7 ids for what a client creates. See ./ids.js and the manual,
 // "Retrying a write". uuidv4 works where crypto.randomUUID does not (a page
 // served over plain HTTP from any host but localhost).
-export { uuidv4, uuidv7 } from "./ids.js";
+export { uuidv4, uuidv7, normalizeUserId } from "./ids.js";
 export { wasReplayed } from "./replayed.js";
 export { MAX_BATCH_OPS };