@larc-iu/plaid-client 0.1.0-alpha.8 → 0.1.0-alpha.9

package/index.d.ts

@@ -4,18 +4,56 @@ interface Page<T = any> {
   nextCursor: string | null;
 }
 
+/** One choice for an `enum` / `multiselect` service parameter. */
+interface ServiceParamOption {
+  value: string;
+  label: string;
+}
+
+/** A single user-controllable argument a service advertises. */
+interface ServiceParam {
+  /** Key the value is sent under in the request payload. */
+  key: string;
+  label: string;
+  type: 'string' | 'number' | 'boolean' | 'enum' | 'multiselect';
+  description?: string;
+  default?: any;
+  required?: boolean;
+  /** Required for `enum` / `multiselect`. */
+  options?: ServiceParamOption[];
+  /** `number` only. */
+  min?: number;
+  max?: number;
+  step?: number;
+  /** `string` only. */
+  placeholder?: string;
+  multiline?: boolean;
+}
+
+/** A service's standardized self-description (lives in `extras`). */
+interface ServiceExtras {
+  schemaVersion?: number;
+  /** Tasks this service serves; from the TASKS vocabulary. */
+  tasks?: string[];
+  /** Rich human description (markdown), beyond the short `description`. */
+  summary?: string;
+  /** Ordered parameter schema, rendered into a form by the UI. */
+  parameters?: ServiceParam[];
+  [key: string]: any;
+}
+
 interface ServiceInfo {
   serviceId: string;
   serviceName: string;
   description: string;
-  extras?: any;
+  extras?: ServiceExtras;
 }
 
 interface DiscoveredService {
   serviceId: string;
   serviceName: string;
   description: string;
-  extras: any;
+  extras: ServiceExtras;
 }
 
 interface ServiceRegistration {
@@ -40,6 +78,7 @@ interface VocabLinksBundle {
   create(vocabItem: string, tokens: any[], metadata?: any): Promise<any>;
   setMetadata(id: string, body: any): Promise<any>;
   deleteMetadata(id: string): Promise<any>;
+  patchMetadata(id: string, body: any): Promise<any>;
   get(id: string, asOf?: string): Promise<any>;
   delete(id: string): Promise<any>;
 }
@@ -61,6 +100,7 @@ interface VocabLayersBundle {
 interface RelationsBundle {
   setMetadata(relationId: string, body: any): Promise<any>;
   deleteMetadata(relationId: string): Promise<any>;
+  patchMetadata(relationId: string, body: any): Promise<any>;
   setTarget(relationId: string, spanId: string): Promise<any>;
   get(relationId: string, asOf?: string): Promise<any>;
   delete(relationId: string): Promise<any>;
@@ -91,6 +131,7 @@ interface SpansBundle {
   bulkDelete(body: any[]): Promise<any>;
   setMetadata(spanId: string, body: any): Promise<any>;
   deleteMetadata(spanId: string): Promise<any>;
+  patchMetadata(spanId: string, body: any): Promise<any>;
 }
 
 interface BatchBundle {
@@ -100,6 +141,7 @@ interface BatchBundle {
 interface TextsBundle {
   setMetadata(textId: string, body: any): Promise<any>;
   deleteMetadata(textId: string): Promise<any>;
+  patchMetadata(textId: string, body: any): Promise<any>;
   create(textLayerId: string, documentId: string, body: string, metadata?: any): Promise<any>;
   get(textId: string, asOf?: string): Promise<any>;
   delete(textId: string): Promise<any>;
@@ -144,6 +186,7 @@ interface DocumentsBundle {
   deleteMedia(documentId: string): Promise<any>;
   setMetadata(documentId: string, body: any): Promise<any>;
   deleteMetadata(documentId: string): Promise<any>;
+  patchMetadata(documentId: string, body: any): Promise<any>;
   audit(documentId: string, startTime?: string, endTime?: string, asOf?: string): Promise<any[]>;
   get(documentId: string, includeBody?: boolean, asOf?: string): Promise<any>;
   delete(documentId: string): Promise<any>;
@@ -198,6 +241,7 @@ interface TextLayersBundle {
 interface VocabItemsBundle {
   setMetadata(id: string, body: any): Promise<any>;
   deleteMetadata(id: string): Promise<any>;
+  patchMetadata(id: string, body: any): Promise<any>;
   create(vocabLayerId: string, form: string, metadata?: any): Promise<any>;
   get(id: string, asOf?: string): Promise<any>;
   delete(id: string): Promise<any>;
@@ -226,6 +270,7 @@ interface TokensBundle {
   shift(tokenId: string, begin?: number, end?: number): Promise<any>;
   setMetadata(tokenId: string, body: any): Promise<any>;
   deleteMetadata(tokenId: string): Promise<any>;
+  patchMetadata(tokenId: string, body: any): Promise<any>;
 }
 
 interface PlaidClientOptions {
@@ -248,6 +293,9 @@ export declare class PlaidClient {
   enterStrictMode(documentId: string): void;
   exitStrictMode(): void;
 
+  // Query
+  query(body: any): Promise<any>;
+
   vocabLinks: VocabLinksBundle;
   vocabLayers: VocabLayersBundle;
   relations: RelationsBundle;
@@ -268,3 +316,64 @@ export declare class PlaidClient {
 }
 
 export default PlaidClient;
+
+// --- Unicode code-point helpers for text offsets ---------------------------
+// Token begin/end offsets are 0-based Unicode code-point indices (not UTF-16).
+/** Number of Unicode code points in `s` (not `s.length`). */
+export function cpLength(s: string): number;
+/** Substring of `s` by code-point indices [begin, end) (end optional). */
+export function cpSlice(s: string, begin: number, end?: number): string;
+/** Prebuilt slicer for many code-point slices of one string (spreads once). */
+export function cpSlicer(s: string): (begin: number, end?: number) => string;
+/** UTF-16 index -> code-point index in `s`. */
+export function utf16ToCp(s: string, u: number): number;
+/** Code-point index -> UTF-16 index in `s` (clamps past the end). */
+export function cpToUtf16(s: string, cp: number): number;
+/** Like indexOf, but the result and `fromCp` are code-point indices; -1 if absent. */
+export function cpIndexOf(s: string, sub: string, fromCp?: number): number;
+
+// --- Shared layer-role vocabulary (cross-app interoperability) --------------
+// Substrate layers are tagged with a role at `config.plaid.role` (a scalar) so
+// that different apps can share a project. See the manual, "Layer Interoperability".
+/** 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; only these values are interoperable across apps. */
+export const ROLES: {
+  readonly BASELINE: 'baseline';
+  readonly SENTENCE: 'sentence';
+  readonly WORD: 'word';
+  readonly SYNTACTIC_WORD: 'syntactic-word';
+  readonly MORPHEME: 'morpheme';
+  readonly TIME_ALIGNMENT: 'time-alignment';
+};
+/** The role recorded on a layer's `config`, or null if none. */
+export function readRole(config?: object): string | null;
+/** The first layer in `layers` carrying the given role, or null. */
+export function findByRole<T extends { config?: object }>(layers: T[] | undefined, role: string): T | null;
+
+// --- Service self-description helpers ----------------------------------------
+// Standardize how a service advertises (in `extras`) the tasks it serves, a
+// summary, and a parameter schema — so a UI can offer service selection, an
+// argument form, and a summary at a fixed integration point. See the manual,
+// "Describing a service".
+/** The controlled task vocabulary — the fixed integration-point goals. */
+export const TASKS: {
+  readonly TOKENIZE: 'tokenize';
+  readonly PARSE: 'parse';
+  readonly TRANSCRIBE: 'transcribe';
+  readonly LINK_VOCAB: 'link-vocab';
+};
+/** Whether a service serves a task (declared `extras.tasks`, legacy id-prefix fallback). */
+export function servesTask(service: DiscoveredService, task: string): boolean;
+/** The discovered services that serve `task`. */
+export function filterServicesByTask(services: DiscoveredService[] | undefined, task: string): DiscoveredService[];
+/** The parameter schema a service declares (ordered), or []. */
+export function getParamSchema(service: DiscoveredService): ServiceParam[];
+/** A service's human summary: `extras.summary`, else `description`, else ''. */
+export function getServiceSummary(service: DiscoveredService): string;
+/** Default form values keyed by param key. */
+export function buildDefaultValues(schema: ServiceParam[]): Record<string, any>;
+/** Coerce/validate raw form values against the schema. */
+export function coerceParamValues(schema: ServiceParam[], raw: Record<string, any>): { values: Record<string, any>; errors: Record<string, string> };

package/package.json

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

package/src/codepoint.js

@@ -0,0 +1,73 @@
+/**
+ * Unicode code-point helpers for working with Plaid text offsets.
+ *
+ * Plaid token offsets (`begin` / `end`) are 0-based indices in Unicode CODE
+ * POINTS (begin inclusive, end exclusive) — NOT UTF-16 code units. JavaScript
+ * strings are UTF-16, so `.length`, `.slice`, `.substring`, `s[i]`,
+ * `String.prototype.indexOf`, and `Intl.Segmenter`'s `index` all count UTF-16
+ * code units, which disagree with code points for astral characters
+ * (>= U+10000 — emoji, and SMP scripts such as Gothic, cuneiform, CJK Ext-B).
+ *
+ * Use these to slice a text body by token offsets, and to compute offsets for
+ * new tokens, in code points. The spread/`for…of` string iterator yields code
+ * points, which is what makes this work.
+ */
+
+/** Number of Unicode code points in `s` (not `s.length`, which is UTF-16). */
+export function cpLength(s) {
+  return [...s].length;
+}
+
+/**
+ * Substring of `s` by CODE-POINT indices [begin, end) (end optional = to end).
+ * Mirrors `String.prototype.slice` semantics but in code points.
+ */
+export function cpSlice(s, begin, end) {
+  return [...s].slice(begin, end).join('');
+}
+
+/**
+ * Prebuilt slicer for taking MANY code-point slices of the same string:
+ * spreads `s` into code points once, then each slice costs O(slice length).
+ * `cpSlice` spreads the whole string per call, which turns quadratic when a
+ * caller slices every token of a large text. Mirror of the server's
+ * `plaid.util.codepoint/cp-slicer`.
+ */
+export function cpSlicer(s) {
+  const chars = [...(s ?? '')];
+  return (begin, end) => chars.slice(begin, end).join('');
+}
+
+/**
+ * Convert a UTF-16 index `u` into `s` to a code-point index — i.e. how many
+ * code points precede `u`. Inverse of `cpToUtf16`. Useful for converting a
+ * DOM/`indexOf`/`Intl.Segmenter` (UTF-16) position into a code-point offset.
+ */
+export function utf16ToCp(s, u) {
+  return [...s.slice(0, u)].length;
+}
+
+/**
+ * Convert a code-point index `cp` into `s` to a UTF-16 index. Clamps to
+ * `s.length` when `cp` is past the end. Inverse of `utf16ToCp`.
+ */
+export function cpToUtf16(s, cp) {
+  if (cp <= 0) return 0;
+  let u = 0;
+  let c = 0;
+  for (const ch of s) {
+    if (c >= cp) break;
+    u += ch.length; // 1 for BMP, 2 for an astral code point (surrogate pair)
+    c += 1;
+  }
+  return u;
+}
+
+/**
+ * Like `String.prototype.indexOf`, but the returned index and `fromCp` are
+ * CODE-POINT indices. Returns -1 when `sub` is not found.
+ */
+export function cpIndexOf(s, sub, fromCp = 0) {
+  const u = s.indexOf(sub, cpToUtf16(s, fromCp));
+  return u < 0 ? -1 : utf16ToCp(s, u);
+}

package/src/index.js

@@ -71,6 +71,15 @@ class PlaidClient {
         this._request('DELETE', `/api/v1/vocab-links/${id}/metadata`, {
           skipResponseTransform: true,
         }),
+      /**
+       * Patch (shallow-merge) metadata for a vocab link. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * @param {string} id - The resource ID
+       * @param {any} body - The metadata patch
+       */
+      patchMetadata: (id, body) =>
+        this._request('PATCH', `/api/v1/vocab-links/${id}/metadata`, {
+          rawBody: body, skipResponseTransform: true,
+        }),
       /**
        * Get a vocab link by ID
        * @param {string} id - The resource ID
@@ -205,6 +214,15 @@ class PlaidClient {
         this._request('DELETE', `/api/v1/relations/${relationId}/metadata`, {
           skipResponseTransform: true,
         }),
+      /**
+       * Patch (shallow-merge) metadata for a relation. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * @param {string} relationId - The relation ID
+       * @param {any} body - The metadata patch
+       */
+      patchMetadata: (relationId, body) =>
+        this._request('PATCH', `/api/v1/relations/${relationId}/metadata`, {
+          rawBody: body, skipResponseTransform: true,
+        }),
       /**
        * Update the target span of a relation.
        * @param {string} relationId - The relation ID
@@ -416,6 +434,15 @@ class PlaidClient {
         this._request('DELETE', `/api/v1/spans/${spanId}/metadata`, {
           skipResponseTransform: true,
         }),
+      /**
+       * Patch (shallow-merge) metadata for a span. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * @param {string} spanId - The span ID
+       * @param {any} body - The metadata patch
+       */
+      patchMetadata: (spanId, body) =>
+        this._request('PATCH', `/api/v1/spans/${spanId}/metadata`, {
+          rawBody: body, skipResponseTransform: true,
+        }),
     };
 
     this.batch = {
@@ -448,6 +475,15 @@ class PlaidClient {
         this._request('DELETE', `/api/v1/texts/${textId}/metadata`, {
           skipResponseTransform: true,
         }),
+      /**
+       * Patch (shallow-merge) metadata for a text. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * @param {string} textId - The text ID
+       * @param {any} body - The metadata patch
+       */
+      patchMetadata: (textId, body) =>
+        this._request('PATCH', `/api/v1/texts/${textId}/metadata`, {
+          rawBody: body, skipResponseTransform: true,
+        }),
       /**
        * Create a new text in a document's text layer. A text is a container for
        * one long string in `body` for a given layer.
@@ -490,33 +526,37 @@ class PlaidClient {
 
     this.users = {
       /**
-       * List all users. Transparently follows pagination cursors and returns
-       * the full flat array.
+       * List (or search) users. Transparently follows pagination cursors and
+       * returns the full flat array. Admin-or-maintainer only.
        * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use listPage() for a single page in a batch.
-       * @param {string} [asOf] - Temporal query timestamp
+       * @param {object} [opts]
+       * @param {string} [opts.q] - Filter to usernames containing this text (case-insensitive)
+       * @param {string} [opts.asOf] - Temporal query timestamp
        */
-      list: (asOf) =>
-        listAll(this, '/api/v1/users', { query: { 'as-of': asOf } }),
+      list: ({ q, asOf } = {}) =>
+        listAll(this, '/api/v1/users', { query: { q, 'as-of': asOf } }),
       /**
-       * Fetch a single page of users.
+       * Fetch a single page of users (optionally filtered by `q`).
        * @param {object} [opts]
+       * @param {string} [opts.q] - Filter to usernames containing this text (case-insensitive)
        * @param {number} [opts.limit] - Page size (1..1000; server default 100)
        * @param {string} [opts.cursor] - Opaque cursor from a previous page
        * @param {string} [opts.asOf] - Temporal query timestamp
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
-      listPage: ({ limit, cursor, asOf } = {}) =>
-        listPage(this, '/api/v1/users', { limit, cursor, query: { 'as-of': asOf } }),
+      listPage: ({ q, limit, cursor, asOf } = {}) =>
+        listPage(this, '/api/v1/users', { limit, cursor, query: { q, 'as-of': asOf } }),
       /**
        * Async-iterate users page by page; yields each page's entries array.
        * @param {object} [opts]
+       * @param {string} [opts.q] - Filter to usernames containing this text (case-insensitive)
        * @param {number} [opts.pageSize] - Per-request page size
        * @param {string} [opts.asOf] - Temporal query timestamp
        * Cannot be used inside a batch (auto-paginates across requests); throws on first iteration if called while batching — use listPage() for a single page in a batch.
        * @returns {AsyncGenerator<Array>}
        */
-      iterPages: ({ pageSize, asOf } = {}) =>
-        iterPages(this, '/api/v1/users', { pageSize, query: { 'as-of': asOf } }),
+      iterPages: ({ q, pageSize, asOf } = {}) =>
+        iterPages(this, '/api/v1/users', { pageSize, query: { q, 'as-of': asOf } }),
       /**
        * Create a new user
        * @param {string} username - The username
@@ -550,11 +590,23 @@ class PlaidClient {
           queryParams: { 'as-of': asOf },
         }),
       /**
-       * Delete a user
+       * Deactivate a user. Users are never hard-deleted: deactivation
+       * rejects their logins and tokens, strips their project memberships
+       * and vocab maintainerships, and revokes their API tokens. The user
+       * stays visible in listings with a deactivated-at timestamp.
+       * Reversible via activate(), which restores login only.
        * @param {string} id - The resource ID
        */
       delete: (id) =>
         this._request('DELETE', `/api/v1/users/${id}`),
+      /**
+       * Reactivate a deactivated user, restoring their ability to log in.
+       * Project memberships, vocab maintainerships, and API tokens removed
+       * at deactivation are NOT restored — re-grant them deliberately.
+       * @param {string} id - The resource ID
+       */
+      activate: (id) =>
+        this._request('POST', `/api/v1/users/${id}/activate`),
       /**
        * Modify a user. Admins may change the username, password, and admin
        * status of any user. All other users may only modify their own username
@@ -760,6 +812,15 @@ class PlaidClient {
         this._request('DELETE', `/api/v1/documents/${documentId}/metadata`, {
           skipResponseTransform: true,
         }),
+      /**
+       * Patch (shallow-merge) metadata for a document. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * @param {string} documentId - The document ID
+       * @param {any} body - The metadata patch
+       */
+      patchMetadata: (documentId, body) =>
+        this._request('PATCH', `/api/v1/documents/${documentId}/metadata`, {
+          rawBody: body, skipResponseTransform: true,
+        }),
       /**
        * Get audit log for a document. Transparently follows pagination cursors
        * and returns the full flat array.
@@ -1086,6 +1147,15 @@ class PlaidClient {
         this._request('DELETE', `/api/v1/vocab-items/${id}/metadata`, {
           skipResponseTransform: true,
         }),
+      /**
+       * Patch (shallow-merge) metadata for a vocab item. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * @param {string} id - The resource ID
+       * @param {any} body - The metadata patch
+       */
+      patchMetadata: (id, body) =>
+        this._request('PATCH', `/api/v1/vocab-items/${id}/metadata`, {
+          rawBody: body, skipResponseTransform: true,
+        }),
       /**
        * Create a new vocab item
        * @param {string} vocabLayerId - The vocab layer ID
@@ -1194,10 +1264,16 @@ class PlaidClient {
        * using begin and end offsets. Tokens may be zero-width and may overlap.
        * For tokens sharing the same begin, precedence controls the linear
        * ordering.
+       *
+       * Offsets are 0-based indices in Unicode CODE POINTS (not UTF-16 code
+       * units): a supplementary-plane character (emoji, SMP script) is one
+       * position. JS strings are UTF-16, so do NOT use `str.length` /
+       * `str.substring` to compute offsets — count code points instead
+       * (e.g. `[...str].length`, or iterate with `codePointAt`).
        * @param {string} tokenLayerId - The token layer ID
        * @param {string} text - The text ID
-       * @param {number} begin - Start offset (inclusive)
-       * @param {number} end - End offset (exclusive)
+       * @param {number} begin - Start offset, inclusive (Unicode code points)
+       * @param {number} end - End offset, exclusive (Unicode code points)
        * @param {number} [precedence] - Ordering precedence
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
@@ -1224,8 +1300,8 @@ class PlaidClient {
       /**
        * Update a token.
        * @param {string} tokenId - The token ID
-       * @param {number} [begin] - New start offset
-       * @param {number} [end] - New end offset
+       * @param {number} [begin] - New start offset, inclusive (Unicode code points)
+       * @param {number} [end] - New end offset, exclusive (Unicode code points)
        * @param {?number} [precedence] - Ordering precedence. Omit (undefined)
        *   to leave unchanged; pass a number to set; pass null explicitly to
        *   CLEAR it (revert to no explicit ordering). bodyOf keeps null but
@@ -1248,10 +1324,10 @@ class PlaidClient {
       bulkDelete: (body) =>
         this._request('DELETE', '/api/v1/tokens/bulk', { body }),
       /**
-       * Split a token at a character offset. The original token becomes the left half
-       * (keeps its ID, spans, vocab-links); the new right token's ID is returned.
+       * Split a token at a Unicode code-point offset. The original token becomes the
+       * left half (keeps its ID, spans, vocab-links); the new right token's ID is returned.
        * @param {string} tokenId - The token ID
-       * @param {number} position - Offset to split at (strictly between begin and end)
+       * @param {number} position - Code-point offset to split at (strictly between begin and end)
        */
       split: (tokenId, position) =>
         this._request('POST', `/api/v1/tokens/${tokenId}/split`, {
@@ -1274,8 +1350,8 @@ class PlaidClient {
        * auto-adjusted to preserve the partition; on non-overlapping layers a shift that
        * would create an overlap is rejected.
        * @param {string} tokenId - The token ID
-       * @param {number} [begin] - New start offset
-       * @param {number} [end] - New end offset
+       * @param {number} [begin] - New start offset, inclusive (Unicode code points)
+       * @param {number} [end] - New end offset, exclusive (Unicode code points)
        */
       shift: (tokenId, begin, end) =>
         this._request('POST', `/api/v1/tokens/${tokenId}/shift`, {
@@ -1298,6 +1374,15 @@ class PlaidClient {
         this._request('DELETE', `/api/v1/tokens/${tokenId}/metadata`, {
           skipResponseTransform: true,
         }),
+      /**
+       * Patch (shallow-merge) metadata for a token. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * @param {string} tokenId - The token ID
+       * @param {any} body - The metadata patch
+       */
+      patchMetadata: (tokenId, body) =>
+        this._request('PATCH', `/api/v1/tokens/${tokenId}/metadata`, {
+          rawBody: body, skipResponseTransform: true,
+        }),
     };
 
     this.messages = {
@@ -1366,8 +1451,8 @@ class PlaidClient {
      *   await client.query({
      *     find: ['?s1', '?s2'],
      *     where: [
-     *       ['span', '?s1', { layer: 'pos', value: 'NOUN' }],
-     *       ['span', '?s2', { layer: 'pos', value: 'VERB' }],
+     *       ['span', '?s1', { layer: posLayerId, value: 'NOUN' }],
+     *       ['span', '?s2', { layer: posLayerId, value: 'VERB' }],
      *       ['covers', '?s1', '?t1'], ['covers', '?s2', '?t2'],
      *       ['precedes', '?t1', '?t2'],
      *     ],
@@ -1375,7 +1460,17 @@ class PlaidClient {
      *     limit: 100,
      *   });
      *
-     * @param {Object} body - The query AST ({find, where, scope?, limit?, return?}).
+     * A `layer` is referenced by its id (its UUID) only — not by name or
+     * path. To match a layer by name, bind it with a `*-layer` clause (e.g.
+     * `['span-layer', '?sl', { name: 'pos' }]`) and use the variable.
+     *
+     * Optional keys: `scope` (restrict to projects by id, `{projectIds}`), `orderBy`
+     * (sort rows), and `bindings` (substitute `?name` placeholders with literals).
+     * `return` may also be an aggregate spec `{group, aggregates}`. See the query
+     * language reference.
+     *
+     * @param {Object} body - The query AST ({find, where, scope?, limit?, orderBy?,
+     *   return?, bindings?}).
      * @returns {Promise<Object>} For 'ids'/'entities': {columns, results, count, truncated}.
      *   For 'count': {return: 'count', count}. Entity cells are full entity objects
      *   (same shape as the GET endpoints).
@@ -1530,3 +1625,20 @@ class PlaidClient {
 
 export default PlaidClient;
 export { PlaidClient };
+
+// Unicode code-point helpers for text offsets (token begin/end are code-point
+// indices). See ./codepoint.js.
+export { cpLength, cpSlice, cpSlicer, utf16ToCp, cpToUtf16, cpIndexOf } from './codepoint.js';
+export { PLAID_NAMESPACE, ROLE_KEY, ROLES, readRole, findByRole } from './roles.js';
+// Service self-description helpers: filter discovered services by task, read a
+// service's parameter schema/summary, and build/coerce form values. See
+// ./serviceSchema.js.
+export {
+  TASKS,
+  servesTask,
+  filterServicesByTask,
+  getParamSchema,
+  getServiceSummary,
+  buildDefaultValues,
+  coerceParamValues,
+} from './serviceSchema.js';

package/src/roles.js

@@ -0,0 +1,57 @@
+/**
+ * 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. */
+export const ROLES = Object.freeze({
+  BASELINE: 'baseline',
+  SENTENCE: 'sentence',
+  WORD: 'word',
+  SYNTACTIC_WORD: 'syntactic-word',
+  MORPHEME: 'morpheme',
+  TIME_ALIGNMENT: 'time-alignment',
+});
+
+/**
+ * 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) {
+  const v = config?.[PLAID_NAMESPACE]?.[ROLE_KEY];
+  return v == null ? null : v;
+}
+
+/**
+ * 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.
+ * @param {Array<{config?: object}>} [layers]
+ * @param {string} role
+ * @returns {object|null}
+ */
+export function findByRole(layers, role) {
+  return (layers || []).find(l => readRole(l?.config) === role) || null;
+}

package/src/serviceSchema.js

@@ -0,0 +1,206 @@
+/**
+ * Service self-description: tasks, summary, and a parameter schema.
+ *
+ * The service framework's transport carries an opaque `extras` JSON map on every
+ * registered service (see services.js). This module standardizes what a service
+ * advertises in that map so apps can, at a fixed integration point (a "task"
+ * like tokenize / parse / transcribe):
+ *
+ *   1. SELECT one of several services that serve the task,
+ *   2. let the user SPECIFY arguments the service declares, and
+ *   3. show the user a service-provided SUMMARY.
+ *
+ * Shape of a service's `extras` (camelCase here; Python services author the
+ * snake_case equivalent and the client transform converts it — see the Plaid
+ * manual, "Describing a service"):
+ *
+ *   {
+ *     schemaVersion: 1,
+ *     tasks: ["tokenize"],              // controlled vocab; REPLACES tok:/asr: id prefixes
+ *     summary: "## markdown …",         // rich human description
+ *     parameters: [                     // ordered; rendered into a form
+ *       { key, label, type, description?, default?, required?,
+ *         options?: [{value, label}],   // enum / multiselect
+ *         min?, max?, step?,            // number
+ *         placeholder?, multiline? }    // string
+ *     ]
+ *   }
+ *
+ * A parameter's `key` is a string VALUE, so it passes over the wire verbatim;
+ * the UI sends `{ [param.key]: value }` in the request data. Declare each `key`
+ * in your service's own convention (Python: snake_case; JS: camelCase) and read
+ * it back under that same key — request data is recased symmetrically, so a
+ * snake_case key round-trips unchanged to a JS UI and back.
+ */
+
+/** The controlled task vocabulary — the fixed integration-point goals. */
+export const TASKS = Object.freeze({
+  TOKENIZE: 'tokenize',
+  PARSE: 'parse',
+  TRANSCRIBE: 'transcribe',
+  /** Create vocab links for unlinked tokens. Services should stamp link
+   * metadata with the provenance convention ({ prov: 'inferred', provSource:
+   * 'service:<id>' }) so UIs can distinguish machine links until confirmed. */
+  LINK_VOCAB: 'link-vocab',
+});
+
+/**
+ * Legacy id-prefix → task map, for services that have not yet migrated to a
+ * declared `tasks` array. Drop once all services advertise `tasks`.
+ */
+const LEGACY_TASK_PREFIXES = Object.freeze({
+  [TASKS.TOKENIZE]: 'tok:',
+  [TASKS.TRANSCRIBE]: 'asr:',
+});
+
+/**
+ * Does `service` serve `task`? Prefers the declared `extras.tasks` array; falls
+ * back to the legacy id-prefix convention for un-migrated services.
+ * @param {{serviceId?: string, extras?: {tasks?: string[]}}} service
+ * @param {string} task one of TASKS
+ * @returns {boolean}
+ */
+export function servesTask(service, task) {
+  const declared = service?.extras?.tasks;
+  if (Array.isArray(declared) && declared.length) {
+    return declared.includes(task);
+  }
+  const prefix = LEGACY_TASK_PREFIXES[task];
+  return !!prefix && typeof service?.serviceId === 'string' && service.serviceId.startsWith(prefix);
+}
+
+/**
+ * The discovered services that serve `task`.
+ * @param {Array} services result of client.messages.discoverServices()
+ * @param {string} task one of TASKS
+ * @returns {Array}
+ */
+export function filterServicesByTask(services, task) {
+  return (services || []).filter((s) => servesTask(s, task));
+}
+
+/**
+ * The parameter schema a service declares (ordered array), or [].
+ * @param {{extras?: {parameters?: Array}}} service
+ * @returns {Array}
+ */
+export function getParamSchema(service) {
+  const params = service?.extras?.parameters;
+  return Array.isArray(params) ? params : [];
+}
+
+/**
+ * A service's human summary: the rich `extras.summary`, else the short
+ * `description`, else ''.
+ * @param {{description?: string, extras?: {summary?: string}}} service
+ * @returns {string}
+ */
+export function getServiceSummary(service) {
+  return service?.extras?.summary || service?.description || '';
+}
+
+/** Valid option values for an enum/multiselect param. */
+function optionValues(param) {
+  return Array.isArray(param?.options) ? param.options.map((o) => o.value) : [];
+}
+
+/**
+ * A single parameter's default, honoring its declared `default` then falling
+ * back per type. For enum/multiselect the declared default is validated against
+ * `options` (an out-of-range declared default never escapes).
+ */
+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 === '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;
+  switch (param.type) {
+    case 'number': return typeof param.min === 'number' ? param.min : 0;
+    case 'boolean': return false;
+    case 'string':
+    default: return '';
+  }
+}
+
+/**
+ * Default values keyed by param key — the initial form state.
+ * @param {Array} schema getParamSchema(service)
+ * @returns {Object} { [key]: defaultValue }
+ */
+export function buildDefaultValues(schema) {
+  const out = {};
+  for (const param of schema || []) {
+    if (!param || !param.key) continue;
+    out[param.key] = defaultForParam(param);
+  }
+  return out;
+}
+
+/**
+ * Coerce/validate raw form values against the schema. Returns the cleaned
+ * values (keyed by param key, ready to merge into the request payload) plus any
+ * validation errors keyed by param key. Unknown keys in `raw` are dropped.
+ * @param {Array} schema getParamSchema(service)
+ * @param {Object} raw current form values
+ * @returns {{values: Object, errors: Object}}
+ */
+export function coerceParamValues(schema, raw) {
+  const values = {};
+  const errors = {};
+  const src = raw || {};
+  for (const param of schema || []) {
+    if (!param || !param.key) continue;
+    const k = param.key;
+    let v = src[k];
+    if (v === undefined) v = defaultForParam(param);
+
+    switch (param.type) {
+      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() === '')) {
+          n = defaultForParam(param);
+        } else {
+          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);
+        v = n;
+        break;
+      }
+      case 'boolean':
+        v = v === true || v === 'true';
+        break;
+      case 'enum': {
+        const opts = optionValues(param);
+        if (opts.length && !opts.includes(v)) v = defaultForParam(param);
+        break;
+      }
+      case 'multiselect': {
+        const opts = optionValues(param);
+        const arr = Array.isArray(v) ? v : (v == null || v === '' ? [] : [v]);
+        v = opts.length ? arr.filter((x) => opts.includes(x)) : arr;
+        break;
+      }
+      case 'string':
+      default:
+        v = v == null ? '' : String(v);
+        break;
+    }
+
+    if (param.required) {
+      const empty = v === '' || v == null || (Array.isArray(v) && v.length === 0);
+      if (empty) errors[k] = `${param.label || k} is required`;
+    }
+    values[k] = v;
+  }
+  return { values, errors };
+}

package/src/transforms.js

@@ -25,7 +25,7 @@ export function transformKeyFromCamel(key) {
 // are never re-cased or namespace-stripped — a label like `case-marker` used as
 // a map key survives intact. Everything else is API envelope and gets the
 // usual case conversion.
-const OPAQUE_KEYS = new Set(['metadata', 'config']);
+const OPAQUE_KEYS = new Set(['metadata', 'config', 'bindings']);
 
 /**
  * Recursively transform request object keys from camelCase to kebab-case.