@larc-iu/plaid-client 0.2.0-alpha.29 → 0.2.0-alpha.30

package/src/operations.d.ts

@@ -0,0 +1,36 @@
+/**
+ * End the key frame `frame` of `group`, wherever it is among the frames open:
+ * the frame under it, or the one open over it, numbers from then on. A plain
+ * function, so a caller that borrows withOperation onto another object
+ * (test doubles do) keeps it.
+ */
+export function dropFrame(group: any, frame: any): void;
+/**
+ * The key for the next keyed request, and the strict-mode stamp it must
+ * claim when an earlier run of its operation already sent it. `joins` says
+ * whether the request joins the open logical operation.
+ * Returns `{ key, pin, record }`: `pin` is undefined when nothing is pinned,
+ * and `record(version)` pins what this request claimed, the first time.
+ */
+export function nextIdempotencyKey(client: any, joins: any): {
+    key: string;
+    pin: any;
+    record: (version: any) => void;
+};
+/** See PlaidClient.beginOperation. */
+export function beginOperation(client: any, message: any, { groupId, kind, ref, keys, minted }?: {}): any;
+/** See PlaidClient.keySeed. */
+export function keySeed(): {
+    seed: string;
+    stamps: Map<any, any>;
+};
+/** See PlaidClient.endOperation. */
+export function endOperation(client: any, message: any): Promise<void>;
+/** See PlaidClient.withOperation. */
+export function withOperation(client: any, message: any, fn: any, { kind, ref, groupId, keys, minted }?: {}): Promise<any>;
+/**
+ * The kinds an operation may say it is (`?group-kind=`), the server's closed
+ * list (plaid.sql.operation-group/kinds). An operation of any other kind is
+ * refused when it begins, before it writes anything.
+ */
+export const OPERATION_KINDS: string[];

package/src/operations.js

