@suss/datalog 0.3.2 → 0.5.0

package/README.md

@@ -3,14 +3,14 @@
 A small semi-naïve Datalog evaluator with stratified negation. This is
 the rules engine behind suss's derived program facts.
 
-## Why suss carries a Datalog engine
+## Why suss ships a Datalog engine
 
-Extraction keeps meeting problems that are naturally *fixpoints*: which
-functions are reachable from an entry point, what a bare `throw err`
-re-throw can actually raise (the union of what everything in the `try`
-block throws, transitively), how a wrapper-of-a-wrapper resolves to its
-underlying route. Expressed as rules over base facts, each analysis is
-a few auditable lines:
+Extraction keeps running into problems that are naturally *fixpoints*:
+which functions are reachable from an entry point, what a bare `throw
+err` re-throw can actually raise (the union of everything the `try`
+block throws, transitively), how a wrapper of a wrapper resolves to its
+underlying route. Write each of those as rules over base facts and it
+comes to a few lines you can check by reading them:
 
 ```ts
 import { Database, evaluate, lit, rule, variable as v } from "@suss/datalog";
@@ -32,16 +32,16 @@ evaluate(db, [
 db.facts("reachable"); // [["main"], ["helper"], ["util"]]
 ```
 
-Termination and soundness are the engine's job, proven once. Negation
-(`notLit`) is *stratified*: a rule set with a negation cycle is a hard
-error at evaluation time, the property that makes rules safe to audit
-independently of any engine.
+Termination and soundness are the engine's job, and we prove them once.
+Negation (`notLit`) is *stratified*: a rule set with a negation cycle is
+a hard error at evaluation time, and that is what lets you check a rule
+on its own without thinking about the engine.
 
-Because rules are plain data (no DSL strings, no embedded code), the
-same rule set can later run on a faster external engine, and (the
-longer game) analyses written against fact shapes (`calls`, `throws`,
-`handles`, …) are language-independent: a second language adapter only
-has to emit the same facts.
+Because rules are plain data, with no DSL strings and no embedded code,
+the same rule set can later run on a faster external engine. Over the
+longer term, an analysis written against a set of facts (`calls`,
+`throws`, `handles`, and so on) does not depend on the language: a
+second language adapter only has to emit the same facts.
 
 ## Design constraints
 
@@ -54,35 +54,36 @@ has to emit the same facts.
 
 ## What it does to stay quick
 
-Semi-naïve iteration keeps per-round work proportional to newly derived
-facts rather than to everything known.
+Semi-naïve iteration keeps the work in each round proportional to the
+facts newly derived rather than to everything already known.
 
 Joins narrow before they scan. Once a literal has any term fixed, either
 written as a constant or bound by an earlier literal, the join looks the
-value up in a per-column index instead of walking the relation. A column
-gets indexed the first time something asks for it and stays current
-after that, so a relation nobody joins on that way carries no index.
+value up in a per-column index instead of walking the whole relation. A
+column gets 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 at all.
 
 `evaluate` picks up where it left off. Call it again with the same rules
-after adding facts and it seeds from the facts you added rather than
-starting the fixpoint over. Callers that interleave "add some facts, ask
-a question" get this without doing anything. Positive rules are monotone,
-so everything derived before still holds.
+after adding facts and it starts from the facts you added rather than
+redoing the whole fixpoint. Callers that go back and forth between
+adding facts and asking questions get this for free. Positive rules are
+monotone, so everything derived earlier still holds.
 
 Negated rules work differently. A new fact can make a negated literal
-stop matching, and the conclusion that rested on it has to go. So a
-re-run with negated rules takes back what the previous pass derived and
-works the answer out again from the base facts. Both paths leave the
-database holding the answer for the facts it has now.
+stop matching, and the conclusion that rested on it has to go. So when
+you re-run with negated rules, the engine throws away what the previous
+pass derived and works the answer out again from the base facts. Either
+way, the database ends up with the answer for the facts it has now.
 
 ## Deriving only what somebody asked for
 
 A rule set written for a whole program derives every conclusion its
