@suss/datalog 0.31.2 → 0.33.0

package/README.md

@@ -48,7 +48,7 @@ second language adapter only has to emit the same facts.
 ## More
 
 - [How the engine evaluates](./DESIGN.md)
-- [Documentation](https://nimbuscloud-ai.github.io/suss/)
+- [Documentation](https://suss.sh/)
 - [Source and issues](https://github.com/nimbuscloud-ai/suss)
 
 ![coverage](../../.github/badges/coverage-datalog.svg)

package/dist/index.cjs

@@ -48,6 +48,99 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/factIndex.ts
+var emptyNode = () => ({
+  present: false,
+  tag: void 0,
+  next: void 0
+});
+var FactIndex = class {
+  /** How many facts are present. */
+  size = 0;
+  root = emptyNode();
+  /** This tuple's key here, whether or not the fact is present. */
+  key(tuple) {
+    let node = this.root;
+    for (let i = 0; i < tuple.length; i++) {
+      let next = node.next;
+      if (next === void 0) {
+        next = /* @__PURE__ */ new Map();
+        node.next = next;
+      }
+      const atom = tuple[i];
+      let child = next.get(atom);
+      if (child === void 0) {
+        child = emptyNode();
+        next.set(atom, child);
+      }
+      node = child;
+    }
+    return node;
+  }
+  /** The key of a fact this relation has, or undefined when it has none. */
+  find(tuple) {
+    let node = this.root;
+    for (let i = 0; i < tuple.length; i++) {
+      const child = node.next?.get(tuple[i]);
+      if (child === void 0) {
+        return void 0;
+      }
+      node = child;
+    }
+    return node.present ? node : void 0;
+  }
+  has(key) {
+    return key.present;
+  }
+  /** Record the fact, under the tag the caller gave it. */
+  put(key, tag) {
+    key.present = true;
+    key.tag = tag;
+    this.size += 1;
+  }
+  tagOf(key) {
+    return key.tag;
+  }
+  setTag(key, tag) {
+    key.tag = tag;
+  }
+  /** Take the fact away, and the tag with it. */
+  remove(key) {
+    key.present = false;
+    key.tag = void 0;
+    this.size -= 1;
+  }
+  /**
+   * Drop what is left of a removed tuple's path, up to the first node
+   * another fact still needs. Without this a relation that is retracted
+   * from over and over keeps a node per tuple it ever had.
+   */
+  prune(tuple) {
+    const path = [this.root];
+    let node = this.root;
+    for (let i = 0; i < tuple.length; i++) {
+      const child = node.next?.get(tuple[i]);
+      if (child === void 0) {
+        return;
+      }
+      node = child;
+      path.push(child);
+    }
+    for (let i = path.length - 1; i > 0; i--) {
+      const child = path[i];
+      if (child.present || (child.next?.size ?? 0) > 0) {
+        return;
+      }
+      path[i - 1].next?.delete(tuple[i - 1]);
+    }
+  }
+  /** Drop every fact, and whatever was kept in order to find them. */
+  clear() {
+    this.root = emptyNode();
+    this.size = 0;
+  }
+};
+
 // src/onDemand.ts
 var adornmentKey = (adornment) => adornment.map((bound) => bound ? "b" : "f").join("");
 var anyBound = (adornment) => adornment.some(Boolean);
@@ -469,6 +562,58 @@ function formatProfile(profile) {
   return lines.join("\n");
 }
 
+// src/relation.ts
+function addToBucket(buckets, key, tuple) {
+  const bucket = buckets.get(key);
+  if (bucket === void 0) {
+    buckets.set(key, [tuple]);
+  } else {
+    bucket.push(tuple);
+  }
+}
+function bucketIn(relation, column, value) {
+  let buckets = relation.columns[column];
+  if (buckets === void 0) {
+    buckets = /* @__PURE__ */ new Map();
+    for (const tuple of relation.tuples) {
+      const at = tuple[column];
+      if (at !== void 0) {
+        addToBucket(buckets, at, tuple);
+      }
+    }
+    relation.columns[column] = buckets;
+  }
+  return buckets.get(value) ?? [];
+}
+
+// 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;
+    }
+  };
+}
+var confidence = confidenceWith(
+  () => void 0
+);
+
 // src/tupleKey.ts
 var atomKey = (a) => typeof a === "number" ? `n${a}:` : `s${a.length}:${a}`;
 var tupleKey = (parts) => {
@@ -507,34 +652,6 @@ function tupleKeyParts(key) {
   return parts;
 }
 
-// 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;
-    }
-  };
-}
-var confidence = confidenceWith(
-  () => void 0
-);
-
 // src/witness.ts
 var Witness = class {
   constructor(rule2, body) {
@@ -611,30 +728,6 @@ var notLit = (relation, ...terms) => ({
 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 keys = /* @__PURE__ */ new WeakMap();
-var keyOf2 = (tuple) => {
-  const known = keys.get(tuple);
-  if (known !== void 0) {
-    return known;
-  }
-  const key = tupleKey(tuple);
-  keys.set(tuple, key);
-  return key;
-};
-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) {
-    index.set(key, [tuple]);
-  } else {
-    bucket.push(tuple);
-  }
-}
 var Database = class {
   store = /* @__PURE__ */ new Map();
   relation(name) {
@@ -643,14 +736,21 @@ var Database = class {
       return existing;
     }
     const created = {
-      keys: /* @__PURE__ */ new Set(),
+      index: new FactIndex(),
       tuples: [],
-      tags: void 0,
-      indexes: /* @__PURE__ */ new Map()
+      columns: []
     };
     this.store.set(name, created);
     return created;
   }
+  /**
+   * The key this relation gives a tuple, whether or not the fact is
+   * present. Evaluation keys its ledger of derived facts by it; a
+   * caller outside this module has nowhere to spend one.
+   */
+  keyFor(relationName, tuple) {
+    return this.relation(relationName).index.key(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,
@@ -660,14 +760,15 @@ var Database = class {
    */
   add(relationName, tuple, tag, merge) {
     const relation = this.relation(relationName);
-    const key = keyOf2(tuple);
-    if (relation.keys.has(key)) {
+    const index = relation.index;
+    const key = index.key(tuple);
+    if (index.has(key)) {
       let outcome = "unchanged";
       if (merge !== void 0) {
-        const stored = relation.tags?.get(key);
+        const stored = index.tagOf(key);
         const merged = merge(stored, tag);
         if (merged !== stored) {
-          tagSlots(relation).set(key, merged);
+          index.setTag(key, merged);
           outcome = "improved";
         }
       }
@@ -676,25 +777,28 @@ var Database = class {
       }
       return outcome;
     }
-    relation.keys.add(key);
+    index.put(key, tag);
     relation.tuples.push(tuple);
-    if (tag !== void 0) {
-      tagSlots(relation).set(key, tag);
-    }
-    for (const [column, index] of relation.indexes) {
+    for (let column = 0; column < relation.columns.length; column++) {
+      const buckets = relation.columns[column];
       const value = tuple[column];
-      if (value !== void 0) {
-        addToBucket(index, value, tuple);
+      if (buckets !== void 0 && value !== void 0) {
+        addToBucket(buckets, value, tuple);
       }
     }
     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));
+    const relation = this.store.get(relationName);
+    if (relation === void 0) {
+      return void 0;
+    }
+    const key = relation.index.find(tuple);
+    return key === void 0 ? void 0 : relation.index.tagOf(key);
   }
   has(relationName, tuple) {
-    return this.store.get(relationName)?.keys.has(keyOf2(tuple)) ?? false;
+    return this.store.get(relationName)?.index.find(tuple) !== void 0;
   }
   facts(relationName) {
     return this.store.get(relationName)?.tuples ?? [];
@@ -710,21 +814,11 @@ var Database = class {
    */
   lookup(relationName, column, value) {
     const relation = this.store.get(relationName);
-    if (relation === void 0) {
-      return [];
-    }
-    let index = relation.indexes.get(column);
-    if (index === void 0) {
-      index = /* @__PURE__ */ new Map();
-      for (const tuple of relation.tuples) {
-        const at = tuple[column];
-        if (at !== void 0) {
-          addToBucket(index, at, tuple);
-        }
-      }
-      relation.indexes.set(column, index);
-    }
-    return index.get(value) ?? [];
+    return relation === void 0 ? [] : bucketIn(relation, column, value);
+  }
+  /** @internal The join resolves a literal's relation once, then narrows on each fixed column. */
+  relationOf(relationName) {
+    return this.store.get(relationName);
   }
   /**
    * Remove facts from a relation. Returns how many were actually there.
@@ -738,22 +832,34 @@ var Database = class {
     if (relation === void 0) {
       return 0;
     }
+    const index = relation.index;
     const going = /* @__PURE__ */ new Set();
+    const gone = [];
     for (const tuple of tuples) {
-      const key = keyOf2(tuple);
-      if (relation.keys.has(key)) {
+      const key = index.find(tuple);
+      if (key !== void 0 && !going.has(key)) {
         going.add(key);
+        gone.push(tuple);
       }
     }
     if (going.size === 0) {
       return 0;
     }
     for (const key of going) {
-      relation.keys.delete(key);
-      relation.tags?.delete(key);
+      index.remove(key);
+    }
+    if (index.size === 0) {
+      relation.tuples = [];
+      index.clear();
+    } else {
+      relation.tuples = relation.tuples.filter(
+        (tuple) => index.find(tuple) !== void 0
+      );
+      for (const tuple of gone) {
+        index.prune(tuple);
+      }
     }
-    relation.tuples = relation.keys.size === 0 ? [] : relation.tuples.filter((tuple) => !going.has(keyOf2(tuple)));
-    relation.indexes.clear();
+    relation.columns.length = 0;
     forgetFacts(this, relationName, going);
     return going.size;
   }
@@ -965,6 +1071,7 @@ function evaluateRule(db, deltas, r, deltaIndex, budget) {
 }
 var boundSource = (db, literal, bindings) => narrowedSource(db, literal, bindings) ?? db.facts(literal.relation);
 function narrowedSource(db, literal, bindings) {
+  const relation = db.relationOf(literal.relation);
   let narrowest = null;
   for (let column = 0; column < literal.terms.length; column++) {
     const term = literal.terms[column];
@@ -972,7 +1079,7 @@ function narrowedSource(db, literal, bindings) {
     if (value === void 0) {
       continue;
     }
-    const bucket = db.lookup(literal.relation, column, value);
+    const bucket = relation === void 0 ? [] : bucketIn(relation, column, value);
     if (bucket.length === 0) {
       return bucket;
     }
@@ -1068,7 +1175,7 @@ function claimFact(db, relation, key) {
     state.derived.get(relation)?.delete(key);
   }
 }
-function forgetFacts(db, relation, keys2) {
+function forgetFacts(db, relation, keys) {
   const states = evaluated.get(db);
   if (states === void 0) {
     return;
@@ -1077,7 +1184,7 @@ function forgetFacts(db, relation, keys2) {
     state.marks = null;
     const ledger = state.derived.get(relation);
     if (ledger !== void 0) {
-      for (const key of keys2) {
+      for (const key of keys) {
         ledger.delete(key);
       }
     }
@@ -1199,7 +1306,7 @@ function runRules(db, rules, algebra, given) {
       ledger = /* @__PURE__ */ new Map();
       derived.set(relation, ledger);
     }
-    ledger.set(keyOf2(tuple), tuple);
+    ledger.set(db.keyFor(relation, tuple), tuple);
     addedHere?.push([relation, tuple]);
   };
   const mergeStored = algebra === void 0 ? void 0 : storedMergeFor(algebra);

package/dist/index.d.cts

@@ -1,3 +1,78 @@
+/**
+ * Which tuples a relation has, and what identifies one of them to
+ * everything else. The tag stored for a fact, each rule set's ledger of
+ * what it derived, and a caller's claim on a fact it asserted all point
+ * at a fact through the key this hands out.
+ *
+ * The join asks for that key again on every candidate the rules
+ * consider, so what the key costs to work out sets the cost of
+ * evaluation. A relation finds a fact by walking a trie of its tuple's
+ * atoms, one map hop per column, and the node the walk lands on is the
+ * fact itself. Nothing is built to identify a tuple, and a membership
+ * test that fails stops at the first column that misses. DESIGN.md says
+ * why the walk is over the atoms rather than over interned integers.
+ */
+
+/**
+ * What identifies one fact inside one relation. Opaque: a key means
+ * nothing to the relation that did not hand it out, and nothing outside
+ * this module reads its fields.
+ */
+interface FactKey {
+    present: boolean;
+    tag: unknown;
+    next: Map<Atom, FactKey> | undefined;
+}
+/** The facts one relation has, and the tag stored against each. */
+declare class FactIndex {
+    /** How many facts are present. */
+    size: number;
+    private root;
+    /** This tuple's key here, whether or not the fact is present. */
+    key(tuple: Tuple): FactKey;
+    /** The key of a fact this relation has, or undefined when it has none. */
+    find(tuple: Tuple): FactKey | undefined;
+    has(key: FactKey): boolean;
+    /** Record the fact, under the tag the caller gave it. */
+    put(key: FactKey, tag: unknown): void;
+    tagOf(key: FactKey): unknown;
+    setTag(key: FactKey, tag: unknown): void;
+    /** Take the fact away, and the tag with it. */
+    remove(key: FactKey): void;
+    /**
+     * Drop what is left of a removed tuple's path, up to the first node
+     * another fact still needs. Without this a relation that is retracted
+     * from over and over keeps a node per tuple it ever had.
+     */
+    prune(tuple: Tuple): void;
+    /** Drop every fact, and whatever was kept in order to find them. */
+    clear(): void;
+}
+
+/**
+ * One relation's facts: which tuples are there, and an index per column
+ * so a join that has a value for a column does not scan them all.
+ *
+ * A column is indexed the first time something asks for it and stays up
+ * to date after that, so a relation nobody joins on that way never gets
+ * an index. The join resolves the relation once per literal and then
+ * narrows on each of that literal's fixed columns, which is why finding
+ * a bucket is a function here rather than a method on the database.
+ */
+
+interface Relation {
+    /** Which tuples are here, and what identifies each of them. */
+    index: FactIndex;
+    tuples: Tuple[];
+    /**
+     * Per column position, the tuples under each value at that position.
+     * The value is the atom itself: a Map already tells 1 from "1", so
+     * encoding it first would build a string out of every node id on every
+     * lookup and buy nothing.
+     */
+    columns: (Map<Atom, Tuple[]> | undefined)[];
+}
+
 /**
  * Confidence levels as a tag algebra: how sure the run is of each
  * derived fact, given how sure it is of the facts and rules behind it.
@@ -354,6 +429,12 @@ type AddOutcome = "added" | "improved" | "unchanged";
 declare class Database {
     private readonly store;
     private relation;
+    /**
+     * The key this relation gives a tuple, whether or not the fact is
+     * present. Evaluation keys its ledger of derived facts by it; a
+     * caller outside this module has nowhere to spend one.
+     */
+    keyFor(relationName: string, tuple: Tuple): FactKey;
     /**
      * 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,
@@ -376,6 +457,8 @@ declare class Database {
      * gets an index.
      */
     lookup(relationName: string, column: number, value: Atom): readonly Tuple[];
+    /** @internal The join resolves a literal's relation once, then narrows on each fixed column. */
+    relationOf(relationName: string): Relation | undefined;
     /**
      * Remove facts from a relation. Returns how many were actually there.
      *

package/dist/index.d.ts

@@ -1,3 +1,78 @@
+/**
+ * Which tuples a relation has, and what identifies one of them to
+ * everything else. The tag stored for a fact, each rule set's ledger of
+ * what it derived, and a caller's claim on a fact it asserted all point
+ * at a fact through the key this hands out.
+ *
+ * The join asks for that key again on every candidate the rules
+ * consider, so what the key costs to work out sets the cost of
+ * evaluation. A relation finds a fact by walking a trie of its tuple's
+ * atoms, one map hop per column, and the node the walk lands on is the
+ * fact itself. Nothing is built to identify a tuple, and a membership
+ * test that fails stops at the first column that misses. DESIGN.md says
+ * why the walk is over the atoms rather than over interned integers.
+ */
+
+/**
+ * What identifies one fact inside one relation. Opaque: a key means
+ * nothing to the relation that did not hand it out, and nothing outside
+ * this module reads its fields.
+ */
+interface FactKey {
+    present: boolean;
+    tag: unknown;
+    next: Map<Atom, FactKey> | undefined;
+}
+/** The facts one relation has, and the tag stored against each. */
+declare class FactIndex {
+    /** How many facts are present. */
+    size: number;
+    private root;
+    /** This tuple's key here, whether or not the fact is present. */
+    key(tuple: Tuple): FactKey;
+    /** The key of a fact this relation has, or undefined when it has none. */
+    find(tuple: Tuple): FactKey | undefined;
+    has(key: FactKey): boolean;
+    /** Record the fact, under the tag the caller gave it. */
+    put(key: FactKey, tag: unknown): void;
+    tagOf(key: FactKey): unknown;
+    setTag(key: FactKey, tag: unknown): void;
+    /** Take the fact away, and the tag with it. */
+    remove(key: FactKey): void;
+    /**
+     * Drop what is left of a removed tuple's path, up to the first node
+     * another fact still needs. Without this a relation that is retracted
+     * from over and over keeps a node per tuple it ever had.
+     */
+    prune(tuple: Tuple): void;
+    /** Drop every fact, and whatever was kept in order to find them. */
+    clear(): void;
+}
+
+/**
+ * One relation's facts: which tuples are there, and an index per column
+ * so a join that has a value for a column does not scan them all.
+ *
+ * A column is indexed the first time something asks for it and stays up
+ * to date after that, so a relation nobody joins on that way never gets
+ * an index. The join resolves the relation once per literal and then
+ * narrows on each of that literal's fixed columns, which is why finding
+ * a bucket is a function here rather than a method on the database.
+ */
+
+interface Relation {
+    /** Which tuples are here, and what identifies each of them. */
+    index: FactIndex;
+    tuples: Tuple[];
+    /**
+     * Per column position, the tuples under each value at that position.
+     * The value is the atom itself: a Map already tells 1 from "1", so
+     * encoding it first would build a string out of every node id on every
+     * lookup and buy nothing.
+     */
+    columns: (Map<Atom, Tuple[]> | undefined)[];
+}
+
 /**
  * Confidence levels as a tag algebra: how sure the run is of each
  * derived fact, given how sure it is of the facts and rules behind it.
@@ -354,6 +429,12 @@ type AddOutcome = "added" | "improved" | "unchanged";
 declare class Database {
     private readonly store;
     private relation;
+    /**
+     * The key this relation gives a tuple, whether or not the fact is
+     * present. Evaluation keys its ledger of derived facts by it; a
+     * caller outside this module has nowhere to spend one.
+     */
+    keyFor(relationName: string, tuple: Tuple): FactKey;
     /**
      * 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,
@@ -376,6 +457,8 @@ declare class Database {
      * gets an index.
      */
     lookup(relationName: string, column: number, value: Atom): readonly Tuple[];
+    /** @internal The join resolves a literal's relation once, then narrows on each fixed column. */
+    relationOf(relationName: string): Relation | undefined;
     /**
      * Remove facts from a relation. Returns how many were actually there.
      *

package/dist/index.js

@@ -1,3 +1,96 @@
+// src/factIndex.ts
+var emptyNode = () => ({
+  present: false,
+  tag: void 0,
+  next: void 0
+});
+var FactIndex = class {
+  /** How many facts are present. */
+  size = 0;
+  root = emptyNode();
+  /** This tuple's key here, whether or not the fact is present. */
+  key(tuple) {
+    let node = this.root;
+    for (let i = 0; i < tuple.length; i++) {
+      let next = node.next;
+      if (next === void 0) {
+        next = /* @__PURE__ */ new Map();
+        node.next = next;
+      }
+      const atom = tuple[i];
+      let child = next.get(atom);
+      if (child === void 0) {
+        child = emptyNode();
+        next.set(atom, child);
+      }
+      node = child;
+    }
+    return node;
+  }
+  /** The key of a fact this relation has, or undefined when it has none. */
+  find(tuple) {
+    let node = this.root;
+    for (let i = 0; i < tuple.length; i++) {
+      const child = node.next?.get(tuple[i]);
+      if (child === void 0) {
+        return void 0;
+      }
+      node = child;
+    }
+    return node.present ? node : void 0;
+  }
+  has(key) {
+    return key.present;
+  }
+  /** Record the fact, under the tag the caller gave it. */
+  put(key, tag) {
+    key.present = true;
+    key.tag = tag;
+    this.size += 1;
+  }
+  tagOf(key) {
+    return key.tag;
+  }
+  setTag(key, tag) {
+    key.tag = tag;
+  }
+  /** Take the fact away, and the tag with it. */
+  remove(key) {
+    key.present = false;
+    key.tag = void 0;
+    this.size -= 1;
+  }
+  /**
+   * Drop what is left of a removed tuple's path, up to the first node
+   * another fact still needs. Without this a relation that is retracted
+   * from over and over keeps a node per tuple it ever had.
+   */
+  prune(tuple) {
+    const path = [this.root];
+    let node = this.root;
+    for (let i = 0; i < tuple.length; i++) {
+      const child = node.next?.get(tuple[i]);
+      if (child === void 0) {
+        return;
+      }
+      node = child;
+      path.push(child);
+    }
+    for (let i = path.length - 1; i > 0; i--) {
+      const child = path[i];
+      if (child.present || (child.next?.size ?? 0) > 0) {
+        return;
+      }
+      path[i - 1].next?.delete(tuple[i - 1]);
+    }
+  }
+  /** Drop every fact, and whatever was kept in order to find them. */
+  clear() {
+    this.root = emptyNode();
+    this.size = 0;
+  }
+};
+
 // src/onDemand.ts
 var adornmentKey = (adornment) => adornment.map((bound) => bound ? "b" : "f").join("");
 var anyBound = (adornment) => adornment.some(Boolean);
@@ -419,6 +512,58 @@ function formatProfile(profile) {
   return lines.join("\n");
 }
 
+// src/relation.ts
+function addToBucket(buckets, key, tuple) {
+  const bucket = buckets.get(key);
+  if (bucket === void 0) {
+    buckets.set(key, [tuple]);
+  } else {
+    bucket.push(tuple);
+  }
+}
+function bucketIn(relation, column, value) {
+  let buckets = relation.columns[column];
+  if (buckets === void 0) {
+    buckets = /* @__PURE__ */ new Map();
+    for (const tuple of relation.tuples) {
+      const at = tuple[column];
+      if (at !== void 0) {
+        addToBucket(buckets, at, tuple);
+      }
+    }
+    relation.columns[column] = buckets;
+  }
+  return buckets.get(value) ?? [];
+}
+
+// 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;
+    }
+  };
+}
+var confidence = confidenceWith(
+  () => void 0
+);
+
 // src/tupleKey.ts
 var atomKey = (a) => typeof a === "number" ? `n${a}:` : `s${a.length}:${a}`;
 var tupleKey = (parts) => {
@@ -457,34 +602,6 @@ function tupleKeyParts(key) {
   return parts;
 }
 
-// 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;
-    }
-  };
-}
-var confidence = confidenceWith(
-  () => void 0
-);
-
 // src/witness.ts
 var Witness = class {
   constructor(rule2, body) {
@@ -561,30 +678,6 @@ var notLit = (relation, ...terms) => ({
 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 keys = /* @__PURE__ */ new WeakMap();
-var keyOf2 = (tuple) => {
-  const known = keys.get(tuple);
-  if (known !== void 0) {
-    return known;
-  }
-  const key = tupleKey(tuple);
-  keys.set(tuple, key);
-  return key;
-};
-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) {
-    index.set(key, [tuple]);
-  } else {
-    bucket.push(tuple);
-  }
-}
 var Database = class {
   store = /* @__PURE__ */ new Map();
   relation(name) {
@@ -593,14 +686,21 @@ var Database = class {
       return existing;
     }
     const created = {
-      keys: /* @__PURE__ */ new Set(),
+      index: new FactIndex(),
       tuples: [],
-      tags: void 0,
-      indexes: /* @__PURE__ */ new Map()
+      columns: []
     };
     this.store.set(name, created);
     return created;
   }
+  /**
+   * The key this relation gives a tuple, whether or not the fact is
+   * present. Evaluation keys its ledger of derived facts by it; a
+   * caller outside this module has nowhere to spend one.
+   */
+  keyFor(relationName, tuple) {
+    return this.relation(relationName).index.key(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,
@@ -610,14 +710,15 @@ var Database = class {
    */
   add(relationName, tuple, tag, merge) {
     const relation = this.relation(relationName);
-    const key = keyOf2(tuple);
-    if (relation.keys.has(key)) {
+    const index = relation.index;
+    const key = index.key(tuple);
+    if (index.has(key)) {
       let outcome = "unchanged";
       if (merge !== void 0) {
-        const stored = relation.tags?.get(key);
+        const stored = index.tagOf(key);
         const merged = merge(stored, tag);
         if (merged !== stored) {
-          tagSlots(relation).set(key, merged);
+          index.setTag(key, merged);
           outcome = "improved";
         }
       }
@@ -626,25 +727,28 @@ var Database = class {
       }
       return outcome;
     }
-    relation.keys.add(key);
+    index.put(key, tag);
     relation.tuples.push(tuple);
-    if (tag !== void 0) {
-      tagSlots(relation).set(key, tag);
-    }
-    for (const [column, index] of relation.indexes) {
+    for (let column = 0; column < relation.columns.length; column++) {
+      const buckets = relation.columns[column];
       const value = tuple[column];
-      if (value !== void 0) {
-        addToBucket(index, value, tuple);
+      if (buckets !== void 0 && value !== void 0) {
+        addToBucket(buckets, value, tuple);
       }
     }
     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));
+    const relation = this.store.get(relationName);
+    if (relation === void 0) {
+      return void 0;
+    }
+    const key = relation.index.find(tuple);
+    return key === void 0 ? void 0 : relation.index.tagOf(key);
   }
   has(relationName, tuple) {
-    return this.store.get(relationName)?.keys.has(keyOf2(tuple)) ?? false;
+    return this.store.get(relationName)?.index.find(tuple) !== void 0;
   }
   facts(relationName) {
     return this.store.get(relationName)?.tuples ?? [];
@@ -660,21 +764,11 @@ var Database = class {
    */
   lookup(relationName, column, value) {
     const relation = this.store.get(relationName);
-    if (relation === void 0) {
-      return [];
-    }
-    let index = relation.indexes.get(column);
-    if (index === void 0) {
-      index = /* @__PURE__ */ new Map();
-      for (const tuple of relation.tuples) {
-        const at = tuple[column];
-        if (at !== void 0) {
-          addToBucket(index, at, tuple);
-        }
-      }
-      relation.indexes.set(column, index);
-    }
-    return index.get(value) ?? [];
+    return relation === void 0 ? [] : bucketIn(relation, column, value);
+  }
+  /** @internal The join resolves a literal's relation once, then narrows on each fixed column. */
+  relationOf(relationName) {
+    return this.store.get(relationName);
   }
   /**
    * Remove facts from a relation. Returns how many were actually there.
@@ -688,22 +782,34 @@ var Database = class {
     if (relation === void 0) {
       return 0;
     }
+    const index = relation.index;
     const going = /* @__PURE__ */ new Set();
+    const gone = [];
     for (const tuple of tuples) {
-      const key = keyOf2(tuple);
-      if (relation.keys.has(key)) {
+      const key = index.find(tuple);
+      if (key !== void 0 && !going.has(key)) {
         going.add(key);
+        gone.push(tuple);
       }
     }
     if (going.size === 0) {
       return 0;
     }
     for (const key of going) {
-      relation.keys.delete(key);
-      relation.tags?.delete(key);
+      index.remove(key);
+    }
+    if (index.size === 0) {
+      relation.tuples = [];
+      index.clear();
+    } else {
+      relation.tuples = relation.tuples.filter(
+        (tuple) => index.find(tuple) !== void 0
+      );
+      for (const tuple of gone) {
+        index.prune(tuple);
+      }
     }
-    relation.tuples = relation.keys.size === 0 ? [] : relation.tuples.filter((tuple) => !going.has(keyOf2(tuple)));
-    relation.indexes.clear();
+    relation.columns.length = 0;
     forgetFacts(this, relationName, going);
     return going.size;
   }
@@ -915,6 +1021,7 @@ function evaluateRule(db, deltas, r, deltaIndex, budget) {
 }
 var boundSource = (db, literal, bindings) => narrowedSource(db, literal, bindings) ?? db.facts(literal.relation);
 function narrowedSource(db, literal, bindings) {
+  const relation = db.relationOf(literal.relation);
   let narrowest = null;
   for (let column = 0; column < literal.terms.length; column++) {
     const term = literal.terms[column];
@@ -922,7 +1029,7 @@ function narrowedSource(db, literal, bindings) {
     if (value === void 0) {
       continue;
     }
-    const bucket = db.lookup(literal.relation, column, value);
+    const bucket = relation === void 0 ? [] : bucketIn(relation, column, value);
     if (bucket.length === 0) {
       return bucket;
     }
@@ -1018,7 +1125,7 @@ function claimFact(db, relation, key) {
     state.derived.get(relation)?.delete(key);
   }
 }
-function forgetFacts(db, relation, keys2) {
+function forgetFacts(db, relation, keys) {
   const states = evaluated.get(db);
   if (states === void 0) {
     return;
@@ -1027,7 +1134,7 @@ function forgetFacts(db, relation, keys2) {
     state.marks = null;
     const ledger = state.derived.get(relation);
     if (ledger !== void 0) {
-      for (const key of keys2) {
+      for (const key of keys) {
         ledger.delete(key);
       }
     }
@@ -1149,7 +1256,7 @@ function runRules(db, rules, algebra, given) {
       ledger = /* @__PURE__ */ new Map();
       derived.set(relation, ledger);
     }
-    ledger.set(keyOf2(tuple), tuple);
+    ledger.set(db.keyFor(relation, tuple), tuple);
     addedHere?.push([relation, tuple]);
   };
   const mergeStored = algebra === void 0 ? void 0 : storedMergeFor(algebra);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/datalog",
-  "version": "0.31.2",
+  "version": "0.33.0",
   "type": "module",
   "description": "A small semi-naive Datalog evaluator with stratified negation, the rules engine suss runs its whole-program analyses on.",
   "keywords": [