@@ -0,0 +1,164 @@
+/**
+ * Logical operations: the audit-log group a run of writes is labelled with,
+ * its kind and reference, and the Idempotency-Keys that make a rerun send the
+ * same requests. The client's beginOperation, keySeed, endOperation and
+ * withOperation (whose notes say what each does) call these, with the client
+ * as `client`. The twin of plaid-client-py's operations.py.
+ */
+
+import { uuidv4, uuidv7 } from "./ids.js";
+
+/**
+ * The kinds an operation may say it is (`?group-kind=`), the server's closed
+ * list (plaid.sql.operation-group/kinds). An operation of any other kind is
+ * refused when it begins, before it writes anything.
+ */
+export const OPERATION_KINDS = [
+  "assistant-plan",
+  "service-run",
+  "import",
+  "bulk-edit",
+  "guess-adoption",
+  "repair",
+  "review",
+];
+
+/**
+ * End the key frame `frame` of `group`, wherever it is among the frames open:
+ * the frame under it, or the one open over it, numbers from then on. A plain
+ * function, so a caller that borrows withOperation onto another object
+ * (test doubles do) keeps it.
+ */
+export function dropFrame(group, frame) {
+  if (!group || !frame || group.frames[0] === frame) return;
+  group.frames = group.frames.filter((f) => f !== frame);
+}
+
+/**
+ * The key for the next keyed request, and the strict-mode stamp it must
+ * claim when an earlier run of its operation already sent it. `joins` says
+ * whether the request joins the open logical operation.
+ * Returns `{ key, pin, record }`: `pin` is undefined when nothing is pinned,
+ * and `record(version)` pins what this request claimed, the first time.
+ */
+export function nextIdempotencyKey(client, joins) {
+  const frame = joins ? client.operationGroup?.frames.at(-1) : null;
+  const keys = frame?.keys;
+  if (!keys) return { key: uuidv7(), pin: undefined, record: () => {} };
+  const n = frame.count;
+  frame.count += 1;
+  const pinned = keys.stamps.has(n);
+  return {
+    key: `${keys.seed}.${n}`,
+    pin: pinned ? keys.stamps.get(n) : undefined,
+    record: (version) => {
+      if (!pinned) keys.stamps.set(n, version ?? null);
+    },
+  };
+}
+
+/** See PlaidClient.beginOperation. */
+export function beginOperation(client, message, { groupId, kind, ref, keys, minted } = {}) {
+  if (kind != null && !OPERATION_KINDS.includes(String(kind))) {
+    throw new Error(
+      `Unknown operation kind "${kind}". It is one of: ${OPERATION_KINDS.join(", ")}.`,
+    );
+  }
+  const frame = {
+    keys: keys || null,
+    count: 0,
+    // Any iterable of ids (a Set, an array).
+    minted: minted ? new Set(minted) : null,
+    depth: 1,
+  };
+  const open = client.operationGroup;
+  client._openedFrame = null;
+  if (open) {
+    // A nested operation joins the outer one. When it brings its own key
+    // seed or ids (a queued edit run inside a longer operation), it numbers
+    // the keys in a frame of its own until it ends, then the frame under it
+    // numbers again.
+    open.depth += 1;
+    if (keys || minted) {
+      frame.depth = open.depth;
+      open.frames.push(frame);
+      client._openedFrame = frame;
+    }
+    return open.id;
+  }
+  client.operationGroup = {
+    id: groupId ? String(groupId) : uuidv4(),
+    message: message == null ? null : String(message),
+    kind: kind == null ? null : String(kind),
+    ref: ref == null ? null : String(ref),
+    depth: 1,
+    written: false,
+    refined: undefined,
+    frames: [frame],
+  };
+  client._openedFrame = frame;
+  return client.operationGroup.id;
+}
+
+/** See PlaidClient.keySeed. */
+export function keySeed() {
+  return { seed: uuidv7(), stamps: new Map() };
+}
+
+/** See PlaidClient.endOperation. */
+export async function endOperation(client, message) {
+  const group = client.operationGroup;
+  if (!group) return;
+  if (group.depth > 1) {
+    // A frame begun at client depth by hand (beginOperation) ends here. One
+    // begun by withOperation is ended by that call itself (_dropFrame).
+    const top = group.frames.at(-1);
+    if (group.frames.length > 1 && !top.owned && top.depth === group.depth) {
+      group.frames.pop();
+    }
+    group.depth -= 1;
+    return;
+  }
+  client.operationGroup = null;
+  const refined = message !== undefined ? message : group.refined;
+  if (refined !== undefined && group.written) {
+    try {
+      await client.operationGroups.update(group.id, refined);
+    } catch (e) {
+      // 404: the group never materialized server-side (every tagged write
+      // failed or a batch was aborted). Nothing to relabel — not an error.
+      if (e.status !== 404) throw e;
+    }
+  }
+}
+
+/** See PlaidClient.withOperation. */
+export async function withOperation(client, message, fn, { kind, ref, groupId, keys, minted } = {}) {
+  client.beginOperation(message, { kind, ref, groupId, keys, minted });
+  const group = client.operationGroup;
+  // The key frame client call opened is ended by client call, whatever else
+  // began or ended meanwhile, not by whichever end comes at its depth.
+  const frame = client._openedFrame;
+  if (frame) frame.owned = true;
+  const setMessage = (msg) => {
+    if (group.depth === 1) group.refined = msg;
+  };
+  let result;
+  try {
+    result = await fn(setMessage);
+  } catch (e) {
+    // A relabel the server refuses (a token scoped to projects may not
+    // relabel a group, which names none) must not take the place of the
+    // error `fn` threw: the caller answers for that one.
+    dropFrame(group, frame);
+    try {
+      await client.endOperation();
+    } catch (relabel) {
+      console.warn('The operation was not relabelled:', relabel);
+    }
+    throw e;
+  }
+  dropFrame(group, frame);
+  await client.endOperation();
+  return result;
+}

package/src/provenance.d.ts

@@ -60,13 +60,21 @@
  *     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).
+ *     probability (a raw logprob is NOT one — put it in provDetail), and
+ *     calibrate it on held-out data, so that values stated at 70% are
+ *     right about 70% of the time. Apps mark a value below the project's
+ *     threshold (readConfidenceThreshold), one number for every producer.
  *   - 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
