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

package/index.d.ts

@@ -106,6 +106,26 @@ export class ServiceCancelled extends Error {
   constructor(message?: string);
 }
 
+/** The key a run's stored record names its requester under. */
+export const REQUESTED_BY: "requestedBy";
+
+/** The person who asked for one service run. Both fields are null when nobody asked. */
+export interface Requester {
+  id: string | null;
+  name: string | null;
+  /** `"<text>, requested by <name>"`, or `text` when nobody asked. */
+  label(text: string): string;
+  /** `{ id, name }` for a stored report, or null when nobody asked. */
+  record(): { id: string; name: string | null } | null;
+  /** A machine stamp's `provDetail` with `requestedBy: <id>` added. */
+  detail(detail?: Record<string, any>): Record<string, any>;
+}
+
+export function makeRequester(id?: string | null, name?: string | null): Requester;
+
+/** The requester of one request, from the `requesterId` in a `serve` handler's data, named by display name. */
+export function requesterOf(client: { users: { get(id: string): Promise<any> } }, data: any): Promise<Requester>;
+
 /** The cancellation half of a responseHelper, on its own. */
 export function createCancelScope(isCancelled: () => boolean): {
   readonly cancelled: boolean;
@@ -471,6 +491,65 @@ interface Comment {
   edited: boolean;
 }
 
+/** A research-telemetry event type (core manual, "Research telemetry"). */
+type ClientEventType =
+  | "suggestion.shown"
+  | "suggestion.adopted"
+  | "suggestion.dismissed"
+  | "plan.opened";
+
+interface ClientEventFields {
+  projectId: string;
+  documentId?: string;
+  targetId?: string;
+  /** Keyed by single lowercase words: value, source, field, written, conversation. */
+  data?: Record<string, any>;
+}
+
+interface ClientEvent {
+  id: number;
+  projectId: string;
+  documentId: string | null;
+  userId: string;
+  type: ClientEventType;
+  targetId: string | null;
+  data: Record<string, any> | null;
+  clientTs: string | null;
+  ts: string;
+}
+
+interface ClientEventFilters {
+  types?: ClientEventType | ClientEventType[] | string;
+  startTime?: string;
+  endTime?: string;
+}
+
+interface EventsBundle {
+  /** Buffer one event; never throws. False when not recorded (switch off, a repeat shown). */
+  record(type: ClientEventType, fields: ClientEventFields): boolean;
+  flush(): void;
+  setEnabled(projectId: string, on: boolean): void;
+  create(
+    projectId: string,
+    events: Array<{
+      type: ClientEventType;
+      documentId?: string;
+      targetId?: string;
+      data?: Record<string, any>;
+      clientTs?: string;
+    }>,
+  ): Promise<{ count: number }>;
+  list(projectId: string, filters?: ClientEventFilters): Promise<ClientEvent[]>;
+  listPage(
+    projectId: string,
+    opts?: ClientEventFilters & { limit?: number; cursor?: string },
+  ): Promise<Page<ClientEvent>>;
+  iterPages(
+    projectId: string,
+    opts?: ClientEventFilters & { pageSize?: number },
+  ): AsyncGenerator<ClientEvent[]>;
+}
+
 interface CommentsBundle {
   create(
     entityType: CommentableType,
@@ -889,6 +968,8 @@ interface TokenLayersBundle {
 /** Handle passed to a `documents.locked()` block. */
 export declare class DocumentLock {
   readonly documentId: string;
+  /** The holder id the acquire answered with. */
+  readonly lockId: string | null;
   /** The DocumentLockLost if the lock lapsed, else null. */
   readonly lost: DocumentLockLost | null;
   /** Throw if the lock lapsed; call it between steps that have not written. */
@@ -907,12 +988,23 @@ export const DOCUMENT_LOCK_TTL_MS: 60000;
 
 interface DocumentsBundle {
   checkLock(documentId: string): Promise<any>;
+  /** Take the lock as a new holder. The answer's `lockId` names it. */
   acquireLock(documentId: string, auditMessage?: string): Promise<any>;
-  releaseLock(documentId: string, auditMessage?: string): Promise<any>;
+  /** Renew `lockId`'s lock while it is live. 423 once it has lapsed. */
+  renewLock(
+    documentId: string,
+    lockId: string,
+    auditMessage?: string,
+  ): Promise<any>;
+  releaseLock(
+    documentId: string,
+    lockId: string,
+    auditMessage?: string,
+  ): Promise<any>;
   /**
    * Hold the document's lock for the length of `fn`, renewing it while `fn`
-   * runs and releasing it on the way out. Rejects with a 423 if another user
-   * holds it, and with DocumentLockLost if a renewal fails.
+   * runs and releasing it on the way out. Rejects with a 423 if it is already
+   * held, and with DocumentLockLost if a renewal fails.
    */
   locked<T>(
     documentId: string,
@@ -1027,6 +1119,8 @@ interface MessagesBundle {
       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[];
+      /** Carry no open operation: the service's writes are a group of their own, not part of whatever operation this client has open. */
+      noOperation?: boolean;
     },
   ): Promise<any>;
   /**
@@ -1256,6 +1350,15 @@ interface PlaidClientOptions {
   onAuthError?: ((error: Error) => void) | null;
 }
 
+/** What kind of operation a logical-operation group is (`?group-kind=`). */
+export type OperationKind =
+  | 'assistant-plan'
+  | 'service-run'
+  | 'import'
+  | 'bulk-edit'
+  | 'guess-adoption'
+  | 'repair';
+
 export interface OperationGroupsBundle {
   get(id: string): Promise<any>;
   update(id: string, message: string | null): Promise<any>;
@@ -1332,6 +1435,10 @@ export declare class PlaidClient {
   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;
+  /** The server's clock minus this machine's, in ms, from the last response with a Date header, or null before one. */
+  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;
 
   // Batches.
   //
@@ -1355,12 +1462,23 @@ export declare class PlaidClient {
   // Logical operations (audit-log grouping). While one is open every write is
   // stamped with its group id so the audit log folds them into one entry.
   // Not atomic; nesting flattens into the outer operation.
-  operationGroup: { id: string; message: string | null } | null;
-  beginOperation(message: string, opts?: { id?: string }): string;
+  // `kind` is one of OperationKind (the server refuses any other) and `ref`
+  // names what the operation came from; nesting keeps the outer ones.
+  operationGroup: {
+    id: string;
+    message: string | null;
+    kind: OperationKind | null;
+    ref: string | null;
+  } | null;
+  beginOperation(
+    message: string,
+    opts?: { id?: string; kind?: OperationKind; ref?: string },
+  ): string;
   endOperation(message?: string): Promise<void>;
   withOperation<T>(
     message: string,
     fn: (setMessage: (msg: string) => void) => Promise<T> | T,
+    opts?: { kind?: OperationKind; ref?: string },
   ): Promise<T>;
   operationGroups: OperationGroupsBundle;
 
@@ -1382,6 +1500,7 @@ export declare class PlaidClient {
   admin: AdminBundle;
   audit: AuditBundle;
   comments: CommentsBundle;
+  events: EventsBundle;
   guidelines: GuidelinesBundle;
   tokenLayers: TokenLayersBundle;
   documents: DocumentsBundle;

package/package.json

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

package/src/documentLock.js

@@ -10,8 +10,9 @@
  * silence, a person's edit lands between the read the work was planned from and
  * the write about to go out, and the write clobbers it.
  *
- * A `locked()` block therefore renews on a timer of its own. The renewal is a
- * plain acquire: the server refreshes a lock whose holder asks for it again.
+ * A `locked()` block therefore renews on a timer of its own. The renewal is an
+ * acquire that names the holder's `lockId`: the server refreshes the lock that
+ * id holds, and refuses one somebody else holds (the same user included).
  *
  * The beat is unconditional rather than "only when no write has gone out
  * recently". The request layer knows the method of a call but not which
@@ -157,9 +158,10 @@ export class LockKeeper {
       try {
         await this._refresh(this._documentId);
       } catch (error) {
-        // 423 is definitive: somebody else holds the document now, so ours had
-        // already expired. Anything else may be a blip, and is only fatal once
-        // the lock we are renewing has actually run out.
+        // 423 is definitive: somebody else holds the document now, or ours
+        // expired or was dropped, and the server never takes it back.
+        // Anything else may be a blip, and is only fatal once the lock we are
+        // renewing has actually run out.
         if (error?.status === 423 || this._clock() >= deadline) {
           this._fail(error);
           return;
@@ -203,8 +205,10 @@ export class LockKeeper {
  * between steps of work that has not written anything yet.
  */
 export class DocumentLock {
-  constructor(documentId, keeper) {
+  constructor(documentId, keeper, lockId = null) {
     this.documentId = documentId;
+    /** The holder id the acquire answered with. */
+    this.lockId = lockId;
     this._keeper = keeper;
   }
 
@@ -255,12 +259,13 @@ export async function withDocumentLock(
     throw error;
   }
 
+  const lockId = info?.lockId ?? null;
   let keeper = null;
   if (keepAlive) {
     const ttlMs = lockTtlMs(info?.expiresAt, Date.now());
     client.documentLockLost = null;
     keeper = new LockKeeper(
-      (id) => client.documents.acquireLock(id),
+      (id) => client.documents.renewLock(id, lockId),
       documentId,
       ttlMs,
       {
@@ -275,7 +280,7 @@ export async function withDocumentLock(
   let result;
   let threw = false;
   try {
-    result = await fn(new DocumentLock(documentId, keeper));
+    result = await fn(new DocumentLock(documentId, keeper, lockId));
   } catch (error) {
     threw = true;
     throw error;
@@ -286,7 +291,7 @@ export async function withDocumentLock(
     // Best-effort release: the server TTL reclaims a stranded lock, and we must
     // not let a release failure mask the real error from the body.
     try {
-      await client.documents.releaseLock(documentId);
+      await client.documents.releaseLock(documentId, lockId);
     } catch {
       /* the lock expires on its own */
     }

package/src/events.js

@@ -0,0 +1,256 @@
+import { transformRequest } from "./transforms.js";
+
+// ---------------------------------------------------------------------------
+// Client events: the opt-in research telemetry of a project (core manual,
+// "Research telemetry").
+//
+// `client.events.record(type, fields)` is a fire-and-forget recorder. It
+// buffers events and sends them every FLUSH_INTERVAL_MS or FLUSH_AT events,
+// and when the page is hidden (`pagehide`, with `keepalive` so the request
+// outlives the page). A batch that fails is dropped: no retry, no toast, no
+// error for the caller. Nothing it does can block or break the screen that
+// called it.
+//
+// It sends nothing for a project whose switch is off. The switch is read once
+// from the project (`config.plaid.research.telemetry`) and kept for
+// FLAG_TTL_MS; `events.setEnabled` tells it at once, which is what the
+// settings checkbox does. A server refusal (the switch was turned off since)
+// turns it off here too.
+//
+// ONE recorder per server per page, whatever client records into it: an app
+// makes a client per editor, and a suggestion's "shown" is deduplicated for
+// the page session, not per client. The last client to record lends its
+// token to the next send.
+// ---------------------------------------------------------------------------
+
+/** Every event type the server accepts. */
+export const EVENT_TYPES = Object.freeze([
+  "suggestion.shown",
+  "suggestion.adopted",
+  "suggestion.dismissed",
+  "plan.opened",
+]);
+
+export const FLUSH_INTERVAL_MS = 10000;
+export const FLUSH_AT = 50;
+export const FLAG_TTL_MS = 5 * 60 * 1000;
+// Events per request. A browser refuses a `keepalive` request whose body,
+// with every other keepalive request still in flight, passes 64 KiB, and a
+// refused request is lost. So the pagehide send goes out in small pieces, and
+// only that send is keepalive: a backlog sent while the page stays (the first
+// page of a grid, drawn while the switch was still being read, can hold
+// hundreds of guesses) would otherwise lose everything past the quota. The
+// server takes up to 500 in one request.
+const PER_REQUEST = FLUSH_AT;
+// A suggested or written value is a gloss, not prose. A long one is cut, in
+// code points as the server counts them, so no character is split in two.
+// The server refuses a value past this length, and a key its type does not
+// take (core manual, "Research telemetry").
+const MAX_VALUE_CHARS = 200;
+
+const clip = (v) => {
+  if (typeof v !== "string" || v.length <= MAX_VALUE_CHARS) return v;
+  const cps = Array.from(v);
+  return cps.length > MAX_VALUE_CHARS
+    ? cps.slice(0, MAX_VALUE_CHARS).join("")
+    : v;
+};
+
+export class EventRecorder {
+  /**
+   * @param {object} [opts]
+   * @param {function} [opts.now] - Clock, for tests
+   * @param {object} [opts.window] - Where `pagehide` fires (default globalThis)
+   */
+  constructor({ now = () => Date.now(), window = globalThis } = {}) {
+    this.client = null;
+    this.buffer = [];
+    this.timer = null;
+    this.now = now;
+    // projectId -> { state: 'on' | 'off' | 'pending', at }
+    this.flags = new Map();
+    // "shown" keys already recorded this page session.
+    this.seen = new Set();
+    this._onPageHide = () => this.flush({ keepalive: true });
+    this.window = window;
+    window?.addEventListener?.("pagehide", this._onPageHide);
+  }
+
+  /** Tell the recorder a project's switch, e.g. right after changing it. */
+  setEnabled(projectId, on) {
+    this.flags.set(projectId, { state: on ? "on" : "off", at: this.now() });
+    if (!on) this._drop(projectId);
+    else if (this.buffer.length) this._schedule();
+  }
+
+  /**
+   * Record one event. Returns true when it was buffered, false when it was
+   * not (switch off, a repeat "shown", an unknown type, no project).
+   */
+  record(client, type, { projectId, documentId, targetId, data } = {}) {
+    try {
+      if (!EVENT_TYPES.includes(type) || !projectId) return false;
+      this.client = client;
+      const flag = this._flag(projectId);
+      if (flag === "off") return false;
+      // A key with no value is left out: the server takes only a string or
+      // a number.
+      const clipped = data
+        ? Object.fromEntries(
+            Object.entries(data)
+              .filter(([, v]) => v != null)
+              .map(([k, v]) => [k, clip(v)]),
+          )
+        : undefined;
+      let key = null;
+      if (type === "suggestion.shown") {
+        key = JSON.stringify([
+          projectId,
+          targetId ?? null,
+          clipped?.field ?? null,
+          clipped?.value ?? null,
+        ]);
+        if (this.seen.has(key)) return false;
+        this.seen.add(key);
+      }
+      this.buffer.push({
+        projectId,
+        key,
+        event: {
+          type,
+          documentId: documentId ?? undefined,
+          targetId: targetId == null ? undefined : String(targetId),
+          data: clipped,
+          clientTs: new Date(this.now()).toISOString(),
+        },
+      });
+      if (this.buffer.length >= FLUSH_AT) this.flush();
+      else this._schedule();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Send what is buffered for every project whose switch is known to be on,
+   * drop what is buffered for one known to be off, and keep the rest until
+   * the switch is known. With `keepalive` (the page is going away) nothing is
+   * kept.
+   */
+  flush({ keepalive = false } = {}) {
+    clearTimeout(this.timer);
+    this.timer = null;
+    const keep = [];
+    const byProject = new Map();
+    for (const entry of this.buffer) {
+      const state = this.flags.get(entry.projectId)?.state;
+      if (state === "on") {
+        if (!byProject.has(entry.projectId)) byProject.set(entry.projectId, []);
+        byProject.get(entry.projectId).push(entry.event);
+      } else if (state === "off") {
+        if (entry.key) this.seen.delete(entry.key);
+      } else if (!keepalive) {
+        keep.push(entry);
+      }
+    }
+    this.buffer = keep;
+    for (const [projectId, events] of byProject) {
+      for (let i = 0; i < events.length; i += PER_REQUEST) {
+        this._send(projectId, events.slice(i, i + PER_REQUEST), keepalive);
+      }
+    }
+  }
+
+  /** Stop listening for `pagehide` and forget everything (tests). */
+  close() {
+    clearTimeout(this.timer);
+    this.timer = null;
+    this.buffer = [];
+    this.window?.removeEventListener?.("pagehide", this._onPageHide);
+  }
+
+  _schedule() {
+    if (this.timer == null) {
+      this.timer = setTimeout(() => this.flush(), FLUSH_INTERVAL_MS);
+    }
+  }
+
+  _drop(projectId) {
+    this.buffer = this.buffer.filter((e) => {
+      if (e.projectId !== projectId) return true;
+      if (e.key) this.seen.delete(e.key);
+      return false;
+    });
+  }
+
+  // The switch as known now: 'on', 'off' or 'pending'. An unknown one sets
+  // off a read of the project, and a stale one a fresh read while the old
+  // answer stands. The answer flushes or drops what is buffered.
+  _flag(projectId) {
+    const known = this.flags.get(projectId);
+    const fresh = known && this.now() - known.at < FLAG_TTL_MS;
+    if (known && (fresh || known.checking)) return known.state;
+    this.flags.set(projectId, {
+      state: known ? known.state : "pending",
+      at: known ? known.at : 0,
+      checking: true,
+    });
+    const client = this.client;
+    Promise.resolve()
+      .then(() => client.projects.get(projectId))
+      .then(
+        (project) => project?.config?.plaid?.research?.telemetry === true,
+        () => false,
+      )
+      .then((on) => {
+        this.flags.set(projectId, { state: on ? "on" : "off", at: this.now() });
+        if (!on) this._drop(projectId);
+        else if (this.buffer.length >= FLUSH_AT) this.flush();
+        else if (this.buffer.length) this._schedule();
+      });
+    return known ? known.state : "pending";
+  }
+
+  _send(projectId, events, keepalive) {
+    const client = this.client;
+    try {
+      const url = `${client.baseUrl}/api/v1/projects/${projectId}/events`;
+      fetch(url, {
+        method: "POST",
+        keepalive,
+        headers: {
+          Authorization: `Bearer ${client.token}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(transformRequest(events)),
+      }).then(
+        (res) => {
+          // The switch was turned off since it was read.
+          if (res.status === 403) this.setEnabled(projectId, false);
+        },
+        () => {},
+      );
+    } catch {
+      /* dropped, as every failed batch is */
+    }
+  }
+}
+
+const recorders = new Map();
+
+/** The page's recorder for `client`'s server. */
+export function recorderFor(client) {
+  let r = recorders.get(client.baseUrl);
+  if (!r) {
+    r = new EventRecorder();
+    recorders.set(client.baseUrl, r);
+  }
+  return r;
+}
+
+/** Forget every recorder (tests). */
+export function resetEventRecorders() {
+  for (const r of recorders.values()) r.close();
+  recorders.clear();
+}

package/src/http.js

@@ -64,6 +64,18 @@ export const DEFAULT_TIMEOUT_MS = 30000;
 // nothing and costs a retry stacked on a write that is still running.
 export const DEFAULT_BATCH_TIMEOUT_MS = 180000;
 
+/**
+ * Note how far the server's clock is from this machine's, from a response's
+ * Date header, for `client.serverNow()`. A time the server stamped (an audit
+ * entry's `ts`) has to be judged against the server's clock: a browser clock
+ * minutes off would misjudge it. A response with no readable Date header
+ * leaves the last offset as it was.
+ */
+export function noteServerClock(client, headers) {
+  const at = Date.parse(headers?.get?.("date") ?? "");
+  if (!Number.isNaN(at)) client.serverClockOffsetMs = at - Date.now();
+}
+
 /**
  * Extract and update document versions from response headers and body.
  *
@@ -412,6 +424,8 @@ export function prepareRequest(client, method, path, options = {}) {
     url += `${separator}group-id=${encodeURIComponent(group.id)}`;
     if (group.message)
       url += `&group-message=${encodeURIComponent(group.message)}`;
+    if (group.kind) url += `&group-kind=${encodeURIComponent(group.kind)}`;
+    if (group.ref) url += `&group-ref=${encodeURIComponent(group.ref)}`;
     group.written = true;
   }
 
@@ -600,6 +614,7 @@ export async function makeRequest(client, method, path, options = {}) {
       }
       return res;
     });
+    noteServerClock(client, response.headers);
 
     if (!response.ok) {
       const error = makeHttpError(

package/src/index.js

@@ -17,6 +17,7 @@ import {
   DEFAULT_BATCH_TIMEOUT_MS,
 } from "./http.js";
 import { listAll, listPage, iterPages } from "./pagination.js";
+import { recorderFor } from "./events.js";
 import { withDocumentLock } from "./documentLock.js";
 import { createSSEConnection } from "./sse.js";
 import {
@@ -206,6 +207,15 @@ async function sendChunks(client, url, ops, stamps, results) {
   }
 }
 
+/** The query of an events read: `types` as the wire's comma-separated list. */
+function eventQuery(types, startTime, endTime) {
+  return {
+    types: Array.isArray(types) ? types.join(",") || undefined : types,
+    "start-time": startTime,
+    "end-time": endTime,
+  };
+}
+
 class PlaidClient {
   /**
    * Create a new PlaidClient instance
@@ -232,6 +242,9 @@ class PlaidClient {
           ? options.timeout
           : DEFAULT_BATCH_TIMEOUT_MS;
     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().
+    this.serverClockOffsetMs = null;
     this.strictModeDocumentId = null;
     // Set to a DocumentLockLost while a `documents.locked()` block's keep-alive
     // has failed. Every write throws it until the block exits; see
@@ -251,6 +264,17 @@ class PlaidClient {
     this._installResources();
   }
 
+  /**
+   * 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
+   * audit entry's `ts`, against this rather than `Date.now()`: a browser
+   * clock can be minutes off.
+   * @returns {Date}
+   */
+  serverNow() {
+    return new Date(Date.now() + (this.serverClockOffsetMs ?? 0));
+  }
+
   /**
    * The API bundles (`client.documents`, `client.tokens`, ...). Installed on
    * the client, and again on every batch it opens (see `batch()`): a batch is
@@ -1773,7 +1797,11 @@ class PlaidClient {
       checkLock: (documentId) =>
         this._request("GET", `/api/v1/documents/${documentId}/lock`),
       /**
-       * Acquire or refresh a document lock.
+       * Acquire a document lock as a new holder.
+       *
+       * The answer's `lockId` names the holder: `renewLock` and `releaseLock`
+       * take it. While the lock is held, a second acquire is refused with
+       * HTTP 423, whoever makes it, this user included.
        *
        * 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
@@ -1788,13 +1816,30 @@ class PlaidClient {
           outOfBand: true,
         }),
       /**
-       * Release a document lock. outOfBand, for the same reason as
+       * Renew the lock `lockId` holds while it is live. HTTP 423 if another
+       * holder has it, and also once it has expired or been dropped, even when
+       * nobody holds the document now: a renewal never takes a free document.
+       * outOfBand, for the same reason as acquireLock.
+       * @param {string} documentId - The document ID
+       * @param {string} lockId - The `lockId` acquireLock answered with
+       */
+      renewLock: (documentId, lockId, auditMessage) =>
+        this._request("POST", `/api/v1/documents/${documentId}/lock`, {
+          queryParams: { "lock-id": lockId },
+          auditMessage,
+          outOfBand: true,
+        }),
+      /**
+       * Release the lock `lockId` holds. Idempotent: a lock that holder no
+       * longer has is left alone. outOfBand, for the same reason as
        * acquireLock: queued, the lock would be held until the batch submits,
        * and not released at all if it aborts.
        * @param {string} documentId - The document ID
+       * @param {string} lockId - The `lockId` acquireLock answered with
        */
-      releaseLock: (documentId, auditMessage) =>
+      releaseLock: (documentId, lockId, auditMessage) =>
         this._request("DELETE", `/api/v1/documents/${documentId}/lock`, {
+          queryParams: { "lock-id": lockId },
           auditMessage,
           outOfBand: true,
         }),
@@ -1812,9 +1857,9 @@ class PlaidClient {
        * tokenizer that deletes and recreates a document's tokens, spans and
        * relations. A single atomic call does not need it. While the lock is
        * held, writes to the document by ANOTHER user are refused with HTTP
-       * 423; the holder's own writes pass and renew it. If another user
-       * already holds it this rejects with a readable 423 and `fn` does not
-       * run.
+       * 423; the holder's own writes pass and renew it. If anyone already
+       * holds it, another block of this same user included, this rejects with
+       * a readable 423 and `fn` does not run.
        *
        * The lock is renewed for as long as `fn` runs, so work that computes
        * for minutes before it writes holds the lock the whole time rather than
@@ -1824,11 +1869,13 @@ class PlaidClient {
        * success. `fn` receives a lock handle and may read `lock.lost` (or call
        * `lock.raiseIfLost()`) to give up sooner.
        *
-       * NOT re-entrant: nesting two `locked()` blocks on one document would
-       * release on the inner exit and leave the outer unprotected. Lock at
-       * exactly one level per call path. 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.
+       * 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
+       * 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.
        * @param {string} documentId - The document ID
        * @param {(lock: DocumentLock) => any} fn - The work to run while holding it
        * @param {object} [options] - `{ keepAlive }`: renew on a timer (default true)
@@ -2809,7 +2856,7 @@ class PlaidClient {
        * @param {number} [timeout=10000] - Timeout in ms
        * @param {function} [onProgress] - Called with each progress payload {percent, message}
        * @param {AbortSignal} [signal] - Abort to stop waiting; rejects with an AbortError
-       * @param {Object} [opts] - {requestId, onAccepted, projectIds}
+       * @param {Object} [opts] - {requestId, onAccepted, projectIds, noOperation}
        * @returns {Promise<any>} The service's result
        */
       requestService: (
@@ -3125,6 +3172,100 @@ class PlaidClient {
         ),
     };
 
+    this.events = {
+      /**
+       * Record one research-telemetry event (core manual, "Research
+       * telemetry"). Fire and forget: the event is buffered and sent with
+       * others every ten seconds, at fifty events, and when the page is
+       * hidden. A batch that fails is dropped, nothing is retried, and
+       * nothing is ever thrown. Sends nothing for a project whose switch
+       * (`config.plaid.research.telemetry`) is off, which it reads from the
+       * project itself. `suggestion.shown` is recorded once per target,
+       * field and value in a page session.
+       * @param {'suggestion.shown'|'suggestion.adopted'|'suggestion.dismissed'|'plan.opened'} type - The event type
+       * @param {object} fields
+       * @param {string} fields.projectId - The project it happened in
+       * @param {string} [fields.documentId] - The document it happened in
+       * @param {string} [fields.targetId] - What it is about: a token, a plan
+       * @param {object} [fields.data] - Its details, keyed by single lowercase words (`value`, `source`, `field`, `written`, `conversation`)
+       * @returns {boolean} Whether the event was buffered
+       */
+      record: (type, fields) => recorderFor(this).record(this, type, fields),
+      /**
+       * Send what the recorder holds now, rather than at its next interval.
+       */
+      flush: () => recorderFor(this).flush(),
+      /**
+       * Tell the recorder a project's switch at once, e.g. right after a
+       * maintainer changed it. Turning it off drops what is buffered.
+       * @param {string} projectId - The project
+       * @param {boolean} on - Whether telemetry is on
+       */
+      setEnabled: (projectId, on) => recorderFor(this).setEnabled(projectId, on),
+      /**
+       * Record events directly, with no buffering. Requires write access, and
+       * the server refuses with a 403 while the project's switch is off. All
+       * or nothing: one bad event refuses the request with a 400 naming it.
+       * @param {string} projectId - The project the events happened in
+       * @param {Array<{type: string, documentId?: string, targetId?: string, data?: object, clientTs?: string}>} events - At most 500 events
+       * @returns {Promise<{count: number}>}
+       */
+      create: (projectId, events) =>
+        this._request("POST", `/api/v1/projects/${projectId}/events`, {
+          body: events,
+          outOfBand: true,
+        }),
+      /**
+       * A project's events in arrival order. Maintainer or admin only.
+       * Transparently follows pagination cursors and returns the full flat
+       * array.
+       * @param {string} projectId - The project to read
+       * @param {object} [filters]
+       * @param {string|string[]} [filters.types] - Only these types
+       * @param {string} [filters.startTime] - Only events the server stamped at or after this instant
+       * @param {string} [filters.endTime] - Only events the server stamped at or before this instant
+       */
+      list: (projectId, { types, startTime, endTime } = {}) =>
+        listAll(this, `/api/v1/projects/${projectId}/events`, {
+          query: eventQuery(types, startTime, endTime),
+        }),
+      /**
+       * One page of a project's events. Maintainer or admin only.
+       * @param {string} projectId - The project to read
+       * @param {object} [opts]
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @param {string|string[]} [opts.types] - Only these types
+       * @param {string} [opts.startTime] - Only events at or after this instant
+       * @param {string} [opts.endTime] - Only events at or before this instant
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      listPage: (
+        projectId,
+        { limit, cursor, types, startTime, endTime } = {},
+      ) =>
+        listPage(this, `/api/v1/projects/${projectId}/events`, {
+          limit,
+          cursor,
+          query: eventQuery(types, startTime, endTime),
+        }),
+      /**
+       * Async-iterate a project's events page by page; yields each page's entries array.
+       * @param {string} projectId - The project to read
+       * @param {object} [opts]
+       * @param {number} [opts.pageSize] - Per-request page size
+       * @param {string|string[]} [opts.types] - Only these types
+       * @param {string} [opts.startTime] - Only events at or after this instant
+       * @param {string} [opts.endTime] - Only events at or before this instant
+       * @returns {AsyncGenerator<Array>}
+       */
+      iterPages: (projectId, { pageSize, types, startTime, endTime } = {}) =>
+        iterPages(this, `/api/v1/projects/${projectId}/events`, {
+          pageSize,
+          query: eventQuery(types, startTime, endTime),
+        }),
+    };
+
     this.guidelines = {
       /**
        * Create a guideline in a project. `title` is the handle an assistant
@@ -3271,11 +3412,19 @@ class PlaidClient {
    * control), and neither does a broadcast message (`messages.sendMessage`):
    * none of them is audited, so there would be nothing under the label.
    *
+   * `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.
+   *
    * @param {string} message - Human label for the operation.
-   * @param {object} [opts] - Optional `{ id }`: adopt an existing group id instead of minting one (a service joining the requester's operation; `requestService` propagates an open operation to the service automatically).
+   * @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.
    * @returns {string} The operation's group id.
    */
-  beginOperation(message, { id } = {}) {
+  beginOperation(message, { id, kind, ref } = {}) {
     if (this.operationGroup) {
       this.operationGroup.depth += 1;
       return this.operationGroup.id;
@@ -3283,6 +3432,8 @@ class PlaidClient {
     this.operationGroup = {
       id: id || crypto.randomUUID(),
       message: message == null ? null : String(message),
+      kind: kind == null ? null : String(kind),
+      ref: ref == null ? null : String(ref),
       depth: 1,
       written: false,
       refined: undefined,
@@ -3329,12 +3480,17 @@ class PlaidClient {
    *     setMessage(`Merged ${n} morphemes`);
    *   });
    *
+   * The kind and reference (see beginOperation) come after `fn`:
+   *
+   *   await client.withOperation('Import ELAN corpus', run, { kind: 'import', ref: 'format:elan' });
+   *
    * @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.
    * @returns {Promise<any>} Whatever `fn` resolves to.
    */
-  async withOperation(message, fn) {
-    this.beginOperation(message);
+  async withOperation(message, fn, { kind, ref } = {}) {
+    this.beginOperation(message, { kind, ref });
     const group = this.operationGroup;
     const setMessage = (msg) => {
       if (group.depth === 1) group.refined = msg;
@@ -3659,6 +3815,9 @@ export {
 // request, and `critical()` holds that off around writes. See ./services.js
 // and the manual, "Stopping a request".
 export { ServiceCancelled, createCancelScope } from "./services.js";
+// Who asked for a service run, named in its History label and in what it
+// stores. See ./requester.js.
+export { REQUESTED_BY, makeRequester, requesterOf } from "./requester.js";
 // 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.

package/src/provenance.js

@@ -78,7 +78,11 @@
  *   - valueProbs / formProbs: a top-k {label: probability} map over the
  *     alternatives the producer considered, the chosen label included
  *     (provProb, when given, is that label's entry duplicated flat).
- *   - model, and anything else (language, adapter, raw scores).
+ *   - model: what made the prediction (a model name, or a tool and its
+ *     release such as 'stanza==1.11.0'), and version: which version of the
+ *     writer ran ('<release>+<8 hex>', see the manual, "Provenance"). Every
+ *     machine writer records both, one of rules alone only version.
+ *   - anything else (language, adapter, raw scores).
  */
 
 /** The flat metadata keys of the provenance convention. */

package/src/requester.js

@@ -0,0 +1,56 @@
+// Who asked for a service run, named in what the run leaves behind.
+//
+// A plain service writes with its own token, so the History entry of a run
+// reads "by <operator> (via <token>)" and the person who pressed the button is
+// recorded nowhere. Core tells every service who asked (`requesterId` in the
+// request data), and every app's services put that person in the History
+// label and in what they store:
+//
+//   AnCast adjudication against lunch, requested by second
+//
+// This is the JS twin of `plaid_client.workflows.requester`, for a service
+// authored with `serve`. The wording and the stored key are the same.
+//
+// The name is the requester's display name, which any signed-in user may
+// read. When it cannot be read the id stands in for it, and with no requester
+// at all the label is left as it was and nothing is stored.
+
+/** The key a run's stored record names its requester under. */
+export const REQUESTED_BY = "requestedBy";
+
+/**
+ * The person who asked for one run: `id` is their account (their email),
+ * `name` how they are shown. Both are null when nobody asked.
+ */
+export function makeRequester(id = null, name = null) {
+  return {
+    id,
+    name,
+    /** A History label with the requester named, or `text` when nobody asked. */
+    label: (text) => (name ? `${text}, requested by ${name}` : text),
+    /** `{ id, name }` for a stored report, or null when nobody asked. */
+    record: () => (id ? { id, name } : null),
+    /** A machine stamp's `provDetail` with the requester's id added. */
+    detail: (detail = {}) => ({ ...(detail || {}), ...(id ? { [REQUESTED_BY]: id } : {}) }),
+  };
+}
+
+/**
+ * The requester of one request, from the `requesterId` core put in its data,
+ * with their display name read through `client`.
+ * @param {object} client - A PlaidClient (only `users.get` is used)
+ * @param {object} data - The request data a `serve` handler receives
+ */
+export async function requesterOf(client, data) {
+  const id = data && typeof data === "object" ? data.requesterId || null : null;
+  if (!id) return makeRequester();
+  let name = null;
+  try {
+    name = (await client.users.get(id))?.displayName || null;
+  } catch (error) {
+    // The id is always there to fall back on, so a failed read costs the
+    // label nothing but the nicer name.
+    console.warn(`Could not read the requester ${id}: ${error?.message || error}`);
+  }
+  return makeRequester(id, name || id);
+}

package/src/services.js

@@ -402,6 +402,8 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
  * @param {string[]} [opts.projectIds] - Other projects the request is about, beside
  *   `projectId`. A delegating service's token is scoped to `projectId` and to those of
  *   these the requester can read, and reaches nothing else
+ * @param {boolean} [opts.noOperation] - Carry no open operation: the service's writes
+ *   are a group of their own, not part of whatever operation this client has open
  * @returns {Promise<any>} The service's result
  */
 export function requestService(client, projectId, serviceId, data, timeout = 10000, onProgress, signal, opts = {}) {
@@ -410,10 +412,26 @@ export function requestService(client, projectId, serviceId, data, timeout = 100
   // (the Python BaseService adopts the id around process_request). Only for a
   // plain-object payload — that's the only shape the service param schema
   // delivers anyway.
-  const group = client.operationGroup;
+  // Its kind and reference go too, so a service that writes before the
+  // requester does still records them.
+  //
+  // `opts.noOperation` sends none: the service starts a group of its own. For
+  // a request that is its own action whatever else is on the wire, such as
+  // approving an assistant's plan or starting a service run. The client holds
+  // one open operation, so without it an edit still saving at that moment
+  // would take in every write the request makes, under the edit's kind.
+  const group = opts.noOperation ? null : client.operationGroup;
   const payload =
     group && data && typeof data === 'object' && !Array.isArray(data)
-      ? { ...data, operationGroup: { id: group.id, message: group.message } }
+      ? {
+          ...data,
+          operationGroup: {
+            id: group.id,
+            message: group.message,
+            ...(group.kind ? { kind: group.kind } : {}),
+            ...(group.ref ? { ref: group.ref } : {}),
+          },
+        }
       : data;
   const query = new URLSearchParams();
   if (opts.requestId) query.set('request-id', opts.requestId);