-facts support, and a caller asking about one value reads a handful of
-them. `deriveOnDemand` rewrites the rules so the ones nobody is waiting
-on are never derived.
+facts support, and a caller who asks about one value reads only a
+handful of them. `deriveOnDemand` rewrites the rules so that conclusions
+nobody is waiting on never get derived.
 
-Name the relations that have to come out whole, and give each of them a
+List the relations that have to come out whole, and give each of them a
 rule that starts at a base relation you assert:
 
 ```ts
@@ -112,28 +113,28 @@ db.facts("answer"); // [["a", "b"], ["a", "c"]]
 db.facts("reaches"); // the chain from a, and nothing from m
 ```
 
-The rewrite is magic sets. Each derived relation gains a companion
-relation saying which of its rows something is waiting on, that
+The rewrite is magic sets. Each derived relation gets a companion
+relation that records which of its rows something is waiting on, that
 companion becomes a literal in the rule body, and demand travels down
-each body the way the join binds variables. A relation nothing asks for
-is not derived at all, so read back only the relations you named.
+each body the same way the join binds variables. A relation nothing asks
+for is not derived at all, so only read back the relations you listed.
 
-Two things this costs. The companion relations are stored like any
-other, at a few tuples per value asked about, so a caller asking about
-most of a program derives more rather than less. And negation is
-refused: a relation derived only where somebody asked is smaller than
-the one a negated literal was written against, which would make `not
-p(x)` match where it did not.
+This costs you two things. The companion relations are stored like any
+other, at a few tuples per value asked about, so a caller who asks about
+most of a program ends up deriving more rather than less. And the
+rewrite refuses negation: a relation derived only where somebody asked
+is smaller than the one a negated literal was written against, which
+would make `not p(x)` match where it should not.
 
 ### Taking a question back
 
 Demand is a fact, and a fact stays until somebody removes it. A caller
-that asks a thousand questions of one database derives over all thousand
-every time new facts arrive, so the last question costs a thousand
-questions.
+that asks a thousand questions of one database re-derives all thousand
+every time new facts arrive, so the last question costs as much as a
+thousand questions.
 
-`program.demandDriven` names the relations the rewrite restricts, and
-`clearRelations` empties them once an answer has been read:
+`program.demandDriven` lists the relations the rewrite restricts, and
+`clearRelations` empties them once you have read an answer:
 
 ```ts
 clearRelations(db, program.rules, [...program.demandDriven, "asked"]);
@@ -144,19 +145,19 @@ db.facts("reaches"); // the chain from m, and nothing from a
 db.facts("answer"); // a's answers, which nothing took away, plus m's
 ```
 
-`retract` would send the next run back to the base facts, since a fact
+`retract` would send the next run back to the base facts, because a fact
 leaving the database can take away a conclusion drawn anywhere.
-`clearRelations` keeps the resume, because a caller passing these
-relations is saying nothing outside them was derived from them. That
-holds for the relations `deriveOnDemand` restricts: every one of them is
-derived under a demand fact, and only the relations you named as
-complete read from them. Those keep what they hold, which is the answers
-you already read.
-
-Keep the facts you add and the facts rules derive in separate relations.
-Taking a conclusion back cannot tell one from the other, and the
-separation is how Datalog is normally written anyway.
-
-Extraction-scale fact sets are thousands of tuples. If that changes, the
-rule data model is the stable seam and this evaluator is the replaceable
-part.
+`clearRelations` lets the next run resume instead, because a caller who
+passes these relations is saying that nothing outside them was derived
+from them. That is true for the relations `deriveOnDemand` restricts:
+every one of them is derived under a demand fact, and only the relations
+you listed as complete read from them. Those keep what they already
+contain, which is the answers you have read.
+
+Keep the facts you add and the facts the rules derive in separate
+relations. Taking a conclusion back cannot tell one from the other, and
+splitting them is how people normally write Datalog anyway.
+
+Extraction-scale fact sets run to thousands of tuples. If that changes,
+the rule data model is the part that stays and this evaluator is the
+part you replace.

package/dist/index.cjs

