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

package/src/provenance.js

@@ -0,0 +1,123 @@
+/**
+ * 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.
+ *
+ * Three states (the PRESENCE of the `prov` key, not its value, is the
+ * discriminator; absent keys mean "human"):
+ *
+ *   human              — no prov keys; a person 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.
+ *
+ * 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).
+ *
+ * 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.
+ *
+ * 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).
+ */
+
+/** The flat metadata keys of the provenance convention. */
+export const PROV = Object.freeze({
+  /** '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',
+  /** The (currently only) value of `prov`. Presence, not value, decides. */
+  INFERRED: 'inferred',
+});
+
+/** The three provenance states returned by provState. */
+export const PROV_STATES = Object.freeze({
+  HUMAN: 'human',
+  MACHINE: 'machine',
+  VERIFIED: 'verified',
+});
+
+/**
+ * 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)
+ * @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 } : {}),
+});
+
+/**
+ * The fragment for machine-made material that is born verified (e.g. an
+ * import carrying upstream human approval, or a guess written only on
+ * explicit user confirmation). Takes the same optional prediction extras
+ * as stampInferred.
+ */
+export const confirmedInferred = (source, extras = {}) => ({
+  ...stampInferred(source, extras),
+  [PROV.confirmedKey]: true,
+});
+
+/**
+ * Classify an entity's metadata into one of PROV_STATES.
+ * @param {Object|null|undefined} metadata
+ * @returns {'human'|'machine'|'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;
+};
+
+/**
+ * Whether a machine writer must leave this entity alone (write-contract
+ * rule 2): true for human-made and human-verified material.
+ */
+export const isProtected = (metadata) => provState(metadata) !== PROV_STATES.MACHINE;
+
+/**
+ * The metadata fragment a HUMAN edit of this entity should merge in
+ * (write-contract rule 3): { provConfirmed: true } when the entity is
+ * machine-made and unverified, else null (nothing to do).
+ */
+export const verifyOnEdit = (metadata) =>
+  (provState(metadata) === PROV_STATES.MACHINE ? { [PROV.confirmedKey]: true } : null);
+
+/** Canonical provSource for a service: 'service:<serviceId>'. */
+export const serviceSource = (serviceId) => `service:${serviceId}`;

package/src/serviceSchema.js

@@ -33,14 +33,20 @@
  * snake_case key round-trips unchanged to a JS UI and back.
  */
 
-/** The controlled task vocabulary — the fixed integration-point goals. */
+/**
+ * The controlled task vocabulary — the fixed integration-point goals.
+ *
+ * Whatever the task, a service should stamp everything it creates with the
+ * provenance convention (see ./provenance.js: stampInferred(serviceSource(id)))
+ * so UIs can distinguish machine output until a human verifies it, and should
+ * honor the write contract: never destroy human-made or verified material
+ * without an explicit `overwrite` parameter. See the manual, "Provenance".
+ */
 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. */
+  /** Create vocab links for unlinked tokens. */
   LINK_VOCAB: 'link-vocab',
 });
 

package/src/services.js

@@ -11,18 +11,34 @@
 import { transformRequest, transformResponse } from './transforms.js';
 
 /**
- * Discover the services currently connected to a project — a synchronous GET.
- * `timeout` is accepted for back-compat and ignored.
+ * Discover the services seen on a project — a synchronous GET. Returns every
+ * service ever registered on the project: currently connected ones carry
+ * `online: true`; previously-seen offline ones carry `online: false` plus a
+ * `lastSeenAt` stamp. Callers that need a service they can actually submit
+ * work to should filter on `online`.
  *
  * @param {Object} client - PlaidClient instance
  * @param {string} projectId - Project UUID
- * @param {number} [timeout] - Ignored
- * @returns {Promise<Array>} [{serviceId, serviceName, description, extras}]
+ * @returns {Promise<Array>} [{serviceId, serviceName, description, extras, online, lastSeenAt}]
  */
-export function discoverServices(client, projectId, timeout) {
+export function discoverServices(client, projectId) {
   return client._request('GET', `/api/v1/projects/${projectId}/services`);
 }
 
+/**
+ * Forget a previously-seen (offline) service: removes its row from the
+ * project's persistent registry. Maintainer-only; 409 if the service is
+ * currently connected (it would just re-register).
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {string} serviceId - Service ID to forget
+ * @returns {Promise<void>}
+ */
+export function discardService(client, projectId, serviceId) {
+  return client._request('DELETE', `/api/v1/projects/${projectId}/services/${encodeURIComponent(serviceId)}`);
+}
+
 /**
  * Register a service and handle incoming work requests.
  *

package/src/sse.js

@@ -75,6 +75,13 @@ export function createSSEConnection(client, projectId, onEvent, path) {
       });
 
       if (!response.ok) {
+        if (response.status === 409 && streamPath.includes('/services/')) {
+          // Service channel rejected: another live instance holds this
+          // service-id. The serve() reconnect timer will retry — once the
+          // other instance is gone (or its dead channel is reaped) the retry
+          // takes over.
+          console.warn('Service registration rejected (409): another instance of this service is already connected; will retry');
+        }
         throw new Error(`HTTP ${response.status} ${response.statusText}`);
       }