plumb-line-provenance 0.2.0

package/README.md

@@ -0,0 +1,27 @@
+# plumb-line-provenance (JavaScript)
+
+A conservative provenance / confidence / lineage envelope with a
+taint-propagation combination law: once any input is mock or low-confidence,
+every value derived from it inherits that taint automatically — there is no
+escape hatch that silently clears the flag.
+
+```js
+import { mark, derive, metaOf, auditMeta } from "plumb-line-provenance";
+
+const base  = mark(1000, { source: "real", confidence: "high" });
+const rate  = mark(1.25, { source: "mock", confidence: "low" });
+const total = derive([base, rate], (a, r) => a * r);
+
+total.derivedFromMock; // true  — inherited from rate, cannot be cleared
+total.confidence;      // 'low' — only as certain as the weakest input
+auditMeta(metaOf(total)); // []  — internally consistent
+```
+
+You can also copy the `.mjs` files directly into a project and import them
+relatively; both styles work.
+
+- **Specification:** [`SPEC.md`](https://github.com/effythealien/plumb-line/blob/main/primitives/SPEC.md) (envelope schema version 1)
+- **Model, law, examples:** [`README.md`](https://github.com/effythealien/plumb-line/blob/main/primitives/README.md)
+- **License:** Apache-2.0
+
+Python parity package: `plumb-line-provenance` on PyPI.

package/audit.mjs

@@ -0,0 +1,74 @@
+// audit.mjs — runtime consistency checker for provenance metadata.
+import {
+  CONFIDENCE,
+  STATUS,
+  weakestConfidence,
+  weakestSource,
+  isScore,
+} from "./provenance.mjs";
+
+const CLEAN_SOURCES = ["real", "semiReal", "fallback"];
+
+export function auditMeta(meta) {
+  if (!meta) return ["missing meta"];
+  const issues = [];
+  const lineage = Array.isArray(meta.lineage) ? meta.lineage : [];
+
+  if (CLEAN_SOURCES.includes(meta.source) && meta.derivedFromMock === true) {
+    issues.push(
+      `laundering: clean source '${meta.source}' but derivedFromMock is true`,
+    );
+  }
+
+  const lineageConfidences = lineage
+    .map((s) => s?.confidence)
+    .filter((c) => CONFIDENCE.includes(c));
+  if (lineageConfidences.length > 0) {
+    const weakest = weakestConfidence(...lineageConfidences);
+    if (CONFIDENCE.indexOf(meta.confidence) > CONFIDENCE.indexOf(weakest)) {
+      issues.push(
+        `over-claiming: confidence '${meta.confidence}' exceeds weakest lineage confidence '${weakest}'`,
+      );
+    }
+  }
+
+  // Numeric over-claiming — the higher-resolution analog of the ordinal check.
+  if (isScore(meta.confidenceScore)) {
+    const lineageScores = lineage
+      .map((s) => s?.confidenceScore)
+      .filter((c) => isScore(c));
+    if (lineageScores.length > 0) {
+      const weakest = Math.min(...lineageScores);
+      if (meta.confidenceScore > weakest) {
+        issues.push(
+          `over-claiming: confidenceScore ${meta.confidenceScore} exceeds weakest lineage score ${weakest}`,
+        );
+      }
+    }
+  }
+
+  // Source over-claim — weakestSource cannot look cleaner than the lineage proves.
+  if (STATUS.includes(meta.weakestSource)) {
+    const actual = weakestSource(...lineage.map((s) => s?.source));
+    if (actual && STATUS.indexOf(meta.weakestSource) > STATUS.indexOf(actual)) {
+      issues.push(
+        `source over-claim: weakestSource '${meta.weakestSource}' is cleaner than lineage's '${actual}'`,
+      );
+    }
+  }
+
+  const lineageTainted = lineage.some(
+    (s) => Boolean(s?.derivedFromMock) || s?.source === "mock",
+  );
+  if (lineageTainted && meta.derivedFromMock === false) {
+    issues.push(
+      "taint dropped: lineage contains a tainted step but derivedFromMock is false",
+    );
+  }
+
+  if (meta.source === "derived" && lineage.length === 0) {
+    issues.push("unreproducible: derived value has no lineage");
+  }
+
+  return issues;
+}

package/index.mjs

@@ -0,0 +1,3 @@
+export * from "./provenance.mjs";
+export * from "./marked.mjs";
+export * from "./audit.mjs";

package/marked.mjs

@@ -0,0 +1,49 @@
+// marked.mjs — thin wrapper sugar over the provenance law. The law lives in provenance.mjs.
+import { combineProvenance, makeMeta } from "./provenance.mjs";
+
+const META_KEYS = [
+  "source",
+  "confidence",
+  "confidenceScore",
+  "derivedFromMock",
+  "lineage",
+  "weakestSource",
+  "basis",
+  "adapter",
+];
+
+// Only these keys may be supplied as overrides to derive(). lineage and
+// weakestSource always come from the computed combineProvenance result;
+// derivedFromMock taint cannot be cleared through an override.
+const OVERRIDE_KEYS = ["source", "confidence", "confidenceScore", "basis", "adapter"];
+
+export function mark(value, metaInput = {}) {
+  return { value, ...makeMeta(metaInput) };
+}
+
+export function unwrap(marked) {
+  return marked?.value;
+}
+
+export function metaOf(marked) {
+  const meta = {};
+  for (const key of META_KEYS)
+    if (key in (marked || {})) meta[key] = marked[key];
+  return meta;
+}
+
+export function derive(inputs, fn, metaOverride = {}) {
+  const value = fn(...inputs.map(unwrap));
+  const combined = combineProvenance(...inputs.map(metaOf));
+  const safeOverride = {};
+  for (const key of OVERRIDE_KEYS) {
+    if (key in metaOverride) safeOverride[key] = metaOverride[key];
+  }
+  const merged = {
+    ...combined,
+    ...safeOverride,
+    derivedFromMock:
+      combined.derivedFromMock || Boolean(metaOverride.derivedFromMock),
+  };
+  return { value, ...merged };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "plumb-line-provenance",
+  "version": "0.2.0",
+  "description": "Conservative provenance/confidence/lineage envelope with a taint-propagation combination law. Mock or low-confidence data cannot launder itself clean.",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "provenance.mjs",
+    "marked.mjs",
+    "audit.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "prepublishOnly": "vitest run"
+  },
+  "keywords": [
+    "provenance",
+    "lineage",
+    "confidence",
+    "epistemic-honesty",
+    "reproducibility",
+    "data-quality"
+  ],
+  "author": "Aoife Okonedo Martin",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/effythealien/plumb-line/tree/main/primitives",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/effythealien/plumb-line.git",
+    "directory": "primitives/js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "devDependencies": {
+    "vitest": "^2.0.0"
+  }
+}

