@larc-iu/plaid-client 0.2.0-alpha.1 → 0.2.0-alpha.12

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,17 @@
  * 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, and anything else (language, adapter, raw scores).
  */
 
 /** The flat metadata keys of the provenance convention. */
@@ -57,14 +93,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 +163,228 @@ 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 (a patch deletes null-valued keys;
+ * see mergeMetadata for a full replace). 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
+ */
+// eslint-disable-next-line no-unused-vars
+export const contributeOnEdit = (metadata, userId) => ({
+  ...stampContributed(userId),
+  [PROV.confirmedKey]: null,
+});
+
+/**
+ * Merge a metadata fragment the way the server's PATCH does — a null value
+ * deletes the key — for callers that keep a local copy or send a full
+ * replacement (setMetadata). Returns a new object.
  */
-export const verifyOnEdit = (metadata) => (isMachine(metadata) ? PROV_CONFIRMED : null);
+export const mergeMetadata = (metadata, fragment) => {
+  const out = { ...(metadata || {}) };
+  for (const [k, v] of Object.entries(fragment || {})) {
+    if (v === null) delete out[k];
+    else out[k] = v;
+  }
+  return out;
+};
 
 /** 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/roles.js

@@ -25,6 +25,15 @@ export const PLAID_NAMESPACE = 'plaid';
 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';
+
 export const ROLES = Object.freeze({
   BASELINE: 'baseline',
   SENTENCE: 'sentence',

package/src/serviceSchema.js

@@ -21,7 +21,7 @@
  *     parameters: [                     // ordered; rendered into a form
  *       { key, label, type, description?, default?, required?,
  *         options?: [{value, label}],   // enum / multiselect
- *         min?, max?, step?,            // number
+ *         min?, max?, step?, slider?,   // number (slider: drag, don't type)
  *         placeholder?, multiline? }    // string
  *     ]
  *   }
@@ -43,11 +43,27 @@
  * without an explicit `overwrite` parameter. See the manual, "Provenance".
  */
 export const TASKS = Object.freeze({
-  TOKENIZE: 'tokenize',
-  PARSE: 'parse',
-  TRANSCRIBE: 'transcribe',
+  TOKENIZE: "tokenize",
+  PARSE: "parse",
+  TRANSCRIBE: "transcribe",
   /** Create vocab links for unlinked tokens. */
-  LINK_VOCAB: 'link-vocab',
+  LINK_VOCAB: "link-vocab",
+  /** Propose an interlinear analysis (morpheme segmentation + glosses) for words. */
+  ANALYZE: "analyze",
+  /** Propose a free translation for each sentence. */
+  TRANSLATE: "translate",
+  /**
+   * Propose time-aligned speech regions for a recording.
+   *
+   * The odd one out: a detect-speech service RETURNS its regions and writes
+   * nothing, because a time-aligned segment is a stretch of the baseline and
+   * cannot exist without text. The response carries
+   * `{segments: [{timeBegin, timeEnd, speaker?}]}` (seconds), and the app
+   * holds them as proposals until a person types into one.
+   */
+  DETECT_SPEECH: "detect-speech",
+  /** A conversational assistant over a project (chat turns; see plaid-agent). */
+  ASSIST: "assist",
 });
 
 /**
@@ -55,8 +71,8 @@ export const TASKS = Object.freeze({
  * declared `tasks` array. Drop once all services advertise `tasks`.
  */
 const LEGACY_TASK_PREFIXES = Object.freeze({
-  [TASKS.TOKENIZE]: 'tok:',
-  [TASKS.TRANSCRIBE]: 'asr:',
+  [TASKS.TOKENIZE]: "tok:",
+  [TASKS.TRANSCRIBE]: "asr:",
 });
 
 /**
@@ -72,7 +88,11 @@ export function servesTask(service, task) {
     return declared.includes(task);
   }
   const prefix = LEGACY_TASK_PREFIXES[task];
-  return !!prefix && typeof service?.serviceId === 'string' && service.serviceId.startsWith(prefix);
+  return (
+    !!prefix &&
+    typeof service?.serviceId === "string" &&
+    service.serviceId.startsWith(prefix)
+  );
 }
 
 /**
@@ -102,7 +122,7 @@ export function getParamSchema(service) {
  * @returns {string}
  */
 export function getServiceSummary(service) {
-  return service?.extras?.summary || service?.description || '';
+  return service?.extras?.summary || service?.description || "";
 }
 
 /** Valid option values for an enum/multiselect param. */
