plumb-line-provenance 0.2.0 → 0.3.1

package/audit.mjs

@@ -20,9 +20,14 @@ export function auditMeta(meta) {
     );
   }
 
+  // An unknown confidence on a step is laundering, not "no signal": treat it as
+  // the `none` floor (mirroring weakestConfidence), so audit is never laxer than
+  // the combination law. A step that records *no* confidence is still skipped —
+  // absence is genuinely unrankable and must not manufacture a false over-claim.
   const lineageConfidences = lineage
     .map((s) => s?.confidence)
-    .filter((c) => CONFIDENCE.includes(c));
+    .filter((c) => c != null)
+    .map((c) => (CONFIDENCE.includes(c) ? c : "none"));
   if (lineageConfidences.length > 0) {
     const weakest = weakestConfidence(...lineageConfidences);
     if (CONFIDENCE.indexOf(meta.confidence) > CONFIDENCE.indexOf(weakest)) {

package/marked.mjs

@@ -18,7 +18,7 @@ const META_KEYS = [
 const OVERRIDE_KEYS = ["source", "confidence", "confidenceScore", "basis", "adapter"];
 
 export function mark(value, metaInput = {}) {
-  return { value, ...makeMeta(metaInput) };
+  return Object.freeze({ value, ...makeMeta(metaInput) });
 }
 
 export function unwrap(marked) {
@@ -39,11 +39,15 @@ export function derive(inputs, fn, metaOverride = {}) {
   for (const key of OVERRIDE_KEYS) {
     if (key in metaOverride) safeOverride[key] = metaOverride[key];
   }
-  const merged = {
+  // Route the override through makeMeta so derive is never weaker than the
+  // constructor: an out-of-range confidenceScore (or unrankable weakestSource)
+  // is dropped by the same validation, not stored raw. derivedFromMock is
+  // force-OR'd *before* the call, so taint still cannot be cleared (the one law).
+  const merged = makeMeta({
     ...combined,
     ...safeOverride,
     derivedFromMock:
       combined.derivedFromMock || Boolean(metaOverride.derivedFromMock),
-  };
-  return { value, ...merged };
+  });
+  return Object.freeze({ value, ...merged });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumb-line-provenance",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -28,6 +28,9 @@
   ],
   "author": "Aoife Okonedo Martin",
   "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/effythealien/plumb-line/issues"
+  },
   "homepage": "https://github.com/effythealien/plumb-line/tree/main/primitives",
   "repository": {
     "type": "git",
@@ -38,6 +41,6 @@
     "node": ">=16"
   },
   "devDependencies": {
-    "vitest": "^2.0.0"
+    "vitest": "^4.1.9"
   }
 }

package/provenance.mjs

@@ -36,7 +36,15 @@ export function makeMeta({
       derivedFromMock === undefined
         ? source === "mock"
         : Boolean(derivedFromMock),
-    lineage: Array.isArray(lineage) ? [...lineage] : [],
+    // Each meta owns a *frozen copy* of its lineage. Steps are cloned then
+    // frozen so (a) an envelope's recorded history can't be rewritten in place,
+    // and (b) a step shared across parent/child metas can't leak a mutation from
+    // one into the other — the audit trail an auditMeta() trusts stays intact.
+    lineage: Object.freeze(
+      (Array.isArray(lineage) ? lineage : []).map((s) =>
+        s && typeof s === "object" ? Object.freeze({ ...s }) : s,
+      ),
+    ),
   };
   // Optional numeric confidence — a finer-grained companion to the ordinal
   // `confidence`, never a replacement. Stored only when it is a valid score.
@@ -46,7 +54,7 @@ export function makeMeta({
   if (STATUS.includes(weakestSource)) meta.weakestSource = weakestSource;
   if (basis !== undefined) meta.basis = basis;
   if (adapter !== undefined) meta.adapter = adapter;
-  return meta;
+  return Object.freeze(meta);
 }
 
 export function weakestConfidence(...levels) {
@@ -82,16 +90,24 @@ export function combineConfidenceScore(scores) {
   return Math.min(...scores);
 }
 
-let __stepCounter = 0;
-export function __resetStepCounter() {
-  __stepCounter = 0;
-}
-function nextStepId() {
-  __stepCounter += 1;
-  return `step-${__stepCounter}`;
-}
+// Deprecated no-op, kept for import compatibility. Step IDs are now assigned by
+// a counter local to each combineProvenance call (see below), so there is no
+// shared state to reset between runs. Safe to delete from call sites.
+export function __resetStepCounter() {}
 
 export function combineProvenance(...metas) {
+  // A value combined from no inputs is derived from nothing — honestly
+  // 'unavailable', not 'derived'. Returning 'derived' with an empty lineage
+  // would contradict auditMeta's "derived value has no lineage" check
+  // (SPEC §3 vs §5). See #25.
+  if (metas.length === 0) {
+    return makeMeta({
+      source: "unavailable",
+      confidence: "none",
+      derivedFromMock: false,
+      lineage: [],
+    });
+  }
   const derivedFromMock = metas.some((m) => taints(m));
   const confidence = weakestConfidence(...metas.map((m) => m?.confidence));
   const confidenceScore = combineConfidenceScore(
@@ -102,7 +118,6 @@ export function combineProvenance(...metas) {
   );
   const inputSteps = metas.map((m) => {
     const step = {
-      id: nextStepId(),
       of: "input",
       source: m?.source,
       confidence: m?.confidence,
@@ -113,7 +128,16 @@ export function combineProvenance(...metas) {
     if (isScore(m?.confidenceScore)) step.confidenceScore = m.confidenceScore;
     return step;
   });
-  const lineage = [...priorLineage, ...inputSteps];
+  // Renumber the *entire* output lineage from a combine-local counter, so step
+  // IDs are unique-within-output (SPEC §4) for every input shape — two
+  // independently-built inputs each start at step-1, so seeding past the prior
+  // length alone wouldn't stop their inherited steps from colliding. No
+  // module-level state means concurrent combines can't collide either. IDs are
+  // thus a pure function of output structure, not creation order. See #23.
+  const lineage = [...priorLineage, ...inputSteps].map((s, i) => ({
+    ...s,
+    id: `step-${i + 1}`,
+  }));
   return makeMeta({
     source: "derived",
     confidence,