@@ -32,6 +32,8 @@ __export(index_exports, {
   profileEvaluationAsync: () => profileEvaluationAsync,
   rule: () => rule,
   stratify: () => stratify,
+  tupleKey: () => tupleKey,
+  tupleKeyParts: () => tupleKeyParts,
   variable: () => variable
 });
 module.exports = __toCommonJS(index_exports);
@@ -195,6 +197,38 @@ function formatProfile(profile) {
   return lines.join("\n");
 }
 
+// src/tupleKey.ts
+var atomKey = (a) => typeof a === "number" ? `n${a}:` : `s${a.length}:${a}`;
+var tupleKey = (parts) => parts.map(atomKey).join("");
+function tupleKeyParts(key) {
+  const parts = [];
+  let at = 0;
+  while (at < key.length) {
+    const colon = key.indexOf(":", at);
+    if (colon === -1) {
+      throw new Error(`not a tuple key: ${key}`);
+    }
+    const kind = key[at];
+    const header = key.slice(at + 1, colon);
+    if (kind === "n") {
+      parts.push(header);
+      at = colon + 1;
+      continue;
+    }
+    const length = Number(header);
+    if (kind !== "s" || !Number.isInteger(length) || length < 0) {
+      throw new Error(`not a tuple key: ${key}`);
+    }
+    const end = colon + 1 + length;
+    if (end > key.length) {
+      throw new Error(`not a tuple key: ${key}`);
+    }
+    parts.push(key.slice(colon + 1, end));
+    at = end;
+  }
+  return parts;
+}
+
 // src/onDemand.ts
 var adornmentKey = (adornment) => adornment.map((bound) => bound ? "b" : "f").join("");
 var anyBound = (adornment) => adornment.some(Boolean);
@@ -350,8 +384,7 @@ var notLit = (relation, ...terms) => ({
   negated: true
 });
 var rule = (relation, terms, body) => ({ head: { relation, terms }, body });
