@larc-iu/plaid-client 0.2.0-alpha.22 → 0.2.0-alpha.26

package/src/metadataOps.d.ts

@@ -0,0 +1,15 @@
+export function isReservedMetadataKey(key: string): boolean;
+export function metadataOps(fragment: object | null | undefined): MetadataOp[];
+export function applyMetadataOps(metadata: object | null | undefined, ops: MetadataOp[]): Record<string, any>;
+export function mergeMetadata(metadata: object | null | undefined, fragment: object | null | undefined): Record<string, any>;
+/**
+ * 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[];
+};

package/src/metadataOps.js

@@ -8,6 +8,11 @@
 import { PLAID_NAMESPACE } from './roles.js';
 import { PROVENANCE_KEYS } from './provenance.js';
 
+/**
+ * One metadata edit: the body of a metadata PATCH is a list of these.
+ * @typedef {{op: "set", path: string[], value: any} | {op: "delete", path: string[]}} MetadataOp
+ */
+
 const RESERVED_KEYS = new Set([PLAID_NAMESPACE, ...PROVENANCE_KEYS]);
 
 /**
@@ -49,8 +54,8 @@ 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}>}
+ * @param {object|null|undefined} fragment
+ * @returns {MetadataOp[]}
  */
 export const metadataOps = (fragment) =>
   Object.entries(fragment || {}).map(([k, v]) =>
@@ -84,9 +89,9 @@ const applyOp = (node, path, depth, o) => {
  * set or delete, a path through a non-object, or a first key that is blank,
  * over 200 characters or holds a control character. The server's caps on
  * depth, key count, string length and size are not checked here.
- * @param {Object|null|undefined} metadata
- * @param {Array<{op: string, path: string[], value?: any}>} ops
- * @returns {Object}
+ * @param {object|null|undefined} metadata
+ * @param {MetadataOp[]} ops
+ * @returns {Record<string, any>}
  */
 export const applyMetadataOps = (metadata, ops) =>
   (ops || []).reduce((m, o) => {
@@ -111,9 +116,9 @@ export const applyMetadataOps = (metadata, ops) =>
  * 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}
+ * @param {object|null|undefined} metadata
+ * @param {object|null|undefined} fragment
+ * @returns {Record<string, any>}
  */
 export const mergeMetadata = (metadata, fragment) =>
   applyMetadataOps(metadata, metadataOps(fragment));

package/src/pagination.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Fetch every page and return the full flat array of entries, transparently
+ * following `nextCursor` until it is null. This is what `.list()` calls.
+ *
+ * @param {object} client - PlaidClient instance
+ * @param {string} path - API path, e.g. '/api/v1/projects'
+ * @param {object} [opts]
+ * @param {number} [opts.pageSize=1000] - Per-request page size (limit)
+ * @param {object} [opts.query={}] - Extra query params (e.g. { 'as-of': asOf })
+ * @returns {Promise<Array>} The concatenated entries across all pages
+ */
+export function listAll(client: object, path: string, { pageSize, query }?: {
+    pageSize?: number;
+    query?: object;
+}): Promise<any[]>;
+/**
+ * Fetch a single page and return the raw envelope.
+ *
+ * @param {object} client - PlaidClient instance
+ * @param {string} path - API path
+ * @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 {object} [opts.query={}] - Extra query params
+ * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+ */
+export function listPage(client: object, path: string, { limit, cursor, query }?: {
+    limit?: number;
+    cursor?: string;
+    query?: object;
+}): Promise<{
+    entries: any[];
+    nextCursor: (string | null);
+}>;
+/**
+ * Async generator yielding each page's entries array in turn, following
+ * `nextCursor` until it is null.
+ *
+ * @param {object} client - PlaidClient instance
+ * @param {string} path - API path
+ * @param {object} [opts]
+ * @param {number} [opts.pageSize=1000] - Per-request page size (limit)
+ * @param {object} [opts.query={}] - Extra query params
+ * @yields {Array} The entries array for each page
+ */
+export function iterPages(client: object, path: string, { pageSize, query }?: {
+    pageSize?: number;
+    query?: object;
+}): AsyncGenerator<any, void, unknown>;

package/src/pagination.js

@@ -39,8 +39,7 @@ function entriesOf(response, path) {
 
 /**
  * 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.
+ * following `nextCursor` until it is null. This is what `.list()` calls.
  *
  * @param {object} client - PlaidClient instance
  * @param {string} path - API path, e.g. '/api/v1/projects'
@@ -51,23 +50,7 @@ function entriesOf(response, path) {
  */
 export async function listAll(client, path, { pageSize = 1000, query = {} } = {}) {
   const all = [];
-  let cursor = null;
-  let prevCursor;
-  do {
-    const response = await client._request('GET', path, {
-      queryParams: buildQueryParams(query, pageSize, cursor),
-    });
-    all.push(...entriesOf(response, path));
-    prevCursor = cursor;
-    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) {
-      throw new Error(
-        'Pagination cursor did not advance; aborting to avoid an infinite loop.',
-      );
-    }
-  } while (cursor !== null && cursor !== undefined);
+  for await (const entries of iterPages(client, path, { pageSize, query })) all.push(...entries);
   return all;
 }
 

package/src/provenance.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Provenance: the cross-app convention for distinguishing machine-provided
+ * from human-labeled information, expressed as flat metadata keys on
+ * annotation entities (spans, relations, vocab links, optionally tokens).
+ * Flat scalar keys — the query engine matches flat metadata well, nested
+ * objects poorly.
+ *
+ * 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 verifier made it.
+ *   machine            — { prov: 'inferred', provSource: '<producer>' };
+ *                        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, 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, '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
+ * queryability line:
+ *   - provProb: ONE flat number in [0, 1] — the producer's probability for
+ *     the value it chose. Flat scalars are what the query engine filters
+ *     and orders on, so "review the least-confident machine output first"
+ *     is an ordinary query. Omit it unless you can honestly produce a
+ *     probability (a raw logprob is NOT one — put it in provDetail).
+ *   - provDetail: ONE open map for everything else — top-k alternatives or
+ *     distributions, model name/version, raw scores. Deliberately nested
+ *     (not queryable); keep it small (top-k, not whole-vocabulary dumps).
+ * Both describe the machine's ORIGINAL prediction. They are kept after
+ * 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. */
+export const PROV: Readonly<{
+    /** 'inferred' when produced by an algorithm/service; absent = human. */
+    key: "prov";
+    /** Which producer, e.g. 'service:<id>', 'rule:precedent-or-unique'. */
+    sourceKey: "provSource";
+    /** true once a human confirmed (or edited) the inferred value. */
+    confirmedKey: "provConfirmed";
+    /** Producer's probability ([0,1]) for the chosen value. Flat = queryable. */
+    probKey: "provProb";
+    /** Open map of producer extras (alternatives, model version, raw scores). */
+    detailKey: "provDetail";
+    /** `prov` for machine-made material. Any value but CONTRIBUTED reads as machine. */
+    INFERRED: "inferred";
+    /** `prov` for a contributor's material. */
+    CONTRIBUTED: "contributed";
+}>;
+/**
+ * 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: readonly ("prov" | "provSource" | "provConfirmed" | "provProb" | "provDetail")[];
+/** The four provenance states returned by provState. */
+export const PROV_STATES: Readonly<{
+    HUMAN: "human";
+    MACHINE: "machine";
+    CONTRIBUTED: "contributed";
+    VERIFIED: "verified";
+}>;
+export function stampInferred(source: string, { prob, detail }?: {
+    prob?: number;
+    detail?: any;
+}): {
+    provDetail?: any;
+    provProb?: number;
+    prov: "inferred";
+    provSource: string;
+};
+export function confirmedInferred(source: string, extras?: {
+    prob?: number;
+    detail?: Record<string, any>;
+}): {
+    provConfirmed: boolean;
+    provDetail?: any;
+    provProb?: number;
+    prov: "inferred";
+    provSource: string;
+};
+/**
+ * The metadata fragment that verifies machine-made material:
+ * { provConfirmed: true }. Merge (PATCH) it over existing metadata so
+ * prov/provSource/provProb/provDetail survive. This is what verifyOnEdit
+ * returns for machine-unverified material; use it directly for explicit
+ * confirmation gestures (a "confirm" button, confirm-on-touch) where the
+ * caller has already checked isMachine.
+ */
+export const PROV_CONFIRMED: Readonly<{
+    provConfirmed: true;
+}>;
+export function stampContributed(userId: string): {
+    prov: "contributed";
+    provSource: string;
+};
+export function provState(metadata: object | null | undefined): "human" | "machine" | "contributed" | "verified";
+export function provOrigin(metadata: object | null | undefined): null | "inferred" | "contributed";
+export function isMachine(metadata: object | null | undefined): boolean;
+export function isProtected(metadata: object | null | undefined): boolean;
+export function needsReview(metadata: object | null | undefined): boolean;
+export function verifyOnEdit(metadata: object | null | undefined): Readonly<{
+    provConfirmed: true;
+}>;
+export function contributeOnEdit(metadata: object | null | undefined, userId: string): {
+    prov: "contributed";
+    provSource: string;
+    provConfirmed: null;
+};
+export function serviceSource(serviceId: string): string;
+export function userSource(userId: string): string;
+/** The config key, under the `plaid` namespace, holding the review lists. */
+export const REVIEW_KEY: "review";
+export function readReview(config?: object | null): {
+    users: string[];
+    roles: string[];
+};
+export function projectRole(project: object, userId: string, { isAdmin }?: {
+    isAdmin?: boolean;
+}): "maintainer" | "writer" | "reader";
+export function isReviewed(project: object | null | undefined, userId: string | null | undefined, { isAdmin }?: {
+    isAdmin?: boolean;
+}): boolean;
+export function withReviewedUser(review: {
+    users?: string[];
+    roles?: string[];
+} | null | undefined, userId: string, reviewed: boolean): {
+    users: string[];
+    roles: string[];
+};
+export function writerPolicy(contributorId?: string | null): {
+    contributorId: string | null;
+    isContributor: boolean;
+    createStamp: any | null;
+    editStamp: (metadata: any) => any | null;
+    confirmStamp: (metadata: any) => any | null;
+    adoptStamp: (source: string, detail?: any) => any;
+    reviewable: (metadata: any) => boolean;
+    reviewableState: (state: string) => boolean;
+};

package/src/provenance.js

@@ -151,6 +151,8 @@ export const stampInferred = (source, { prob, detail } = {}) => ({
  * import carrying upstream human approval, or a guess written only on
  * explicit user confirmation). Takes the same optional prediction extras
  * as stampInferred.
+ * @param {string} source
+ * @param {{prob?: number, detail?: Record<string, any>}} [extras]
  */
 export const confirmedInferred = (source, extras = {}) => ({
   ...stampInferred(source, extras),
@@ -179,7 +181,7 @@ export const stampContributed = (userId) => ({
 
 /**
  * Classify an entity's metadata into one of PROV_STATES.
- * @param {Object|null|undefined} metadata
+ * @param {object|null|undefined} metadata
  * @returns {'human'|'machine'|'contributed'|'verified'}
  */
 export const provState = (metadata) => {
@@ -193,6 +195,7 @@ export const provState = (metadata) => {
  * 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'.
+ * @param {object|null|undefined} metadata
  * @returns {null|'inferred'|'contributed'}
  */
 export const provOrigin = (metadata) => {
@@ -203,12 +206,16 @@ export const provOrigin = (metadata) => {
 /**
  * Whether this entity is machine-made and not yet verified — the material
  * machine writers may replace. Complement of isProtected.
+ * @param {object|null|undefined} metadata
+ * @returns {boolean}
  */
 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, contributed and verified material.
+ * @param {object|null|undefined} metadata
+ * @returns {boolean}
  */
 export const isProtected = (metadata) => !isMachine(metadata);
 
@@ -216,6 +223,8 @@ export const isProtected = (metadata) => !isMachine(metadata);
  * 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.
+ * @param {object|null|undefined} metadata
+ * @returns {boolean}
  */
 export const needsReview = (metadata) => {
   const s = provState(metadata);
@@ -226,6 +235,7 @@ export const needsReview = (metadata) => {
  * 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).
+ * @param {object|null|undefined} metadata
  */
 export const verifyOnEdit = (metadata) => (needsReview(metadata) ? PROV_CONFIRMED : null);
 
@@ -235,10 +245,11 @@ export const verifyOnEdit = (metadata) => (needsReview(metadata) ? PROV_CONFIRME
  * 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
+ * @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
+ * @returns {{prov: "contributed", provSource: string, provConfirmed: null}}
  */
 // eslint-disable-next-line no-unused-vars
 export const contributeOnEdit = (metadata, userId) => ({
@@ -246,10 +257,18 @@ export const contributeOnEdit = (metadata, userId) => ({
   [PROV.confirmedKey]: null,
 });
 
-/** Canonical provSource for a service: 'service:<serviceId>'. */
+/**
+ * Canonical provSource for a service: 'service:<serviceId>'.
+ * @param {string} serviceId
+ * @returns {string}
+ */
 export const serviceSource = (serviceId) => `service:${serviceId}`;
 
-/** Canonical provSource for a contributor: 'user:<userId>'. */
+/**
+ * Canonical provSource for a contributor: 'user:<userId>'.
+ * @param {string} userId
+ * @returns {string}
+ */
 export const userSource = (userId) => `user:${userId}`;
 
 // ---- review: whose work is reviewed (a project-config norm) ----
@@ -259,7 +278,8 @@ export const REVIEW_KEY = 'review';
 
 /**
  * The project's review lists, normalized: { users: string[], roles: string[] }.
- * @param {Object|null|undefined} config - a project's `config`
+ * @param {object|null} [config] - a project's `config`
+ * @returns {{users: string[], roles: string[]}}
  */
 export const readReview = (config) => {
   const raw = config?.plaid?.[REVIEW_KEY];
@@ -271,7 +291,7 @@ export const readReview = (config) => {
  * 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 {object} project - with `maintainers`, `writers`, `readers`
  * @param {string} userId
  * @param {Object} [opts]
  * @param {boolean} [opts.isAdmin]
@@ -287,6 +307,10 @@ export const projectRole = (project, userId, { isAdmin = false } = {}) => {
 /**
  * Whether this person's work is reviewed in this project: named in
  * review.users, or holding a role named in review.roles.
+ * @param {object|null|undefined} project
+ * @param {string|null|undefined} userId
+ * @param {{isAdmin?: boolean}} [opts]
+ * @returns {boolean}
  */
 export const isReviewed = (project, userId, { isAdmin = false } = {}) => {
   if (!project || userId == null) return false;
@@ -300,6 +324,10 @@ export const isReviewed = (project, userId, { isAdmin = false } = {}) => {
  * 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).
+ * @param {{users?: string[], roles?: string[]} | null | undefined} review
+ * @param {string} userId
+ * @param {boolean} reviewed
+ * @returns {{users: string[], roles: string[]}}
  */
 export const withReviewedUser = (review, userId, reviewed) => {
   const { users, roles } = readReview({ plaid: { [REVIEW_KEY]: review } });

package/src/replayed.d.ts

@@ -0,0 +1,3 @@
+/** `value` marked as replayed, when it is an object or a list. */
+export function markReplayed(value: any): any;
+export function wasReplayed(answer: unknown): boolean;

package/src/replayed.js

@@ -19,7 +19,11 @@ export function markReplayed(value) {
   return value;
 }
 
-/** Whether a client answer was replayed from its key's first send. */
+/**
+ * Whether a client answer was replayed from its key's first send.
+ * @param {unknown} answer
+ * @returns {boolean}
+ */
 export const wasReplayed = (answer) =>
   answer !== null &&
   typeof answer === "object" &&

package/src/requester.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The person who asked for one run: `id` is their account (their email),
+ * `name` how they are shown. Both are null when nobody asked.
+ * @param {string | null} [id]
+ * @param {string | null} [name]
+ * @returns {Requester}
+ */
+export function makeRequester(id?: string | null, name?: string | null): Requester;
+/**
+ * The requester of one request, from the `requesterId` core put in its data,
+ * with their display name read through `client`.
+ * @param {{users: {get(id: string): Promise<any>}}} client - A PlaidClient (only `users.get` is used)
+ * @param {any} data - The request data a `serve` handler receives
+ * @returns {Promise<Requester>}
+ */
+export function requesterOf(client: {
+    users: {
+        get(id: string): Promise<any>;
+    };
+}, data: any): Promise<Requester>;
+/**
+ * The person who asked for one service run. Both fields are null when nobody
+ * asked.
+ * @typedef {object} Requester
+ * @property {string | null} id
+ * @property {string | null} name
+ * @property {(text: string) => string} label `"<text>, requested by <name>"`,
+ *   or `text` when nobody asked.
+ * @property {() => ({id: string, name: string | null} | null)} record
+ *   `{ id, name }` for a stored report, or null when nobody asked.
+ * @property {(detail?: Record<string, any>) => Record<string, any>} detail A
+ *   machine stamp's `provDetail` with `requestedBy: <id>` added.
+ */
+/** 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 type 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>;
+};

package/src/requester.js

@@ -15,12 +15,29 @@
 // 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 person who asked for one service run. Both fields are null when nobody
+ * asked.
+ * @typedef {object} Requester
+ * @property {string | null} id
+ * @property {string | null} name
+ * @property {(text: string) => string} label `"<text>, requested by <name>"`,
+ *   or `text` when nobody asked.
+ * @property {() => ({id: string, name: string | null} | null)} record
+ *   `{ id, name }` for a stored report, or null when nobody asked.
+ * @property {(detail?: Record<string, any>) => Record<string, any>} detail A
+ *   machine stamp's `provDetail` with `requestedBy: <id>` added.
+ */
+
 /** The key a run's stored record names its requester under. */
-export const REQUESTED_BY = "requestedBy";
+export const REQUESTED_BY = /** @type {const} */ ("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.
+ * @param {string | null} [id]
+ * @param {string | null} [name]
+ * @returns {Requester}
  */
 export function makeRequester(id = null, name = null) {
   return {
@@ -38,8 +55,9 @@ export function makeRequester(id = null, name = null) {
 /**
  * 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
+ * @param {{users: {get(id: string): Promise<any>}}} client - A PlaidClient (only `users.get` is used)
+ * @param {any} data - The request data a `serve` handler receives
+ * @returns {Promise<Requester>}
  */
 export async function requesterOf(client, data) {
   const id = data && typeof data === "object" ? data.requesterId || null : null;

package/src/roles.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The role recorded on a layer's `config`, or null if none.
+ * @param {object} [config] a layer's `config` object
+ * @returns {string|null}
+ */
+export function readRole(config?: object): string | null;
+/**
+ * The first layer in `layers` carrying the given role, or null. The single
+ * "find a layer by its role" primitive — apps build their named finders
+ * (findWordTokenLayer, etc.) on top of this.
+ * @template {{config?: object}} T
+ * @param {T[] | undefined} layers
+ * @param {string} role
+ * @returns {T | null}
+ */
+export function findByRole<T extends {
+    config?: object;
+}>(layers: T[] | undefined, role: string): T | null;
+/**
+ * Shared layer-role vocabulary for cross-app interoperability.
+ *
+ * Apps that share a Plaid project agree on the *substrate* — the text and token
+ * layers — by tagging each shared layer with a ROLE under the reserved `plaid`
+ * config namespace (`config.plaid.role`, a scalar). Annotations stay private to
+ * each app under that app's own namespace. See the Plaid manual, "Layer
+ * Interoperability". The role inventory is small and fixed:
+ *
+ *   baseline        the primary text layer
+ *   sentence        sentence token layer
+ *   word            orthographic-word token layer (CoNLL-U "token")
+ *   syntactic-word  grammatical words below the word (CoNLL-U "word" / MWT splits)
+ *   morpheme        morpheme token layer
+ *   time-alignment  media-timeline token layer
+ *
+ * Only these values are understood across apps; an app may store any string but
+ * loses interoperability for unknown values.
+ */
+/** The reserved config namespace for cross-app conventions. */
+export const PLAID_NAMESPACE: "plaid";
+/** The config key, under `plaid`, holding a layer's role. */
+export const ROLE_KEY: "role";
+/** The fixed role inventory. */
+/**
+ * Layer config key naming the metadata keys a token born of a SPLIT inherits
+ * from the token it came from. Plaid honors it without knowing what the keys
+ * mean; see the manual's `Metadata Preserved Across a Split`. An app declares
+ * it so that a split in ANY app, including one that has never heard of these
+ * keys, does not silently drop them.
+ */
+export const PRESERVE_ON_SPLIT_KEY: "preserveOnSplit";
+/**
+ * Layer config key (true): a space typed inside a token of the text's words
+ * splits it, the token going on the half sharing more letters with it.
+ * Declared on a word layer another app shares, it holds for the whole text.
+ * See the manual's `Changing a text's body`.
+ */
+export const SPLIT_ON_SPACE_KEY: "splitOnSpace";
+export const ROLES: Readonly<{
+    BASELINE: "baseline";
+    SENTENCE: "sentence";
+    WORD: "word";
+    SYNTACTIC_WORD: "syntactic-word";
+    MORPHEME: "morpheme";
+    TIME_ALIGNMENT: "time-alignment";
+}>;