@larc-iu/plaid-client 0.2.0-alpha.3 → 0.2.0-alpha.32

package/src/provenance.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Provenance: the cross-app convention for distinguishing machine-provided
+ * from human-labeled information, expressed as flat metadata keys on
+ * annotation entities (spans, relations, vocab links, optionally tokens).
+ * Flat scalar keys — the query engine matches flat metadata well, nested
+ * objects poorly.
+ *
+ * Two axes. ORIGIN is the `prov` key: absent means a trusted person (a
+ * verifier) made it; 'inferred' means an algorithm or service did;
+ * 'contributed' means a person whose work the project reviews (a
+ * contributor) did. TRUST is `provConfirmed`: true once a verifier vouched
+ * for the value. Together they give four states:
+ *
+ *   human              — no prov keys; a verifier made it.
+ *   machine            — { prov: 'inferred', provSource: '<producer>' };
+ *                        an algorithm/service made it, nobody has vouched.
+ *   contributed        — { prov: 'contributed', provSource: 'user:<id>' };
+ *                        a contributor made it, no verifier has vouched.
+ *   verified           — either origin + { provConfirmed: true }; a verifier
+ *                        confirmed (or edited) it. prov/provSource stay so
+ *                        the origin remains traceable.
+ *
+ * The write contract every machine writer must follow:
+ *   1. Machine writers may freely replace MACHINE (unverified) material.
+ *   2. Machine writers must never modify or delete human, contributed or
+ *      verified material unless explicitly told to overwrite (an explicit,
+ *      per-run, user-facing opt-in — for services, a declared boolean
+ *      `overwrite` parameter). A contributor's work is a person's work.
+ *   3. A verifier's edit of machine or contributed material verifies it:
+ *      the edit also stamps { provConfirmed: true } (see verifyOnEdit).
+ *      A contributor's edit of anything marks it contributed: the edit
+ *      merges stampContributed(userId) and drops any earlier confirmation
+ *      (see contributeOnEdit). Who is a contributor is the PROJECT's call,
+ *      recorded once for every app (see "Review" below); a service running
+ *      as a contributor should stamp likewise.
+ *
+ * REVIEW: which people are contributors. A project records it under the
+ * reserved `plaid` config namespace, so every app that writes on a person's
+ * behalf reads the same answer:
+ *
+ *   config.plaid.review = { users: [userId, ...], roles: ['writer', ...] }
+ *
+ * `users` names people whose work is reviewed whatever their role; `roles`
+ * names whole project roles ('reader' | 'writer' | 'maintainer'; an admin
+ * without an explicit role counts as a maintainer). Either may be absent.
+ * Nothing here grants or denies access: the ACL lists stay the permission
+ * model, and this only says whose work needs a verifier's look. Apps expose
+ * it as a per-member mark on their access screens (readReview, isReviewed,
+ * withReviewedUser) and derive the writer's policy from it (writerPolicy).
+ *
+ * Producer naming: 'service:<serviceId>' for services (use serviceSource),
+ * 'rule:<name>' for built-in rule algorithms, 'user:<userId>' for a
+ * contributor (use userSource), app-specific ids like 'gloss:doc-frequency'
+ * or 'flex-import' otherwise.
+ *
+ * PREDICTION EXTRAS. A producer may also record how confident it was and
+ * what else it considered, in two reserved slots split along the
+ * queryability line:
+ *   - provProb: ONE flat number in [0, 1] — the producer's probability for
+ *     the value it chose. Flat scalars are what the query engine filters
+ *     and orders on, so "review the least-confident machine output first"
+ *     is an ordinary query. Omit it unless you can honestly produce a
+ *     probability (a raw logprob is NOT one — put it in provDetail), 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).
+ * 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
+ * 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).
+ *   - 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
+ *     machine writer records both, one of rules alone only version.
+ *   - anything else (language, adapter, raw scores).
+ */
+/** The flat metadata keys of the provenance convention. */
+export const PROV: Readonly<{
+    /** 'inferred' when produced by an algorithm/service; absent = human. */
+    key: "prov";
+    /** Which producer, e.g. 'service:<id>', 'rule:precedent-or-unique'. */
+    sourceKey: "provSource";
+    /** true once a human confirmed (or edited) the inferred value. */
+    confirmedKey: "provConfirmed";
+    /** Producer's probability ([0,1]) for the chosen value. Flat = queryable. */
+    probKey: "provProb";
+    /** Open map of producer extras (alternatives, model version, raw scores). */
+    detailKey: "provDetail";
+    /** `prov` for machine-made material. Any value but CONTRIBUTED reads as machine. */
+    INFERRED: "inferred";
+    /** `prov` for a contributor's material. */
+    CONTRIBUTED: "contributed";
+}>;
+/**
+ * Every provenance key, for a caller that has to name them as a set rather
+ * than read one: what a token layer declares under
+ * `config.plaid.preserveOnSplit` so a token born of a split inherits the
+ * origin of the token it came from, and what a reshape carries by hand.
+ *
+ * Provenance is the one metadata family Plaid itself owns. The user cannot
+ * maintain it, and in a shared project usually cannot even see it, since it
+ * may belong to an app they are not using. Everything else on an entity is
+ * the user's own content and no structural operation should touch it.
+ */
+export const PROVENANCE_KEYS: readonly ("prov" | "provSource" | "provConfirmed" | "provProb" | "provDetail")[];
+/** The four provenance states returned by provState. */
+export const PROV_STATES: Readonly<{
+    HUMAN: "human";
+    MACHINE: "machine";
+    CONTRIBUTED: "contributed";
+    VERIFIED: "verified";
+}>;
+export function stampInferred(source: string, { prob, detail }?: {
+    prob?: number;
+    detail?: any;
+}): {
+    provDetail?: any;
+    provProb?: number;
+    prov: "inferred";
+    provSource: string;
+};
+export function confirmedInferred(source: string, extras?: {
+    prob?: number;
+    detail?: Record<string, any>;
+}): {
+    provConfirmed: boolean;
+    provDetail?: any;
+    provProb?: number;
+    prov: "inferred";
+    provSource: string;
+};
+/**
+ * The metadata fragment that verifies machine-made material:
+ * { provConfirmed: true }. Merge (PATCH) it over existing metadata so
+ * prov/provSource/provProb/provDetail survive. This is what verifyOnEdit
+ * returns for machine-unverified material; use it directly for explicit
+ * confirmation gestures (a "confirm" button, confirm-on-touch) where the
+ * caller has already checked isMachine.
+ */
+export const PROV_CONFIRMED: Readonly<{
+    provConfirmed: true;
+}>;
+export function stampContributed(userId: string): {
+    prov: "contributed";
+    provSource: string;
+};
+export function provState(metadata: object | null | undefined): "human" | "machine" | "contributed" | "verified";
+export function provOrigin(metadata: object | null | undefined): null | "inferred" | "contributed";
+export function isMachine(metadata: object | null | undefined): boolean;
+export function isProtected(metadata: object | null | undefined): boolean;
+export function needsReview(metadata: object | null | undefined): boolean;
+export function verifyOnEdit(metadata: object | null | undefined): Readonly<{
+    provConfirmed: true;
+}>;
+export function contributeOnEdit(metadata: object | null | undefined, userId: string): {
+    prov: "contributed";
+    provSource: string;
+    provConfirmed: null;
+};
+export function serviceSource(serviceId: string): string;
+export function userSource(userId: string): string;
+/** The config key, under the `plaid` namespace, holding the review lists. */
+export const REVIEW_KEY: "review";
+export function readReview(config?: object | null): {
+    users: string[];
+    roles: string[];
+};
+export function reviewsAnyone(config?: object | null): boolean;
+export function projectRole(project: object, userId: string, { isAdmin }?: {
+    isAdmin?: boolean;
+}): "maintainer" | "writer" | "reader";
+export function isReviewed(project: object | null | undefined, userId: string | null | undefined, { isAdmin }?: {
+    isAdmin?: boolean;
+}): boolean;
+export function withReviewedUser(review: {
+    users?: string[];
+    roles?: string[];
+} | null | undefined, userId: string, reviewed: boolean): {
+    users: string[];
+    roles: string[];
+};
+/**
+ * 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;
+};