plumb-line-provenance 0.3.1 → 0.4.1

package/audit.mjs

@@ -9,8 +9,21 @@ import {
 
 const CLEAN_SOURCES = ["real", "semiReal", "fallback"];
 
+/**
+ * Checks a provenance metadata envelope for internal consistency.
+ * Returns an empty array when the envelope is consistent; otherwise returns
+ * one string per issue found. Issue prefixes:
+ * - `"laundering:"` — a clean source combined with mock taint
+ * - `"over-claiming:"` — confidence or confidenceScore higher than lineage supports
+ * - `"source over-claim:"` — weakestSource cleaner than lineage proves
+ * - `"taint dropped:"` — a tainted lineage step but derivedFromMock is false
+ * - `"unreproducible:"` — source is "derived" but lineage is empty
+ * - `"missing meta"` — input is not a plain object (null, undefined, or a non-object)
+ * @param {object|null|undefined} meta - Envelope to audit
+ * @returns {string[]} List of issue descriptions; empty means consistent
+ */
 export function auditMeta(meta) {
-  if (!meta) return ["missing meta"];
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) return ["missing meta"];
   const issues = [];
   const lineage = Array.isArray(meta.lineage) ? meta.lineage : [];
 
@@ -77,3 +90,34 @@ export function auditMeta(meta) {
 
   return issues;
 }
+
+// The four required fields (SPEC §1) and their type predicates, in the order
+// they appear in the envelope table.
+const REQUIRED_FIELDS = [
+  ["source", (v) => typeof v === "string", "a string"],
+  ["confidence", (v) => typeof v === "string", "a string"],
+  ["derivedFromMock", (v) => typeof v === "boolean", "a boolean"],
+  ["lineage", (v) => Array.isArray(v), "an array"],
+];
+
+// validateEnvelope — the *structural* checker, complementary to auditMeta.
+// auditMeta verifies logical consistency among the fields that ARE present and
+// tolerates absence as "unknown" (SPEC §2); it therefore passes a structurally
+// empty `{}`. validateEnvelope verifies the four required fields (SPEC §1) are
+// present and well-typed. Like auditMeta it is total: it returns a list of issue
+// strings (empty = structurally valid) and never throws.
+export function validateEnvelope(meta) {
+  if (meta === null || meta === undefined) return ["missing meta"];
+  if (typeof meta !== "object" || Array.isArray(meta)) {
+    return ["not an envelope object"];
+  }
+  const issues = [];
+  for (const [name, ok, typeLabel] of REQUIRED_FIELDS) {
+    if (!(name in meta)) {
+      issues.push(`missing required field: ${name}`);
+    } else if (!ok(meta[name])) {
+      issues.push(`field '${name}' must be ${typeLabel}`);
+    }
+  }
+  return issues;
+}

package/marked.mjs

@@ -17,14 +17,33 @@ const META_KEYS = [
 // derivedFromMock taint cannot be cleared through an override.
 const OVERRIDE_KEYS = ["source", "confidence", "confidenceScore", "basis", "adapter"];
 
+/**
+ * Wraps a value with provenance metadata, producing a marked value object.
+ * The returned object is frozen; its `value` property holds the original value
+ * and the remaining properties are the metadata envelope fields.
+ * @param {*} value - Any value to track
+ * @param {object} [metaInput={}] - Initial metadata; same options as {@link makeMeta}
+ * @returns {Readonly<{value: *, source: string, confidence: string, derivedFromMock: boolean, lineage: object[]}>}
+ */
 export function mark(value, metaInput = {}) {
   return Object.freeze({ value, ...makeMeta(metaInput) });
 }
 
+/**
+ * Extracts the raw value from a marked object.
+ * @param {object} marked - A value produced by {@link mark} or {@link derive}
+ * @returns {*} The unwrapped value
+ */
 export function unwrap(marked) {
   return marked?.value;
 }
 
+/**
+ * Extracts the provenance metadata from a marked object as a plain object.
+ * Only the known envelope keys are included; the `value` field is excluded.
+ * @param {object} marked - A value produced by {@link mark} or {@link derive}
+ * @returns {object} Metadata envelope
+ */
 export function metaOf(marked) {
   const meta = {};
   for (const key of META_KEYS)
@@ -32,6 +51,18 @@ export function metaOf(marked) {
   return meta;
 }
 
+/**
+ * Derives a new marked value from one or more marked inputs.
+ * The combination law is applied automatically: mock taint and the weakest
+ * confidence propagate to the result and cannot be overridden.
+ * @param {object[]} inputs - Marked values produced by {@link mark} or {@link derive}
+ * @param {Function} fn - Pure function applied to the unwrapped input values
+ * @param {object} [metaOverride={}] - Optional overrides for `source`, `confidence`,
+ *   `confidenceScore`, `basis`, or `adapter`; `derivedFromMock` cannot be cleared.
+ *   By convention `basis` is an operation label naming the transform `fn`
+ *   (e.g. `"pricing.applyFx@v3"`) — lineage records input states, not `fn`. See SPEC §4.
+ * @returns {Readonly<{value: *, source: string, confidence: string, derivedFromMock: boolean, lineage: object[]}>}
+ */
 export function derive(inputs, fn, metaOverride = {}) {
   const value = fn(...inputs.map(unwrap));
   const combined = combineProvenance(...inputs.map(metaOf));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumb-line-provenance",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "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",
@@ -41,6 +41,7 @@
     "node": ">=16"
   },
   "devDependencies": {
+    "fast-check": "^4.8.0",
     "vitest": "^4.1.9"
   }
 }

package/provenance.mjs

@@ -15,10 +15,28 @@ export const STATUS = [
 ];
 export const CONFIDENCE = ["none", "low", "medium", "high"];
 
+/**
+ * Returns true when x is a finite number in [0, 1].
+ * @param {*} x
+ * @returns {boolean}
+ */
 export function isScore(x) {
   return typeof x === "number" && Number.isFinite(x) && x >= 0 && x <= 1;
 }
 
+/**
+ * Constructs a frozen provenance metadata envelope.
+ * @param {object} [opts]
+ * @param {string} [opts.source="derived"] - One of {@link STATUS}
+ * @param {string} [opts.confidence="none"] - One of {@link CONFIDENCE}
+ * @param {number} [opts.confidenceScore] - Numeric precision in [0, 1]; omitted when invalid
+ * @param {boolean} [opts.derivedFromMock] - Defaults to `source === "mock"`
+ * @param {object[]} [opts.lineage=[]] - Prior lineage steps; each step is frozen
+ * @param {string} [opts.weakestSource] - Lowest-ranked source in ancestry; one of {@link STATUS}
+ * @param {*} [opts.basis] - Arbitrary domain metadata (passed through unchanged)
+ * @param {*} [opts.adapter] - Adapter identifier (passed through unchanged)
+ * @returns {Readonly<object>} Frozen envelope
+ */
 export function makeMeta({
   source = "derived",
   confidence = "none",
@@ -57,6 +75,12 @@ export function makeMeta({
   return Object.freeze(meta);
 }
 
+/**
+ * Returns the weakest (lowest-ranked) confidence level among the given values.
+ * Unknown values are treated as `"none"`. Returns `"none"` when called with no arguments.
+ * @param {...string} levels - Values from {@link CONFIDENCE}
+ * @returns {string} Weakest confidence level
+ */
 export function weakestConfidence(...levels) {
   if (levels.length === 0) return "none";
   let minIdx = CONFIDENCE.length - 1;
@@ -67,12 +91,22 @@ export function weakestConfidence(...levels) {
   return CONFIDENCE[minIdx];
 }
 
+/**
+ * Returns true when the envelope carries mock taint
+ * (either `derivedFromMock` is truthy or `source` is `"mock"`).
+ * @param {object|null|undefined} meta
+ * @returns {boolean}
+ */
 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.
+/**
+ * Returns the least-trustworthy source among the given values, ranked by {@link STATUS}.
+ * Unknown values are ignored. Returns `undefined` when nothing is rankable.
+ * @param {...string} sources - Values from {@link STATUS}
+ * @returns {string|undefined}
+ */
 export function weakestSource(...sources) {
   let minIdx = STATUS.length;
   for (const s of sources) {
@@ -82,9 +116,13 @@ export function weakestSource(...sources) {
   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.
+/**
+ * Returns the minimum of an array of numeric confidence scores,
+ * but only when every element is a valid score. Returns `undefined` if any
+ * element is missing or invalid — a gap is "unknown", not zero.
+ * @param {number[]} scores
+ * @returns {number|undefined}
+ */
 export function combineConfidenceScore(scores) {
   if (scores.length === 0 || !scores.every(isScore)) return undefined;
   return Math.min(...scores);
@@ -95,6 +133,17 @@ export function combineConfidenceScore(scores) {
 // shared state to reset between runs. Safe to delete from call sites.
 export function __resetStepCounter() {}
 
+/**
+ * Applies the taint-propagation combination law to one or more metadata envelopes
+ * and returns a new derived envelope. This is the core invariant: mock taint
+ * propagates forward and cannot be cleared.
+ *
+ * Calling with zero arguments returns an `"unavailable"` envelope (not `"derived"`),
+ * because a value derived from nothing has no honest provenance.
+ *
+ * @param {...object} metas - Provenance envelopes produced by {@link makeMeta}
+ * @returns {Readonly<object>} Combined envelope with `source: "derived"`
+ */
 export function combineProvenance(...metas) {
   // A value combined from no inputs is derived from nothing — honestly
   // 'unavailable', not 'derived'. Returning 'derived' with an empty lineage