@@ -117,20 +137,25 @@ function optionValues(param) {
  */
 function defaultForParam(param) {
   const opts = optionValues(param);
-  if (param.type === 'enum') {
-    if (param.default != null && opts.includes(param.default)) return param.default;
-    return opts[0] ?? '';
+  if (param.type === "enum") {
+    if (param.default != null && opts.includes(param.default))
+      return param.default;
+    return opts[0] ?? "";
   }
-  if (param.type === 'multiselect') {
+  if (param.type === "multiselect") {
     const arr = Array.isArray(param.default) ? param.default : [];
     return opts.length ? arr.filter((x) => opts.includes(x)) : arr;
   }
-  if (param.default !== undefined && param.default !== null) return param.default;
+  if (param.default !== undefined && param.default !== null)
+    return param.default;
   switch (param.type) {
-    case 'number': return typeof param.min === 'number' ? param.min : 0;
-    case 'boolean': return false;
-    case 'string':
-    default: return '';
+    case "number":
+      return typeof param.min === "number" ? param.min : 0;
+    case "boolean":
+      return false;
+    case "string":
+    default:
+      return "";
   }
 }
 
@@ -167,43 +192,48 @@ export function coerceParamValues(schema, raw) {
     if (v === undefined) v = defaultForParam(param);
 
     switch (param.type) {
-      case 'number': {
+      case "number": {
         // Blank / nullish counts as "missing" → the param's default (matches the
         // Python client, where float('') raises and falls back to the default).
         let n;
-        if (v === '' || v == null || (typeof v === 'string' && v.trim() === '')) {
+        if (
+          v === "" ||
+          v == null ||
+          (typeof v === "string" && v.trim() === "")
+        ) {
           n = defaultForParam(param);
         } else {
-          n = typeof v === 'number' ? v : Number(v);
+          n = typeof v === "number" ? v : Number(v);
           if (Number.isNaN(n)) n = defaultForParam(param);
         }
-        if (typeof param.min === 'number') n = Math.max(param.min, n);
-        if (typeof param.max === 'number') n = Math.min(param.max, n);
+        if (typeof param.min === "number") n = Math.max(param.min, n);
+        if (typeof param.max === "number") n = Math.min(param.max, n);
         v = n;
         break;
       }
-      case 'boolean':
-        v = v === true || v === 'true';
+      case "boolean":
+        v = v === true || v === "true";
         break;
-      case 'enum': {
+      case "enum": {
         const opts = optionValues(param);
         if (opts.length && !opts.includes(v)) v = defaultForParam(param);
         break;
       }
-      case 'multiselect': {
+      case "multiselect": {
         const opts = optionValues(param);
-        const arr = Array.isArray(v) ? v : (v == null || v === '' ? [] : [v]);
+        const arr = Array.isArray(v) ? v : v == null || v === "" ? [] : [v];
         v = opts.length ? arr.filter((x) => opts.includes(x)) : arr;
         break;
       }
-      case 'string':
+      case "string":
       default:
-        v = v == null ? '' : String(v);
+        v = v == null ? "" : String(v);
         break;
     }
 
     if (param.required) {
-      const empty = v === '' || v == null || (Array.isArray(v) && v.length === 0);
+      const empty =
+        v === "" || v == null || (Array.isArray(v) && v.length === 0);
       if (empty) errors[k] = `${param.label || k} is required`;
     }
     values[k] = v;