@larc-iu/plaid-client 0.2.0-alpha.14 → 0.2.0-alpha.17

package/index.d.ts

@@ -15,7 +15,7 @@ interface ServiceParam {
   /** Key the value is sent under in the request payload. */
   key: string;
   label: string;
-  type: "string" | "number" | "boolean" | "enum" | "multiselect";
+  type: "string" | "number" | "boolean" | "enum" | "multiselect" | "field";
   description?: string;
   default?: any;
   required?: boolean;
@@ -30,6 +30,11 @@ interface ServiceParam {
   /** `string` only. */
   placeholder?: string;
   multiline?: boolean;
+  /**
+   * `field` only: the scope of the project's annotation fields the value names
+   * one of. A `field` value is a string everywhere else.
+   */
+  scope?: "Sentence" | "Word" | "Morpheme";
 }
 
 /** A service's standardized self-description (lives in `extras`). */
@@ -72,7 +77,8 @@ interface ServiceRegistration {
 }
 
 /** Connection-state transitions reported by a service registration. */
-type ServiceStatusEvent = "registered" | "reconnected" | "disconnected";
+/** "stopped": the server refused the channel for a reason retrying cannot fix (a revoked token, no write access, no such project), which ends the registration. */
+type ServiceStatusEvent = "registered" | "reconnected" | "disconnected" | "stopped";
 
 interface ResponseHelper {
   requestId: string;
@@ -111,6 +117,11 @@ interface SSEConnection {
   close(): void;
   getStats(): any;
   readyState: number;
+  /**
+   * Once CLOSED, why: null when this side closed it. A refused stream's error
+   * carries the HTTP `status`, and one the server ended is named "StreamClosed".
+   */
+  error: (Error & { status?: number }) | null;
 }
 
 interface VocabLinksBundle {
@@ -124,13 +135,45 @@ interface VocabLinksBundle {
   bulkDelete(body: any[], auditMessage?: string): Promise<void>;
   setMetadata(id: string, body: any, auditMessage?: string): Promise<any>;
   deleteMetadata(id: string, auditMessage?: string): Promise<any>;
-  patchMetadata(id: string, body: any, auditMessage?: string): Promise<any>;
-  get(id: string, asOf?: string): Promise<any>;
+  patchMetadata(id: string, body: MetadataOp[], auditMessage?: string): Promise<any>;
+  get(id: string): Promise<any>;
   delete(id: string, auditMessage?: string): Promise<any>;
 }
 
+/** What `vocabLayers.restoreItem` did, or with `dryRun` would do. */
+interface VocabItemRestoreSummary {
+  /** The entry was gone and came back under its old id. */
+  inserted: boolean;
+  /** A living entry's form was set back. */
+  form: boolean;
+  /** A living entry's fields were set back. */
+  metadata: boolean;
+  /** 0 when nothing changes. */
+  total: number;
+}
+
 interface VocabLayersBundle {
+  /** `asOf` reads the vocabulary as it was at that instant. */
   get(id: string, includeItems?: boolean, asOf?: string): Promise<any>;
+  /** One entry as it was at `asOf`, also when it has been deleted since. */
+  getItemAt(id: string, itemId: string, asOf: string): Promise<any>;
+  /** `itemId` keeps only the changes that wrote that one entry. */
+  audit(
+    id: string,
+    startTime?: string,
+    endTime?: string,
+    opTypes?: string[] | string,
+    itemId?: string,
+  ): Promise<any[]>;
+  auditPage(id: string, opts?: AuditPageOptions & { itemId?: string }): Promise<Page>;
+  /** Put one entry back as it was at `asOf`. Maintainers of the vocabulary only. */
+  restoreItem(
+    id: string,
+    itemId: string,
+    asOf: string,
+    options?: { dryRun?: boolean },
+    auditMessage?: string,
+  ): Promise<VocabItemRestoreSummary>;
   delete(id: string, auditMessage?: string): Promise<any>;
   update(id: string, name: string, auditMessage?: string): Promise<any>;
   setConfig(
@@ -146,13 +189,9 @@ interface VocabLayersBundle {
     configKey: string,
     auditMessage?: string,
   ): Promise<any>;
-  list(asOf?: string): Promise<any[]>;
-  listPage(opts?: {
-    limit?: number;
-    cursor?: string;
-    asOf?: string;
-  }): Promise<Page>;
-  iterPages(opts?: { pageSize?: number; asOf?: string }): AsyncGenerator<any[]>;
+  list(): Promise<any[]>;
+  listPage(opts?: { limit?: number; cursor?: string }): Promise<Page>;
+  iterPages(opts?: { pageSize?: number }): AsyncGenerator<any[]>;
   create(name: string, auditMessage?: string): Promise<any>;
   addMaintainer(
     id: string,
@@ -175,7 +214,7 @@ interface RelationsBundle {
   deleteMetadata(relationId: string, auditMessage?: string): Promise<any>;
   patchMetadata(
     relationId: string,
-    body: any,
+    body: MetadataOp[],
     auditMessage?: string,
   ): Promise<any>;
   setTarget(
@@ -183,7 +222,7 @@ interface RelationsBundle {
     spanId: string,
     auditMessage?: string,
   ): Promise<any>;
-  get(relationId: string, asOf?: string): Promise<any>;
+  get(relationId: string): Promise<any>;
   delete(relationId: string, auditMessage?: string): Promise<any>;
   update(relationId: string, value: any, auditMessage?: string): Promise<any>;
   setSource(
@@ -218,7 +257,7 @@ interface SpanLayersBundle {
     configKey: string,
     auditMessage?: string,
   ): Promise<any>;
-  get(spanLayerId: string, asOf?: string): Promise<any>;
+  get(spanLayerId: string): Promise<any>;
   delete(spanLayerId: string, auditMessage?: string): Promise<any>;
   update(
     spanLayerId: string,
@@ -246,7 +285,7 @@ interface SpansBundle {
     metadata?: any,
     auditMessage?: string,
   ): Promise<any>;
-  get(spanId: string, asOf?: string): Promise<any>;
+  get(spanId: string): Promise<any>;
   delete(spanId: string, auditMessage?: string): Promise<any>;
   update(spanId: string, value: any, auditMessage?: string): Promise<any>;
   bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
@@ -254,17 +293,13 @@ interface SpansBundle {
   bulkUpdate(body: any[], auditMessage?: string): Promise<{ count: number }>;
   setMetadata(spanId: string, body: any, auditMessage?: string): Promise<any>;
   deleteMetadata(spanId: string, auditMessage?: string): Promise<any>;
-  patchMetadata(spanId: string, body: any, auditMessage?: string): Promise<any>;
-}
-
-interface BatchBundle {
-  submit(body: any[], auditMessage?: string): Promise<any>;
+  patchMetadata(spanId: string, body: MetadataOp[], auditMessage?: string): Promise<any>;
 }
 
 interface TextsBundle {
   setMetadata(textId: string, body: any, auditMessage?: string): Promise<any>;
   deleteMetadata(textId: string, auditMessage?: string): Promise<any>;
-  patchMetadata(textId: string, body: any, auditMessage?: string): Promise<any>;
+  patchMetadata(textId: string, body: MetadataOp[], auditMessage?: string): Promise<any>;
   create(
     textLayerId: string,
     documentId: string,
@@ -272,19 +307,16 @@ interface TextsBundle {
     metadata?: any,
     auditMessage?: string,
   ): Promise<any>;
-  get(textId: string, asOf?: string): Promise<any>;
+  get(textId: string): Promise<any>;
   delete(textId: string, auditMessage?: string): Promise<any>;
   update(textId: string, body: any, auditMessage?: string): Promise<any>;
 }
 
 interface UsersBundle {
-  list(asOf?: string): Promise<any[]>;
-  listPage(opts?: {
-    limit?: number;
-    cursor?: string;
-    asOf?: string;
-  }): Promise<Page>;
-  iterPages(opts?: { pageSize?: number; asOf?: string }): AsyncGenerator<any[]>;
+  /** `q` narrows to users whose id or display name contains it (admin or maintainer). */
+  list(opts?: { q?: string }): Promise<any[]>;
+  listPage(opts?: { q?: string; limit?: number; cursor?: string }): Promise<Page>;
+  iterPages(opts?: { q?: string; pageSize?: number }): AsyncGenerator<any[]>;
   create(
     email: string,
     password: string,
@@ -296,10 +328,10 @@ interface UsersBundle {
     userId: string,
     startTime?: string,
     endTime?: string,
-    asOf?: string,
+    opTypes?: string[] | string,
   ): Promise<any[]>;
   auditPage(userId: string, opts?: AuditPageOptions): Promise<Page>;
-  get(id: string, asOf?: string): Promise<any>;
+  get(id: string): Promise<any>;
   delete(id: string, auditMessage?: string): Promise<any>;
   activate(id: string, auditMessage?: string): Promise<any>;
   update(
@@ -361,6 +393,60 @@ interface CommentFilters {
 type CommentableType =
   "document" | "text" | "token" | "span" | "relation" | "vocab-item";
 
+/**
+ * One entry in a project's annotation manual: a short Markdown document
+ * stating a convention the project follows. Read by the people on the
+ * project, and by the assistant before it proposes anything.
+ */
+interface Guideline {
+  id: string;
+  projectId: string;
+  /** The handle the assistant asks for a guideline by. Not required to be unique. */
+  title: string;
+  /** The Markdown text. Present on a single read and on a list made with `includeBodies`. */
+  body?: string;
+  /** The body's length in characters. Present on a list made WITHOUT `includeBodies`. */
+  bodyChars?: number;
+  /** Whether the assistant is given this one in full on every turn. */
+  pinned: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface GuidelinesBundle {
+  create(
+    projectId: string,
+    title: string,
+    opts?: { body?: string; pinned?: boolean },
+    auditMessage?: string,
+  ): Promise<{ id: string }>;
+  get(id: string): Promise<Guideline>;
+  update(
+    id: string,
+    changes?: {
+      title?: string;
+      body?: string;
+      pinned?: boolean;
+      /** Write only if this is still the stored updatedAt; 409 otherwise. */
+      expectedUpdatedAt?: string;
+    },
+    auditMessage?: string,
+  ): Promise<Guideline>;
+  delete(id: string, auditMessage?: string): Promise<any>;
+  list(
+    projectId: string,
+    opts?: { includeBodies?: boolean },
+  ): Promise<Guideline[]>;
+  listPage(
+    projectId: string,
+    opts?: { includeBodies?: boolean; limit?: number; cursor?: string },
+  ): Promise<Page<Guideline>>;
+  iterPages(
+    projectId: string,
+    opts?: { includeBodies?: boolean; pageSize?: number },
+  ): AsyncGenerator<Guideline[]>;
+}
+
 interface Comment {
   id: string;
   /** The owning project, or null for a comment on a vocabulary entry. */
@@ -418,6 +504,10 @@ interface CommentsBundle {
     vocabId: string,
     opts?: { entityId?: string; limit?: number; cursor?: string },
   ): Promise<Page<Comment>>;
+  iterInVocabPages(
+    vocabId: string,
+    opts?: { entityId?: string; pageSize?: number },
+  ): AsyncGenerator<Comment[]>;
   /** `{entryId: count}` over a vocabulary; keys are raw entry ids. */
   countsInVocab(
     vocabId: string,
@@ -497,6 +587,12 @@ interface ServerLimits {
   metadataStringLength?: number;
   metadataTotalBytes?: number;
   userDataValueBytes?: number;
+  guidelineTitleLength?: number;
+  guidelineBodyLength?: number;
+  /** The shortest password the server accepts on any path. */
+  passwordMinLength?: number;
+  /** How long a document lock is held before it lapses. */
+  lockExpirationMs?: number;
 }
 
 interface ServerHealth {
@@ -506,7 +602,8 @@ interface ServerHealth {
   audit: { dbSizeMb?: number; auditRows?: number; error?: string };
 }
 
-interface DocumentLock {
+/** A document lock as the admin lock listing reports it. */
+interface DocumentLockInfo {
   documentId: string;
   userId: string;
   expiresAt: number;
@@ -565,6 +662,15 @@ interface ServerReport {
   settings: Record<string, any>;
 }
 
+/** The signed-in user's sign-ins. Signing in is `PlaidClient.login`. */
+interface AuthBundle {
+  /**
+   * End every sign-in of this user on every device, this client's included.
+   * Named API tokens are not affected. Goes out at once even on a batch.
+   */
+  logoutEverywhere(): Promise<void>;
+}
+
 /** Server-level facts. `info` is fetched at most once per client. */
 interface ServerBundle {
   info(): Promise<{ limits: ServerLimits }>;
@@ -576,7 +682,7 @@ interface ServerBundle {
 interface AdminBundle {
   server(): Promise<ServerReport>;
   backup(): Promise<BackupStatus>;
-  locks(): Promise<{ entries: DocumentLock[] }>;
+  locks(): Promise<{ entries: DocumentLockInfo[] }>;
   releaseLock(documentId: string): Promise<{ result: string }>;
   rateLimits(): Promise<RateLimitSnapshot>;
   clearRateLimits(opts?: {
@@ -680,7 +786,6 @@ type AdminUserDataEntry = UserDataEntry & { userId: string };
 interface AuditPageOptions {
   startTime?: string;
   endTime?: string;
-  asOf?: string;
   opTypes?: string[] | string;
   /** "desc" pages newest-first; a cursor belongs to the direction that made it. */
   order?: "asc" | "desc";
@@ -772,7 +877,7 @@ interface TokenLayersBundle {
     configKey: string,
     auditMessage?: string,
   ): Promise<any>;
-  get(tokenLayerId: string, asOf?: string): Promise<any>;
+  get(tokenLayerId: string): Promise<any>;
   delete(tokenLayerId: string, auditMessage?: string): Promise<any>;
   update(
     tokenLayerId: string,
@@ -801,7 +906,7 @@ export declare class DocumentLockLost extends Error {
 export const DOCUMENT_LOCK_TTL_MS: 60000;
 
 interface DocumentsBundle {
-  checkLock(documentId: string, asOf?: string): Promise<any>;
+  checkLock(documentId: string): Promise<any>;
   acquireLock(documentId: string, auditMessage?: string): Promise<any>;
   releaseLock(documentId: string, auditMessage?: string): Promise<any>;
   /**
@@ -833,17 +938,26 @@ interface DocumentsBundle {
   deleteMetadata(documentId: string, auditMessage?: string): Promise<any>;
   patchMetadata(
     documentId: string,
-    body: any,
+    body: MetadataOp[],
     auditMessage?: string,
   ): Promise<any>;
   audit(
     documentId: string,
     startTime?: string,
     endTime?: string,
-    asOf?: string,
+    opTypes?: string[] | string,
   ): Promise<any[]>;
   auditPage(documentId: string, opts?: AuditPageOptions): Promise<Page>;
-  get(documentId: string, includeBody?: boolean, asOf?: string): Promise<any>;
+  /**
+   * `asOf` reads the document as it was at that instant. `layers` narrows a
+   * body read to the named layers (ids of any kind), and needs `includeBody`.
+   */
+  get(
+    documentId: string,
+    includeBody?: boolean,
+    asOf?: string,
+    layers?: string[] | string,
+  ): Promise<any>;
   delete(documentId: string, auditMessage?: string): Promise<any>;
   update(documentId: string, name: string, auditMessage?: string): Promise<any>;
   create(
@@ -868,11 +982,8 @@ interface DocumentsBundle {
 }
 
 interface MessagesBundle {
-  sendMessage(
-    projectId: string,
-    data: any,
-    auditMessage?: string,
-  ): Promise<any>;
+  /** Broadcast to the project's listeners. Never saved and never part of an operation. */
+  sendMessage(projectId: string, data: any): Promise<any>;
   listen(
     projectId: string,
     onEvent: (eventType: string, data: any) => void | boolean,
@@ -909,7 +1020,33 @@ interface MessagesBundle {
     timeout?: number,
     onProgress?: (progress: any) => void,
     signal?: AbortSignal,
+    opts?: {
+      /** A request id you mint, so you know it before submitting; resubmitting one rejoins that request. */
+      requestId?: string;
+      /** Called with the request id as soon as the server has taken the request. */
+      onAccepted?: (requestId: string) => void;
+      /** Other projects the request is about. A delegating service's token reaches `projectId` and those of these the requester can read, nothing else. */
+      projectIds?: string[];
+    },
+  ): Promise<any>;
+  /**
+   * Rejoin a request made earlier: the latest progress is replayed, then the
+   * result, or at once if it already finished. Only its submitter (or an
+   * admin). Rejects with a 404 when the request is unknown or expired.
+   */
+  attachServiceRequest(
+    projectId: string,
+    requestId: string,
+    timeout?: number,
+    onProgress?: (progress: any) => void,
+    signal?: AbortSignal,
   ): Promise<any>;
+  /**
+   * Ask the service to stop a request made earlier. The request still ends
+   * with whatever the service then reports. 404 if unknown or expired, 409
+   * once finished.
+   */
+  cancelServiceRequest(projectId: string, requestId: string): Promise<void>;
 }
 
 interface ProjectsBundle {
@@ -944,12 +1081,18 @@ interface ProjectsBundle {
     projectId: string,
     startTime?: string,
     endTime?: string,
-    asOf?: string,
+    opTypes?: string[] | string,
   ): Promise<any[]>;
   auditPage(projectId: string, opts?: AuditPageOptions): Promise<Page>;
+  /**
+   * When the calling user last wrote to each document of the project, as a
+   * `{documentId: timestamp}` map; documents they never wrote to are absent.
+   * The keys are document ids, so the response is not key-transformed.
+   */
+  myLastEdits(projectId: string): Promise<Record<string, string>>;
   linkVocab(id: string, vocabId: string, auditMessage?: string): Promise<any>;
   unlinkVocab(id: string, vocabId: string, auditMessage?: string): Promise<any>;
-  get(id: string, asOf?: string): Promise<any>;
+  get(id: string): Promise<any>;
   listDocuments(id: string): Promise<any[]>;
   listDocumentsPage(
     id: string,
@@ -959,15 +1102,16 @@ interface ProjectsBundle {
     id: string,
     opts?: { pageSize?: number },
   ): AsyncGenerator<any[]>;
-  delete(id: string, auditMessage?: string): Promise<any>;
   update(id: string, name: string, auditMessage?: string): Promise<any>;
-  list(asOf?: string): Promise<any[]>;
-  listPage(opts?: {
-    limit?: number;
-    cursor?: string;
-    asOf?: string;
-  }): Promise<Page>;
-  iterPages(opts?: { pageSize?: number; asOf?: string }): AsyncGenerator<any[]>;
+  /** The project is gone when this returns, and what it holds is removed on the server afterwards. The timeout defaults to the client's. */
+  delete(
+    id: string,
+    auditMessage?: string,
+    options?: { timeout?: number | null },
+  ): Promise<any>;
+  list(): Promise<any[]>;
+  listPage(opts?: { limit?: number; cursor?: string }): Promise<Page>;
+  iterPages(opts?: { pageSize?: number }): AsyncGenerator<any[]>;
   create(name: string, auditMessage?: string): Promise<any>;
 }
 
@@ -985,7 +1129,7 @@ interface TextLayersBundle {
     configKey: string,
     auditMessage?: string,
   ): Promise<any>;
-  get(textLayerId: string, asOf?: string): Promise<any>;
+  get(textLayerId: string): Promise<any>;
   delete(textLayerId: string, auditMessage?: string): Promise<any>;
   update(
     textLayerId: string,
@@ -1003,7 +1147,7 @@ interface TextLayersBundle {
 interface VocabItemsBundle {
   setMetadata(id: string, body: any, auditMessage?: string): Promise<any>;
   deleteMetadata(id: string, auditMessage?: string): Promise<any>;
-  patchMetadata(id: string, body: any, auditMessage?: string): Promise<any>;
+  patchMetadata(id: string, body: MetadataOp[], auditMessage?: string): Promise<any>;
   create(
     vocabLayerId: string,
     form: string,
@@ -1012,7 +1156,8 @@ interface VocabItemsBundle {
   ): Promise<any>;
   bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
   bulkDelete(body: any[], auditMessage?: string): Promise<void>;
-  get(id: string, asOf?: string): Promise<any>;
+  bulkUpdate(body: any[], auditMessage?: string): Promise<{ count: number }>;
+  get(id: string): Promise<any>;
   delete(id: string, auditMessage?: string): Promise<any>;
   update(id: string, form: string, auditMessage?: string): Promise<any>;
 }
@@ -1041,7 +1186,7 @@ interface RelationLayersBundle {
     configKey: string,
     auditMessage?: string,
   ): Promise<any>;
-  get(relationLayerId: string, asOf?: string): Promise<any>;
+  get(relationLayerId: string): Promise<any>;
   delete(relationLayerId: string, auditMessage?: string): Promise<any>;
   update(
     relationLayerId: string,
@@ -1060,7 +1205,7 @@ interface TokensBundle {
     metadata?: any,
     auditMessage?: string,
   ): Promise<any>;
-  get(tokenId: string, asOf?: string): Promise<any>;
+  get(tokenId: string): Promise<any>;
   delete(tokenId: string, auditMessage?: string): Promise<any>;
   update(
     tokenId: string,
@@ -1088,7 +1233,7 @@ interface TokensBundle {
   deleteMetadata(tokenId: string, auditMessage?: string): Promise<any>;
   patchMetadata(
     tokenId: string,
-    body: any,
+    body: MetadataOp[],
     auditMessage?: string,
   ): Promise<any>;
 }
@@ -1116,8 +1261,40 @@ export interface OperationGroupsBundle {
   update(id: string, message: string | null): Promise<any>;
 }
 
+/**
+ * A batch: the client's bundles, on which every write of project data queues
+ * until `submit()`. See `PlaidClient.batch()`.
+ */
+export interface PlaidBatch extends PlaidClient {
+  /** The client this batch was opened on. */
+  readonly client: PlaidClient;
+  /** The queued operations, in order. */
+  readonly operations: Array<{ path: string; method: string; body?: any }>;
+  /**
+   * Send the queued operations and resolve to one result per operation, in
+   * order. Up to MAX_BATCH_OPS operations go as one atomic request. A larger
+   * batch goes as consecutive requests, each atomic on its own, so a failure
+   * in a later one leaves the earlier ones committed. The error then carries
+   * `committed`, how many operations were saved (0 when none were), and
+   * `committedResults`, their results in queue order.
+   */
+  submit(): Promise<any[]>;
+  /** Drop the queued operations without sending them. */
+  abort(): void;
+}
+
 export declare class PlaidClient {
   constructor(baseUrl: string, token: string, options?: PlaidClientOptions);
+  /** Liveness, version and database size, with no authentication. */
+  static health(
+    baseUrl: string,
+    options?: { timeout?: number | null },
+  ): Promise<ServerHealth>;
+  /** The limits this server enforces, with no authentication. */
+  static info(
+    baseUrl: string,
+    options?: { timeout?: number | null },
+  ): Promise<{ limits: ServerLimits }>;
   static login(
     baseUrl: string,
     userId: string,
@@ -1139,28 +1316,37 @@ export declare class PlaidClient {
     credentials: { email?: string; password: string; displayName?: string },
     options?: PlaidClientOptions,
   ): Promise<{ client: PlaidClient; userId: string; kind: string }>;
+  /** The server's base URL, without a trailing slash. */
+  readonly baseUrl: string;
+  /** The bearer token every request carries. */
+  token: string;
   timeout: number | null;
   batchTimeout: number | null;
+  /** The document strict mode is entered for, or null. */
+  readonly strictModeDocumentId: string | null;
+  /** The DocumentLockLost of the open `locked()` block whose lock lapsed, or null. Cleared when that block exits. */
+  documentLockLost: DocumentLockLost | null;
   /** Fired once on HTTP 401 (see PlaidClientOptions.onAuthError). */
   onAuthError: ((error: Error) => void) | null;
+  /** The latest version seen for each document written through this client, keyed by document id. */
+  documentVersions: Record<string, number>;
+  /** True once a response left its version list out (X-Document-Versions-Omitted, past fifty documents). Every version held was then forgotten, and the strict-mode document's is read again before the next write. */
+  documentVersionsOmitted?: boolean;
 
-  // Batch control methods.
+  // Batches.
   //
-  // Batch mode is one flag on the whole client, so it catches every write made
-  // while it is open, including writes made by code that knows nothing about
-  // the batch. Reads are never caught: every read method goes over the wire
-  // while a batch is open and is answered from the state the batch has not
-  // committed yet, so app chrome sharing a client with an importer keeps
-  // working. Neither are the calls that signal something out of band rather
-  // than write project data: stopping a service request, a service reporting
-  // its progress or result, taking and dropping a document lock, and the admin
-  // actions on the server itself.
-  beginBatch(): void;
-  submitBatch(): Promise<any[]>;
-  abortBatch(): void;
-  isBatchMode(): boolean;
-  /** Run `fn` with a batch open, then submit atomically (or abort if `fn` throws). Resolves to the results array. Writes inside `fn` queue; reads go over the wire and see the pre-batch state. */
-  batched(fn: () => void | Promise<void>): Promise<any[]>;
+  // A batch is a view of the client with the same bundles. A write of project
+  // data made on the batch queues; a call made on the client itself always
+  // goes over the wire, whatever batches are open, so a write by code that
+  // knows nothing about a batch can never land inside it. A read, or a signal
+  // that carries no project data (stopping a service request, a service
+  // reporting its progress, taking and dropping a document lock, the admin
+  // actions on the server itself), goes over the wire even when made on the
+  // batch.
+  /** Open a batch. Queue writes on it, then `submit()` them (one atomic request up to MAX_BATCH_OPS operations), or `abort()`. Not nestable. */
+  batch(): PlaidBatch;
+  /** Run `fn` with a batch, then submit it as `submit()` does (or abort if `fn` throws). Resolves to the results array, one entry per queued write. */
+  batched(fn: (batch: PlaidBatch) => void | Promise<void>): Promise<any[]>;
 
   // Strict mode methods
   enterStrictMode(documentId: string): void;
@@ -1179,23 +1365,24 @@ export declare class PlaidClient {
   operationGroups: OperationGroupsBundle;
 
   // Query
-  query(body: any, auditMessage?: string): Promise<any>;
+  query(body: any): Promise<any>;
 
   vocabLinks: VocabLinksBundle;
   vocabLayers: VocabLayersBundle;
   relations: RelationsBundle;
   spanLayers: SpanLayersBundle;
   spans: SpansBundle;
-  batch: BatchBundle;
   texts: TextsBundle;
   users: UsersBundle;
   apiTokens: ApiTokensBundle;
   userData: UserDataBundle;
   invites: InvitesBundle;
   server: ServerBundle;
+  auth: AuthBundle;
   admin: AdminBundle;
   audit: AuditBundle;
   comments: CommentsBundle;
+  guidelines: GuidelinesBundle;
   tokenLayers: TokenLayersBundle;
   documents: DocumentsBundle;
   messages: MessagesBundle;
@@ -1230,6 +1417,8 @@ export function cpIndexOf(s: string, sub: string, fromCp?: number): number;
 export const PLAID_NAMESPACE: "plaid";
 /** The config key, under `plaid`, holding a layer's role. */
 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";
 
 /** The server's cap on operations per batch request; a larger batch goes as consecutive requests. */
 export const MAX_BATCH_OPS: 1000;
@@ -1262,9 +1451,11 @@ export const TASKS: {
   readonly TRANSCRIBE: "transcribe";
   readonly LINK_VOCAB: "link-vocab";
   readonly ANALYZE: "analyze";
+  readonly DRAFT_GRAPH: "draft-graph";
   readonly TRANSLATE: "translate";
   readonly ASSIST: "assist";
   readonly DETECT_SPEECH: "detect-speech";
+  readonly COMPARE: "compare";
 };
 /** Whether a service serves a task (declared `extras.tasks`, legacy id-prefix fallback). */
 export function servesTask(service: DiscoveredService, task: string): boolean;
@@ -1293,7 +1484,7 @@ export function coerceParamValues(
 // replace unverified machine material but must never touch human/verified
 // material without an explicit overwrite opt-in; any human edit verifies.
 // See the manual, "Provenance".
-type ProvState = "human" | "machine" | "verified";
+type ProvState = "human" | "machine" | "contributed" | "verified";
 export const PROV: {
   readonly key: "prov";
   readonly sourceKey: "provSource";
@@ -1301,12 +1492,16 @@ export const PROV: {
   readonly probKey: "provProb";
   readonly detailKey: "provDetail";
   readonly INFERRED: "inferred";
+  readonly CONTRIBUTED: "contributed";
 };
 export const PROV_STATES: {
   readonly HUMAN: "human";
   readonly MACHINE: "machine";
+  readonly CONTRIBUTED: "contributed";
   readonly VERIFIED: "verified";
 };
+/** The provenance keys Plaid itself owns — what a split carries and a reshape keeps. */
+export const PROVENANCE_KEYS: readonly string[];
 /** Optional prediction extras: prob = a probability in [0,1] for the chosen value
  * (flat + queryable; omit unless it honestly is one); detail = an open map of
  * producer extras (top-k alternatives, model version, raw scores; keep it small).
@@ -1351,3 +1546,102 @@ export function verifyOnEdit(
 ): { 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";
+  provSource: string;
+};
+/** Where an entity came from, confirmed or not: what a verified entity's tooltip needs. */
+export function provOrigin(
+  metadata: object | null | undefined,
+): null | "inferred" | "contributed";
+/** Whether a verifier still has to look at this entity: machine-made or contributed, unconfirmed. */
+export function needsReview(metadata: object | null | undefined): boolean;
+/** The fragment a CONTRIBUTOR's edit merges in: the contributed stamp, dropping any confirmation. */
+export function contributeOnEdit(
+  metadata: object | null | undefined,
+  userId: string,
+): { prov: "contributed"; provSource: string; provConfirmed: null };
+/** Merge a fragment into a local copy, a null value deleting the key: applyMetadataOps(metadata, metadataOps(fragment)), refused where the server would refuse it. Returns a new object. */
+export function mergeMetadata(
+  metadata: object | null | undefined,
+  fragment: object | null | undefined,
+): Record<string, any>;
+
+// --- Create responses ---------------------------------------------------------
+/** The id a single create answered with, read off the call's response or its batch result (`{status, body}`). Undefined when it gave none. */
+export function createdId(result: any): string | undefined;
+/** The ids a bulk create answered with, in input order, read off the call's response or its batch result. Empty when it gave none. */
+export function createdIds(result: any): string[];
+
+// --- Metadata ops -------------------------------------------------------------
+/** One metadata edit: the body of a metadata PATCH is a list of these. */
+export type MetadataOp =
+  | { op: "set"; path: string[]; value: any }
+  | { op: "delete"; path: string[] };
+/** The ops that set each top-level key of a fragment, a null value deleting it. */
+export function metadataOps(
+  fragment: object | null | undefined,
+): MetadataOp[];
+/** Apply ops to a local copy the way the server does. Returns a new object; throws where the server would refuse. */
+export function applyMetadataOps(
+  metadata: object | null | undefined,
+  ops: MetadataOp[],
+): Record<string, any>;
+/** True for a top-level metadata key Plaid keeps for itself (`plaid` and the provenance keys), never a user's field. */
+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[];
+  roles: string[];
+};
+/** A person's role in a project from its ACL lists; an admin with no entry is a maintainer. */
+export function projectRole(
+  project: object | null | undefined,
+  userId: string | null | undefined,
+  opts?: { isAdmin?: boolean },
+): "maintainer" | "writer" | "reader" | null;
+/** Whether this person's work is reviewed here: named in review.users, or holding a role in review.roles. */
+export function isReviewed(
+  project: object | null | undefined,
+  userId: string | null | undefined,
+  opts?: { isAdmin?: boolean },
+): boolean;
+/** The review lists with one person added to or removed from `users`. Pure. */
+export function withReviewedUser(
+  review: { users?: string[]; roles?: string[] } | null | undefined,
+  userId: string,
+  reviewed: boolean,
+): { users: string[]; roles: string[] };
+/** What one writer's writes carry and what their review gestures act on. */
+export function writerPolicy(contributorId?: string | null): {
+  readonly contributorId: string | null;
+  readonly isContributor: boolean;
+  /** The metadata a NEW entity carries: null for a verifier. */
+  readonly createStamp: Record<string, any> | null;
+  /** The fragment an EDIT merges, or null when there is nothing to merge. */
+  readonly editStamp: (
+    metadata: object | null | undefined,
+  ) => Record<string, any> | null;
+  /** The fragment an explicit confirm gesture merges, or null. */
+  readonly confirmStamp: (
+    metadata: object | null | undefined,
+  ) => Record<string, any> | null;
+  /** What an adopted suggestion is written with. */
+  readonly adoptStamp: (
+    source: string,
+    detail?: Record<string, any>,
+  ) => Record<string, any>;
+  /** Whether this writer's review gesture acts on the entity. */
+  readonly reviewable: (metadata: object | null | undefined) => boolean;
+  /** The same test over a provState. */
+  readonly reviewableState: (state: string) => boolean;
+};