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

package/src/metadataOps.js

@@ -0,0 +1,117 @@
+/**
+ * Metadata ops: the body of every metadata PATCH, and the `metadata` of a
+ * bulk update entry. An op is `{op: 'set', path, value}` or
+ * `{op: 'delete', path}`, where `path` is a non-empty array of keys into the
+ * nested metadata, the first a top-level key. See the manual, "Metadata".
+ */
+
+import { PLAID_NAMESPACE } from './roles.js';
+import { PROVENANCE_KEYS } from './provenance.js';
+
+const RESERVED_KEYS = new Set([PLAID_NAMESPACE, ...PROVENANCE_KEYS]);
+
+/**
+ * True for a top-level metadata key Plaid keeps for itself: the shared `plaid`
+ * namespace (settings every app reads, such as the text direction) and the
+ * provenance keys. Neither is ever a user's metadata field, so an app neither
+ * lists it as one nor writes a field's value to it.
+ * @param {string} key
+ * @returns {boolean}
+ */
+export const isReservedMetadataKey = (key) => RESERVED_KEYS.has(key);
+
+// The longest top-level key the server takes, in UTF-16 code units (Java's
+// String length, which is what it counts).
+const MAX_KEY_LENGTH = 200;
+
+// Java's Character.isWhitespace, which the server's blank check uses: the
+// Unicode space separators except the three no-break spaces, and the ASCII
+// whitespace controls.
+const isJavaWhitespace = (c) =>
+  (/[\p{Zs}\p{Zl}\p{Zp}]/u.test(c) && c !== '\u00A0' && c !== '\u2007' && c !== '\u202F') ||
+  /[\t\n\u000B\f\r\u001C-\u001F]/.test(c);
+
+/**
+ * True when the server accepts `k` as a top-level metadata key: not blank,
+ * at most 200 UTF-16 code units, and no ASCII control character.
+ * @param {string} k
+ * @returns {boolean}
+ */
+const validMetadataKey = (k) =>
+  typeof k === 'string' &&
+  k.length <= MAX_KEY_LENGTH &&
+  !/[\u0000-\u001F\u007F]/.test(k) &&
+  ![...k].every(isJavaWhitespace);
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * The ops that set each top-level key of `fragment`, deleting a key whose
+ * value is null. This is how a provenance fragment (verifyOnEdit,
+ * contributeOnEdit, ...) is sent as a patch.
+ * @param {Object|null|undefined} fragment
+ * @returns {Array<{op: string, path: string[], value?: any}>}
+ */
+export const metadataOps = (fragment) =>
+  Object.entries(fragment || {}).map(([k, v]) =>
+    v === null ? { op: 'delete', path: [k] } : { op: 'set', path: [k], value: v },
+  );
+
+const applyOp = (node, path, depth, o) => {
+  const [k, ...more] = path.slice(depth);
+  if (more.length === 0) {
+    const out = { ...node };
+    if (o.op === 'set') out[k] = o.value;
+    else delete out[k];
+    return out;
+  }
+  const child = Object.prototype.hasOwnProperty.call(node, k) ? node[k] : undefined;
+  if (child === undefined) {
+    return o.op === 'set' ? { ...node, [k]: applyOp({}, path, depth + 1, o) } : node;
+  }
+  if (!isObject(child)) {
+    throw new Error(
+      `Metadata path ${JSON.stringify(path.slice(0, depth + 1))} holds a value that is not an object`,
+    );
+  }
+  return { ...node, [k]: applyOp(child, path, depth + 1, 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).
+ * @param {Object|null|undefined} metadata
+ * @param {Array<{op: string, path: string[], value?: any}>} ops
+ * @returns {Object}
+ */
+export const applyMetadataOps = (metadata, ops) =>
+  (ops || []).reduce((m, o) => {
+    if (!Array.isArray(o.path) || o.path.length === 0) {
+      throw new Error('A metadata op needs a non-empty path');
+    }
+    if (!validMetadataKey(o.path[0])) {
+      throw new Error('Invalid metadata key');
+    }
+    if (o.op !== 'set' && o.op !== 'delete') {
+      throw new Error(`Unknown metadata op '${o.op}': expected set or delete`);
+    }
+    if (o.op === 'set' && !('value' in o)) {
+      throw new Error('A set op needs a value');
+    }
+    return applyOp(m, o.path, 0, o);
+  }, { ...(metadata || {}) });
+
+/**
+ * Merge a top-level fragment into a local copy, a null value deleting the
+ * key: applyMetadataOps over metadataOps(fragment), so the same result as
+ * sending those ops, refused where the server would refuse them. How an app
+ * mirrors a provenance stamp (verifyOnEdit, contributeOnEdit, ...) on the row
+ * it shows. Returns a new object.
+ * @param {Object|null|undefined} metadata
+ * @param {Object|null|undefined} fragment
+ * @returns {Object}
+ */
+export const mergeMetadata = (metadata, fragment) =>
+  applyMetadataOps(metadata, metadataOps(fragment));

package/src/pagination.js

@@ -10,6 +10,10 @@
  * Each helper threads the client through to `client._request`, so auth
  * headers, base URL, and response transforms all apply exactly as for any
  * other request.
+ *
+ * A page is a read, so it goes over the wire even when the helper is handed a
+ * batch (see the note at the top of http.js): each page is answered from the
+ * pool, in order, against the state no batch has committed yet.
  */
 
 // Merge caller query params with paging params, dropping undefined/null so we
@@ -21,16 +25,23 @@ function buildQueryParams(query, limit, cursor) {
   return params;
 }
 
+// Every collection endpoint answers with the envelope. A bare array or any
+// other shape is a broken endpoint, so name it and stop rather than return a
+// silently truncated result.
+function entriesOf(response, path) {
+  if (!response || !Array.isArray(response.entries)) {
+    throw new Error(
+      `GET ${path} did not return a paginated envelope (no 'entries' array)`,
+    );
+  }
+  return response.entries;
+}
+
 /**
  * Fetch every page and return the full flat array of entries, transparently
  * following `nextCursor` until it is null. This is what `.list()` calls so it
  * stays backward compatible with the pre-pagination (bare-array) contract.
  *
- * NOTE: This auto-paginates and therefore CANNOT be used inside a batch — each
- * page's request needs the previous page's `nextCursor`, which doesn't exist
- * until the batch executes. It throws immediately when `client.isBatching` is
- * true. Use `listPage` for a single page inside a batch.
- *
  * @param {object} client - PlaidClient instance
  * @param {string} path - API path, e.g. '/api/v1/projects'
  * @param {object} [opts]
@@ -39,11 +50,6 @@ function buildQueryParams(query, limit, cursor) {
  * @returns {Promise<Array>} The concatenated entries across all pages
  */
 export async function listAll(client, path, { pageSize = 1000, query = {} } = {}) {
-  if (client.isBatching) {
-    throw new Error(
-      `Cannot auto-paginate ${path} inside a batch: list methods follow cursors across multiple requests, which a batch cannot do. Use listPage() for a single page inside a batch, or call list() outside the batch.`,
-    );
-  }
   const all = [];
   let cursor = null;
   let prevCursor;
@@ -51,19 +57,7 @@ export async function listAll(client, path, { pageSize = 1000, query = {} } = {}
     const response = await client._request('GET', path, {
       queryParams: buildQueryParams(query, pageSize, cursor),
     });
-    // Compatibility shim: a non-paginated server (or proxy) may return a bare
-    // array. Treat it as a terminal full result with no further paging.
-    if (Array.isArray(response)) {
-      all.push(...response);
-      break;
-    }
-    if (response && Array.isArray(response.entries)) {
-      all.push(...response.entries);
-    } else {
-      throw new Error(
-        "Unexpected list response shape (no 'entries'); server may be incompatible.",
-      );
-    }
+    all.push(...entriesOf(response, path));
     prevCursor = cursor;
     cursor = response.nextCursor;
     // Guard against a buggy server/proxy that returns a constant non-null
@@ -98,11 +92,6 @@ export async function listPage(client, path, { limit, cursor, query = {} } = {})
  * Async generator yielding each page's entries array in turn, following
  * `nextCursor` until it is null.
  *
- * NOTE: This auto-paginates and therefore CANNOT be used inside a batch — each
- * page's request needs the previous page's `nextCursor`, which doesn't exist
- * until the batch executes. It throws on first iteration when
- * `client.isBatching` is true. Use `listPage` for a single page inside a batch.
- *
  * @param {object} client - PlaidClient instance
  * @param {string} path - API path
  * @param {object} [opts]
@@ -111,18 +100,13 @@ export async function listPage(client, path, { limit, cursor, query = {} } = {})
  * @yields {Array} The entries array for each page
  */
 export async function* iterPages(client, path, { pageSize = 1000, query = {} } = {}) {
-  if (client.isBatching) {
-    throw new Error(
-      `Cannot auto-paginate ${path} inside a batch: list methods follow cursors across multiple requests, which a batch cannot do. Use listPage() for a single page inside a batch, or call list() outside the batch.`,
-    );
-  }
   let cursor = null;
   let prevCursor;
   do {
     const response = await client._request('GET', path, {
       queryParams: buildQueryParams(query, pageSize, cursor),
     });
-    const entries = (response && Array.isArray(response.entries)) ? response.entries : [];
+    const entries = entriesOf(response, path);
     // Suppress the trailing empty page that the server emits when a collection's
     // size is an exact multiple of the page size (a final full page with a
     // non-null cursor, then an empty page). Still follow the cursor below.
@@ -130,7 +114,7 @@ export async function* iterPages(client, path, { pageSize = 1000, query = {} } =
       yield entries;
     }
     prevCursor = cursor;
-    cursor = response ? response.nextCursor : null;
+    cursor = response.nextCursor;
     // Guard against a buggy server/proxy that returns a constant non-null
     // cursor, which would otherwise loop forever.
     if (cursor !== null && cursor !== undefined && cursor === prevCursor) {

package/src/provenance.js

@@ -5,28 +5,53 @@
  * Flat scalar keys — the query engine matches flat metadata well, nested
  * objects poorly.
  *
- * Three states (the PRESENCE of the `prov` key, not its value, is the
- * discriminator; absent keys mean "human"):
+ * Two axes. ORIGIN is the `prov` key: absent means a trusted person (a
+ * verifier) made it; 'inferred' means an algorithm or service did;
+ * 'contributed' means a person whose work the project reviews (a
+ * contributor) did. TRUST is `provConfirmed`: true once a verifier vouched
+ * for the value. Together they give four states:
  *
- *   human              — no prov keys; a person made it.
+ *   human              — no prov keys; a verifier made it.
  *   machine            — { prov: 'inferred', provSource: '<producer>' };
- *                        an algorithm/service made it, no human has vouched.
- *   verified           — same + { provConfirmed: true }; machine-made and a
- *                        human confirmed (or edited) it. provSource stays so
- *                        machine origin remains traceable.
+ *                        an algorithm/service made it, nobody has vouched.
+ *   contributed        — { prov: 'contributed', provSource: 'user:<id>' };
+ *                        a contributor made it, no verifier has vouched.
+ *   verified           — either origin + { provConfirmed: true }; a verifier
+ *                        confirmed (or edited) it. prov/provSource stay so
+ *                        the origin remains traceable.
  *
  * The write contract every machine writer must follow:
  *   1. Machine writers may freely replace MACHINE (unverified) material.
- *   2. Machine writers must never modify or delete human or verified
- *      material unless explicitly told to overwrite (an explicit, per-run,
- *      user-facing opt-in — for services, a declared boolean `overwrite`
- *      parameter).
- *   3. Any human edit of a machine annotation verifies it: the edit also
- *      stamps { provConfirmed: true } (see verifyOnEdit).
+ *   2. Machine writers must never modify or delete human, contributed or
+ *      verified material unless explicitly told to overwrite (an explicit,
+ *      per-run, user-facing opt-in — for services, a declared boolean
+ *      `overwrite` parameter). A contributor's work is a person's work.
+ *   3. A verifier's edit of machine or contributed material verifies it:
+ *      the edit also stamps { provConfirmed: true } (see verifyOnEdit).
+ *      A contributor's edit of anything marks it contributed: the edit
+ *      merges stampContributed(userId) and drops any earlier confirmation
+ *      (see contributeOnEdit). Who is a contributor is the PROJECT's call,
+ *      recorded once for every app (see "Review" below); a service running
+ *      as a contributor should stamp likewise.
+ *
+ * REVIEW: which people are contributors. A project records it under the
+ * reserved `plaid` config namespace, so every app that writes on a person's
+ * behalf reads the same answer:
+ *
+ *   config.plaid.review = { users: [userId, ...], roles: ['writer', ...] }
+ *
+ * `users` names people whose work is reviewed whatever their role; `roles`
+ * names whole project roles ('reader' | 'writer' | 'maintainer'; an admin
+ * without an explicit role counts as a maintainer). Either may be absent.
+ * Nothing here grants or denies access: the ACL lists stay the permission
+ * model, and this only says whose work needs a verifier's look. Apps expose
+ * it as a per-member mark on their access screens (readReview, isReviewed,
+ * withReviewedUser) and derive the writer's policy from it (writerPolicy).
  *
  * Producer naming: 'service:<serviceId>' for services (use serviceSource),
- * 'rule:<name>' for built-in rule algorithms, app-specific ids like
- * 'gloss:doc-frequency' or 'flex-import' otherwise.
+ * 'rule:<name>' for built-in rule algorithms, 'user:<userId>' for a
+ * contributor (use userSource), app-specific ids like 'gloss:doc-frequency'
+ * or 'flex-import' otherwise.
  *
  * PREDICTION EXTRAS. A producer may also record how confident it was and
  * what else it considered, in two reserved slots split along the
@@ -43,6 +68,21 @@
  * human edits (history is valuable), so a consumer must not present
  * provProb as confidence in the CURRENT value once the entity is verified
  * (provConfirmed is exactly the flag to check).
+ *
+ * Recommended provDetail keys, so consumers (review dashboards, ranked
+ * alternatives) can read any producer's output:
+ *   - value (spans) / form (morpheme tokens): the value the producer
+ *     wrote, mirroring the entity's own field. The entity may be edited
+ *     later; this copy is what makes "accepted as-is" vs "corrected"
+ *     answerable once the entity is verified.
+ *   - 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: 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. */
@@ -57,14 +97,36 @@ export const PROV = Object.freeze({
   probKey: 'provProb',
   /** Open map of producer extras (alternatives, model version, raw scores). */
   detailKey: 'provDetail',
-  /** The (currently only) value of `prov`. Presence, not value, decides. */
+  /** `prov` for machine-made material. Any value but CONTRIBUTED reads as machine. */
   INFERRED: 'inferred',
+  /** `prov` for a contributor's material. */
+  CONTRIBUTED: 'contributed',
 });
 
-/** The three provenance states returned by provState. */
+/**
+ * Every provenance key, for a caller that has to name them as a set rather
+ * than read one: what a token layer declares under
+ * `config.plaid.preserveOnSplit` so a token born of a split inherits the
+ * origin of the token it came from, and what a reshape carries by hand.
+ *
+ * Provenance is the one metadata family Plaid itself owns. The user cannot
+ * maintain it, and in a shared project usually cannot even see it, since it
+ * may belong to an app they are not using. Everything else on an entity is
+ * the user's own content and no structural operation should touch it.
+ */
+export const PROVENANCE_KEYS = Object.freeze([
+  PROV.key,
+  PROV.sourceKey,
+  PROV.confirmedKey,
+  PROV.probKey,
+  PROV.detailKey,
+]);
+
+/** The four provenance states returned by provState. */
 export const PROV_STATES = Object.freeze({
   HUMAN: 'human',
   MACHINE: 'machine',
+  CONTRIBUTED: 'contributed',
   VERIFIED: 'verified',
 });
 
@@ -105,35 +167,214 @@ export const confirmedInferred = (source, extras = {}) => ({
  */
 export const PROV_CONFIRMED = Object.freeze({ [PROV.confirmedKey]: true });
 
+/**
+ * The metadata fragment a contributor's work carries:
+ * { prov: 'contributed', provSource: 'user:<userId>' }.
+ * @param {string} userId
+ */
+export const stampContributed = (userId) => ({
+  [PROV.key]: PROV.CONTRIBUTED,
+  [PROV.sourceKey]: userSource(userId),
+});
+
 /**
  * Classify an entity's metadata into one of PROV_STATES.
  * @param {Object|null|undefined} metadata
- * @returns {'human'|'machine'|'verified'}
+ * @returns {'human'|'machine'|'contributed'|'verified'}
  */
 export const provState = (metadata) => {
   if (!metadata || metadata[PROV.key] == null) return PROV_STATES.HUMAN;
-  return metadata[PROV.confirmedKey] ? PROV_STATES.VERIFIED : PROV_STATES.MACHINE;
+  if (metadata[PROV.confirmedKey]) return PROV_STATES.VERIFIED;
+  return metadata[PROV.key] === PROV.CONTRIBUTED ? PROV_STATES.CONTRIBUTED : PROV_STATES.MACHINE;
 };
 
 /**
- * Whether this entity is machine-made and not yet human-verified — the
- * material that still needs review, that machine writers may replace, and
- * that a human confirmation gesture acts on. Complement of isProtected.
+ * Where an entity came from, confirmed or not: null for a verifier's own
+ * work, PROV.INFERRED for a machine's, PROV.CONTRIBUTED for a contributor's.
+ * What a verified entity's tooltip needs, since provState folds both
+ * origins into 'verified'.
+ * @returns {null|'inferred'|'contributed'}
+ */
+export const provOrigin = (metadata) => {
+  if (!metadata || metadata[PROV.key] == null) return null;
+  return metadata[PROV.key] === PROV.CONTRIBUTED ? PROV.CONTRIBUTED : PROV.INFERRED;
+};
+
+/**
+ * Whether this entity is machine-made and not yet verified — the material
+ * machine writers may replace. Complement of isProtected.
  */
 export const isMachine = (metadata) => provState(metadata) === PROV_STATES.MACHINE;
 
 /**
  * Whether a machine writer must leave this entity alone (write-contract
- * rule 2): true for human-made and human-verified material.
+ * rule 2): true for human-made, contributed and verified material.
  */
 export const isProtected = (metadata) => !isMachine(metadata);
 
 /**
- * The metadata fragment a HUMAN edit of this entity should merge in
- * (write-contract rule 3): PROV_CONFIRMED when the entity is machine-made
- * and unverified, else null (nothing to do).
+ * Whether a verifier still has to look at this entity: machine-made or
+ * contributed, and not yet confirmed. What review UIs mark and sweep, and
+ * what a verifier's confirmation gesture acts on.
+ */
+export const needsReview = (metadata) => {
+  const s = provState(metadata);
+  return s === PROV_STATES.MACHINE || s === PROV_STATES.CONTRIBUTED;
+};
+
+/**
+ * The metadata fragment a VERIFIER's edit of this entity should merge in
+ * (write-contract rule 3): PROV_CONFIRMED when the entity needs review,
+ * else null (nothing to do).
+ */
+export const verifyOnEdit = (metadata) => (needsReview(metadata) ? PROV_CONFIRMED : null);
+
+/**
+ * The metadata fragment a CONTRIBUTOR's edit of this entity should merge in
+ * (write-contract rule 3): the contributed stamp, plus provConfirmed: null
+ * so an earlier confirmation is dropped (send it with metadataOps, which
+ * turns a null into a delete, or apply it locally with mergeMetadata). Prediction extras a machine
+ * recorded stay, as history.
+ * @param {Object|null|undefined} metadata - unused today; the fragment is
+ *   the same whatever the entity was, and the parameter keeps the shape of
+ *   verifyOnEdit so callers can swap one for the other
+ * @param {string} userId
  */
-export const verifyOnEdit = (metadata) => (isMachine(metadata) ? PROV_CONFIRMED : null);
+// eslint-disable-next-line no-unused-vars
+export const contributeOnEdit = (metadata, userId) => ({
+  ...stampContributed(userId),
+  [PROV.confirmedKey]: null,
+});
 
 /** Canonical provSource for a service: 'service:<serviceId>'. */
 export const serviceSource = (serviceId) => `service:${serviceId}`;
+
+/** Canonical provSource for a contributor: 'user:<userId>'. */
+export const userSource = (userId) => `user:${userId}`;
+
+// ---- 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 = Object.freeze(['reader', 'writer', 'maintainer']);
+
+/**
+ * The project's review lists, normalized: { users: string[], roles: string[] }.
+ * @param {Object|null|undefined} config - a project's `config`
+ */
+export const readReview = (config) => {
+  const raw = config?.plaid?.[REVIEW_KEY];
+  const list = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
+  return { users: list(raw?.users), roles: list(raw?.roles) };
+};
+
+/**
+ * A person's role in a project from its ACL lists: 'maintainer' | 'writer' |
+ * 'reader' | null. An admin with no explicit entry is a maintainer, as the
+ * permission model treats them.
+ * @param {Object} project - with `maintainers`, `writers`, `readers`
+ * @param {string} userId
+ * @param {Object} [opts]
+ * @param {boolean} [opts.isAdmin]
+ */
+export const projectRole = (project, userId, { isAdmin = false } = {}) => {
+  const inList = (l) => Array.isArray(l) && userId != null && l.includes(userId);
+  if (inList(project?.maintainers)) return 'maintainer';
+  if (inList(project?.writers)) return 'writer';
+  if (inList(project?.readers)) return 'reader';
+  return isAdmin ? 'maintainer' : null;
+};
+
+/**
+ * Whether this person's work is reviewed in this project: named in
+ * review.users, or holding a role named in review.roles.
+ */
+export const isReviewed = (project, userId, { isAdmin = false } = {}) => {
+  if (!project || userId == null) return false;
+  const { users, roles } = readReview(project.config);
+  if (users.includes(userId)) return true;
+  const role = projectRole(project, userId, { isAdmin });
+  return role != null && roles.includes(role);
+};
+
+/**
+ * The review lists with one person added to or removed from `users`
+ * (`roles` untouched). Pure; write the result with
+ * projects.setConfig(id, 'plaid', REVIEW_KEY, next).
+ */
+export const withReviewedUser = (review, userId, reviewed) => {
+  const { users, roles } = readReview({ plaid: { [REVIEW_KEY]: review } });
+  const next = users.filter((u) => u !== userId);
+  if (reviewed) next.push(userId);
+  return { users: next, roles };
+};
+
+// ---- the writer's policy: what a person's writes carry ----
+
+/**
+ * What one writer's writes carry and what their review gestures act on,
+ * given who they are: `contributorId` is their user id when their work is
+ * reviewed (isReviewed), else null for a verifier. Apps derive this once per
+ * document and route every human write through it, so the convention's
+ * rule 3 has one implementation.
+ *
+ * @param {string|null} contributorId
+ * @returns {{
+ *   contributorId: string|null,
+ *   isContributor: boolean,
+ *   createStamp: Object|null,
+ *   editStamp: (metadata: Object) => Object|null,
+ *   confirmStamp: (metadata: Object) => Object|null,
+ *   adoptStamp: (source: string, detail?: Object) => Object,
+ *   reviewable: (metadata: Object) => boolean,
+ *   reviewableState: (state: string) => boolean,
+ * }}
+ */
+export const writerPolicy = (contributorId = null) => {
+  const id = contributorId || null;
+  const contributor = id != null;
+  // Material this writer's review gestures act on: a verifier reviews
+  // machine and contributed material; a contributor reviews machine
+  // proposals only, since their own vouching is itself a contribution.
+  const reviewable = (metadata) => (contributor ? isMachine(metadata) : needsReview(metadata));
+  const reviewableState = (state) =>
+    contributor
+      ? state === PROV_STATES.MACHINE
+      : state === PROV_STATES.MACHINE || state === PROV_STATES.CONTRIBUTED;
+  return Object.freeze({
+    contributorId: id,
+    isContributor: contributor,
+    /** The metadata a NEW entity carries: null for a verifier. */
+    createStamp: contributor ? stampContributed(id) : null,
+    /**
+     * The fragment an EDIT merges over the entity's metadata, or null when
+     * there is nothing to merge: a verifier confirms what needs review; a
+     * contributor's edit marks the entity contributed, dropping any earlier
+     * confirmation.
+     */
+    editStamp: (metadata) => (contributor ? contributeOnEdit(metadata, id) : verifyOnEdit(metadata)),
+    /**
+     * The fragment an explicit confirm gesture merges, or null when there is
+     * nothing for this writer to confirm: PROV_CONFIRMED for a verifier, the
+     * contributed stamp for a contributor accepting a machine proposal.
+     */
+    confirmStamp: (metadata) => {
+      if (!reviewable(metadata)) return null;
+      return contributor ? contributeOnEdit(metadata, id) : PROV_CONFIRMED;
+    },
+    /**
+     * What an adopted suggestion is written with (a guess or a picked value
+     * into an empty cell): born-verified with the suggestion's producer as
+     * its source for a verifier; contributed for a contributor, with the
+     * producer kept as provDetail.guess. `detail` is the prediction extras.
+     */
+    adoptStamp: (source, detail) =>
+      contributor
+        ? { ...stampContributed(id), [PROV.detailKey]: { ...(detail || {}), guess: source } }
+        : confirmedInferred(source, { detail }),
+    reviewable,
+    reviewableState,
+  });
+};

package/src/replayed.js

@@ -0,0 +1,27 @@
+// A write sent under an Idempotency-Key whose request the server had already
+// run (its first answer was lost, and the client sent it again) is answered
+// from what that first send stored, with `Idempotent-Replayed: true`, and
+// writes nothing. The client resends on its own (retryUnknown), so the header
+// never reaches the caller. It is marked on the answer instead: `replayed`,
+// true and not enumerable, so the answer reads, compares and serializes as it
+// would unmarked. Only an answer with a JSON object or list body can carry it.
+// Imports nothing.
+
+/** `value` marked as replayed, when it is an object or a list. */
+export function markReplayed(value) {
+  if (value !== null && typeof value === "object") {
+    Object.defineProperty(value, "replayed", {
+      value: true,
+      enumerable: false,
+      configurable: true,
+    });
+  }
+  return value;
+}
+
+/** Whether a client answer was replayed from its key's first send. */
+export const wasReplayed = (answer) =>
+  answer !== null &&
+  typeof answer === "object" &&
+  Object.getOwnPropertyDescriptor(answer, "replayed")?.enumerable === false &&
+  answer.replayed === true;

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);
+}