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

package/index.d.ts

@@ -667,7 +667,7 @@ interface Invite {
   id: string;
   /** "signup" | "password-reset" */
   kind: string;
-  /** "active" | "used" | "expired" | "revoked" */
+  /** "active" | "used" | "expired" | "revoked" | "inactive" */
   status: string;
   createdBy: string;
   createdAt: string;
@@ -685,7 +685,7 @@ interface Invite {
 interface InvitePreview {
   /** "signup" | "password-reset" */
   kind: string;
-  /** "active" | "used" | "expired" | "revoked" */
+  /** "active" | "used" | "expired" | "revoked" | "inactive" */
   status: string;
   expiresAt: string;
   grantAdmin: boolean;
@@ -977,7 +977,10 @@ interface InvitesBundle {
     all?: boolean;
     pageSize?: number;
   }): AsyncGenerator<Invite[]>;
-  /** The `code` is returned ONCE and is not recoverable afterward. */
+  /**
+   * The `code` is returned ONCE and is not recoverable afterward. Needs a
+   * signed-in session: a named API token cannot mint any invite (403).
+   */
   create(
     opts?: CreateInviteOptions,
     auditMessage?: string,
@@ -1069,9 +1072,6 @@ export declare class DocumentLockLost extends Error {
   readonly cause?: unknown;
 }
 
-/** The server's default document-lock window, in ms. */
-export const DOCUMENT_LOCK_TTL_MS: 60000;
-
 interface DocumentsBundle {
   checkLock(documentId: string): Promise<any>;
   /**
@@ -1615,6 +1615,10 @@ export declare class PlaidClient {
   serverClockOffsetMs: number | null;
   /** The server's time now, from its last response's Date header (to the second), else this machine's. Judge a time the server stamped, such as an audit entry's `ts`, against this rather than `Date.now()`. */
   serverNow(): Date;
+  /** Hear every time a request is sent again: after a 503, or for a keyed write after its answer was lost (no response, 502, 504). Called before the wait. Returns the unsubscribe. */
+  onRetry(
+    listener: (info: { attempt: number; retries: number; delay: number; error: Error }) => void,
+  ): () => void;
 
   // Batches.
   //
@@ -1702,8 +1706,6 @@ export function cpSlice(s: string, begin: number, end?: number): string;
 export function cpSlicer(s: string): (begin: number, end?: number) => string;
 /** UTF-16 index -> code-point index in `s`. */
 export function utf16ToCp(s: string, u: number): number;
-/** Code-point index -> UTF-16 index in `s` (clamps past the end). */
-export function cpToUtf16(s: string, cp: number): number;
 /** Like indexOf, but the result and `fromCp` are code-point indices; -1 if absent. */
 export function cpIndexOf(s: string, sub: string, fromCp?: number): number;
 
@@ -1735,13 +1737,13 @@ export const PLAID_NAMESPACE: "plaid";
 export const ROLE_KEY: "role";
 /** Layer config key naming the metadata keys a token born of a SPLIT inherits. */
 export const PRESERVE_ON_SPLIT_KEY: "preserveOnSplit";
-/** Layer config key asking Plaid to take a text edit plainly on the layer (see the manual's "Changing a text's body"). */
-export const PLAIN_EDITS_KEY: "plainEdits";
-/** Layer config key: a space typed inside a word of the text splits it (beside plainEdits). */
+/** Layer config key: a space typed inside a word of the text splits it (see the manual's "Changing a text's body"). */
 export const SPLIT_ON_SPACE_KEY: "splitOnSpace";
 
 /** The server's cap on operations per batch request; a larger batch goes as consecutive requests. */
 export const MAX_BATCH_OPS: 1000;
+/** How long `admin.backup()` waits for the server to finish writing a backup, in ms. */
+export const BACKUP_TIMEOUT_MS: number;
 /** The fixed role inventory; only these values are interoperable across apps. */
 export const ROLES: {
   readonly BASELINE: "baseline";
@@ -1854,20 +1856,12 @@ export function confirmedInferred(
 };
 /** Classify an entity's metadata into one of the three provenance states. */
 export function provState(metadata: object | null | undefined): ProvState;
-/** The verifying fragment, { provConfirmed: true }: PATCH it over existing metadata. */
-export const PROV_CONFIRMED: { readonly provConfirmed: true };
 /** Machine-made and not yet human-verified (needs review, replaceable, confirmable). */
 export function isMachine(metadata: object | null | undefined): boolean;
 /** Whether a machine writer must leave this entity alone (human or verified). !isMachine. */
 export function isProtected(metadata: object | null | undefined): boolean;
-/** The fragment a HUMAN edit should merge in: PROV_CONFIRMED iff machine-unverified, else null. */
-export function verifyOnEdit(
-  metadata: object | null | undefined,
-): { readonly provConfirmed: true } | null;
 /** Canonical provSource for a service: 'service:<serviceId>'. */
 export function serviceSource(serviceId: string): string;
-/** Canonical provSource for a contributor: 'user:<userId>'. */
-export function userSource(userId: string): string;
 /** The metadata fragment a contributor's work carries. */
 export function stampContributed(userId: string): {
   prov: "contributed";
@@ -1925,8 +1919,6 @@ export function isReservedMetadataKey(key: string): boolean;
 // --- Review: whose work is reviewed (a project-config norm) -------------------
 /** The config key, under the `plaid` namespace, holding the review lists. */
 export const REVIEW_KEY: "review";
-/** The project roles a review list may name. */
-export const PROJECT_ROLES: readonly ["reader", "writer", "maintainer"];
 /** A project's review lists, normalized. */
 export function readReview(config?: object | null): {
   users: string[];
@@ -2004,8 +1996,6 @@ export interface ConstraintViolation {
   value?: any;
   parts?: string[];
 }
-/** The constraint types. */
-export const CONSTRAINT_TYPES: readonly string[];
 /** The camelCased violations of a write refused by a layer constraint, or null. */
 export function violationsOf(err: any): ConstraintViolation[] | null;
 export function valueSetAllows(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larc-iu/plaid-client",
-  "version": "0.2.0-alpha.20",
+  "version": "0.2.0-alpha.21",
   "description": "JavaScript client for the Plaid annotation API",
   "type": "module",
   "repository": {

package/src/constraints.js

@@ -7,17 +7,6 @@
 
 import { transformResponse } from "./transforms.js";
 
-/** The constraint types, by the layer kind that may carry them. */
-export const CONSTRAINT_TYPES = Object.freeze([
-  "max-in-degree",
-  "acyclic",
-  "same-ancestor",
-  "single-span",
-  "value-set",
-  "coextensive",
-  "single-link",
-]);
-
 /**
  * The violations of a write refused by a layer constraint, camelCased
  * ({constraint, namespace, layer, layerName, document, at, ids, value?,

package/src/documentLock.js

@@ -1,3 +1,5 @@
+import { isUnknownOutcome, retryUnknown } from "./http.js";
+
 /**
  * Keeping a document lock alive for as long as a `locked()` block runs.
  *
@@ -27,21 +29,6 @@
  * that is missing somewhere.
  */
 
-/**
- * How long plaid-core holds a document lock before it expires, in ms.
- * `plaid.server.locks/default-lock-expiration-ms`. An operator can change it
- * with `:plaid.server.locks/config :expiration-ms`, and a server publishes what
- * it enforces as `lockExpirationMs` in `GET /info`. This is the last resort:
- * what a live lock is renewed against is the `expiresAt` on the acquire
- * response, which names the moment rather than the window.
- */
-export const DOCUMENT_LOCK_TTL_MS = 60000;
-
-// Widest lock lifetime we will believe from a server response. Past this the
-// number is a clock skew between this machine and the server rather than a
-// configured window, and the documented default is the better guess.
-const MAX_BELIEVABLE_TTL_MS = 3600000;
-
 /**
  * The lock a `documents.locked()` block was holding is no longer held.
  *
@@ -62,25 +49,31 @@ export class DocumentLockLost extends Error {
 /**
  * How long a freshly taken lock lasts, from the server's own answer.
  *
- * `expiresAt` is the epoch-millisecond stamp the lock endpoints return.
- * Comparing it against this machine's clock is the only way to learn a window
- * an operator has retuned, and it is also the one place a clock skew can get
- * in, so an answer outside a believable band falls back to the documented
- * default rather than to a beat that never fires or fires constantly.
+ * `expiresAt` is the epoch-millisecond moment the lock endpoints return, on
+ * the server's clock, so it is read against the server's clock too
+ * (`client.serverNow()`): this machine's clock being off cannot stretch or
+ * shrink the window. It is how a window an operator has retuned
+ * (`:plaid.server.locks/config :expiration-ms`) reaches the keeper.
  *
- * @param {number|undefined} expiresAt
- * @param {number} nowMs
- * @param {number} [fallback]
+ * An answer that cannot be a window (none, already over, past an hour) is
+ * core's default, 60 s.
+ *
+ * @param {number} expiresAt
+ * @param {number} serverNowMs
  * @returns {number}
  */
-export function lockTtlMs(expiresAt, nowMs, fallback = DOCUMENT_LOCK_TTL_MS) {
-  if (typeof expiresAt === "number" && Number.isFinite(expiresAt)) {
-    const ttl = expiresAt - nowMs;
-    if (ttl > 0 && ttl <= MAX_BELIEVABLE_TTL_MS) return ttl;
-  }
-  return fallback;
+export function lockTtlMs(expiresAt, serverNowMs) {
+  const ttl = expiresAt - serverNowMs;
+  // No answer at all, or one past an hour or already over: this machine's
+  // clock stood in for the server's (a page that cannot read its Date
+  // header) and is far off. Core's default window is the better guess.
+  return Number.isFinite(ttl) && ttl > 0 && ttl <= MAX_TTL_MS ? ttl : DEFAULT_TTL_MS;
 }
 
+// Core's default lock window, and the longest one believed.
+const DEFAULT_TTL_MS = 60000;
+const MAX_TTL_MS = 3600000;
+
 /**
  * Renews one document's lock until the block holding it exits.
  *
@@ -100,9 +93,7 @@ export class LockKeeper {
   ) {
     this._refresh = refresh;
     this._documentId = documentId;
-    // A window under two seconds leaves no room for a retry; treat it as a
-    // misconfiguration and beat at the documented rate instead.
-    this._ttlMs = ttlMs >= 2000 ? ttlMs : DOCUMENT_LOCK_TTL_MS;
+    this._ttlMs = ttlMs;
     this._onLost = onLost;
     this._clock = clock;
     this._sleep = sleep || ((ms) => this._defaultSleep(ms));
@@ -219,16 +210,11 @@ export class DocumentLock {
 }
 
 /**
- * Tries a `locked()` block makes at an acquire whose outcome is unknown, and the
- * pause before the next, which grows by this much each time.
+ * The pause before sending again an acquire whose outcome is unknown, which
+ * grows by this much each time (three sends in all).
  */
-export const LOCK_ACQUIRE_ATTEMPTS = 3;
 export const LOCK_ACQUIRE_RETRY_MS = 500;
 
-// The HTTP status of a request that may or may not have reached the server: no
-// answer at all (0), or a proxy's 502 or 504.
-const UNKNOWN_OUTCOME_STATUSES = new Set([0, 502, 504]);
-
 function mintLockId() {
   return globalThis.crypto.randomUUID();
 }
@@ -237,45 +223,42 @@ function mintLockId() {
  * The acquire of a `locked()` block, under the holder id it minted.
  *
  * An acquire whose outcome is unknown (no answer, a timeout, a 502 or a 504)
- * may have taken the lock. It is sent again under the same id, which the server
- * answers 200 while that holder has it. When every attempt is unknown, the lock
- * it may hold is released on the way out, so it does not stand in everyone's
- * way until it expires.
+ * may have taken the lock. It is sent again under the same id as any write is
+ * (`retryUnknown`), which the server answers 200 while that holder has it.
+ * When every send is unknown (or the network went), the lock it may hold is
+ * released on the way out, so it does not stand in everyone's way until it
+ * expires.
  */
 async function takeLock(client, documentId, lockId, retryMs) {
-  for (let attempt = 0; ; attempt += 1) {
-    try {
-      return await client.documents.acquireLock(documentId, undefined, lockId);
-    } catch (error) {
-      if (error?.status === 423) {
-        // The error body is raw JSON off the wire, so it is still kebab-cased.
-        const body = error.responseData || {};
-        const holder = body.userId || body["user-id"] || "another user";
-        const readable = new Error(
-          `This document is being edited by ${holder}. Try again once they're done.`,
-        );
-        readable.status = 423;
-        readable.statusText = error.statusText;
-        readable.url = error.url;
-        readable.method = error.method;
-        readable.responseData = error.responseData;
-        readable.cause = error;
-        throw readable;
-      }
-      if (!UNKNOWN_OUTCOME_STATUSES.has(error?.status)) throw error;
-      if (attempt + 1 < LOCK_ACQUIRE_ATTEMPTS) {
-        await new Promise((resolve) =>
-          setTimeout(resolve, retryMs * (attempt + 1)),
-        );
-        continue;
-      }
+  try {
+    return await retryUnknown(
+      () => client.documents.acquireLock(documentId, undefined, lockId),
+      { delaysMs: [retryMs, 2 * retryMs] },
+    );
+  } catch (error) {
+    if (error?.status === 423) {
+      // The error body is raw JSON off the wire, so it is still kebab-cased.
+      const body = error.responseData || {};
+      const holder = body.userId || body["user-id"] || "another user";
+      const readable = new Error(
+        `This document is being edited by ${holder}. Try again once they're done.`,
+      );
+      readable.status = 423;
+      readable.statusText = error.statusText;
+      readable.url = error.url;
+      readable.method = error.method;
+      readable.responseData = error.responseData;
+      readable.cause = error;
+      throw readable;
+    }
+    if (isUnknownOutcome(error)) {
       try {
         await client.documents.releaseLock(documentId, lockId);
       } catch {
         /* the lock expires on its own */
       }
-      throw error;
     }
+    throw error;
   }
 }
 
@@ -300,7 +283,7 @@ export async function withDocumentLock(
   const lockId = info?.lockId ?? minted;
   let keeper = null;
   if (keepAlive) {
-    const ttlMs = lockTtlMs(info?.expiresAt, Date.now());
+    const ttlMs = lockTtlMs(info.expiresAt, client.serverNow().getTime());
     client.documentLockLost = null;
     keeper = new LockKeeper(
       (id) => client.documents.renewLock(id, lockId),

package/src/http.js

@@ -46,9 +46,11 @@ import { uuidv7 } from "./ids.js";
 // does not 409 the next. A batch split past MAX_BATCH_OPS restamps each later
 // request with the version the one before it left (see submitBatch).
 //
-// `noBatch` is not part of that judgment. It marks the four calls the batch
-// transport cannot carry at all (the multipart media and avatar uploads, the
-// user-data store's put and delete) and raises so the caller finds out. A
+// `noBatch` is not part of that judgment. It marks the calls a batch cannot
+// carry at all (the multipart media and avatar uploads, the user-data store's
+// put and delete, and minting an API token or an invite, whose answer is a
+// secret the server refuses to keep with a keyed batch's answer) and raises
+// so the caller finds out. A
 // batch inside a batch is refused by the batch itself. Never put it on a read: it turns a swallowed read into a
 // thrown one, which is what the chrome hit when an unrelated import was
 // running. A blobless DELETE beside an upload is not one of them: it carries
@@ -240,10 +242,10 @@ export async function retryWhileBusy(
 // ---------------------------------------------------------------------------
 // The Idempotency-Key.
 //
-// Every write that is not a signal (`outOfBand`), an upload (`noBatch`) or a
-// call that mints a secret (`noIdempotency`) goes out with an
-// `Idempotency-Key` header, and so does every batch request (a queued op has
-// none: its batch request carries one). The server keeps the answer to a
+// Every write that is not a signal (`outOfBand`) or a call a batch cannot
+// carry (`noBatch`: an upload, user data, a call that mints a secret) goes out
+// with an `Idempotency-Key` header, and so does every batch request (a queued
+// op has none: its batch request carries one). The server keeps the answer to a
 // keyed write for a day, and the same key sent again for the same request is
 // answered from it with `Idempotent-Replayed: true`, writing nothing. So a
 // write whose answer was lost (no response, 502, 504) can be sent again
@@ -274,6 +276,22 @@ export function isUnknownOutcome(error) {
   return status === 0 || status === 502 || status === 504;
 }
 
+/**
+ * Whether a create refused with `status` and body `data` was made by an
+ * earlier send of the same work: `409 id-taken` for an id in `minted` (a Set
+ * of the ids the work minted for its creates), and not for a row deleted
+ * since (there is nothing to go on with). The one rule for a lost answer's
+ * create. The Python twin is `minted_taken`.
+ */
+export function mintedTaken(status, data, minted) {
+  return (
+    status === 409 &&
+    data?.error === "id-taken" &&
+    !data.deleted &&
+    !!minted?.has(data.id)
+  );
+}
+
 /**
  * Run `attempt`, sending it again after each delay in `delaysMs` while it
  * fails with an unknown outcome. Only for a keyed write, whose resend is
@@ -588,8 +606,7 @@ export function takesIdempotencyKey(method, options = {}) {
   return (
     method !== "GET" &&
     !options.outOfBand &&
-    !options.noBatch &&
-    !options.noIdempotency
+    !options.noBatch
   );
 }
 
@@ -705,8 +722,8 @@ export async function queueRequest(batch, method, path, options = {}) {
  *   rawBody         - Body value passed directly (no transform). Mutually exclusive with body.
  *   formData        - If true, body is FormData; skip Content-Type header
  *   queryParams     - Object of query param key/values to append
- *   noBatch         - If true, throw when made on a batch. Only for calls the
- *                     batch transport cannot carry at all (see the note at the
+ *   noBatch         - If true, throw when made on a batch. Only for calls a
+ *                     batch cannot carry at all (see the note at the
  *                     top of this file); never for a read.
  *   outOfBand       - If true, the call is a signal rather than a write of
  *                     project data: made on a batch it still goes over the
@@ -807,22 +824,22 @@ export async function makeRequest(client, method, path, options = {}) {
   };
 
   try {
+    const onRetry = (info) => client._noteRetry?.(info);
     const response = keyed
-      ? await retryUnknown(() => retryWhileBusy(attempt), {
+      ? await retryUnknown(() => retryWhileBusy(attempt, { onRetry }), {
           delaysMs: client.retryDelaysMs,
+          onRetry,
         })
-      : await retryWhileBusy(attempt);
+      : await retryWhileBusy(attempt, { onRetry });
     noteServerClock(client, response.headers);
 
     if (!response.ok) {
       const errorData = await parseErrorBody(response);
-      // Only a single create: a bulk refused whole made none of its rows.
-      // Never a deleted row: there is nothing to open.
+      // Answered as made only for a single create, the one whose answer is
+      // the id alone. A bulk or a batch taken so is made whole (it is one
+      // transaction), and a caller that sends one decides what it answers.
       if (
-        response.status === 409 &&
-        errorData?.error === "id-taken" &&
-        !errorData.deleted &&
-        minted?.has(errorData.id) &&
+        mintedTaken(response.status, errorData, minted) &&
         requestBody?.id === errorData.id
       ) {
         if (stampedGroup) stampedGroup.written = true;

package/src/index.js

@@ -133,6 +133,12 @@ async function anonymousGet(baseUrl, path, options = {}) {
  */
 const MAX_BATCH_OPS = 1000;
 
+/**
+ * How long `admin.backup()` waits for the server to finish writing a backup:
+ * minutes on a large database, past the usual per-request timeout.
+ */
+export const BACKUP_TIMEOUT_MS = 30 * 60 * 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
@@ -337,10 +343,37 @@ class PlaidClient {
     // the stored token and route back to login. See makeRequest in http.js.
     this.onAuthError = options.onAuthError || null;
     this._authErrorFired = false;
+    // Who hears that a request is being sent again (onRetry).
+    this._retryListeners = new Set();
 
     this._installResources();
   }
 
+  /**
+   * 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,
+   * 504). The listener gets `{ attempt, retries, delay, error }` before the
+   * wait. A screen that writes through the client directly can say it is
+   * retrying while the server does not answer, though the browser is online.
+   * @param {(info: {attempt: number, retries: number, delay: number, error: Error}) => void} listener
+   * @returns {() => void} the unsubscribe
+   */
+  onRetry(listener) {
+    this._retryListeners.add(listener);
+    return () => this._retryListeners.delete(listener);
+  }
+
+  /** Tell every `onRetry` listener. A listener that throws is passed over. */
+  _noteRetry(info) {
+    for (const listener of this._retryListeners) {
+      try {
+        listener(info);
+      } catch (_) {
+        /* a listener must not stop the retry */
+      }
+    }
+  }
+
   /**
    * The server's time now, as its last response's Date header put it (to the
    * second), else this machine's. Judge a time the server stamped, such as an
@@ -1171,7 +1204,8 @@ class PlaidClient {
           query: { q },
         }),
       /**
-       * Create a new user.
+       * Create a new user. Admin only, and not with a named API token (403):
+       * it needs a sign-in token.
        * @param {string} email - The account's email address. It becomes the
        *   user's id and is what they log in with; it can never be changed.
        * @param {string} password - The password
@@ -1266,7 +1300,8 @@ class PlaidClient {
       /**
        * Modify a user. Admins may change the display name, password, and admin
        * status of any user. All other users may only modify their own display
-       * name or password.
+       * name or password. A password change cannot be made with a named API
+       * token (403): it needs a sign-in token.
        *
        * A user's id is their email address and is fixed for the life of the
        * account — it is what they log in with, so nothing can change it.
@@ -1489,6 +1524,8 @@ class PlaidClient {
        * Mint a named API token for a user. The returned `token` is the signed
        * credential and is shown ONLY here — store it immediately. API tokens
        * do not expire and survive password changes / logout; revoke to kill.
+       * A client signed in with a named API token cannot do this (403): it
+       * 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"
        * @returns {Promise<{id: string, name: string, token: string}>}
@@ -1497,11 +1534,14 @@ 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,
+          // The answer is the secret, which the server never keeps, so it
+          // takes no Idempotency-Key and a batch cannot carry it.
+          noBatch: true,
         }),
       /**
        * Revoke a named API token (soft-revoke; idempotent).
+       * A client signed in with a named API token cannot do this (403): it
+       * needs a sign-in token.
        * @param {string} userId - The user ID who owns the token
        * @param {string} tokenId - The token ID to revoke
        */
@@ -1564,6 +1604,9 @@ class PlaidClient {
        * invite, no password resets — so for a non-admin, projectId/projectRole
        * are required in practice (403 without them).
        *
+       * Needs a signed-in session: a client signed in with a named API token
+       * cannot mint any invite (403).
+       *
        * EVERY option is optional; `create()` with no arguments mints a
        * single-use signup link granting nothing but an account. Two pairing
        * rules the server enforces with a 400: projectId and projectRole must be
@@ -1593,8 +1636,9 @@ class PlaidClient {
       ) =>
         this._request("POST", "/api/v1/invites", {
           auditMessage,
-          // The answer is the code, which the server never keeps.
-          noIdempotency: true,
+          // The answer is the code, which the server never keeps, so it
+          // takes no Idempotency-Key and a batch cannot carry it.
+          noBatch: true,
           body: bodyOf({
             "project-id": projectId,
             "project-role": projectRole,
@@ -1629,13 +1673,22 @@ class PlaidClient {
        * Resolves to the backup block with `ok` reporting whether the snapshot
        * succeeded. Uses VACUUM INTO, which only reads, so it is safe while
        * people are working. Admin only.
+       *
+       * The server answers once the backup is written, which takes minutes on
+       * a large database, so this waits up to `BACKUP_TIMEOUT_MS` (30 minutes)
+       * 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}>}
        *
        * outOfBand, as every admin action on the server itself is: none of them
        * writes project data (see the note at the top of http.js).
        */
       backup: () =>
-        this._request("POST", "/api/v1/admin/backup", { outOfBand: true }),
+        this._request("POST", "/api/v1/admin/backup", {
+          outOfBand: true,
+          timeout: BACKUP_TIMEOUT_MS,
+        }),
       /**
        * Documents currently held by an editing lock, with who holds each and
        * when it expires on its own. Admin only.
@@ -3854,8 +3907,10 @@ class PlaidClient {
         }
         return res;
       };
-      const response = await retryUnknown(() => retryWhileBusy(attempt), {
+      const onRetry = (info) => this._noteRetry(info);
+      const response = await retryUnknown(() => retryWhileBusy(attempt, { onRetry }), {
         delaysMs: this.retryDelaysMs,
+        onRetry,
       }).catch((error) => {
         error.idempotencyKey = key;
         // 401 means the token is missing, expired or invalid: fire the app's
@@ -3982,7 +4037,8 @@ class PlaidClient {
    * Describe an invite code, with NO authentication — this is what a signup
    * page calls before the redeemer has an account. Returns the kind of link
    * ("signup" or "password-reset"), its status ("active", "used", "expired",
-   * "revoked"), and the project it grants access to, if any.
+   * "revoked", or "inactive" when its creator can no longer grant what it
+   * grants), and the project it grants access to, if any.
    *
    * Throws a 404-shaped error if the code is unknown. A known-but-dead code
    * resolves normally with a non-"active" status, so the page can say why.
@@ -4176,7 +4232,7 @@ function constraintMethods(client, kind) {
 
 export default PlaidClient;
 export { PlaidClient };
-export { CONSTRAINT_TYPES, valueSetAllows, violationsOf } from "./constraints.js";
+export { valueSetAllows, violationsOf } from "./constraints.js";
 
 // Unicode code-point helpers for text offsets (token begin/end are code-point
 // indices). See ./codepoint.js.
@@ -4185,7 +4241,6 @@ export {
   cpSlice,
   cpSlicer,
   utf16ToCp,
-  cpToUtf16,
   cpIndexOf,
 } from "./codepoint.js";
 export { composeTextEdits, gapsToOps, applyTextOps } from "./textEdits.js";
@@ -4193,7 +4248,6 @@ export {
   PLAID_NAMESPACE,
   ROLE_KEY,
   PRESERVE_ON_SPLIT_KEY,
-  PLAIN_EDITS_KEY,
   SPLIT_ON_SPACE_KEY,
   ROLES,
   readRole,
@@ -4222,11 +4276,7 @@ export { REQUESTED_BY, makeRequester, requesterOf } from "./requester.js";
 // Document locks: `client.documents.locked()` holds one for a block of work and
 // renews it while the block runs. DocumentLockLost is what a write throws once
 // a renewal has failed. See ./documentLock.js.
-export {
-  DOCUMENT_LOCK_TTL_MS,
-  DocumentLock,
-  DocumentLockLost,
-} from "./documentLock.js";
+export { DocumentLock, DocumentLockLost } from "./documentLock.js";
 // Provenance: the cross-app convention for who made an annotation (flat
 // prov/provSource/provConfirmed metadata; absence = a verifier; 'inferred' =
 // a machine; 'contributed' = a person whose work is reviewed), plus the
@@ -4234,7 +4284,6 @@ export {
 export {
   PROV,
   PROV_STATES,
-  PROV_CONFIRMED,
   PROVENANCE_KEYS,
   stampInferred,
   confirmedInferred,
@@ -4244,12 +4293,9 @@ export {
   isMachine,
   isProtected,
   needsReview,
-  verifyOnEdit,
   contributeOnEdit,
   serviceSource,
-  userSource,
   REVIEW_KEY,
-  PROJECT_ROLES,
   readReview,
   projectRole,
   isReviewed,

package/src/metadataOps.js

@@ -80,8 +80,10 @@ const applyOp = (node, path, depth, o) => {
 /**
  * Apply ops to a local copy of an entity's metadata the way the server does,
  * for an optimistic update. Returns a new object and never mutates its input.
- * Throws where the server would refuse (a path through a non-object, or a
- * first key that is blank, over 200 characters or holds a control character).
+ * Throws on part of what the server refuses: an empty path, an op other than
+ * set or delete, a path through a non-object, or a first key that is blank,
+ * over 200 characters or holds a control character. The server's caps on
+ * depth, key count, string length and size are not checked here.
  * @param {Object|null|undefined} metadata
  * @param {Array<{op: string, path: string[], value?: any}>} ops
  * @returns {Object}

package/src/provenance.js

@@ -257,9 +257,6 @@ export const userSource = (userId) => `user:${userId}`;
 /** The config key, under the `plaid` namespace, holding the review lists. */
 export const REVIEW_KEY = 'review';
 
-/** The project roles a review list may name. */
-export const PROJECT_ROLES = Object.freeze(['reader', 'writer', 'maintainer']);
-
 /**
  * The project's review lists, normalized: { users: string[], roles: string[] }.
  * @param {Object|null|undefined} config - a project's `config`

package/src/roles.js

@@ -35,19 +35,10 @@ export const ROLE_KEY = 'role';
 export const PRESERVE_ON_SPLIT_KEY = 'preserveOnSplit';
 
 /**
- * Layer config key (true) asking Plaid to take a text edit plainly on the
- * layer: an edit inside a token, or touching its edge with no whitespace
- * between, grows or shrinks it, a typed space never splits it, a deleted one
- * never joins two, and only a token whose whole text is deleted goes. See the
- * manual's `Changing a text's body`.
- */
-export const PLAIN_EDITS_KEY = 'plainEdits';
-
-/**
- * Layer config key (true), beside PLAIN_EDITS_KEY: a space typed inside a
- * token of the text's words splits it, the token going on the half sharing
- * more letters with it. Declared on a word layer another app shares, it holds
- * for the whole text.
+ * Layer config key (true): a space typed inside a token of the text's words
+ * splits it, the token going on the half sharing more letters with it.
+ * Declared on a word layer another app shares, it holds for the whole text.
+ * See the manual's `Changing a text's body`.
  */
 export const SPLIT_ON_SPACE_KEY = 'splitOnSpace';
 

package/src/serviceSchema.js

@@ -16,7 +16,7 @@
  *
  *   {
  *     schemaVersion: 1,
- *     tasks: ["tokenize"],              // controlled vocab; REPLACES tok:/asr: id prefixes
+ *     tasks: ["tokenize"],              // controlled vocab (TASKS)
  *     summary: "## markdown …",         // rich human description
  *     parameters: [                     // ordered; rendered into a form
  *       { key, label, type, description?, default?, required?,
@@ -63,8 +63,8 @@ export const TASKS = Object.freeze({
    *
    * Apart from `analyze` on purpose. A task is the CONTRACT a spot offers a
    * service against, and these two share almost none of it: an analyze
-   * request names the three token layers plus the language, metalanguage and
-   * orthography, and writes morphemes and glosses. Both claimed `analyze` for
+   * request names the three token layers plus the language and metalanguage,
+   * and writes morphemes and glosses. Both claimed `analyze` for
    * a while, so every app offering an analyze spot offered the other app's
    * services, which could not answer the request they would have been given.
    */
@@ -93,32 +93,14 @@ export const TASKS = Object.freeze({
 });
 
 /**
- * Legacy id-prefix → task map, for services that have not yet migrated to a
- * declared `tasks` array. Drop once all services advertise `tasks`.
- */
-const LEGACY_TASK_PREFIXES = Object.freeze({
-  [TASKS.TOKENIZE]: "tok:",
-  [TASKS.TRANSCRIBE]: "asr:",
-});
-
-/**
- * Does `service` serve `task`? Prefers the declared `extras.tasks` array; falls
- * back to the legacy id-prefix convention for un-migrated services.
+ * Does `service` serve `task`, as its declared `extras.tasks` says?
  * @param {{serviceId?: string, extras?: {tasks?: string[]}}} service
  * @param {string} task one of TASKS
  * @returns {boolean}
  */
 export function servesTask(service, task) {
   const declared = service?.extras?.tasks;
-  if (Array.isArray(declared) && declared.length) {
-    return declared.includes(task);
-  }
-  const prefix = LEGACY_TASK_PREFIXES[task];
-  return (
-    !!prefix &&
-    typeof service?.serviceId === "string" &&
-    service.serviceId.startsWith(prefix)
-  );
+  return Array.isArray(declared) && declared.includes(task);
 }
 
 /**

package/src/services.js

@@ -434,7 +434,10 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
  * you already made rejoins it instead of starting another.
  *
  * Errors that leave the request alive carry `pending: true`: a timeout, a
- * stop, a dropped connection. An error without it is the end of the request.
+ * stop, a dropped connection, a proxy's 502 or 504. An error without it is
+ * the end of the request. With `opts.requestId`, a request whose answer went
+ * missing (a dropped connection, a 502 or 504) is rejoined by that id a few
+ * times before the error is given.
  *
  * @param {Object} client - PlaidClient instance
  * @param {string} projectId - Project UUID
@@ -485,7 +488,7 @@ export function requestService(client, projectId, serviceId, data, timeout = 100
   if (opts.requestId) query.set('request-id', opts.requestId);
   if (opts.projectIds?.length) query.set('project-ids', opts.projectIds.join(','));
   const qs = String(query) ? `?${query}` : '';
-  return streamServiceRequest(
+  const submit = () => streamServiceRequest(
     client,
     {
       url: `${client.baseUrl}/api/v1/projects/${projectId}/services/${encodeURIComponent(serviceId)}/requests${qs}`,
@@ -500,6 +503,14 @@ export function requestService(client, projectId, serviceId, data, timeout = 100
     signal,
     opts.onAccepted,
   );
+  // A request whose id is known is rejoined when its answer goes missing, so
+  // a run the service took and finished is not reported failed.
+  if (!opts.requestId) return submit();
+  return rejoinLost(
+    submit,
+    () => attachServiceRequest(client, projectId, opts.requestId, timeout, onProgress, signal),
+    signal,
+  );
 }
 
 /**
@@ -612,6 +623,62 @@ export function cancelServiceRequest(client, projectId, requestId) {
  */
 const stillRunning = (err) => Object.assign(err, { pending: true });
 
+/**
+ * A still-running error whose cause is that the ANSWER went missing: the
+ * request could not be sent or read to its end, or a proxy answered for the
+ * server (502, 504). Not a timeout or a stop, which are the caller's own
+ * choice to stop waiting. A submit whose answer was lost rejoins its request
+ * (`rejoinLost`).
+ */
+const lostAnswer = (err) => Object.assign(stillRunning(err), { lostAnswer: true });
+
+/** How long to wait before each attempt to rejoin a request whose answer was lost. */
+const REJOIN_DELAYS_MS = [1000, 3000, 9000];
+
+const delay = (ms, signal) =>
+  new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+
+/**
+ * `submit()` again, by attaching to the request `requestId` names, while its
+ * answer is the one that went missing. The request was taken, or never
+ * reached the server: attaching follows a taken one to its end, and a 404
+ * says the server never had it, so the first error stands. Each attempt
+ * whose answer goes missing too waits a little longer before the next.
+ */
+async function rejoinLost(submit, attach, signal) {
+  let first;
+  try {
+    return await submit();
+  } catch (err) {
+    if (!err?.lostAnswer) throw err;
+    first = err;
+  }
+  let last = first;
+  for (const ms of REJOIN_DELAYS_MS) {
+    await delay(ms, signal);
+    if (signal?.aborted) throw last;
+    try {
+      return await attach();
+    } catch (err) {
+      if (err?.status === 404) throw first;
+      if (!err?.lostAnswer) throw err;
+      last = err;
+    }
+  }
+  throw last;
+}
+
 /**
  * Open a request stream (submit or attach) and read it to its terminal
  * event: `accepted` names the request, `progress` events go to `onProgress`,
@@ -679,7 +746,7 @@ function streamServiceRequest(client, { url, method, body, onStatus, what }, tim
       } catch (error) {
         // The POST may or may not have reached the server. Treat it as alive:
         // rejoining a request that was never made simply 404s.
-        if (error.name !== 'AbortError') finish(reject, stillRunning(new Error(`${what} could not be sent: ${error.message}`)));
+        if (error.name !== 'AbortError') finish(reject, lostAnswer(new Error(`${what} could not be sent: ${error.message}`)));
         return;
       }
 
@@ -691,7 +758,9 @@ function streamServiceRequest(client, { url, method, body, onStatus, what }, tim
       if (!response.ok) {
         const err = new Error(`${what} failed: HTTP ${response.status} ${response.statusText}`);
         err.status = response.status;
-        finish(reject, err);
+        // A proxy's 502 or 504 is no answer from the server: the request may
+        // have been taken, and the service may be running it.
+        finish(reject, response.status === 502 || response.status === 504 ? lostAnswer(err) : err);
         return;
       }
 
@@ -733,9 +802,9 @@ function streamServiceRequest(client, { url, method, body, onStatus, what }, tim
             }
           }
         }
-        finish(reject, stillRunning(new Error('Service closed the connection without a result')));
+        finish(reject, lostAnswer(new Error('Service closed the connection without a result')));
       } catch (error) {
-        if (error.name !== 'AbortError') finish(reject, stillRunning(new Error(`${what} stream error: ${error.message}`)));
+        if (error.name !== 'AbortError') finish(reject, lostAnswer(new Error(`${what} stream error: ${error.message}`)));
       }
     })();
   });