package/provenance.mjs

@@ -0,0 +1,126 @@
+// provenance.mjs — the provenance/lineage law (single source).
+
+// Schema version of the provenance metadata envelope (Principle 7). Declared so
+// consumers can pin to a shape; embedding it per-meta and validating against it
+// is planned.
+export const PROVENANCE_VERSION = 1;
+
+export const STATUS = [
+  "unavailable",
+  "mock",
+  "fallback",
+  "semiReal",
+  "derived",
+  "real",
+];
+export const CONFIDENCE = ["none", "low", "medium", "high"];
+
+export function isScore(x) {
+  return typeof x === "number" && Number.isFinite(x) && x >= 0 && x <= 1;
+}
+
+export function makeMeta({
+  source = "derived",
+  confidence = "none",
+  confidenceScore,
+  derivedFromMock,
+  lineage = [],
+  weakestSource,
+  basis,
+  adapter,
+} = {}) {
+  const meta = {
+    source,
+    confidence,
+    derivedFromMock:
+      derivedFromMock === undefined
+        ? source === "mock"
+        : Boolean(derivedFromMock),
+    lineage: Array.isArray(lineage) ? [...lineage] : [],
+  };
+  // Optional numeric confidence — a finer-grained companion to the ordinal
+  // `confidence`, never a replacement. Stored only when it is a valid score.
+  if (isScore(confidenceScore)) meta.confidenceScore = confidenceScore;
+  // Computed-only resolution beyond the derivedFromMock boolean; passed through
+  // here so chained derives carry it, but never settable as a derive override.
+  if (STATUS.includes(weakestSource)) meta.weakestSource = weakestSource;
+  if (basis !== undefined) meta.basis = basis;
+  if (adapter !== undefined) meta.adapter = adapter;
+  return meta;
+}
+
+export function weakestConfidence(...levels) {
+  if (levels.length === 0) return "none";
+  let minIdx = CONFIDENCE.length - 1;
+  for (const level of levels) {
+    const idx = CONFIDENCE.indexOf(level);
+    minIdx = Math.min(minIdx, idx === -1 ? 0 : idx);
+  }
+  return CONFIDENCE[minIdx];
+}
+
+export function taints(meta) {
+  return Boolean(meta?.derivedFromMock) || meta?.source === "mock";
+}
+
+// Least-trustworthy source among the given values, ranked by STATUS. Unknown
+// values are ignored; returns undefined when nothing is rankable.
+export function weakestSource(...sources) {
+  let minIdx = STATUS.length;
+  for (const s of sources) {
+    const idx = STATUS.indexOf(s);
+    if (idx !== -1) minIdx = Math.min(minIdx, idx);
+  }
+  return minIdx === STATUS.length ? undefined : STATUS[minIdx];
+}
+
+// Conservative numeric floor: the minimum, but only when every input carries a
+// score. A missing score is "unknown" and cannot be dropped from a min, so any
+// gap yields undefined (omit) rather than an over-claim.
+export function combineConfidenceScore(scores) {
+  if (scores.length === 0 || !scores.every(isScore)) return undefined;
+  return Math.min(...scores);
+}
+
+let __stepCounter = 0;
+export function __resetStepCounter() {
+  __stepCounter = 0;
+}
+function nextStepId() {
+  __stepCounter += 1;
+  return `step-${__stepCounter}`;
+}
+
+export function combineProvenance(...metas) {
+  const derivedFromMock = metas.some((m) => taints(m));
+  const confidence = weakestConfidence(...metas.map((m) => m?.confidence));
+  const confidenceScore = combineConfidenceScore(
+    metas.map((m) => m?.confidenceScore),
+  );
+  const priorLineage = metas.flatMap((m) =>
+    Array.isArray(m?.lineage) ? m.lineage : [],
+  );
+  const inputSteps = metas.map((m) => {
+    const step = {
+      id: nextStepId(),
+      of: "input",
+      source: m?.source,
+      confidence: m?.confidence,
+      derivedFromMock: taints(m),
+    };
+    // Record the numeric score too when the input carries one, so the numeric
+    // over-claim audit works on real derive output, not just hand-built metas.
+    if (isScore(m?.confidenceScore)) step.confidenceScore = m.confidenceScore;
+    return step;
+  });
+  const lineage = [...priorLineage, ...inputSteps];
+  return makeMeta({
+    source: "derived",
+    confidence,
+    confidenceScore,
+    derivedFromMock,
+    lineage,
+    // Weakest source anywhere in the ancestry, read off the full lineage.
+    weakestSource: weakestSource(...lineage.map((s) => s?.source)),
+  });
+}