-var atomKey = (a) => typeof a === "number" ? `n${a}:` : `s${a.length}:${a}`;
-var keyOf2 = (tuple) => tuple.map(atomKey).join("");
+var keyOf2 = (tuple) => tupleKey(tuple);
 function addToBucket(index, key, tuple) {
   const bucket = index.get(key);
   if (bucket === void 0) {
@@ -390,7 +423,7 @@ var Database = class {
     for (const [column, index] of relation.indexes) {
       const value = tuple[column];
       if (value !== void 0) {
-        addToBucket(index, atomKey(value), tuple);
+        addToBucket(index, value, tuple);
       }
     }
     return true;
@@ -402,13 +435,13 @@ var Database = class {
     return this.store.get(relationName)?.tuples ?? [];
   }
   /**
-   * The facts holding `value` at `column`. A join reaches for this
-   * instead of scanning the whole relation once one of its terms is
-   * already bound.
+   * The facts with `value` at `column`. Once one of a literal's terms
+   * is already bound, the join uses this instead of scanning the whole
+   * relation.
    *
    * A column is indexed the first time somebody asks for it and stays
-   * up to date after that, so a relation nobody joins on this way
-   * carries no index at all.
+   * up to date after that, so a relation nobody joins on this way never
+   * gets an index.
    */
   lookup(relationName, column, value) {
     const relation = this.store.get(relationName);
@@ -421,19 +454,19 @@ var Database = class {
       for (const tuple of relation.tuples) {
         const at = tuple[column];
         if (at !== void 0) {
-          addToBucket(index, atomKey(at), tuple);
+          addToBucket(index, at, tuple);
         }
       }
       relation.indexes.set(column, index);
     }
-    return index.get(atomKey(value)) ?? [];
+    return index.get(value) ?? [];
   }
   /**
    * Remove facts from a relation. Returns how many were actually there.
    *
-   * Evaluation uses this to take back what it derived last time when a
-   * rule set uses negation, where a new fact can invalidate an old
-   * conclusion. Callers rarely need it.
+   * When a rule set uses negation, a new fact can invalidate an old
+   * conclusion, so evaluation calls this to remove what it derived last
+   * time. Callers rarely need it.
    */
   retract(relationName, tuples) {
     const relation = this.store.get(relationName);
@@ -537,7 +570,7 @@ function groundNegated(literal, bindings) {
     const bound = bindings.get(term.name);
     if (bound === void 0) {
       throw new Error(
-        `unbound variable "${term.name}" in negated literal "${literal.relation}" \u2014 negated literals may only use variables bound by earlier positive literals`
+        `unbound variable "${term.name}" in negated literal "${literal.relation}": negated literals may only use variables bound by earlier positive literals`
       );
     }
     return bound;
@@ -690,6 +723,11 @@ function shapeOf(rules) {
   shapes.set(rules, shape);
   return shape;
 }
+function couldProduce(db, rule2) {
+  return rule2.body.every(
+    (literal) => literal.negated || db.size(literal.relation) > 0
+  );
+}
 function runRules(db, rules) {
   const {
     signature,
@@ -748,6 +786,9 @@ function runRules(db, rules) {
     };
     const applyDelta = (seed, derivedOnly) => {
       for (const r of stratum) {
+        if (!couldProduce(db, r)) {
+          continue;
+        }
         const positives = r.body.filter((l) => !l.negated);
         for (let i = 0; i < positives.length; i++) {
           const literal = positives[i];
@@ -763,6 +804,9 @@ function runRules(db, rules) {
     };
     if (marks === void 0 || marks === null) {
       for (const r of stratum) {
+        if (!couldProduce(db, r)) {
+          continue;
+        }
         const all = /* @__PURE__ */ new Map();
         for (const l of r.body) {
           if (!l.negated) {
@@ -814,5 +858,7 @@ function addTo(buckets, relation, tuple) {
   profileEvaluationAsync,
   rule,
   stratify,
+  tupleKey,
+  tupleKeyParts,
   variable
 });

package/dist/index.d.cts

@@ -12,7 +12,7 @@ interface OnDemandRules {
     demandDriven: string[];
 }
 /**
- * Rewrite `rules` so the relations named in `complete` still come out
+ * Rewrite `rules` so the relations listed in `complete` still come out
  * whole and everything else is derived only where those relations reach.
  *
  * Demand enters as ordinary facts. Give a complete relation a rule whose
@@ -21,7 +21,7 @@ interface OnDemandRules {
  * fact into demand for one value's chain.
  *
  * Relations no complete relation reaches are dropped, so a caller reading
- * a relation it did not name gets nothing. Negation is rejected: a
+ * a relation it did not list gets nothing. Negation is rejected: a
  * demand-restricted relation is smaller than the one a negated literal
  * was written against, and a smaller relation makes `not p(x)` true where
  * it was false.
@@ -98,8 +98,8 @@ declare function profileEvaluation<T>(fn: () => T): {
 /**
  * The async twin, for callers whose extraction is a promise. The scope
  * stays open across every await inside `fn`, so anything else that
- * evaluates rules on the same thread meanwhile is charged here too. One
- * extraction at a time is the case this is built for.
+ * evaluates rules on the same thread meanwhile is charged here too. This
+ * is built for the case of one extraction at a time.
  */
 declare function profileEvaluationAsync<T>(fn: () => Promise<T>): Promise<{
     result: T;
@@ -108,6 +108,28 @@ declare function profileEvaluationAsync<T>(fn: () => Promise<T>): Promise<{
 /** Render a profile as the table a human reads in a terminal. */
 declare function formatProfile(profile: EvaluationProfile): string;
 
+declare const tupleKey: (parts: readonly Atom[]) => string;
+/**
+ * Throws on a string `tupleKey` did not produce. A key that does not
+ * parse means a caller mixed two encodings, and parsing it leniently
+ * would make every result after it quietly wrong.
+ */
+declare function tupleKeyParts(key: string): string[];
+
+/**
+ * @suss/datalog, a small semi-naïve Datalog evaluator with stratified
+ * negation, and the rules engine behind suss's derived program facts:
+ * reachable closures, wrapper resolution, throw propagation, origin
+ * chains. Rules are plain data (`Rule`) rather than code, so the same
+ * rules can later run on a faster engine, or be read on their own.
+ *
+ * It is pure TypeScript with no dependencies, because the npm-shipped
+ * CLI cannot require a native binary. Negation is stratified, so a
+ * negation cycle throws at evaluation time rather than quietly giving a
+ * wrong answer. Joins are nested-loop with hash indexing on bound
+ * positions, which suits the thousands of tuples extraction produces.
+ */
+
 /** Tuple values. Callers intern richer identities (AST nodes, summaries) to atoms. */
 type Atom = string | number;
 type Tuple = readonly Atom[];
@@ -119,7 +141,7 @@ type Term = {
     type: "constant";
     value: Atom;
 };
-/** Shorthand constructors — rules stay readable without a parser. */
+/** Shorthand constructors, so rules stay readable without a parser. */
 declare const variable: (name: string) => Term;
 declare const constant: (value: Atom) => Term;
 interface Literal {
@@ -152,21 +174,21 @@ declare class Database {
     has(relationName: string, tuple: Tuple): boolean;
     facts(relationName: string): readonly Tuple[];
     /**
-     * The facts holding `value` at `column`. A join reaches for this
-     * instead of scanning the whole relation once one of its terms is
-     * already bound.
+     * The facts with `value` at `column`. Once one of a literal's terms
+     * is already bound, the join uses this instead of scanning the whole
+     * relation.
      *
      * A column is indexed the first time somebody asks for it and stays
-     * up to date after that, so a relation nobody joins on this way
-     * carries no index at all.
+     * up to date after that, so a relation nobody joins on this way never
+     * gets an index.
      */
     lookup(relationName: string, column: number, value: Atom): readonly Tuple[];
     /**
      * Remove facts from a relation. Returns how many were actually there.
      *
-     * Evaluation uses this to take back what it derived last time when a
-     * rule set uses negation, where a new fact can invalidate an old
-     * conclusion. Callers rarely need it.
+     * When a rule set uses negation, a new fact can invalidate an old
+     * conclusion, so evaluation calls this to remove what it derived last
+     * time. Callers rarely need it.
      */
     retract(relationName: string, tuples: Iterable<Tuple>): number;
     size(relationName: string): number;
@@ -175,8 +197,9 @@ declare class Database {
 /**
  * Assign each derived relation a stratum such that positive
  * dependencies never decrease the stratum and negative dependencies
- * strictly increase it. Iterates to fixpoint; a stratum exceeding the
- * relation count means a negation cycle — not stratifiable, hard error.
+ * strictly increase it. Iterates to fixpoint. A stratum above the
+ * relation count means there is a negation cycle, which cannot be
+ * stratified, so this throws.
  */
 declare function stratify(rules: Rule[]): Rule[][];
 /**
@@ -201,12 +224,12 @@ declare function evaluate(db: Database, rules: Rule[]): Database;
  * questions. Every relation `deriveOnDemand` restricts is derived under
  * a demand fact, so clearing the demand together with everything under
  * it costs one question's worth of derivation rather than every
- * question asked so far. The relations named as complete keep what they
- * hold, which is the answers a caller has already read.
+ * question asked so far. The relations listed as complete keep their
+ * contents, which are the answers a caller has already read.
  *
  * Any other rule set over the same database does start over, since a
  * relation it derived from may be one of these.
  */
 declare function clearRelations(db: Database, rules: Rule[], relations: readonly string[]): void;
 
-export { type Atom, Database, type EvaluationProfile, type Literal, type OnDemandRules, type Rule, type RuleCost, type Term, type Tuple, clearRelations, constant, deriveOnDemand, evaluate, formatProfile, lit, notLit, profileEvaluation, profileEvaluationAsync, rule, stratify, variable };
+export { type Atom, Database, type EvaluationProfile, type Literal, type OnDemandRules, type Rule, type RuleCost, type Term, type Tuple, clearRelations, constant, deriveOnDemand, evaluate, formatProfile, lit, notLit, profileEvaluation, profileEvaluationAsync, rule, stratify, tupleKey, tupleKeyParts, variable };

package/dist/index.d.ts

@@ -12,7 +12,7 @@ interface OnDemandRules {
     demandDriven: string[];
 }
 /**
- * Rewrite `rules` so the relations named in `complete` still come out
+ * Rewrite `rules` so the relations listed in `complete` still come out
  * whole and everything else is derived only where those relations reach.
  *
  * Demand enters as ordinary facts. Give a complete relation a rule whose
@@ -21,7 +21,7 @@ interface OnDemandRules {
  * fact into demand for one value's chain.
  *
  * Relations no complete relation reaches are dropped, so a caller reading
- * a relation it did not name gets nothing. Negation is rejected: a
+ * a relation it did not list gets nothing. Negation is rejected: a
  * demand-restricted relation is smaller than the one a negated literal
  * was written against, and a smaller relation makes `not p(x)` true where
  * it was false.
@@ -98,8 +98,8 @@ declare function profileEvaluation<T>(fn: () => T): {
 /**
  * The async twin, for callers whose extraction is a promise. The scope
  * stays open across every await inside `fn`, so anything else that
- * evaluates rules on the same thread meanwhile is charged here too. One
- * extraction at a time is the case this is built for.
+ * evaluates rules on the same thread meanwhile is charged here too. This
+ * is built for the case of one extraction at a time.
  */
 declare function profileEvaluationAsync<T>(fn: () => Promise<T>): Promise<{
     result: T;
@@ -108,6 +108,28 @@ declare function profileEvaluationAsync<T>(fn: () => Promise<T>): Promise<{
 /** Render a profile as the table a human reads in a terminal. */
 declare function formatProfile(profile: EvaluationProfile): string;
 
+declare const tupleKey: (parts: readonly Atom[]) => string;
+/**
+ * Throws on a string `tupleKey` did not produce. A key that does not
+ * parse means a caller mixed two encodings, and parsing it leniently
+ * would make every result after it quietly wrong.
+ */
+declare function tupleKeyParts(key: string): string[];
+
+/**
+ * @suss/datalog, a small semi-naïve Datalog evaluator with stratified
+ * negation, and the rules engine behind suss's derived program facts:
+ * reachable closures, wrapper resolution, throw propagation, origin
+ * chains. Rules are plain data (`Rule`) rather than code, so the same
+ * rules can later run on a faster engine, or be read on their own.
+ *
+ * It is pure TypeScript with no dependencies, because the npm-shipped
+ * CLI cannot require a native binary. Negation is stratified, so a
+ * negation cycle throws at evaluation time rather than quietly giving a
+ * wrong answer. Joins are nested-loop with hash indexing on bound
+ * positions, which suits the thousands of tuples extraction produces.
+ */
+
 /** Tuple values. Callers intern richer identities (AST nodes, summaries) to atoms. */
 type Atom = string | number;
 type Tuple = readonly Atom[];
@@ -119,7 +141,7 @@ type Term = {
     type: "constant";
     value: Atom;
 };
-/** Shorthand constructors — rules stay readable without a parser. */
+/** Shorthand constructors, so rules stay readable without a parser. */
 declare const variable: (name: string) => Term;
 declare const constant: (value: Atom) => Term;
 interface Literal {
@@ -152,21 +174,21 @@ declare class Database {
     has(relationName: string, tuple: Tuple): boolean;
     facts(relationName: string): readonly Tuple[];
     /**
-     * The facts holding `value` at `column`. A join reaches for this
-     * instead of scanning the whole relation once one of its terms is
-     * already bound.
+     * The facts with `value` at `column`. Once one of a literal's terms
+     * is already bound, the join uses this instead of scanning the whole
+     * relation.
      *
      * A column is indexed the first time somebody asks for it and stays
-     * up to date after that, so a relation nobody joins on this way
-     * carries no index at all.
+     * up to date after that, so a relation nobody joins on this way never
+     * gets an index.
      */
     lookup(relationName: string, column: number, value: Atom): readonly Tuple[];
     /**
      * Remove facts from a relation. Returns how many were actually there.
      *
-     * Evaluation uses this to take back what it derived last time when a
-     * rule set uses negation, where a new fact can invalidate an old
-     * conclusion. Callers rarely need it.
+     * When a rule set uses negation, a new fact can invalidate an old
+     * conclusion, so evaluation calls this to remove what it derived last
+     * time. Callers rarely need it.
      */
     retract(relationName: string, tuples: Iterable<Tuple>): number;
     size(relationName: string): number;
@@ -175,8 +197,9 @@ declare class Database {
 /**
  * Assign each derived relation a stratum such that positive
  * dependencies never decrease the stratum and negative dependencies
- * strictly increase it. Iterates to fixpoint; a stratum exceeding the
- * relation count means a negation cycle — not stratifiable, hard error.
+ * strictly increase it. Iterates to fixpoint. A stratum above the
+ * relation count means there is a negation cycle, which cannot be
+ * stratified, so this throws.
  */
 declare function stratify(rules: Rule[]): Rule[][];
 /**
@@ -201,12 +224,12 @@ declare function evaluate(db: Database, rules: Rule[]): Database;
  * questions. Every relation `deriveOnDemand` restricts is derived under
  * a demand fact, so clearing the demand together with everything under
  * it costs one question's worth of derivation rather than every
- * question asked so far. The relations named as complete keep what they
- * hold, which is the answers a caller has already read.
+ * question asked so far. The relations listed as complete keep their
+ * contents, which are the answers a caller has already read.
  *
  * Any other rule set over the same database does start over, since a
  * relation it derived from may be one of these.
  */
 declare function clearRelations(db: Database, rules: Rule[], relations: readonly string[]): void;
 
-export { type Atom, Database, type EvaluationProfile, type Literal, type OnDemandRules, type Rule, type RuleCost, type Term, type Tuple, clearRelations, constant, deriveOnDemand, evaluate, formatProfile, lit, notLit, profileEvaluation, profileEvaluationAsync, rule, stratify, variable };
+export { type Atom, Database, type EvaluationProfile, type Literal, type OnDemandRules, type Rule, type RuleCost, type Term, type Tuple, clearRelations, constant, deriveOnDemand, evaluate, formatProfile, lit, notLit, profileEvaluation, profileEvaluationAsync, rule, stratify, tupleKey, tupleKeyParts, variable };

package/dist/index.js

@@ -157,6 +157,38 @@ function formatProfile(profile) {
   return lines.join("\n");
 }
 
+// src/tupleKey.ts
+var atomKey = (a) => typeof a === "number" ? `n${a}:` : `s${a.length}:${a}`;
+var tupleKey = (parts) => parts.map(atomKey).join("");
+function tupleKeyParts(key) {
+  const parts = [];
+  let at = 0;
+  while (at < key.length) {
+    const colon = key.indexOf(":", at);
+    if (colon === -1) {
+      throw new Error(`not a tuple key: ${key}`);
+    }
+    const kind = key[at];
+    const header = key.slice(at + 1, colon);
+    if (kind === "n") {
+      parts.push(header);
+      at = colon + 1;
+      continue;
+    }
+    const length = Number(header);
+    if (kind !== "s" || !Number.isInteger(length) || length < 0) {
+      throw new Error(`not a tuple key: ${key}`);
+    }
+    const end = colon + 1 + length;
+    if (end > key.length) {
+      throw new Error(`not a tuple key: ${key}`);
+    }
+    parts.push(key.slice(colon + 1, end));
+    at = end;
+  }
+  return parts;
+}
+
 // src/onDemand.ts
 var adornmentKey = (adornment) => adornment.map((bound) => bound ? "b" : "f").join("");
 var anyBound = (adornment) => adornment.some(Boolean);
@@ -312,8 +344,7 @@ var notLit = (relation, ...terms) => ({
   negated: true
 });
 var rule = (relation, terms, body) => ({ head: { relation, terms }, body });
-var atomKey = (a) => typeof a === "number" ? `n${a}:` : `s${a.length}:${a}`;
-var keyOf2 = (tuple) => tuple.map(atomKey).join("");
+var keyOf2 = (tuple) => tupleKey(tuple);
 function addToBucket(index, key, tuple) {
   const bucket = index.get(key);
   if (bucket === void 0) {
@@ -352,7 +383,7 @@ var Database = class {
     for (const [column, index] of relation.indexes) {
       const value = tuple[column];
       if (value !== void 0) {
-        addToBucket(index, atomKey(value), tuple);
+        addToBucket(index, value, tuple);
       }
     }
     return true;
@@ -364,13 +395,13 @@ var Database = class {
     return this.store.get(relationName)?.tuples ?? [];
   }
   /**
-   * The facts holding `value` at `column`. A join reaches for this
-   * instead of scanning the whole relation once one of its terms is
-   * already bound.
+   * The facts with `value` at `column`. Once one of a literal's terms
+   * is already bound, the join uses this instead of scanning the whole
+   * relation.
    *
    * A column is indexed the first time somebody asks for it and stays
-   * up to date after that, so a relation nobody joins on this way
-   * carries no index at all.
+   * up to date after that, so a relation nobody joins on this way never
+   * gets an index.
    */
   lookup(relationName, column, value) {
     const relation = this.store.get(relationName);
@@ -383,19 +414,19 @@ var Database = class {
       for (const tuple of relation.tuples) {
         const at = tuple[column];
         if (at !== void 0) {
-          addToBucket(index, atomKey(at), tuple);
+          addToBucket(index, at, tuple);
         }
       }
       relation.indexes.set(column, index);
     }
-    return index.get(atomKey(value)) ?? [];
+    return index.get(value) ?? [];
   }
   /**
    * Remove facts from a relation. Returns how many were actually there.
    *
-   * Evaluation uses this to take back what it derived last time when a
-   * rule set uses negation, where a new fact can invalidate an old
-   * conclusion. Callers rarely need it.
+   * When a rule set uses negation, a new fact can invalidate an old
+   * conclusion, so evaluation calls this to remove what it derived last
+   * time. Callers rarely need it.
    */
   retract(relationName, tuples) {
     const relation = this.store.get(relationName);
@@ -499,7 +530,7 @@ function groundNegated(literal, bindings) {
     const bound = bindings.get(term.name);
     if (bound === void 0) {
       throw new Error(
-        `unbound variable "${term.name}" in negated literal "${literal.relation}" \u2014 negated literals may only use variables bound by earlier positive literals`
+        `unbound variable "${term.name}" in negated literal "${literal.relation}": negated literals may only use variables bound by earlier positive literals`
       );
     }
     return bound;
@@ -652,6 +683,11 @@ function shapeOf(rules) {
   shapes.set(rules, shape);
   return shape;
 }
+function couldProduce(db, rule2) {
+  return rule2.body.every(
+    (literal) => literal.negated || db.size(literal.relation) > 0
+  );
+}
 function runRules(db, rules) {
   const {
     signature,
@@ -710,6 +746,9 @@ function runRules(db, rules) {
     };
     const applyDelta = (seed, derivedOnly) => {
       for (const r of stratum) {
+        if (!couldProduce(db, r)) {
+          continue;
+        }
         const positives = r.body.filter((l) => !l.negated);
         for (let i = 0; i < positives.length; i++) {
           const literal = positives[i];
@@ -725,6 +764,9 @@ function runRules(db, rules) {
     };
     if (marks === void 0 || marks === null) {
       for (const r of stratum) {
+        if (!couldProduce(db, r)) {
+          continue;
+        }
         const all = /* @__PURE__ */ new Map();
         for (const l of r.body) {
           if (!l.negated) {
@@ -775,5 +817,7 @@ export {
   profileEvaluationAsync,
   rule,
   stratify,
+  tupleKey,
+  tupleKeyParts,
   variable
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/datalog",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "type": "module",
   "description": "A small semi-naïve Datalog evaluator with stratified negation — the rules engine behind suss's derived program facts.",
   "keywords": [