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

package/src/index.js

@@ -13,13 +13,22 @@ import {
   makeNetworkError,
   timeoutSignal,
   retryWhileBusy,
+  retryUnknown,
+  nextIdempotencyKey,
+  mergeVersions,
+  IDEMPOTENCY_HEADER,
+  REPLAYED_HEADER,
   DEFAULT_TIMEOUT_MS,
   DEFAULT_BATCH_TIMEOUT_MS,
 } from "./http.js";
+import { uuidv7 } from "./ids.js";
+import { constraintsBody } from "./constraints.js";
 import { listAll, listPage, iterPages } from "./pagination.js";
 import { recorderFor } from "./events.js";
 import { withDocumentLock } from "./documentLock.js";
 import { createSSEConnection } from "./sse.js";
+import { makeBatchRef, rebaseRefs } from "./batchRef.js";
+import { markReplayed, wasReplayed } from "./replayed.js";
 import {
   discoverServices,
   discardService,
@@ -47,6 +56,10 @@ function opTypesParam(opTypes) {
   return joined.length > 0 ? joined : undefined;
 }
 
+// The same for an audit `kinds` filter (`?kinds=`): operation kinds, such as
+// "review", in a list or a ready-made string.
+const kindsParam = opTypesParam;
+
 // Helper: build body object, filtering out undefined values
 function bodyOf(obj) {
   const result = {};
@@ -131,8 +144,10 @@ function openBatch(client) {
   batch.client = client;
   batch.operations = [];
   // The document each queued op's strict-mode stamp is for (null for none),
-  // index for index with `operations`.
+  // and the logical operation it joined (null for none), index for index with
+  // `operations`.
   batch.stampedDocuments = [];
+  batch.stampedGroups = [];
   batch.open = true;
   batch._request = (method, path, options = {}) =>
     queueRequest(batch, method, path, options);
@@ -140,10 +155,14 @@ function openBatch(client) {
     throw new Error("A batch is not nestable: queue on the batch you have");
   };
   batch.batched = batch.batch;
+  // A stand-in for the id op n will create, for a later op's body (see
+  // batchRef.js). The server fills it in inside the batch's transaction.
+  batch.ref = (opIndex = -1, index) => makeBatchRef(batch, opIndex, index);
   batch.submit = () => submitBatch(batch);
   batch.abort = () => {
     batch.operations = [];
     batch.stampedDocuments = [];
+    batch.stampedGroups = [];
     batch.open = false;
   };
   batch._installResources();
@@ -157,8 +176,10 @@ async function submitBatch(batch) {
   batch.open = false;
   const ops = batch.operations;
   const stamps = batch.stampedDocuments;
+  const groups = batch.stampedGroups;
   batch.operations = [];
   batch.stampedDocuments = [];
+  batch.stampedGroups = [];
   if (ops.length === 0) return [];
   const client = batch.client;
   const url = `${client.baseUrl}/api/v1/batch`;
@@ -176,9 +197,14 @@ async function submitBatch(batch) {
   // were saved) and `committedResults` (their results, in queue order), so a
   // caller can tell a partial write from a batch that saved nothing. The
   // failed request itself counts as unsaved, even when its answer was lost.
+  //
+  // Each request's results are marked replayed when that request was (see
+  // replayed.js), and the combined results when any request was: then some of
+  // the batch stored nothing new, which is what a caller reading the mark
+  // needs to know. The same holds for `committedResults`.
   const results = [];
   try {
-    await sendChunks(client, url, ops, stamps, results);
+    await sendChunks(client, url, ops, stamps, results, groups);
   } catch (error) {
     if (error && typeof error === "object") {
       error.committed = results.length;
@@ -189,24 +215,71 @@ async function submitBatch(batch) {
   return results;
 }
 
-async function sendChunks(client, url, ops, stamps, results) {
+/** The document-version an op's path claims, as a number, or null. */
+function claimedVersion(path) {
+  const v = new URLSearchParams(path.split("?")[1] ?? "").get("document-version");
+  return v == null ? null : Number(v);
+}
+
+async function sendChunks(client, url, ops, stamps, results, groups = []) {
+  // Every chunk's refs are checked before the first request goes, so a batch
+  // whose refs cannot resolve writes nothing.
+  const chunks = [];
   for (let i = 0; i < ops.length; i += MAX_BATCH_OPS) {
-    let chunk = ops.slice(i, i + MAX_BATCH_OPS);
-    if (i > 0) {
+    chunks.push(
+      ops
+        .slice(i, i + MAX_BATCH_OPS)
+        .map((op) =>
+          i > 0 && op.refs ? { ...op, refs: rebaseRefs(op.refs, i) } : op,
+        ),
+    );
+  }
+  for (let c = 0; c < chunks.length; c++) {
+    const i = c * MAX_BATCH_OPS;
+    let chunk = chunks[c];
+    // One Idempotency-Key per request, minted as the request is formed, so a
+    // resend of this chunk is answered from its first send when that landed.
+    // Inside an operation opened with keys, a chunk whose ops joined it takes
+    // the operation's next key and claims the version its first run claimed.
+    const joins = groups
+      .slice(i, i + chunk.length)
+      .some((g) => g && g === client.operationGroup);
+    const { key, pin, record } = nextIdempotencyKey(client, joins);
+    const claim = (docId) =>
+      pin !== undefined ? pin : client.documentVersions[docId];
+    if (i > 0 || pin !== undefined) {
       chunk = chunk.map((op, j) => {
         const docId = stamps[i + j];
         if (!docId) return op;
-        const path = restampDocumentVersion(
-          op.path,
-          client.documentVersions[docId],
-        );
+        const path = restampDocumentVersion(op.path, claim(docId));
         return { ...op, path };
       });
     }
-    results.push(...(await client._postBatch(url, chunk)));
+    // Pin what the chunk actually claims: the first stamped op's version as
+    // its path now carries it.
+    const j = stamps.slice(i, i + chunk.length).findIndex(Boolean);
+    record(j < 0 ? null : claimedVersion(chunk[j].path));
+    const answered = await client._postBatch(url, chunk, { key });
+    results.push(...answered);
+    if (wasReplayed(answered)) markReplayed(results);
+    // The server took the chunk, so each operation it joined exists.
+    for (let j = i; j < i + chunk.length; j++) {
+      if (groups[j]) groups[j].written = true;
+    }
   }
 }
 
+/**
+ * End the key frame `frame` of `group`, wherever it is among the frames open:
+ * the frame under it, or the one open over it, numbers from then on. A plain
+ * function, so a caller that borrows withOperation onto another object
+ * (test doubles do) keeps it.
+ */
+function dropFrame(group, frame) {
+  if (!group || !frame || group.frames[0] === frame) return;
+  group.frames = group.frames.filter((f) => f !== frame);
+}
+
 /** The query of an events read: `types` as the wire's comma-separated list. */
 function eventQuery(types, startTime, endTime) {
   return {
@@ -241,6 +314,9 @@ class PlaidClient {
         : options.timeout !== undefined
           ? options.timeout
           : DEFAULT_BATCH_TIMEOUT_MS;
+    // Delays (ms) before sending a keyed write again when its answer was lost
+    // (no response, 502, 504). See the Idempotency-Key note in http.js.
+    this.retryDelaysMs = options.retryDelaysMs;
     this.documentVersions = {};
     // The server's clock minus this machine's, in ms, from the last response
     // with a Date header (null before one). See serverNow().
@@ -253,7 +329,8 @@ class PlaidClient {
     // The open logical operation (audit-log group), or null. While set, every
     // write is stamped with `?group-id=` (+ `group-message`) so the audit log
     // folds them into ONE expandable entry. See beginOperation / withOperation.
-    // Shape: { id, message, depth, written, refined }.
+    // Shape: { id, message, depth, written, refined, frames }, where each of
+    // `frames` is { keys, count, minted, depth, owned } and the last numbers.
     this.operationGroup = null;
     // Optional callback fired once (per client) when any request returns HTTP
     // 401 — i.e. the token is missing/expired/invalid. Apps use it to discard
@@ -289,10 +366,10 @@ class PlaidClient {
        * @param {Array} tokens - The tokens to link
        * @param {any} [metadata] - Metadata for the link. Omit to leave unset; pass null to send JSON null.
        */
-      create: (vocabItem, tokens, metadata, auditMessage) =>
+      create: (vocabItem, tokens, metadata, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/vocab-links", {
           auditMessage,
-          body: bodyOf({ "vocab-item": vocabItem, tokens, metadata }),
+          body: bodyOf({ id, "vocab-item": vocabItem, tokens, metadata }),
         }),
       /**
        * Create multiple vocab links in a single operation. Entries may
@@ -396,14 +473,17 @@ class PlaidClient {
        *   `['vocab-item/delete', 'vocab-item/restore']`)
        * @param {string} [itemId] - Only the changes that wrote this one entry,
        *   each with only its operations that did
+       * @param {string[]|string} [kinds] - Only the entries of operations of
+       *   these kinds (e.g. `['review', 'guess-adoption']`), each whole
        */
-      audit: (id, startTime, endTime, opTypes, itemId) =>
+      audit: (id, startTime, endTime, opTypes, itemId, kinds) =>
         listAll(this, `/api/v1/vocab-layers/${id}/audit`, {
           query: {
             "start-time": startTime,
             "end-time": endTime,
             "op-types": opTypesParam(opTypes),
             "item-id": itemId,
+            kinds: kindsParam(kinds),
           },
         }),
       /**
@@ -421,7 +501,7 @@ class PlaidClient {
        */
       auditPage: (
         id,
-        { startTime, endTime, opTypes, order, limit, cursor, itemId } = {},
+        { startTime, endTime, opTypes, kinds, order, limit, cursor, itemId } = {},
       ) =>
         listPage(this, `/api/v1/vocab-layers/${id}/audit`, {
           limit,
@@ -430,6 +510,7 @@ class PlaidClient {
             "start-time": startTime,
             "end-time": endTime,
             "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
             order,
             "item-id": itemId,
           },
@@ -488,24 +569,29 @@ class PlaidClient {
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`: the value read for this key (null or undefined when it
+       *   was absent). The write is then refused with a 409 when the stored value differs.
        */
-      setConfig: (id, namespace, configKey, configValue, auditMessage) =>
+      setConfig: (id, namespace, configKey, configValue, auditMessage, options) =>
         this._request(
           "PUT",
           `/api/v1/vocab-layers/${id}/config/${namespace}/${configKey}`,
-          { auditMessage, rawBody: configValue, skipResponseTransform: true },
+          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) =>
+      deleteConfig: (id, namespace, configKey, auditMessage, options) =>
         this._request(
           "DELETE",
           `/api/v1/vocab-layers/${id}/config/${namespace}/${configKey}`,
-          { auditMessage, skipResponseTransform: true },
+          configRequest(auditMessage, undefined, options, true),
         ),
       /**
        * List all vocab layers accessible to user. Transparently follows
@@ -538,10 +624,10 @@ class PlaidClient {
        * Create a new vocab layer. Note: this also registers the user as a maintainer.
        * @param {string} name - The name
        */
-      create: (name, auditMessage) =>
+      create: (name, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/vocab-layers", {
           auditMessage,
-          body: bodyOf({ name }),
+          body: bodyOf({ id, name }),
         }),
       /**
        * Assign a user as a maintainer for this vocab layer.
@@ -650,10 +736,19 @@ class PlaidClient {
        * @param {any} value - The value
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (layerId, sourceId, targetId, value, metadata, auditMessage) =>
+      create: (
+        layerId,
+        sourceId,
+        targetId,
+        value,
+        metadata,
+        auditMessage,
+        { id } = {},
+      ) =>
         this._request("POST", "/api/v1/relations", {
           auditMessage,
           body: bodyOf({
+            id,
             "layer-id": layerId,
             "source-id": sourceId,
             "target-id": targetId,
@@ -696,31 +791,31 @@ class PlaidClient {
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`: the value read for this key (null or undefined when it
+       *   was absent). The write is then refused with a 409 when the stored value differs.
        */
-      setConfig: (
-        spanLayerId,
-        namespace,
-        configKey,
-        configValue,
-        auditMessage,
-      ) =>
+      setConfig: (spanLayerId, namespace, configKey, configValue, auditMessage, options) =>
         this._request(
           "PUT",
           `/api/v1/span-layers/${spanLayerId}/config/${namespace}/${configKey}`,
-          { auditMessage, rawBody: configValue, skipResponseTransform: true },
+          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) =>
+      deleteConfig: (spanLayerId, namespace, configKey, auditMessage, options) =>
         this._request(
           "DELETE",
           `/api/v1/span-layers/${spanLayerId}/config/${namespace}/${configKey}`,
-          { auditMessage, skipResponseTransform: true },
+          configRequest(auditMessage, undefined, options, true),
         ),
+      ...constraintMethods(this, "span-layers"),
       /**
        * Get a span layer by ID.
        * @param {string} spanLayerId - The span layer ID
@@ -750,10 +845,10 @@ class PlaidClient {
        * @param {string} tokenLayerId - The token layer ID
        * @param {string} name - The name
        */
-      create: (tokenLayerId, name, auditMessage) =>
+      create: (tokenLayerId, name, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/span-layers", {
           auditMessage,
-          body: bodyOf({ "token-layer-id": tokenLayerId, name }),
+          body: bodyOf({ id, "token-layer-id": tokenLayerId, name }),
         }),
       /**
        * Shift a span layer's display order.
@@ -786,10 +881,11 @@ class PlaidClient {
        * @param {any} value - The value
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (spanLayerId, tokens, value, metadata, auditMessage) =>
+      create: (spanLayerId, tokens, value, metadata, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/spans", {
           auditMessage,
           body: bodyOf({
+            id,
             "span-layer-id": spanLayerId,
             tokens,
             value,
@@ -958,10 +1054,18 @@ class PlaidClient {
        * @param {string} body - The request body
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (textLayerId, documentId, body, metadata, auditMessage) =>
+      create: (
+        textLayerId,
+        documentId,
+        body,
+        metadata,
+        auditMessage,
+        { id } = {},
+      ) =>
         this._request("POST", "/api/v1/texts", {
           auditMessage,
           body: bodyOf({
+            id,
             "text-layer-id": textLayerId,
             "document-id": documentId,
             body,
@@ -989,13 +1093,45 @@ class PlaidClient {
        *   {type: 'replace', index, length, value: string} — unlike
        *     delete+insert, a token covering the whole range is resized to keep
        *     it (respell a word in place without losing its annotations).
+       * A list is applied exactly as sent. With `base` (the `digest` of the
+       * body the update was made on, as every read of a text gives it) the
+       * update applies only to that body, and is refused with 409 and
+       * `text-changed` otherwise. Strict mode then does not stamp it, unless
+       * `versioned` is true (a batch whose later writes are stamped needs its
+       * first write stamped too).
        * @param {string} textId - The text ID
        * @param {any} body - The request body
+       * @param {string} [auditMessage]
+       * @param {{base?: string, versioned?: boolean}} [options]
+       */
+      update: (textId, body, auditMessage, { base, versioned } = {}) =>
+        this._request("PATCH", `/api/v1/texts/${textId}`, {
+          auditMessage,
+          body: bodyOf({ body, base }),
+          versioned: versioned ?? (base === undefined || base === null),
+        }),
+      /**
+       * Change a text's body by the edits made at the caret: a list of edit
+       * directives as `update` takes them (code-point indices, applied in
+       * order, each index in the body the ones before it left). Only their
+       * net change counts. An insert or a delete stays where it was made, and
+       * a stretch deleted and typed over is read as a whole new body is. The
+       * answer is the text with its new `digest` and `reshape` (the tokens
+       * moved, the spans and vocab links trimmed, the rows deleted). With
+       * `base`, the digest of the body the edits were made on, the edit
+       * applies only to that body and is refused with 409 and `text-changed`
+       * otherwise, and strict mode does not stamp it unless `versioned` is
+       * true. See composeTextEdits and gapsToOps.
+       * @param {string} textId - The text ID
+       * @param {Array<object>} edits - The edit directives
+       * @param {string} [auditMessage]
+       * @param {{base?: string, versioned?: boolean}} [options]
        */
-      update: (textId, body, auditMessage) =>
+      edit: (textId, edits, auditMessage, { base, versioned } = {}) =>
         this._request("PATCH", `/api/v1/texts/${textId}`, {
           auditMessage,
-          body: bodyOf({ body }),
+          body: bodyOf({ edits, base }),
+          versioned: versioned ?? (base === undefined || base === null),
         }),
     };
 
@@ -1065,13 +1201,16 @@ class PlaidClient {
        *   types, spelled as in an entry's `op/type` (e.g.
        *   `['span-layer/create', 'span-layer/delete']`). An entry appears when
        *   one of its operations matches, carrying only the ones that did.
+       * @param {string[]|string} [kinds] - Only the entries of operations of
+       *   these kinds (e.g. `['review', 'guess-adoption']`), each whole
        */
-      audit: (userId, startTime, endTime, opTypes) =>
+      audit: (userId, startTime, endTime, opTypes, kinds) =>
         listAll(this, `/api/v1/users/${userId}/audit`, {
           query: {
             "start-time": startTime,
             "end-time": endTime,
             "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
           },
         }),
       /**
@@ -1087,7 +1226,7 @@ class PlaidClient {
        */
       auditPage: (
         userId,
-        { startTime, endTime, opTypes, order, limit, cursor } = {},
+        { startTime, endTime, opTypes, kinds, order, limit, cursor } = {},
       ) =>
         listPage(this, `/api/v1/users/${userId}/audit`, {
           limit,
@@ -1096,6 +1235,7 @@ class PlaidClient {
             "start-time": startTime,
             "end-time": endTime,
             "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
             order,
           },
         }),
@@ -1357,6 +1497,8 @@ class PlaidClient {
         this._request("POST", `/api/v1/users/${userId}/tokens`, {
           auditMessage,
           body: bodyOf({ name }),
+          // The answer is the secret, which the server never keeps.
+          noIdempotency: true,
         }),
       /**
        * Revoke a named API token (soft-revoke; idempotent).
@@ -1451,6 +1593,8 @@ class PlaidClient {
       ) =>
         this._request("POST", "/api/v1/invites", {
           auditMessage,
+          // The answer is the code, which the server never keeps.
+          noIdempotency: true,
           body: bodyOf({
             "project-id": projectId,
             "project-role": projectRole,
@@ -1623,13 +1767,16 @@ class PlaidClient {
        * @param {string[]|string} [opts.opTypes] - Only these op types (e.g.
        *   `['span-layer/create']`). An entry appears when one of its operations
        *   matches, carrying only the ones that did.
+       * @param {string[]|string} [opts.kinds] - Only the entries of operations
+       *   of these kinds (e.g. `['review']`), each whole
        */
-      list: ({ startTime, endTime, opTypes } = {}) =>
+      list: ({ startTime, endTime, opTypes, kinds } = {}) =>
         listAll(this, "/api/v1/audit", {
           query: {
             "start-time": startTime,
             "end-time": endTime,
             "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
           },
         }),
       /**
@@ -1641,7 +1788,7 @@ class PlaidClient {
        * @param {string} [opts.cursor] - Opaque cursor from a previous page
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
-      listPage: ({ startTime, endTime, opTypes, order, limit, cursor } = {}) =>
+      listPage: ({ startTime, endTime, opTypes, kinds, order, limit, cursor } = {}) =>
         listPage(this, "/api/v1/audit", {
           limit,
           cursor,
@@ -1649,6 +1796,7 @@ class PlaidClient {
             "start-time": startTime,
             "end-time": endTime,
             "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
             order,
           },
         }),
@@ -1656,13 +1804,14 @@ class PlaidClient {
        * Async-iterate the instance-wide audit log page by page. Admin only.
        * @returns {AsyncGenerator<Array>}
        */
-      iterPages: ({ startTime, endTime, opTypes, pageSize } = {}) =>
+      iterPages: ({ startTime, endTime, opTypes, kinds, pageSize } = {}) =>
         iterPages(this, "/api/v1/audit", {
           pageSize,
           query: {
             "start-time": startTime,
             "end-time": endTime,
             "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
           },
         }),
       /**
@@ -1722,10 +1871,12 @@ class PlaidClient {
         overlapMode,
         parentTokenLayerId,
         auditMessage,
+        { id } = {},
       ) =>
         this._request("POST", "/api/v1/token-layers", {
           auditMessage,
           body: bodyOf({
+            id,
             "text-layer-id": textLayerId,
             name,
             "overlap-mode": overlapMode,
@@ -1738,31 +1889,31 @@ class PlaidClient {
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`: the value read for this key (null or undefined when it
+       *   was absent). The write is then refused with a 409 when the stored value differs.
        */
-      setConfig: (
-        tokenLayerId,
-        namespace,
-        configKey,
-        configValue,
-        auditMessage,
-      ) =>
+      setConfig: (tokenLayerId, namespace, configKey, configValue, auditMessage, options) =>
         this._request(
           "PUT",
           `/api/v1/token-layers/${tokenLayerId}/config/${namespace}/${configKey}`,
-          { auditMessage, rawBody: configValue, skipResponseTransform: true },
+          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) =>
+      deleteConfig: (tokenLayerId, namespace, configKey, auditMessage, options) =>
         this._request(
           "DELETE",
           `/api/v1/token-layers/${tokenLayerId}/config/${namespace}/${configKey}`,
-          { auditMessage, skipResponseTransform: true },
+          configRequest(auditMessage, undefined, options, true),
         ),
+      ...constraintMethods(this, "token-layers"),
       /**
        * Get a token layer by ID.
        * @param {string} tokenLayerId - The token layer ID
@@ -1803,15 +1954,26 @@ class PlaidClient {
        * take it. While the lock is held, a second acquire is refused with
        * HTTP 423, whoever makes it, this user included.
        *
+       * `newLockId` names the holder from the client's side (a fresh UUID). An
+       * acquire whose answer never arrived can then be sent again, which
+       * answers 200 while that holder has the lock, or released. Without it
+       * the server mints the id, and a lost answer leaves a lock nobody can
+       * release until it expires.
+       *
        * outOfBand: the lock is a signal, not project data (see the note at
        * the top of http.js). Queued on a batch it would be taken only at
        * submit, after every write it was meant to guard, and until then answer
        * success to a caller that does not hold it and cannot see the 423
        * saying somebody else does.
        * @param {string} documentId - The document ID
+       * @param {string} [auditMessage]
+       * @param {string} [newLockId] - A holder id this client minted
        */
-      acquireLock: (documentId, auditMessage) =>
+      acquireLock: (documentId, auditMessage, newLockId) =>
         this._request("POST", `/api/v1/documents/${documentId}/lock`, {
+          ...(newLockId !== undefined && newLockId !== null
+            ? { queryParams: { "new-lock-id": newLockId } }
+            : {}),
           auditMessage,
           outOfBand: true,
         }),
@@ -1872,7 +2034,10 @@ class PlaidClient {
        * The lock is per HOLDER: each block is its own, named by
        * `lock.lockId`, and only that id renews or releases it. NOT
        * re-entrant: a nested `locked()` block on one document is a second
-       * holder and gets the 423. Lock at exactly one level per call path. A
+       * holder and gets the 423. Lock at exactly one level per call path.
+       * The block mints its holder id and sends it with the acquire, so an
+       * acquire whose answer was lost is sent again (up to three tries) and,
+       * if none is answered, released rather than left to expire. A
        * lost lock is recorded on the CLIENT, like strict mode, so it stops
        * every write the client makes (on any batch of it too) and not only the
        * ones this block makes.
@@ -1961,13 +2126,16 @@ class PlaidClient {
        *   types, spelled as in an entry's `op/type` (e.g.
        *   `['span-layer/create', 'span-layer/delete']`). An entry appears when
        *   one of its operations matches, carrying only the ones that did.
+       * @param {string[]|string} [kinds] - Only the entries of operations of
+       *   these kinds (e.g. `['review', 'guess-adoption']`), each whole
        */
-      audit: (documentId, startTime, endTime, opTypes) =>
+      audit: (documentId, startTime, endTime, opTypes, kinds) =>
         listAll(this, `/api/v1/documents/${documentId}/audit`, {
           query: {
             "start-time": startTime,
             "end-time": endTime,
             "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
           },
         }),
       /**
@@ -1983,7 +2151,7 @@ class PlaidClient {
        */
       auditPage: (
         documentId,
-        { startTime, endTime, opTypes, order, limit, cursor } = {},
+        { startTime, endTime, opTypes, kinds, order, limit, cursor } = {},
       ) =>
         listPage(this, `/api/v1/documents/${documentId}/audit`, {
           limit,
@@ -1992,6 +2160,7 @@ class PlaidClient {
             "start-time": startTime,
             "end-time": endTime,
             "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
             order,
           },
         }),
@@ -2064,10 +2233,10 @@ class PlaidClient {
        * @param {string} name - The name
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (projectId, name, metadata, auditMessage) =>
+      create: (projectId, name, metadata, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/documents", {
           auditMessage,
-          body: bodyOf({ "project-id": projectId, name, metadata }),
+          body: bodyOf({ id, "project-id": projectId, name, metadata }),
         }),
       /**
        * Copy a document and everything in it into a new document of the same
@@ -2083,10 +2252,10 @@ class PlaidClient {
        *   file behind
        * @param {string} [auditMessage] - Custom audit message for this operation
        */
-      copy: (documentId, name, { includeMedia } = {}, auditMessage) =>
+      copy: (documentId, name, { includeMedia, id } = {}, auditMessage) =>
         this._request("POST", `/api/v1/documents/${documentId}/copy`, {
           auditMessage,
-          body: bodyOf({ name, "include-media": includeMedia }),
+          body: bodyOf({ id, name, "include-media": includeMedia }),
         }),
     };
 
@@ -2133,24 +2302,29 @@ class PlaidClient {
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`: the value read for this key (null or undefined when it
+       *   was absent). The write is then refused with a 409 when the stored value differs.
        */
-      setConfig: (id, namespace, configKey, configValue, auditMessage) =>
+      setConfig: (id, namespace, configKey, configValue, auditMessage, options) =>
         this._request(
           "PUT",
           `/api/v1/projects/${id}/config/${namespace}/${configKey}`,
-          { auditMessage, rawBody: configValue, skipResponseTransform: true },
+          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) =>
+      deleteConfig: (id, namespace, configKey, auditMessage, options) =>
         this._request(
           "DELETE",
           `/api/v1/projects/${id}/config/${namespace}/${configKey}`,
-          { auditMessage, skipResponseTransform: true },
+          configRequest(auditMessage, undefined, options, true),
         ),
       /**
        * Assign a user as a maintainer for this project.
@@ -2182,13 +2356,16 @@ class PlaidClient {
        *   types, spelled as in an entry's `op/type` (e.g.
        *   `['span-layer/create', 'span-layer/delete']`). An entry appears when
        *   one of its operations matches, carrying only the ones that did.
+       * @param {string[]|string} [kinds] - Only the entries of operations of
+       *   these kinds (e.g. `['review', 'guess-adoption']`), each whole
        */
-      audit: (projectId, startTime, endTime, opTypes) =>
+      audit: (projectId, startTime, endTime, opTypes, kinds) =>
         listAll(this, `/api/v1/projects/${projectId}/audit`, {
           query: {
             "start-time": startTime,
             "end-time": endTime,
             "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
           },
         }),
       /**
@@ -2204,7 +2381,7 @@ class PlaidClient {
        */
       auditPage: (
         projectId,
-        { startTime, endTime, opTypes, order, limit, cursor } = {},
+        { startTime, endTime, opTypes, kinds, order, limit, cursor } = {},
       ) =>
         listPage(this, `/api/v1/projects/${projectId}/audit`, {
           limit,
@@ -2213,6 +2390,7 @@ class PlaidClient {
             "start-time": startTime,
             "end-time": endTime,
             "op-types": opTypesParam(opTypes),
+            kinds: kindsParam(kinds),
             order,
           },
         }),
@@ -2345,10 +2523,10 @@ class PlaidClient {
        * Create a new project. Note: this also registers the user as a maintainer.
        * @param {string} name - The name
        */
-      create: (name, auditMessage) =>
+      create: (name, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/projects", {
           auditMessage,
-          body: bodyOf({ name }),
+          body: bodyOf({ id, name }),
         }),
     };
 
@@ -2359,30 +2537,29 @@ class PlaidClient {
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`: the value read for this key (null or undefined when it
+       *   was absent). The write is then refused with a 409 when the stored value differs.
        */
-      setConfig: (
-        textLayerId,
-        namespace,
-        configKey,
-        configValue,
-        auditMessage,
-      ) =>
+      setConfig: (textLayerId, namespace, configKey, configValue, auditMessage, options) =>
         this._request(
           "PUT",
           `/api/v1/text-layers/${textLayerId}/config/${namespace}/${configKey}`,
-          { auditMessage, rawBody: configValue, skipResponseTransform: true },
+          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) =>
+      deleteConfig: (textLayerId, namespace, configKey, auditMessage, options) =>
         this._request(
           "DELETE",
           `/api/v1/text-layers/${textLayerId}/config/${namespace}/${configKey}`,
-          { auditMessage, skipResponseTransform: true },
+          configRequest(auditMessage, undefined, options, true),
         ),
       /**
        * Get a text layer by ID.
@@ -2423,10 +2600,10 @@ class PlaidClient {
        * @param {string} projectId - The project ID
        * @param {string} name - The name
        */
-      create: (projectId, name, auditMessage) =>
+      create: (projectId, name, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/text-layers", {
           auditMessage,
-          body: bodyOf({ "project-id": projectId, name }),
+          body: bodyOf({ id, "project-id": projectId, name }),
         }),
     };
 
@@ -2465,10 +2642,10 @@ class PlaidClient {
        * @param {string} form - The vocab item form
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (vocabLayerId, form, metadata, auditMessage) =>
+      create: (vocabLayerId, form, metadata, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/vocab-items", {
           auditMessage,
-          body: bodyOf({ "vocab-layer-id": vocabLayerId, form, metadata }),
+          body: bodyOf({ id, "vocab-layer-id": vocabLayerId, form, metadata }),
         }),
       /**
        * Create multiple vocab items in a single operation. Entries may target
@@ -2515,9 +2692,35 @@ class PlaidClient {
        * of those links has its version bumped, and a strict-mode client picks
        * up their new versions from the response.
        * @param {string} id - The resource ID
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expectedLinkCount?: number}} [options] - `expectedLinkCount`: the
+       *   number of links the caller showed. The delete is refused with a 409 when
+       *   the entry has any other number of links by then.
        */
-      delete: (id, auditMessage) =>
-        this._request("DELETE", `/api/v1/vocab-items/${id}`, { auditMessage }),
+      delete: (id, auditMessage, { expectedLinkCount } = {}) =>
+        this._request("DELETE", `/api/v1/vocab-items/${id}`, {
+          auditMessage,
+          queryParams: { "expected-link-count": expectedLinkCount },
+        }),
+      /**
+       * Merge entries into this one, in one operation. Every link to a loser
+       * moves to the survivor (keeping its id and metadata), except a link on
+       * words the survivor is already linked to, which is deleted, and then the
+       * losers are deleted. Links are read when the merge runs, so one made
+       * after the caller looked moves too. Every loser must be in the
+       * survivor's vocabulary, and a loser that is already gone is skipped, so
+       * a repeated merge changes nothing. References to a loser in other
+       * entries' metadata are the caller's to rewrite, in the same batch.
+       * Needs maintainer rights on the vocabulary.
+       * @param {string} survivorId - The entry that stays
+       * @param {string[]} loserIds - The entries merged into it
+       * @returns {Promise<{moved: number, duplicates: number, removed: string[]}>}
+       */
+      merge: (survivorId, loserIds, auditMessage) =>
+        this._request("POST", `/api/v1/vocab-items/${survivorId}/merge`, {
+          auditMessage,
+          body: { losers: loserIds },
+        }),
       /**
        * Update a vocab item's form. A document read carries the entry's form on
        * every link to it, so a rename restates those documents: each has its
@@ -2550,10 +2753,10 @@ class PlaidClient {
        * @param {string} spanLayerId - The span layer ID
        * @param {string} name - The name
        */
-      create: (spanLayerId, name, auditMessage) =>
+      create: (spanLayerId, name, auditMessage, { id } = {}) =>
         this._request("POST", "/api/v1/relation-layers", {
           auditMessage,
-          body: bodyOf({ "span-layer-id": spanLayerId, name }),
+          body: bodyOf({ id, "span-layer-id": spanLayerId, name }),
         }),
       /**
        * Set a configuration value for a layer in an editor namespace.
@@ -2561,31 +2764,31 @@ class PlaidClient {
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{expected?: any}} [options] - `expected`: the value read for this key (null or undefined when it
+       *   was absent). The write is then refused with a 409 when the stored value differs.
        */
-      setConfig: (
-        relationLayerId,
-        namespace,
-        configKey,
-        configValue,
-        auditMessage,
-      ) =>
+      setConfig: (relationLayerId, namespace, configKey, configValue, auditMessage, options) =>
         this._request(
           "PUT",
           `/api/v1/relation-layers/${relationLayerId}/config/${namespace}/${configKey}`,
-          { auditMessage, rawBody: configValue, skipResponseTransform: true },
+          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) =>
+      deleteConfig: (relationLayerId, namespace, configKey, auditMessage, options) =>
         this._request(
           "DELETE",
           `/api/v1/relation-layers/${relationLayerId}/config/${namespace}/${configKey}`,
-          { auditMessage, skipResponseTransform: true },
+          configRequest(auditMessage, undefined, options, true),
         ),
+      ...constraintMethods(this, "relation-layers"),
       /**
        * Get a relation layer by ID.
        * @param {string} relationLayerId - The relation layer ID
@@ -2639,10 +2842,12 @@ class PlaidClient {
         precedence,
         metadata,
         auditMessage,
+        { id } = {},
       ) =>
         this._request("POST", "/api/v1/tokens", {
           auditMessage,
           body: bodyOf({
+            id,
             "token-layer-id": tokenLayerId,
             text,
             begin,
@@ -2707,11 +2912,21 @@ class PlaidClient {
        * left half (keeps its ID, spans, vocab-links); the new right token's ID is returned.
        * @param {string} tokenId - The token ID
        * @param {number} position - Code-point offset to split at (strictly between begin and end)
-       */
-      split: (tokenId, position, auditMessage) =>
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{id?: string}} [options] - `id`: the right half's id, a UUIDv7 this
+       *   client minted. A relation layer whose relations must stay inside one token
+       *   of this layer declares a same-ancestor constraint, and the server deletes
+       *   the relations the split leaves crossing in the same transaction.
+       */
+      split: (
+        tokenId,
+        position,
+        auditMessage,
+        { id } = {},
+      ) =>
         this._request("POST", `/api/v1/tokens/${tokenId}/split`, {
           auditMessage,
-          body: bodyOf({ position }),
+          body: bodyOf({ id, position }),
         }),
       /**
        * Merge two tokens. The left token (smaller begin) survives with the combined
@@ -3000,9 +3215,13 @@ class PlaidClient {
        * @param {object} [opts]
        * @param {string} [opts.anchorLabel] - What the comment is about, in words (at most 200 characters)
        */
-      create: (entityType, entityId, body, { anchorLabel } = {}) =>
+      create: (entityType, entityId, body, { anchorLabel, id } = {}) =>
         this._request("POST", "/api/v1/comments", {
+          // A comment is not audited, so it never joins an open operation,
+          // and never takes a number from an edit's Idempotency-Key seed.
+          noOperation: true,
           body: bodyOf({
+            id,
             "entity-type": entityType,
             "entity-id": entityId,
             body,
@@ -3021,13 +3240,17 @@ class PlaidClient {
        * @param {string} body - The replacement text
        */
       update: (id, body) =>
-        this._request("PATCH", `/api/v1/comments/${id}`, { body: { body } }),
+        this._request("PATCH", `/api/v1/comments/${id}`, {
+          body: { body },
+          noOperation: true,
+        }),
       /**
        * Delete a comment. The author may delete their own; a project
        * maintainer (or admin) may delete any.
        * @param {string} id - The comment id
        */
-      delete: (id) => this._request("DELETE", `/api/v1/comments/${id}`),
+      delete: (id) =>
+        this._request("DELETE", `/api/v1/comments/${id}`, { noOperation: true }),
       /**
        * List comments in a project, oldest first. Transparently follows
        * pagination cursors and returns the full flat array.
@@ -3279,10 +3502,10 @@ class PlaidClient {
        * @param {string} [opts.body] - The Markdown text (up to 20000 characters; may be empty)
        * @param {boolean} [opts.pinned] - Send this one to the assistant in full on every turn
        */
-      create: (projectId, title, { body, pinned } = {}, auditMessage) =>
+      create: (projectId, title, { body, pinned, id } = {}, auditMessage) =>
         this._request("POST", `/api/v1/projects/${projectId}/guidelines`, {
           auditMessage,
-          body: bodyOf({ title, body, pinned }),
+          body: bodyOf({ id, title, body, pinned }),
         }),
       /**
        * Read one guideline, Markdown body included.
@@ -3414,20 +3637,47 @@ class PlaidClient {
    *
    * `kind` says what kind of operation this is, for a program reading the
    * log: one of `assistant-plan`, `service-run`, `import`, `bulk-edit`,
-   * `guess-adoption` or `repair` (the server refuses any other). `ref` is a
-   * short string naming what the operation came from, in the shape its kind
-   * documents (the core manual, "Kinds of operation"). Both are recorded from
-   * the first write like the label, and a nested operation keeps the outer
-   * one's.
+   * `guess-adoption`, `repair` or `review` (the server refuses any other).
+   * `ref` is a short string naming what the operation came from, in the
+   * shape its kind documents (the core manual, "Kinds of operation"). Both
+   * are recorded from the first write like the label, and a nested operation
+   * keeps the outer one's.
+   *
+   * `keys` (from `keySeed()`) makes a run of the operation send the same
+   * requests as an earlier run with the same keys: the nth keyed request that
+   * joins it takes the Idempotency-Key `<seed>.<n>` and the document-version
+   * its first run claimed, so a request that landed is answered from its
+   * first send and writes nothing again. The count starts at 0 at each
+   * outermost begin. A nested operation joins the outer one's keys, unless it
+   * brings its own: then it numbers from 0 under its own seed until its
+   * matching end, and the outer numbering resumes after it.
    *
    * @param {string} message - Human label for the operation.
-   * @param {object} [opts] - Optional `{ id, kind, ref }`. `id` adopts an existing group id instead of minting one (a service joining the requester's operation; `requestService` propagates an open operation to the service automatically). `kind` and `ref` are described above.
+   * @param {object} [opts] - Optional `{ id, kind, ref, keys }`. `id` adopts an existing group id instead of minting one (a service joining the requester's operation; `requestService` propagates an open operation to the service automatically). `kind`, `ref` and `keys` are described above.
    * @returns {string} The operation's group id.
    */
-  beginOperation(message, { id, kind, ref } = {}) {
-    if (this.operationGroup) {
-      this.operationGroup.depth += 1;
-      return this.operationGroup.id;
+  beginOperation(message, { id, kind, ref, keys, minted } = {}) {
+    const frame = {
+      keys: keys || null,
+      count: 0,
+      // Any iterable of ids (a Set, an array).
+      minted: minted ? new Set(minted) : null,
+      depth: 1,
+    };
+    const open = this.operationGroup;
+    this._openedFrame = null;
+    if (open) {
+      // A nested operation joins the outer one. When it brings its own key
+      // seed or ids (a queued edit run inside a longer operation), it numbers
+      // the keys in a frame of its own until it ends, then the frame under it
+      // numbers again.
+      open.depth += 1;
+      if (keys || minted) {
+        frame.depth = open.depth;
+        open.frames.push(frame);
+        this._openedFrame = frame;
+      }
+      return open.id;
     }
     this.operationGroup = {
       id: id || crypto.randomUUID(),
@@ -3437,10 +3687,22 @@ class PlaidClient {
       depth: 1,
       written: false,
       refined: undefined,
+      frames: [frame],
     };
+    this._openedFrame = frame;
     return this.operationGroup.id;
   }
 
+  /**
+   * A seed for the Idempotency-Keys of a logical operation that may be run
+   * again from the top (see beginOperation's `keys`). Keep it with the work
+   * it belongs to and pass it to every run.
+   * @returns {{seed: string, stamps: Map<number, number|null>}}
+   */
+  keySeed() {
+    return { seed: uuidv7(), stamps: new Map() };
+  }
+
   /**
    * End the current logical operation. With no argument this is purely local
    * (no request). Pass a refined `message` to relabel the group now that the
@@ -3454,6 +3716,12 @@ class PlaidClient {
     const group = this.operationGroup;
     if (!group) return;
     if (group.depth > 1) {
+      // A frame begun at this depth by hand (beginOperation) ends here. One
+      // begun by withOperation is ended by that call itself (_dropFrame).
+      const top = group.frames.at(-1);
+      if (group.frames.length > 1 && !top.owned && top.depth === group.depth) {
+        group.frames.pop();
+      }
       group.depth -= 1;
       return;
     }
@@ -3486,22 +3754,40 @@ class PlaidClient {
    *
    * @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 }`, as for beginOperation.
+   * @param {object} [opts] - Optional `{ kind, ref, id, keys }`, as for beginOperation.
    * @returns {Promise<any>} Whatever `fn` resolves to.
    */
-  async withOperation(message, fn, { kind, ref } = {}) {
-    this.beginOperation(message, { kind, ref });
+  async withOperation(message, fn, { kind, ref, id, keys, minted } = {}) {
+    this.beginOperation(message, { kind, ref, id, keys, minted });
     const group = this.operationGroup;
+    // The key frame this call opened is ended by this call, whatever else
+    // began or ended meanwhile, not by whichever end comes at its depth.
+    const frame = this._openedFrame;
+    if (frame) frame.owned = true;
     const setMessage = (msg) => {
       if (group.depth === 1) group.refined = msg;
     };
+    let result;
     try {
-      return await fn(setMessage);
-    } finally {
-      await this.endOperation();
+      result = await fn(setMessage);
+    } catch (e) {
+      // A relabel the server refuses (a token scoped to projects may not
+      // relabel a group, which names none) must not take the place of the
+      // error `fn` threw: the caller answers for that one.
+      dropFrame(group, frame);
+      try {
+        await this.endOperation();
+      } catch (relabel) {
+        console.warn('The operation was not relabelled:', relabel);
+      }
+      throw e;
     }
+    dropFrame(group, frame);
+    await this.endOperation();
+    return result;
   }
 
+
   /**
    * Open a batch: a view of this client with the same bundles, on which every
    * write of project data queues instead of going out. `submit()` sends the
@@ -3533,14 +3819,17 @@ class PlaidClient {
   /**
    * POST one batch request (at most MAX_BATCH_OPS operations). Resolves to
    * one `{ status, headers, body }` per operation, with only the body
-   * recased: the headers keep the server's spelling.
+   * recased: the headers keep the server's spelling. `key` is the request's
+   * Idempotency-Key: a batch whose answer is lost (no response, 502, 504) is
+   * sent again under it, and answered from the first send if that landed.
    */
-  async _postBatch(url, body) {
+  async _postBatch(url, body, { key = uuidv7() } = {}) {
     const fetchOptions = {
       method: "POST",
       headers: {
         Authorization: `Bearer ${this.token}`,
         "Content-Type": "application/json",
+        [IDEMPOTENCY_HEADER]: key,
       },
       body: JSON.stringify(body),
     };
@@ -3549,17 +3838,26 @@ class PlaidClient {
       // Retry a 503: the batch is atomic, so a refused one wrote nothing and
       // repeating it is safe. A fresh timeout signal per attempt — an
       // AbortSignal.timeout stays aborted once it fires.
-      const response = await retryWhileBusy(async () => {
+      const attempt = async () => {
         const signal = timeoutSignal(this.batchTimeout);
-        const res = await fetch(
-          url,
-          signal ? { ...fetchOptions, signal } : fetchOptions,
-        );
+        let res;
+        try {
+          res = await fetch(
+            url,
+            signal ? { ...fetchOptions, signal } : fetchOptions,
+          );
+        } catch (e) {
+          throw makeNetworkError(e, url, "POST");
+        }
         if (!res.ok) {
           throw makeHttpError(res, await parseErrorBody(res), url, "POST");
         }
         return res;
+      };
+      const response = await retryUnknown(() => retryWhileBusy(attempt), {
+        delaysMs: this.retryDelaysMs,
       }).catch((error) => {
+        error.idempotencyKey = key;
         // 401 means the token is missing, expired or invalid: fire the app's
         // auth-error handler once, exactly as makeRequest does.
         if (
@@ -3578,6 +3876,8 @@ class PlaidClient {
       });
 
       const results = await response.json();
+      // A replayed batch carries the versions right after its first send.
+      const replayed = response.headers?.get?.(REPLAYED_HEADER) === "true";
 
       // Extract document versions from each batch response
       for (const result of results) {
@@ -3588,10 +3888,11 @@ class PlaidClient {
             );
             if (typeof versionsMap === "object" && versionsMap !== null) {
               // Clone once per response, then merge — not once per entry.
-              this.documentVersions = {
-                ...this.documentVersions,
-                ...versionsMap,
-              };
+              this.documentVersions = mergeVersions(
+                this.documentVersions,
+                versionsMap,
+                replayed,
+              );
             }
           } catch (e) {
             console.warn(
@@ -3602,13 +3903,16 @@ class PlaidClient {
         }
       }
 
-      return results.map((result) => ({
+      const out = results.map((result) => ({
         ...result,
         body: transformResponse(result.body),
       }));
+      return replayed ? markReplayed(out) : out;
     } catch (error) {
-      if (error.status) throw error;
-      throw makeNetworkError(error, url, "POST");
+      if (error.status !== undefined) throw error;
+      throw Object.assign(makeNetworkError(error, url, "POST"), {
+        idempotencyKey: key,
+      });
     }
   }
 
@@ -3777,8 +4081,102 @@ class PlaidClient {
   }
 }
 
+
+/**
+ * The request options of a config write. With `options.expected` present
+ * (even as undefined, which means the key was absent) the write is a
+ * compare-and-set: `?if-unchanged=true` and the body `{expected, value}`,
+ * which the server refuses with a 409 when the stored value is no longer
+ * `expected`. Without it the body is the value itself. Config is opaque, so
+ * neither body is re-cased.
+ */
+function configRequest(auditMessage, value, options, isDelete = false) {
+  if (!options || !Object.hasOwn(options, "expected")) {
+    return isDelete
+      ? { auditMessage, skipResponseTransform: true }
+      : { auditMessage, rawBody: value, skipResponseTransform: true };
+  }
+  const expected = options.expected === undefined ? null : options.expected;
+  return {
+    auditMessage,
+    queryParams: { "if-unchanged": true },
+    rawBody: isDelete ? { expected } : { expected, value },
+    skipResponseTransform: true,
+  };
+}
+
+/**
+ * The four layer-constraint methods of a layer bundle, on `/api/v1/<kind>`.
+ * See constraints.js and the core manual, "Layer constraints".
+ */
+function constraintMethods(client, kind) {
+  const base = (layerId) => `/api/v1/${kind}/${layerId}/constraints`;
+  return {
+    /**
+     * Declare an app namespace's constraints on this layer, replacing that
+     * namespace's list. Refused with 422 and the violations when the layer's
+     * stored data breaks them (see violationsOf).
+     * @param {string} layerId - The layer ID
+     * @param {string} namespace - The declaring app's namespace, e.g. "igt"
+     * @param {Array<object>} constraints - e.g. [{type: "single-span"}, {type: "value-set", values: ["N"]}]
+     * @param {string} [auditMessage] - Audit message for this write
+     * @param {{expected?: Array<object>|null}} [options] - `expected`: the list read for this
+     *   namespace (null when it was absent). The write is then refused with a 409 when the stored
+     *   list differs.
+     * @returns {Promise<{constraints: object}>} the layer's whole constraint map
+     */
+    setConstraints: (layerId, namespace, constraints, auditMessage, options) =>
+      client._request("PUT", `${base(layerId)}/${namespace}`, {
+        auditMessage,
+        body: constraintsBody(constraints, options),
+      }),
+    /**
+     * Remove an app namespace's constraints from this layer.
+     * @param {string} layerId - The layer ID
+     * @param {string} namespace - The declaring app's namespace
+     * @param {string} [auditMessage] - Audit message for this write
+     * @param {{expected?: Array<object>|null}} [options] - `expected`, as on setConstraints.
+     */
+    deleteConstraints: (layerId, namespace, auditMessage, options) => {
+      const body = constraintsBody(undefined, options);
+      return client._request("DELETE", `${base(layerId)}/${namespace}`, {
+        auditMessage,
+        ...(Object.keys(body).length ? { body } : {}),
+      });
+    },
+    /**
+     * The violations the given constraints would meet in this layer's stored
+     * data. Writes nothing.
+     * @param {string} layerId - The layer ID
+     * @param {Array<object>} constraints - The list to check
+     * @returns {Promise<{violations: Array<object>, violationCount: number}>}
+     */
+    checkConstraints: (layerId, constraints) =>
+      client._request("POST", `${base(layerId)}/check`, { body: { constraints } }),
+    /**
+     * Apply the remedies of the given constraints' remediable types
+     * (coextensive, single-span, single-link, same-ancestor) to every
+     * violation in this layer's stored data, one operation per document.
+     * With `document`, only that document is repaired, and a writer may
+     * ask. A document another user holds the lock on is left as it is and
+     * listed under `locked`.
+     * @param {string} layerId - The layer ID
+     * @param {Array<object>} constraints - The list to repair for
+     * @param {string} [auditMessage] - Audit message for this write
+     * @param {{document?: string}} [options]
+     * @returns {Promise<{repaired: Array<object>, locked: Array<{document: string, lockedBy: string}>, violations: Array<object>, violationCount: number}>}
+     */
+    repairConstraints: (layerId, constraints, auditMessage, options) =>
+      client._request("POST", `${base(layerId)}/repair`, {
+        auditMessage,
+        body: options?.document ? { constraints, document: options.document } : { constraints },
+      }),
+  };
+}
+
 export default PlaidClient;
 export { PlaidClient };
+export { CONSTRAINT_TYPES, valueSetAllows, violationsOf } from "./constraints.js";
 
 // Unicode code-point helpers for text offsets (token begin/end are code-point
 // indices). See ./codepoint.js.
@@ -3790,10 +4188,13 @@ export {
   cpToUtf16,
   cpIndexOf,
 } from "./codepoint.js";
+export { composeTextEdits, gapsToOps, applyTextOps } from "./textEdits.js";
 export {
   PLAID_NAMESPACE,
   ROLE_KEY,
   PRESERVE_ON_SPLIT_KEY,
+  PLAIN_EDITS_KEY,
+  SPLIT_ON_SPACE_KEY,
   ROLES,
   readRole,
   findByRole,
@@ -3866,4 +4267,8 @@ export {
 // The ids a create or bulk create answered with, off the call or its batch
 // result. See ./created.js.
 export { createdId, createdIds } from "./created.js";
+// UUIDv7 ids for what a client creates. See ./ids.js and the manual,
+// "Retrying a write".
+export { uuidv7 } from "./ids.js";
+export { wasReplayed } from "./replayed.js";
 export { MAX_BATCH_OPS };