@suss/datalog 0.9.0 → 0.11.0

package/dist/index.cjs

@@ -21,7 +21,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   Database: () => Database,
+  Witness: () => Witness,
   clearRelations: () => clearRelations,
+  confidence: () => confidence,
+  confidenceWith: () => confidenceWith,
   constant: () => constant,
   deriveOnDemand: () => deriveOnDemand,
   evaluate: () => evaluate,
@@ -30,14 +33,161 @@ __export(index_exports, {
   notLit: () => notLit,
   profileEvaluation: () => profileEvaluation,
   profileEvaluationAsync: () => profileEvaluationAsync,
+  proofOf: () => proofOf,
   rule: () => rule,
+  ruleLabel: () => ruleLabel,
   stratify: () => stratify,
   tupleKey: () => tupleKey,
   tupleKeyParts: () => tupleKeyParts,
-  variable: () => variable
+  variable: () => variable,
+  witnesses: () => witnesses
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/onDemand.ts
+var adornmentKey = (adornment) => adornment.map((bound) => bound ? "b" : "f").join("");
+var anyBound = (adornment) => adornment.some(Boolean);
+var keyOf = ({ relation, adornment }) => `${relation}/${adornmentKey(adornment)}`;
+var boundTerms = (terms, adornment) => terms.filter((_, column) => adornment[column]);
+var positiveLiteral = (relation, terms) => ({
+  relation,
+  terms,
+  negated: false
+});
+var demandRewrites = /* @__PURE__ */ new WeakSet();
+var isDemandRewritten = (rules) => demandRewrites.has(rules);
+function deriveOnDemand(rules, complete) {
+  const negated = rules.find((r) => r.body.some((l) => l.negated));
+  if (negated !== void 0) {
+    throw new Error(
+      `cannot derive "${negated.head.relation}" on demand: its rule uses negation, and a relation derived only where somebody asked can make a negated literal match where it did not`
+    );
+  }
+  const rulesByHead = /* @__PURE__ */ new Map();
+  for (const r of rules) {
+    const existing = rulesByHead.get(r.head.relation);
+    if (existing === void 0) {
+      rulesByHead.set(r.head.relation, [r]);
+    } else {
+      existing.push(r);
+    }
+  }
+  const derives = (relation) => rulesByHead.has(relation);
+  const asked = /* @__PURE__ */ new Map();
+  const pending = [];
+  const want = (adorned) => {
+    const key = keyOf(adorned);
+    if (!asked.has(key)) {
+      asked.set(key, adorned);
+      pending.push(adorned);
+    }
+  };
+  for (const relation of complete) {
+    const derivedBy = rulesByHead.get(relation);
+    if (derivedBy === void 0) {
+      throw new Error(
+        `no rule derives "${relation}", so it cannot be asked for in full`
+      );
+    }
+    want({ relation, adornment: derivedBy[0].head.terms.map(() => false) });
+  }
+  while (pending.length > 0) {
+    const adorned = pending.pop();
+    for (const r of rulesByHead.get(adorned.relation) ?? []) {
+      const adornments = bodyAdornments(r, adorned.adornment, derives);
+      r.body.forEach((literal, at) => {
+        const adornment = adornments[at];
+        if (adornment !== null) {
+          want({ relation: literal.relation, adornment });
+        }
+      });
+    }
+  }
+  const variantsOf = /* @__PURE__ */ new Map();
+  for (const { relation } of asked.values()) {
+    variantsOf.set(relation, (variantsOf.get(relation) ?? 0) + 1);
+  }
+  const nameOf = (relation, adornment) => {
+    if (!anyBound(adornment) || variantsOf.get(relation) === 1) {
+      return relation;
+    }
+    return `${relation}:${adornmentKey(adornment)}`;
+  };
+  const demandOn = (relation, adornment) => `wanted:${nameOf(relation, adornment)}`;
+  const rewritten = [];
+  const demandDriven = /* @__PURE__ */ new Set();
+  const already = /* @__PURE__ */ new Set();
+  const emit = (r) => {
+    const key = JSON.stringify(r);
+    if (!already.has(key)) {
+      already.add(key);
+      rewritten.push(r);
+    }
+  };
+  for (const adorned of asked.values()) {
+    if (anyBound(adorned.adornment)) {
+      demandDriven.add(nameOf(adorned.relation, adorned.adornment));
+      demandDriven.add(demandOn(adorned.relation, adorned.adornment));
+    }
+    for (const r of rulesByHead.get(adorned.relation) ?? []) {
+      const guard = anyBound(adorned.adornment) ? [
+        positiveLiteral(
+          demandOn(adorned.relation, adorned.adornment),
+          boundTerms(r.head.terms, adorned.adornment)
+        )
+      ] : [];
+      const adornments = bodyAdornments(r, adorned.adornment, derives);
+      const body = [];
+      r.body.forEach((literal, at) => {
+        const adornment = adornments[at];
+        if (adornment !== null && anyBound(adornment)) {
+          emit({
+            head: {
+              relation: demandOn(literal.relation, adornment),
+              terms: boundTerms(literal.terms, adornment)
+            },
+            body: [...guard, ...body]
+          });
+        }
+        body.push(
+          adornment === null ? literal : positiveLiteral(
+            nameOf(literal.relation, adornment),
+            literal.terms
+          )
+        );
+      });
+      emit({
+        head: {
+          relation: nameOf(adorned.relation, adorned.adornment),
+          terms: r.head.terms
+        },
+        body: [...guard, ...body]
+      });
+    }
+  }
+  demandRewrites.add(rewritten);
+  return { rules: rewritten, demandDriven: [...demandDriven] };
+}
+function bodyAdornments(r, headAdornment, derives) {
+  const bound = /* @__PURE__ */ new Set();
+  r.head.terms.forEach((term, column) => {
+    if (headAdornment[column] && term.type === "variable") {
+      bound.add(term.name);
+    }
+  });
+  return r.body.map((literal) => {
+    const adornment = derives(literal.relation) ? literal.terms.map(
+      (term) => term.type === "constant" || bound.has(term.name)
+    ) : null;
+    for (const term of literal.terms) {
+      if (term.type === "variable") {
+        bound.add(term.name);
+      }
+    }
+    return adornment;
+  });
+}
+
 // src/profile.ts
 var open = [];
 var isProfiling = () => open.length > 0;
@@ -229,145 +379,92 @@ function tupleKeyParts(key) {
   return parts;
 }
 
-// src/onDemand.ts
-var adornmentKey = (adornment) => adornment.map((bound) => bound ? "b" : "f").join("");
-var anyBound = (adornment) => adornment.some(Boolean);
-var keyOf = ({ relation, adornment }) => `${relation}/${adornmentKey(adornment)}`;
-var boundTerms = (terms, adornment) => terms.filter((_, column) => adornment[column]);
-var positiveLiteral = (relation, terms) => ({
-  relation,
-  terms,
-  negated: false
-});
-function deriveOnDemand(rules, complete) {
-  const negated = rules.find((r) => r.body.some((l) => l.negated));
-  if (negated !== void 0) {
-    throw new Error(
-      `cannot derive "${negated.head.relation}" on demand: its rule uses negation, and a relation derived only where somebody asked can make a negated literal match where it did not`
-    );
-  }
-  const rulesByHead = /* @__PURE__ */ new Map();
-  for (const r of rules) {
-    const existing = rulesByHead.get(r.head.relation);
-    if (existing === void 0) {
-      rulesByHead.set(r.head.relation, [r]);
-    } else {
-      existing.push(r);
-    }
-  }
-  const derives = (relation) => rulesByHead.has(relation);
-  const asked = /* @__PURE__ */ new Map();
-  const pending = [];
-  const want = (adorned) => {
-    const key = keyOf(adorned);
-    if (!asked.has(key)) {
-      asked.set(key, adorned);
-      pending.push(adorned);
+// src/confidence.ts
+var RANK = {
+  low: 0,
+  medium: 1,
+  high: 2
+};
+function confidenceWith(levelOf) {
+  return {
+    asserted: "high",
+    absent: "high",
+    combine(bodyTags, derivation) {
+      let lowest = levelOf(derivation.rule) ?? "high";
+      for (const tag of bodyTags) {
+        if (RANK[tag] < RANK[lowest]) {
+          lowest = tag;
+        }
+      }
+      return lowest;
+    },
+    merge(stored, incoming) {
+      return RANK[incoming] > RANK[stored] ? incoming : stored;
     }
   };
-  for (const relation of complete) {
-    const derivedBy = rulesByHead.get(relation);
-    if (derivedBy === void 0) {
-      throw new Error(
-        `no rule derives "${relation}", so it cannot be asked for in full`
-      );
-    }
-    want({ relation, adornment: derivedBy[0].head.terms.map(() => false) });
+}
+var confidence = confidenceWith(
+  () => void 0
+);
+
+// src/witness.ts
+var Witness = class {
+  constructor(rule2, body) {
+    this.rule = rule2;
+    this.body = body;
   }
-  while (pending.length > 0) {
-    const adorned = pending.pop();
-    for (const r of rulesByHead.get(adorned.relation) ?? []) {
-      const adornments = bodyAdornments(r, adorned.adornment, derives);
-      r.body.forEach((literal, at) => {
-        const adornment = adornments[at];
-        if (adornment !== null) {
-          want({ relation: literal.relation, adornment });
-        }
-      });
-    }
+  rule;
+  body;
+};
+var witnesses = {
+  asserted: "asserted",
+  absent: "absent",
+  // A witness is built from the derivation alone, and saying so lets
+  // the evaluator skip the body-tag lookups, which were most of the
+  // tagged path's cost on a large sweep.
+  ignoresBodyTags: true,
+  combine: (_bodyTags, derivation) => new Witness(derivation.rule, derivation.body),
+  merge: (stored) => stored
+};
+var DEFAULT_MAX_DEPTH = 128;
+function proofOf(db, relation, tuple, options = {}) {
+  return walk(
+    db,
+    relation,
+    tuple,
+    options.maxDepth ?? DEFAULT_MAX_DEPTH,
+    /* @__PURE__ */ new Set()
+  );
+}
+var premiseOf = {
+  fact: (db, match, depth, path) => walk(db, match.relation, match.tuple, depth, path),
+  absence: (_db, match) => ({
+    kind: "absence",
+    relation: match.relation,
+    tuple: match.tuple
+  })
+};
+function walk(db, relation, tuple, depth, path) {
+  if (!db.has(relation, tuple)) {
+    return { kind: "absence", relation, tuple };
   }
-  const variantsOf = /* @__PURE__ */ new Map();
-  for (const { relation } of asked.values()) {
-    variantsOf.set(relation, (variantsOf.get(relation) ?? 0) + 1);
+  const tag = db.tagOf(relation, tuple);
+  if (!(tag instanceof Witness)) {
+    return { kind: "fact", relation, tuple };
   }
-  const nameOf = (relation, adornment) => {
-    if (!anyBound(adornment) || variantsOf.get(relation) === 1) {
-      return relation;
-    }
-    return `${relation}:${adornmentKey(adornment)}`;
-  };
-  const demandOn = (relation, adornment) => `wanted:${nameOf(relation, adornment)}`;
-  const rewritten = [];
-  const demandDriven = /* @__PURE__ */ new Set();
-  const already = /* @__PURE__ */ new Set();
-  const emit = (r) => {
-    const key = JSON.stringify(r);
-    if (!already.has(key)) {
-      already.add(key);
-      rewritten.push(r);
-    }
-  };
-  for (const adorned of asked.values()) {
-    if (anyBound(adorned.adornment)) {
-      demandDriven.add(nameOf(adorned.relation, adorned.adornment));
-      demandDriven.add(demandOn(adorned.relation, adorned.adornment));
-    }
-    for (const r of rulesByHead.get(adorned.relation) ?? []) {
-      const guard = anyBound(adorned.adornment) ? [
-        positiveLiteral(
-          demandOn(adorned.relation, adorned.adornment),
-          boundTerms(r.head.terms, adorned.adornment)
-        )
-      ] : [];
-      const adornments = bodyAdornments(r, adorned.adornment, derives);
-      const body = [];
-      r.body.forEach((literal, at) => {
-        const adornment = adornments[at];
-        if (adornment !== null && anyBound(adornment)) {
-          emit({
-            head: {
-              relation: demandOn(literal.relation, adornment),
-              terms: boundTerms(literal.terms, adornment)
-            },
-            body: [...guard, ...body]
-          });
-        }
-        body.push(
-          adornment === null ? literal : positiveLiteral(
-            nameOf(literal.relation, adornment),
-            literal.terms
-          )
-        );
-      });
-      emit({
-        head: {
-          relation: nameOf(adorned.relation, adorned.adornment),
-          terms: r.head.terms
-        },
-        body: [...guard, ...body]
-      });
-    }
+  if (depth <= 0) {
+    return { kind: "truncated", relation, tuple, reason: "depth" };
   }
-  return { rules: rewritten, demandDriven: [...demandDriven] };
-}
-function bodyAdornments(r, headAdornment, derives) {
-  const bound = /* @__PURE__ */ new Set();
-  r.head.terms.forEach((term, column) => {
-    if (headAdornment[column] && term.type === "variable") {
-      bound.add(term.name);
-    }
-  });
-  return r.body.map((literal) => {
-    const adornment = derives(literal.relation) ? literal.terms.map(
-      (term) => term.type === "constant" || bound.has(term.name)
-    ) : null;
-    for (const term of literal.terms) {
-      if (term.type === "variable") {
-        bound.add(term.name);
-      }
-    }
-    return adornment;
-  });
+  const key = tupleKey([relation, ...tuple]);
+  if (path.has(key)) {
+    return { kind: "truncated", relation, tuple, reason: "cycle" };
+  }
+  path.add(key);
+  const premises = tag.body.map(
+    (match) => premiseOf[match.kind](db, match, depth - 1, path)
+  );
+  path.delete(key);
+  return { kind: "derived", relation, tuple, rule: tag.rule, premises };
 }
 
 // src/index.ts
@@ -383,8 +480,16 @@ var notLit = (relation, ...terms) => ({
   terms,
   negated: true
 });
-var rule = (relation, terms, body) => ({ head: { relation, terms }, body });
+var rule = (relation, terms, body, name) => name === void 0 ? { head: { relation, terms }, body } : { head: { relation, terms }, body, name };
+var literalName = (literal) => literal.negated ? `!${literal.relation}` : literal.relation;
+var ruleLabel = (r) => r.name ?? `${r.head.relation} :- ${r.body.map(literalName).join(", ")}`;
 var keyOf2 = (tuple) => tupleKey(tuple);
+function tagSlots(relation) {
+  if (relation.tags === void 0) {
+    relation.tags = /* @__PURE__ */ new Map();
+  }
+  return relation.tags;
+}
 function addToBucket(index, key, tuple) {
   const bucket = index.get(key);
   if (bucket === void 0) {
@@ -403,30 +508,53 @@ var Database = class {
     const created = {
       keys: /* @__PURE__ */ new Set(),
       tuples: [],
+      tags: void 0,
       indexes: /* @__PURE__ */ new Map()
     };
     this.store.set(name, created);
     return created;
   }
-  /** Add a fact; returns true when the tuple is new. */
-  add(relationName, tuple) {
+  /**
+   * Add a fact, or merge a tag into one already present. A new fact
+   * stores `tag` when one is given. For a fact already present,
+   * `merge` gets the stored tag (undefined when there is none) and the
+   * incoming one; returning anything but the stored value stores the
+   * result and reports "improved".
+   */
+  add(relationName, tuple, tag, merge) {
     const relation = this.relation(relationName);
     const key = keyOf2(tuple);
     if (relation.keys.has(key)) {
+      let outcome = "unchanged";
+      if (merge !== void 0) {
+        const stored = relation.tags?.get(key);
+        const merged = merge(stored, tag);
+        if (merged !== stored) {
+          tagSlots(relation).set(key, merged);
+          outcome = "improved";
+        }
+      }
       if (!isDeriving(this)) {
         claimFact(this, relationName, key);
       }
-      return false;
+      return outcome;
     }
     relation.keys.add(key);
     relation.tuples.push(tuple);
+    if (tag !== void 0) {
+      tagSlots(relation).set(key, tag);
+    }
     for (const [column, index] of relation.indexes) {
       const value = tuple[column];
       if (value !== void 0) {
         addToBucket(index, value, tuple);
       }
     }
-    return true;
+    return "added";
+  }
+  /** The tag stored for this fact, or undefined when there is none. */
+  tagOf(relationName, tuple) {
+    return this.store.get(relationName)?.tags?.get(keyOf2(tuple));
   }
   has(relationName, tuple) {
     return this.store.get(relationName)?.keys.has(keyOf2(tuple)) ?? false;
@@ -485,6 +613,7 @@ var Database = class {
     }
     for (const key of going) {
       relation.keys.delete(key);
+      relation.tags?.delete(key);
     }
     relation.tuples = relation.tuples.filter(
       (tuple) => !going.has(keyOf2(tuple))
@@ -625,6 +754,69 @@ function boundSource(db, literal, bindings) {
   }
   return db.facts(literal.relation);
 }
+var EMPTY_TAGS = [];
+function evaluateRuleTagged(db, deltas, r, deltaIndex, algebra) {
+  const results = [];
+  const bodyTags = [];
+  const bodyMatches = [];
+  const readsTags = algebra.ignoresBodyTags !== true;
+  const step = (literalIndex, positiveIndex, bindings) => {
+    if (literalIndex === r.body.length) {
+      results.push({
+        tuple: headTuple(r.head, bindings),
+        tag: algebra.combine(readsTags ? bodyTags.slice() : EMPTY_TAGS, {
+          rule: r,
+          body: bodyMatches.slice()
+        })
+      });
+      return;
+    }
+    const literal = r.body[literalIndex];
+    if (literal.negated) {
+      const grounded = groundNegated(literal, bindings);
+      if (!db.has(literal.relation, grounded)) {
+        if (readsTags) {
+          bodyTags.push(algebra.absent);
+        }
+        bodyMatches.push({
+          kind: "absence",
+          relation: literal.relation,
+          tuple: grounded
+        });
+        step(literalIndex + 1, positiveIndex, bindings);
+        if (readsTags) {
+          bodyTags.pop();
+        }
+        bodyMatches.pop();
+      }
+      return;
+    }
+    const source = positiveIndex === deltaIndex ? deltas.get(literal.relation) ?? [] : boundSource(db, literal, bindings);
+    for (const tuple of source) {
+      const next = unify(literal, tuple, bindings);
+      if (next !== null) {
+        if (readsTags) {
+          const stored = db.tagOf(literal.relation, tuple);
+          bodyTags.push(
+            stored === void 0 ? algebra.asserted : stored
+          );
+        }
+        bodyMatches.push({
+          kind: "fact",
+          relation: literal.relation,
+          tuple
+        });
+        step(literalIndex + 1, positiveIndex + 1, next);
+        if (readsTags) {
+          bodyTags.pop();
+        }
+        bodyMatches.pop();
+      }
+    }
+  };
+  step(0, 0, /* @__PURE__ */ new Map());
+  return results;
+}
 var evaluated = /* @__PURE__ */ new WeakMap();
 var deriving = /* @__PURE__ */ new Map();
 function isDeriving(db) {
@@ -684,10 +876,15 @@ function currentMarks(db) {
   }
   return marks;
 }
-function evaluate(db, rules) {
+function evaluate(db, rules, algebra) {
+  if (algebra !== void 0 && isDemandRewritten(rules)) {
+    throw new Error(
+      "cannot evaluate demand-rewritten rules with a tag algebra: tags would follow the demand-transformed rules rather than the ones the caller wrote"
+    );
+  }
   deriving.set(db, (deriving.get(db) ?? 0) + 1);
   try {
-    return runRules(db, rules);
+    return runRules(db, rules, algebra);
   } finally {
     const depth = (deriving.get(db) ?? 1) - 1;
     if (depth === 0) {
@@ -728,7 +925,16 @@ function couldProduce(db, rule2) {
     (literal) => literal.negated || db.size(literal.relation) > 0
   );
 }
-function runRules(db, rules) {
+function storedMergeFor(algebra) {
+  return (stored, incoming) => {
+    const merged = algebra.merge(
+      stored === void 0 ? algebra.asserted : stored,
+      incoming
+    );
+    return stored === void 0 && merged === algebra.asserted ? void 0 : merged;
+  };
+}
+function runRules(db, rules, algebra) {
   const {
     signature,
     name: ruleSetName,
@@ -749,37 +955,64 @@ function runRules(db, rules) {
     state.derived.clear();
   }
   const derived = state.derived;
+  const noteDerived = (relation, tuple) => {
+    let ledger = derived.get(relation);
+    if (ledger === void 0) {
+      ledger = /* @__PURE__ */ new Map();
+      derived.set(relation, ledger);
+    }
+    ledger.set(keyOf2(tuple), tuple);
+  };
+  const mergeStored = algebra === void 0 ? void 0 : storedMergeFor(algebra);
   const marks = canResume(rules, state) ? state.marks : void 0;
   for (const stratum of strata) {
     let delta = /* @__PURE__ */ new Map();
     const derivedHere = new Set(stratum.map((r) => r.head.relation));
     const record = (relation, tuple) => {
-      if (db.add(relation, tuple)) {
+      if (db.add(relation, tuple) === "added") {
         addTo(delta, relation, tuple);
-        let ledger = derived.get(relation);
-        if (ledger === void 0) {
-          ledger = /* @__PURE__ */ new Map();
-          derived.set(relation, ledger);
+        noteDerived(relation, tuple);
+      }
+    };
+    const recordTagged = mergeStored === void 0 ? void 0 : (relation, tuple, tag) => {
+      const outcome = db.add(relation, tuple, tag, mergeStored);
+      if (outcome === "unchanged") {
+        return;
+      }
+      addTo(delta, relation, tuple);
+      if (outcome === "added") {
+        noteDerived(relation, tuple);
+      }
+    };
+    const deriveInto = (r, seed, deltaIndex) => {
+      if (algebra !== void 0 && recordTagged !== void 0) {
+        for (const found of evaluateRuleTagged(
+          db,
+          seed,
+          r,
+          deltaIndex,
+          algebra
+        )) {
+          recordTagged(r.head.relation, found.tuple, found.tag);
         }
-        ledger.set(keyOf2(tuple), tuple);
+        return;
+      }
+      for (const tuple of evaluateRule(db, seed, r, deltaIndex)) {
+        record(r.head.relation, tuple);
       }
     };
     const runOneRule = (r, seed, deltaIndex) => {
       if (!isProfiling()) {
-        for (const tuple of evaluateRule(db, seed, r, deltaIndex)) {
-          record(r.head.relation, tuple);
-        }
+        deriveInto(r, seed, deltaIndex);
         return;
       }
       const startedAt = performance.now();
       const before = db.size(r.head.relation);
-      for (const tuple of evaluateRule(db, seed, r, deltaIndex)) {
-        record(r.head.relation, tuple);
-      }
+      deriveInto(r, seed, deltaIndex);
       chargeRule(
         ruleSetName,
         r.head.relation,
-        r.body.map((l) => l.negated ? `!${l.relation}` : l.relation),
+        r.body.map(literalName),
         performance.now() - startedAt,
         db.size(r.head.relation) - before
       );
@@ -847,7 +1080,10 @@ function addTo(buckets, relation, tuple) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Database,
+  Witness,
   clearRelations,
+  confidence,
+  confidenceWith,
   constant,
   deriveOnDemand,
   evaluate,
@@ -856,9 +1092,12 @@ function addTo(buckets, relation, tuple) {
   notLit,
   profileEvaluation,
   profileEvaluationAsync,
+  proofOf,
   rule,
+  ruleLabel,
   stratify,
   tupleKey,
   tupleKeyParts,
-  variable
+  variable,
+  witnesses
 });