+ * provDetail describes the machine's ORIGINAL prediction and is kept after
+ * human edits (history is valuable). provProb is the producer's probability
+ * for the value the entity holds, however a person entered it: a value the
+ * producer weighed (one in provDetail.valueProbs, or formProbs for a
+ * morpheme's form) carries that probability, and a value it never weighed
+ * carries none (writerPolicy's valueEditStamp is the one implementation,
+ * and it reads the distribution itself). A consumer still must not present
+ * provProb as the machine's confidence once the entity is verified
  * (provConfirmed is exactly the flag to check).
  *
  * Recommended provDetail keys, so consumers (review dashboards, ranked
@@ -78,6 +86,12 @@
  *   - 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).
+ *   - valueLinks: on a gloss, a list of {value, item, prob}, one per
+ *     alternative that stands for a lexicon entry: its label, the vocab
+ *     item id and its probability (two senses may share a label, so this
+ *     is a list, not a map). igt offers each alternative together with
+ *     its entry as one choice, under Alt+Down on the gloss and in the
+ *     lexicon popover.
  *   - 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
@@ -175,6 +189,7 @@ export function readReview(config?: object | null): {
     users: string[];
     roles: string[];
 };
+export function reviewsAnyone(config?: object | null): boolean;
 export function projectRole(project: object, userId: string, { isAdmin }?: {
     isAdmin?: boolean;
 }): "maintainer" | "writer" | "reader";
@@ -188,12 +203,40 @@ export function withReviewedUser(review: {
     users: string[];
     roles: string[];
 };
+/**
+ * Key of the project's confidence setting under `config.plaid`:
+ * `{ threshold: number in [0, 1] }`. A machine value whose provProb is below
+ * the threshold is DOUBTFUL, and both apps give it a heavier mark. Producers
+ * write provProb calibrated on held-out data (manual, "Provenance"), so one
+ * number serves every service on the project.
+ */
+export const CONFIDENCE_KEY: "confidence";
+/** The threshold when a project sets none: below it, a calibrated value is more likely wrong than right. */
+export const DEFAULT_CONFIDENCE_THRESHOLD: 0.5;
+export function readConfidenceThreshold(config?: object | null): number;
+export function machineProb(metadata: object | null | undefined): number | null;
+export function isDoubtful(metadata: object | null | undefined, threshold?: number): boolean;
+/** The provDetail key of a producer's distribution over a span's or relation's value. */
+export const VALUE_PROBS_KEY: "valueProbs";
+/** The provDetail key of a producer's distribution over a morpheme's form. */
+export const FORM_PROBS_KEY: "formProbs";
+export function readValueProbs(metadata: object | null | undefined, key?: string): {
+    [x: string]: number;
+} | null;
 export function writerPolicy(contributorId?: string | null): {
     contributorId: string | null;
     isContributor: boolean;
     createStamp: any | null;
     editStamp: (metadata: any) => any | null;
+    valueEditStamp: (metadata: any, opts?: {
+        changes?: boolean;
+        value?: string;
+        probsKey?: string;
+        prob?: number | null;
+    }) => any | null;
+    repointStamp: (metadata: any) => any | null;
     confirmStamp: (metadata: any) => any | null;
+    confirmFragment: () => any;
     adoptStamp: (source: string, detail?: any) => any;
     reviewable: (metadata: any) => boolean;
     reviewableState: (state: string) => boolean;

package/src/provenance.js

@@ -60,13 +60,21 @@
  *     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).
+ *     probability (a raw logprob is NOT one — put it in provDetail), and
+ *     calibrate it on held-out data, so that values stated at 70% are
+ *     right about 70% of the time. Apps mark a value below the project's
+ *     threshold (readConfidenceThreshold), one number for every producer.
  *   - 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
+ * provDetail describes the machine's ORIGINAL prediction and is kept after
+ * human edits (history is valuable). provProb is the producer's probability
+ * for the value the entity holds, however a person entered it: a value the
+ * producer weighed (one in provDetail.valueProbs, or formProbs for a
+ * morpheme's form) carries that probability, and a value it never weighed
+ * carries none (writerPolicy's valueEditStamp is the one implementation,
+ * and it reads the distribution itself). A consumer still must not present
+ * provProb as the machine's confidence once the entity is verified
  * (provConfirmed is exactly the flag to check).
  *
  * Recommended provDetail keys, so consumers (review dashboards, ranked
@@ -78,6 +86,12 @@
  *   - 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).
+ *   - valueLinks: on a gloss, a list of {value, item, prob}, one per
+ *     alternative that stands for a lexicon entry: its label, the vocab
+ *     item id and its probability (two senses may share a label, so this
+ *     is a list, not a map). igt offers each alternative together with
+ *     its entry as one choice, under Alt+Down on the gloss and in the
+ *     lexicon popover.
  *   - 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
@@ -130,20 +144,32 @@ export const PROV_STATES = Object.freeze({
   VERIFIED: 'verified',
 });
 
+/**
+ * Whether `p` is a probability, a finite number in [0, 1]: the only thing
+ * written as provProb. A stamp given anything else writes no provProb.
+ * @param {*} p
+ * @returns {boolean}
+ */
+const isProbability = (p) => typeof p === 'number' && p >= 0 && p <= 1;
+
 /**
  * The metadata fragment a machine writer merges into everything it creates.
  * @param {string} source - producer id, e.g. serviceSource(serviceId)
  * @param {Object} [extras] - optional prediction extras:
  * @param {number} [extras.prob] - probability in [0,1] for the chosen value
- *   (omit unless it honestly is one — raw scores go in detail)
+ *   (omit unless it honestly is one — raw scores go in detail). Anything
+ *   else is left out.
  * @param {Object} [extras.detail] - open map of producer extras (top-k
  *   alternatives, model version, raw scores; keep it small)
  */
 export const stampInferred = (source, { prob, detail } = {}) => ({
   [PROV.key]: PROV.INFERRED,
   [PROV.sourceKey]: source,
-  ...(prob !== undefined && prob !== null ? { [PROV.probKey]: prob } : {}),
-  ...(detail ? { [PROV.detailKey]: detail } : {}),
+  ...(isProbability(prob) ? { [PROV.probKey]: prob } : {}),
+  // An empty detail is no detail, as in the Python client.
+  ...(detail && !(typeof detail === 'object' && Object.keys(detail).length === 0)
+    ? { [PROV.detailKey]: detail }
+    : {}),
 });
 
 /**
@@ -287,6 +313,18 @@ export const readReview = (config) => {
   return { users: list(raw?.users), roles: list(raw?.roles) };
 };
 
+/**
+ * Whether the project reviews anybody's work: a person or a role is named in
+ * its review lists. Where it reviews nobody, nothing is contributed, and an
+ * editor's legend has no contributed mark to explain.
+ * @param {object|null} [config] - a project's `config`
+ * @returns {boolean}
+ */
+export const reviewsAnyone = (config) => {
+  const { users, roles } = readReview(config);
+  return users.length > 0 || roles.length > 0;
+};
+
 /**
  * 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
@@ -336,6 +374,76 @@ export const withReviewedUser = (review, userId, reviewed) => {
   return { users: next, roles };
 };
 
+// ---- confidence: which machine values are doubtful ----
+
+/**
+ * Key of the project's confidence setting under `config.plaid`:
+ * `{ threshold: number in [0, 1] }`. A machine value whose provProb is below
+ * the threshold is DOUBTFUL, and both apps give it a heavier mark. Producers
+ * write provProb calibrated on held-out data (manual, "Provenance"), so one
+ * number serves every service on the project.
+ */
+export const CONFIDENCE_KEY = 'confidence';
+
+/** The threshold when a project sets none: below it, a calibrated value is more likely wrong than right. */
+export const DEFAULT_CONFIDENCE_THRESHOLD = 0.5;
+
+/**
+ * The project's confidence threshold, or the default when it sets none or
+ * stores something that is not a number in [0, 1].
+ * @param {object|null} [config] - a project's `config`
+ * @returns {number}
+ */
+export const readConfidenceThreshold = (config) => {
+  const t = config?.plaid?.[CONFIDENCE_KEY]?.threshold;
+  return typeof t === 'number' && t >= 0 && t <= 1 ? t : DEFAULT_CONFIDENCE_THRESHOLD;
+};
+
+/**
+ * The producer's probability for a machine value nobody has reviewed, or
+ * null. Null once a person has confirmed or contributed it, since provProb
+ * describes the original prediction and not the value as it stands.
+ * @param {object|null|undefined} metadata
+ * @returns {number|null}
+ */
+export const machineProb = (metadata) => {
+  if (provState(metadata) !== PROV_STATES.MACHINE) return null;
+  const p = metadata[PROV.probKey];
+  return typeof p === 'number' && Number.isFinite(p) ? p : null;
+};
+
+/**
+ * Whether an unreviewed machine value is below the project's threshold.
+ * @param {object|null|undefined} metadata
+ * @param {number} [threshold] - readConfidenceThreshold(project.config)
+ * @returns {boolean}
+ */
+export const isDoubtful = (metadata, threshold = DEFAULT_CONFIDENCE_THRESHOLD) => {
+  const p = machineProb(metadata);
+  return p != null && p < threshold;
+};
+
+/** The provDetail key of a producer's distribution over a span's or relation's value. */
+export const VALUE_PROBS_KEY = 'valueProbs';
+/** The provDetail key of a producer's distribution over a morpheme's form. */
+export const FORM_PROBS_KEY = 'formProbs';
+
+/**
+ * The distribution a producer recorded under provDetail[key] (valueProbs by
+ * default, formProbs for a morpheme's form), as a {label: probability} map
+ * holding only the entries whose number is a probability, or null when there
+ * is none.
+ * @param {object|null|undefined} metadata
+ * @param {string} [key]
+ * @returns {Object<string, number>|null}
+ */
+export const readValueProbs = (metadata, key = VALUE_PROBS_KEY) => {
+  const raw = metadata?.[PROV.detailKey]?.[key];
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const entries = Object.entries(raw).filter(([v, p]) => v !== '' && isProbability(p));
+  return entries.length ? Object.fromEntries(entries) : null;
+};
+
 // ---- the writer's policy: what a person's writes carry ----
 
 /**
@@ -351,7 +459,10 @@ export const withReviewedUser = (review, userId, reviewed) => {
  *   isContributor: boolean,
  *   createStamp: Object|null,
  *   editStamp: (metadata: Object) => Object|null,
+ *   valueEditStamp: (metadata: Object, opts?: {changes?: boolean, value?: string, probsKey?: string, prob?: number|null}) => Object|null,
+ *   repointStamp: (metadata: Object) => Object|null,
  *   confirmStamp: (metadata: Object) => Object|null,
+ *   confirmFragment: () => Object,
  *   adoptStamp: (source: string, detail?: Object) => Object,
  *   reviewable: (metadata: Object) => boolean,
  *   reviewableState: (state: string) => boolean,
@@ -368,6 +479,9 @@ export const writerPolicy = (contributorId = null) => {
     contributor
       ? state === PROV_STATES.MACHINE
       : state === PROV_STATES.MACHINE || state === PROV_STATES.CONTRIBUTED;
+  const editStamp = (metadata) =>
+    contributor ? contributeOnEdit(metadata, id) : verifyOnEdit(metadata);
+  const confirmFragment = () => (contributor ? contributeOnEdit(null, id) : PROV_CONFIRMED);
   return Object.freeze({
     contributorId: id,
     isContributor: contributor,
@@ -379,16 +493,58 @@ export const writerPolicy = (contributorId = null) => {
      * contributor's edit marks the entity contributed, dropping any earlier
      * confirmation.
      */
-    editStamp: (metadata) => (contributor ? contributeOnEdit(metadata, id) : verifyOnEdit(metadata)),
+    editStamp,
+    /**
+     * The fragment a person's edit of a VALUE merges: editStamp, plus what
+     * the edit means for provProb, the producer's probability for the value
+     * the entity holds, however it was entered. A new `value` the producer
+     * weighed, found in the entity's own provDetail[probsKey] (valueProbs,
+     * or formProbs for a morpheme's form), carries that probability. A
+     * `prob` in [0, 1] is used instead when the caller knows the number
+     * from elsewhere (a gloss alternative's own valueLinks entry). A new
+     * value the producer never weighed removes provProb. A value that
+     * `changes` nothing keeps it. provDetail stays, as history. Null when
+     * there is nothing to merge.
+     */
+    valueEditStamp: (
+      metadata,
+      { changes = true, value, probsKey = VALUE_PROBS_KEY, prob = null } = {},
+    ) => {
+      const stamp = editStamp(metadata);
+      if (!changes) return stamp;
+      const probs = readValueProbs(metadata, probsKey);
+      const weighed =
+        probs && typeof value === 'string' && Object.hasOwn(probs, value) ? probs[value] : null;
+      const p = isProbability(prob) ? prob : weighed;
+      if (p != null) return { ...(stamp || {}), [PROV.probKey]: p };
+      if (metadata?.[PROV.probKey] == null) return stamp;
+      return { ...(stamp || {}), [PROV.probKey]: null };
+    },
+    /**
+     * The fragment that makes a relation whose head a person moved theirs:
+     * every provenance key it held removed, and the create stamp merged, so
+     * it reads as a relation this writer drew (the convention's "a head
+     * re-point yields a person's relation"). Null when there is nothing to
+     * merge.
+     */
+    repointStamp: (metadata) => {
+      const cleared = {};
+      for (const k of PROVENANCE_KEYS) if (metadata?.[k] != null) cleared[k] = null;
+      const fragment = { ...cleared, ...(contributor ? stampContributed(id) : {}) };
+      return Object.keys(fragment).length ? fragment : null;
+    },
     /**
      * 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;
-    },
+    confirmStamp: (metadata) => (reviewable(metadata) ? confirmFragment() : null),
+    /**
+     * The fragment this writer's confirm merges over whatever it confirms,
+     * read without an entity: confirmStamp of anything reviewable. For a
+     * gesture that confirms many entities with one stamp.
+     */
+    confirmFragment,
     /**
      * 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

package/src/roles.d.ts

@@ -1,9 +1,27 @@
+/**
+ * Whether a project records research telemetry: `config.plaid.research.telemetry`
+ * is exactly true.
+ * @param {object} [config] a project's `config` object
+ * @returns {boolean}
+ */
+export function readResearchTelemetry(config?: object): boolean;
 /**
  * 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 ignored-tokens rule on a word layer's `config` (see
+ * `IGNORED_TOKENS_KEY`), or null if none. The one reader of the key in JS.
+ * @param {object} [config] a token layer's `config` object
+ * @returns {{type: string, whitelist?: string[], blacklist?: string[]}|null}
+ */
+export function readIgnoredTokens(config?: object): {
+    type: string;
+    whitelist?: string[];
+    blacklist?: 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
@@ -55,6 +73,27 @@ export const PRESERVE_ON_SPLIT_KEY: "preserveOnSplit";
  * See the manual's `Changing a text's body`.
  */
 export const SPLIT_ON_SPACE_KEY: "splitOnSpace";
+/**
+ * Word layer config key holding the ignored-tokens rule,
+ * `{type, whitelist, blacklist}`: under `type: 'unicodePunctuation'` a word made
+ * only of punctuation is ignored and each one-character entry of `whitelist` is
+ * a letter, under `type: 'blacklist'` the entries of `blacklist` are the words
+ * ignored and its one-character entries the only characters that part words.
+ * Plaid's text rules and the built-in tokenizer read it. See the manual's
+ * `Changing a text's body`.
+ */
+export const IGNORED_TOKENS_KEY: "ignoredTokens";
+/**
+ * Project config key (false to hide): whether the project's tartan shows beside
+ * its name. Absent means shown.
+ */
+export const TARTAN_KEY: "tartan";
+/**
+ * Project config key holding the research settings, `{telemetry}`. Client
+ * events are recorded only while `telemetry` is true. See the manual's
+ * `Research telemetry`.
+ */
+export const RESEARCH_KEY: "research";
 export const ROLES: Readonly<{
     BASELINE: "baseline";
     SENTENCE: "sentence";

package/src/roles.js

@@ -42,6 +42,40 @@ export const PRESERVE_ON_SPLIT_KEY = 'preserveOnSplit';
  */
 export const SPLIT_ON_SPACE_KEY = 'splitOnSpace';
 
+/**
+ * Word layer config key holding the ignored-tokens rule,
+ * `{type, whitelist, blacklist}`: under `type: 'unicodePunctuation'` a word made
+ * only of punctuation is ignored and each one-character entry of `whitelist` is
+ * a letter, under `type: 'blacklist'` the entries of `blacklist` are the words
+ * ignored and its one-character entries the only characters that part words.
+ * Plaid's text rules and the built-in tokenizer read it. See the manual's
+ * `Changing a text's body`.
+ */
+export const IGNORED_TOKENS_KEY = 'ignoredTokens';
+
+/**
+ * Project config key (false to hide): whether the project's tartan shows beside
+ * its name. Absent means shown.
+ */
+export const TARTAN_KEY = 'tartan';
+
+/**
+ * Project config key holding the research settings, `{telemetry}`. Client
+ * events are recorded only while `telemetry` is true. See the manual's
+ * `Research telemetry`.
+ */
+export const RESEARCH_KEY = 'research';
+
+/**
+ * Whether a project records research telemetry: `config.plaid.research.telemetry`
+ * is exactly true.
+ * @param {object} [config] a project's `config` object
+ * @returns {boolean}
+ */
+export function readResearchTelemetry(config) {
+  return config?.[PLAID_NAMESPACE]?.[RESEARCH_KEY]?.telemetry === true;
+}
+
 export const ROLES = Object.freeze({
   BASELINE: 'baseline',
   SENTENCE: 'sentence',
@@ -61,6 +95,16 @@ export function readRole(config) {
   return v == null ? null : v;
 }
 
+/**
+ * The ignored-tokens rule on a word layer's `config` (see
+ * `IGNORED_TOKENS_KEY`), or null if none. The one reader of the key in JS.
+ * @param {object} [config] a token layer's `config` object
+ * @returns {{type: string, whitelist?: string[], blacklist?: string[]}|null}
+ */
+export function readIgnoredTokens(config) {
+  return config?.[PLAID_NAMESPACE]?.[IGNORED_TOKENS_KEY] ?? 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