@suss/datalog 0.1.0 → 0.2.0

package/README.md

@@ -75,6 +75,84 @@ 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.
 
+## 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.
+
+Name the relations that have to come out whole, and give each of them a
+rule that starts at a base relation you assert:
+
+```ts
+const rules = [
+  rule("reaches", [v("x"), v("y")], [lit("edge", v("x"), v("y"))]),
+  rule(
+    "reaches",
+    [v("x"), v("z")],
+    [lit("edge", v("x"), v("y")), lit("reaches", v("y"), v("z"))],
+  ),
+  rule(
+    "answer",
+    [v("x"), v("y")],
+    [lit("asked", v("x")), lit("reaches", v("x"), v("y"))],
+  ),
+];
+
+const db = new Database();
+db.add("edge", ["a", "b"]);
+db.add("edge", ["b", "c"]);
+db.add("edge", ["m", "n"]);
+db.add("asked", ["a"]);
+
+const program = deriveOnDemand(rules, ["answer"]);
+evaluate(db, program.rules);
+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
+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.
+
+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.
+
+### 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.
+
+`program.demandDriven` names the relations the rewrite restricts, and
+`clearRelations` empties them once an answer has been read:
+
+```ts
+clearRelations(db, program.rules, [...program.demandDriven, "asked"]);
+
+db.add("asked", ["m"]);
+evaluate(db, program.rules);
+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
+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.

package/dist/index.cjs

@@ -21,15 +21,322 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   Database: () => Database,
+  clearRelations: () => clearRelations,
   constant: () => constant,
+  deriveOnDemand: () => deriveOnDemand,
   evaluate: () => evaluate,
+  formatProfile: () => formatProfile,
   lit: () => lit,
   notLit: () => notLit,
+  profileEvaluation: () => profileEvaluation,
+  profileEvaluationAsync: () => profileEvaluationAsync,
   rule: () => rule,
   stratify: () => stratify,
   variable: () => variable
 });
 module.exports = __toCommonJS(index_exports);
+
+// src/profile.ts
+var open = [];
+var isProfiling = () => open.length > 0;
+var ruleKey = (head, body) => `${head} <- ${body.join(", ")}`;
+function addCost(into, key, head, body, ms, derived) {
+  const existing = into.get(key);
+  if (existing === void 0) {
+    into.set(key, { head, body, ms, derived, attempts: 1 });
+    return;
+  }
+  existing.ms += ms;
+  existing.derived += derived;
+  existing.attempts += 1;
+}
+function chargeRule(ruleSet, head, body, ms, derived) {
+  const key = ruleKey(head, body);
+  for (const collector of open) {
+    addCost(collector.rules, key, head, body, ms, derived);
+    addCost(setIn(collector, ruleSet).rules, key, head, body, ms, derived);
+  }
+}
+function chargeEvaluation(ruleSet) {
+  for (const collector of open) {
+    collector.evaluations += 1;
+    setIn(collector, ruleSet).evaluations += 1;
+  }
+}
+function chargeRound(ruleSet) {
+  for (const collector of open) {
+    collector.rounds += 1;
+    setIn(collector, ruleSet).rounds += 1;
+  }
+}
+function setIn(collector, ruleSet) {
+  const existing = collector.ruleSets.get(ruleSet);
+  if (existing !== void 0) {
+    return existing;
+  }
+  const created = {
+    derives: new Set(ruleSet.split(", ")),
+    evaluations: 0,
+    rounds: 0,
+    rules: /* @__PURE__ */ new Map()
+  };
+  collector.ruleSets.set(ruleSet, created);
+  return created;
+}
+function chargeRelationSizes(entries, derivedRelations) {
+  const sizes = [...entries];
+  const derived = [...derivedRelations];
+  for (const collector of open) {
+    for (const [relation, tuples] of sizes) {
+      const seen = collector.relations.get(relation) ?? 0;
+      if (tuples > seen) {
+        collector.relations.set(relation, tuples);
+      }
+    }
+    for (const relation of derived) {
+      collector.derivedRelations.add(relation);
+    }
+  }
+}
+function profileEvaluation(fn) {
+  const mine = openScope();
+  try {
+    return { result: fn(), profile: summarise(mine) };
+  } finally {
+    closeScope(mine);
+  }
+}
+async function profileEvaluationAsync(fn) {
+  const mine = openScope();
+  try {
+    return { result: await fn(), profile: summarise(mine) };
+  } finally {
+    closeScope(mine);
+  }
+}
+function openScope() {
+  const mine = {
+    startedAt: performance.now(),
+    rounds: 0,
+    evaluations: 0,
+    rules: /* @__PURE__ */ new Map(),
+    relations: /* @__PURE__ */ new Map(),
+    derivedRelations: /* @__PURE__ */ new Set(),
+    ruleSets: /* @__PURE__ */ new Map()
+  };
+  open.push(mine);
+  return mine;
+}
+function closeScope(mine) {
+  const at = open.lastIndexOf(mine);
+  if (at !== -1) {
+    open.splice(at, 1);
+  }
+}
+var totalMs = (rules) => {
+  let ms = 0;
+  for (const cost of rules) {
+    ms += cost.ms;
+  }
+  return ms;
+};
+var byCost = (a, b) => b.ms - a.ms;
+function summarise(mine) {
+  return {
+    wallMs: performance.now() - mine.startedAt,
+    datalogMs: totalMs(mine.rules.values()),
+    rounds: mine.rounds,
+    evaluations: mine.evaluations,
+    relations: [...mine.relations].map(([relation, tuples]) => ({
+      relation,
+      tuples,
+      derived: mine.derivedRelations.has(relation)
+    })).sort((a, b) => b.tuples - a.tuples),
+    rules: [...mine.rules.values()].sort(byCost),
+    ruleSets: [...mine.ruleSets.values()].map((set) => ({
+      derives: [...set.derives],
+      ms: totalMs(set.rules.values()),
+      evaluations: set.evaluations,
+      rounds: set.rounds,
+      rules: [...set.rules.values()].sort(byCost)
+    })).sort((a, b) => b.ms - a.ms)
+  };
+}
+var share = (part, whole) => `${whole === 0 ? "0.0" : (part / whole * 100).toFixed(1)}%`.padStart(6);
+function ruleLines(rules, datalogMs) {
+  return rules.slice(0, 20).map((r) => {
+    const ms = `${r.ms.toFixed(0)}ms`.padStart(8);
+    const derived = String(r.derived).padStart(7);
+    return `    ${ms} ${share(r.ms, datalogMs)} ${derived} tuples  ${r.attempts} attempts  ${ruleKey(r.head, r.body)}`;
+  });
+}
+function formatProfile(profile) {
+  const lines = [];
+  lines.push(
+    `datalog: ${profile.datalogMs.toFixed(0)}ms (${share(profile.datalogMs, profile.wallMs).trim()} of ${profile.wallMs.toFixed(0)}ms wall), ${profile.evaluations} evaluations, ${profile.rounds} rounds`
+  );
+  const derivedTuples = profile.relations.filter((r) => r.derived).reduce((sum, r) => sum + r.tuples, 0);
+  lines.push("  tuples by relation (d = derived by a rule):");
+  for (const { relation, tuples, derived } of profile.relations.slice(0, 20)) {
+    const mark = derived ? "d" : " ";
+    const of = derived ? share(tuples, derivedTuples) : "     -";
+    lines.push(`    ${mark} ${String(tuples).padStart(8)} ${of}  ${relation}`);
+  }
+  lines.push("  time by rule:");
+  lines.push(...ruleLines(profile.rules, profile.datalogMs));
+  if (profile.ruleSets.length > 1) {
+    lines.push("  by rule set:");
+    for (const set of profile.ruleSets) {
+      lines.push(
+        `    ${`${set.ms.toFixed(0)}ms`.padStart(8)} ${share(set.ms, profile.datalogMs)}  ${set.evaluations} evaluations, ${set.rounds} rounds  ${set.derives.join(", ")}`
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
+// 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);
+    }
+  };
+  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]
+      });
+    }
+  }
+  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/index.ts
 var variable = (name) => ({ type: "variable", name });
 var constant = (value) => ({ type: "constant", value });
 var lit = (relation, ...terms) => ({
@@ -43,9 +350,8 @@ var notLit = (relation, ...terms) => ({
   negated: true
 });
 var rule = (relation, terms, body) => ({ head: { relation, terms }, body });
-var SEP = "\0";
-var atomKey = (a) => `${typeof a === "number" ? "n" : "s"}${a}`;
-var keyOf = (tuple) => tuple.map(atomKey).join(SEP);
+var atomKey = (a) => typeof a === "number" ? `n${a}:` : `s${a.length}:${a}`;
+var keyOf2 = (tuple) => tuple.map(atomKey).join("");
 function addToBucket(index, key, tuple) {
   const bucket = index.get(key);
   if (bucket === void 0) {
@@ -72,7 +378,7 @@ var Database = class {
   /** Add a fact; returns true when the tuple is new. */
   add(relationName, tuple) {
     const relation = this.relation(relationName);
-    const key = keyOf(tuple);
+    const key = keyOf2(tuple);
     if (relation.keys.has(key)) {
       if (!isDeriving(this)) {
         claimFact(this, relationName, key);
@@ -90,7 +396,7 @@ var Database = class {
     return true;
   }
   has(relationName, tuple) {
-    return this.store.get(relationName)?.keys.has(keyOf(tuple)) ?? false;
+    return this.store.get(relationName)?.keys.has(keyOf2(tuple)) ?? false;
   }
   facts(relationName) {
     return this.store.get(relationName)?.tuples ?? [];
@@ -136,7 +442,7 @@ var Database = class {
     }
     const going = /* @__PURE__ */ new Set();
     for (const tuple of tuples) {
-      const key = keyOf(tuple);
+      const key = keyOf2(tuple);
       if (relation.keys.has(key)) {
         going.add(key);
       }
@@ -148,7 +454,7 @@ var Database = class {
       relation.keys.delete(key);
     }
     relation.tuples = relation.tuples.filter(
-      (tuple) => !going.has(keyOf(tuple))
+      (tuple) => !going.has(keyOf2(tuple))
     );
     relation.indexes.clear();
     forgetFacts(this, relationName, going);
@@ -358,8 +664,40 @@ function evaluate(db, rules) {
     }
   }
 }
+function clearRelations(db, rules, relations) {
+  for (const relation of relations) {
+    db.retract(relation, [...db.facts(relation)]);
+  }
+  const state = statesFor(db).get(signatureOf(rules));
+  if (state !== void 0) {
+    state.marks = currentMarks(db);
+  }
+}
+var signatureOf = (rules) => shapeOf(rules).signature;
+var shapes = /* @__PURE__ */ new WeakMap();
+function shapeOf(rules) {
+  const known = shapes.get(rules);
+  if (known !== void 0) {
+    return known;
+  }
+  const derivedRelations = [...new Set(rules.map((r) => r.head.relation))];
+  const shape = {
+    signature: JSON.stringify(rules),
+    name: [...derivedRelations].sort().join(", "),
+    derivedRelations,
+    strata: stratify(rules)
+  };
+  shapes.set(rules, shape);
+  return shape;
+}
 function runRules(db, rules) {
-  const signature = JSON.stringify(rules);
+  const {
+    signature,
+    name: ruleSetName,
+    derivedRelations,
+    strata
+  } = shapeOf(rules);
+  chargeEvaluation(ruleSetName);
   const states = statesFor(db);
   const state = states.get(signature) ?? {
     marks: null,
@@ -374,7 +712,7 @@ function runRules(db, rules) {
   }
   const derived = state.derived;
   const marks = canResume(rules, state) ? state.marks : void 0;
-  for (const stratum of stratify(rules)) {
+  for (const stratum of strata) {
     let delta = /* @__PURE__ */ new Map();
     const derivedHere = new Set(stratum.map((r) => r.head.relation));
     const record = (relation, tuple) => {
@@ -385,8 +723,28 @@ function runRules(db, rules) {
           ledger = /* @__PURE__ */ new Map();
           derived.set(relation, ledger);
         }
-        ledger.set(keyOf(tuple), tuple);
+        ledger.set(keyOf2(tuple), tuple);
+      }
+    };
+    const runOneRule = (r, seed, deltaIndex) => {
+      if (!isProfiling()) {
+        for (const tuple of evaluateRule(db, seed, r, deltaIndex)) {
+          record(r.head.relation, tuple);
+        }
+        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);
       }
+      chargeRule(
+        ruleSetName,
+        r.head.relation,
+        r.body.map((l) => l.negated ? `!${l.relation}` : l.relation),
+        performance.now() - startedAt,
+        db.size(r.head.relation) - before
+      );
     };
     const applyDelta = (seed, derivedOnly) => {
       for (const r of stratum) {
@@ -399,9 +757,7 @@ function runRules(db, rules) {
           if ((seed.get(literal.relation) ?? []).length === 0) {
             continue;
           }
-          for (const tuple of evaluateRule(db, seed, r, i)) {
-            record(r.head.relation, tuple);
-          }
+          runOneRule(r, seed, i);
         }
       }
     };
@@ -413,20 +769,27 @@ function runRules(db, rules) {
             all.set(l.relation, db.facts(l.relation));
           }
         }
-        for (const tuple of evaluateRule(db, all, r, -1)) {
-          record(r.head.relation, tuple);
-        }
+        runOneRule(r, all, -1);
       }
+      chargeRound(ruleSetName);
     } else {
       applyDelta(factsSince(db, marks), false);
+      chargeRound(ruleSetName);
     }
     while (delta.size > 0) {
       const lastDelta = delta;
       delta = /* @__PURE__ */ new Map();
       applyDelta(lastDelta, true);
+      chargeRound(ruleSetName);
     }
   }
   state.marks = currentMarks(db);
+  if (isProfiling()) {
+    chargeRelationSizes(
+      db.relationNames().map((name) => [name, db.size(name)]),
+      derivedRelations
+    );
+  }
   return db;
 }
 function addTo(buckets, relation, tuple) {
@@ -440,10 +803,15 @@ function addTo(buckets, relation, tuple) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Database,
+  clearRelations,
   constant,
+  deriveOnDemand,
   evaluate,
+  formatProfile,
   lit,
   notLit,
+  profileEvaluation,
+  profileEvaluationAsync,
   rule,
   stratify,
   variable

package/dist/index.d.cts

@@ -1,3 +1,113 @@
+/** A rewritten rule set, and which of its relations demand restricts. */
+interface OnDemandRules {
+    /** The rewritten rules, ready to evaluate. */
+    rules: Rule[];
+    /**
+     * The relations derived only where a demand fact reaches them, the
+     * demand relations included. Every one of these is empty until
+     * somebody asks, and only the complete relations are derived from
+     * them, so a caller between questions can clear the lot and keep the
+     * answers.
+     */
+    demandDriven: string[];
+}
+/**
+ * Rewrite `rules` so the relations named 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
+ * first literal is a base relation the caller asserts, as in `answer(x,
+ * z) <- asked(x), comesTo(x, z)`, and the rewrite turns each `asked`
+ * 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
+ * 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.
+ */
+declare function deriveOnDemand(rules: Rule[], complete: readonly string[]): OnDemandRules;
+
+/** What one rule cost, summed over every attempt across every round. */
+interface RuleCost {
+    /** The relation this rule derives. */
+    head: string;
+    /** The body relations, in order, so a rule is recognisable in a report. */
+    body: string[];
+    /** Wall time spent evaluating this rule. */
+    ms: number;
+    /** Tuples this rule added that no earlier derivation had reached. */
+    derived: number;
+    /** How many times the rule was evaluated, over all rounds and deltas. */
+    attempts: number;
+}
+/**
+ * How big a relation grew. `derived` separates the relations rules
+ * concluded from the base facts an adapter emitted, because "derive fewer
+ * tuples" is advice about the first kind and meaningless about the second.
+ */
+interface RelationSize {
+    relation: string;
+    tuples: number;
+    derived: boolean;
+}
+/**
+ * What one rule set cost. A run evaluates several over several databases,
+ * and somebody comparing two changes wants to know which of them moved,
+ * so the totals are kept apart as well as summed.
+ */
+interface RuleSetCost {
+    /** The relations this rule set derives, which is how to tell them apart. */
+    derives: string[];
+    ms: number;
+    evaluations: number;
+    rounds: number;
+    rules: RuleCost[];
+}
+interface EvaluationProfile {
+    /** Wall time for everything the profiled scope did, datalog or not. */
+    wallMs: number;
+    /** Wall time inside rule evaluation, which is the engine's own cost. */
+    datalogMs: number;
+    /** Semi-naive rounds, summed over strata. The seed round counts as one. */
+    rounds: number;
+    /**
+     * How many times a caller asked for a fixpoint. A caller that queries
+     * as it goes evaluates once per query, and each of those re-joins the
+     * whole relation against a small delta, so this number rising with
+     * corpus size is worth more attention than the rule table.
+     */
+    evaluations: number;
+    /** Final tuple count per relation, largest first. */
+    relations: RelationSize[];
+    /** Per-rule cost across every rule set, most expensive first. */
+    rules: RuleCost[];
+    /** The same time, split by the rule set that spent it. */
+    ruleSets: RuleSetCost[];
+}
+/**
+ * Run `fn` with evaluation profiling on, and hand back what it returned
+ * alongside the numbers. Nested calls share the outer collector, so a
+ * caller that profiles a whole extraction gets one profile covering every
+ * `evaluate` inside it rather than a profile per call.
+ */
+declare function profileEvaluation<T>(fn: () => T): {
+    result: T;
+    profile: EvaluationProfile;
+};
+/**
+ * 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.
+ */
+declare function profileEvaluationAsync<T>(fn: () => Promise<T>): Promise<{
+    result: T;
+    profile: EvaluationProfile;
+}>;
+/** Render a profile as the table a human reads in a terminal. */
+declare function formatProfile(profile: EvaluationProfile): string;
+
 /** Tuple values. Callers intern richer identities (AST nodes, summaries) to atoms. */
 type Atom = string | number;
 type Tuple = readonly Atom[];
@@ -76,5 +186,27 @@ declare function stratify(rules: Rule[]): Rule[][];
  * proportional to new facts, not all facts.
  */
 declare function evaluate(db: Database, rules: Rule[]): Database;
+/**
+ * Empty these relations, and leave `rules` able to carry on from where
+ * it got to.
+ *
+ * `retract` cannot do this. A fact leaving the database can take away a
+ * conclusion drawn anywhere, so it sends the next run back to the base
+ * facts. A caller here is saying something stronger than "these facts
+ * are gone": nothing outside `relations` was derived from them, so what
+ * is left is already the fixpoint and the next run has only the facts
+ * that arrive after this to work through.
+ *
+ * That is what a demand-driven rule set gives a caller between
+ * 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.
+ *
+ * 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 Literal, type Rule, type Term, type Tuple, constant, evaluate, lit, notLit, 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, variable };

package/dist/index.d.ts

@@ -1,3 +1,113 @@
+/** A rewritten rule set, and which of its relations demand restricts. */
+interface OnDemandRules {
+    /** The rewritten rules, ready to evaluate. */
+    rules: Rule[];
+    /**
+     * The relations derived only where a demand fact reaches them, the
+     * demand relations included. Every one of these is empty until
+     * somebody asks, and only the complete relations are derived from
+     * them, so a caller between questions can clear the lot and keep the
+     * answers.
+     */
+    demandDriven: string[];
+}
+/**
+ * Rewrite `rules` so the relations named 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
+ * first literal is a base relation the caller asserts, as in `answer(x,
+ * z) <- asked(x), comesTo(x, z)`, and the rewrite turns each `asked`
+ * 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
+ * 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.
+ */
+declare function deriveOnDemand(rules: Rule[], complete: readonly string[]): OnDemandRules;
+
+/** What one rule cost, summed over every attempt across every round. */
+interface RuleCost {
+    /** The relation this rule derives. */
+    head: string;
+    /** The body relations, in order, so a rule is recognisable in a report. */
+    body: string[];
+    /** Wall time spent evaluating this rule. */
+    ms: number;
+    /** Tuples this rule added that no earlier derivation had reached. */
+    derived: number;
+    /** How many times the rule was evaluated, over all rounds and deltas. */
+    attempts: number;
+}
+/**
+ * How big a relation grew. `derived` separates the relations rules
+ * concluded from the base facts an adapter emitted, because "derive fewer
+ * tuples" is advice about the first kind and meaningless about the second.
+ */
+interface RelationSize {
+    relation: string;
+    tuples: number;
+    derived: boolean;
+}
+/**
+ * What one rule set cost. A run evaluates several over several databases,
+ * and somebody comparing two changes wants to know which of them moved,
+ * so the totals are kept apart as well as summed.
+ */
+interface RuleSetCost {
+    /** The relations this rule set derives, which is how to tell them apart. */
+    derives: string[];
+    ms: number;
+    evaluations: number;
+    rounds: number;
+    rules: RuleCost[];
+}
+interface EvaluationProfile {
+    /** Wall time for everything the profiled scope did, datalog or not. */
+    wallMs: number;
+    /** Wall time inside rule evaluation, which is the engine's own cost. */
+    datalogMs: number;
+    /** Semi-naive rounds, summed over strata. The seed round counts as one. */
+    rounds: number;
+    /**
+     * How many times a caller asked for a fixpoint. A caller that queries
+     * as it goes evaluates once per query, and each of those re-joins the
+     * whole relation against a small delta, so this number rising with
+     * corpus size is worth more attention than the rule table.
+     */
+    evaluations: number;
+    /** Final tuple count per relation, largest first. */
+    relations: RelationSize[];
+    /** Per-rule cost across every rule set, most expensive first. */
+    rules: RuleCost[];
+    /** The same time, split by the rule set that spent it. */
+    ruleSets: RuleSetCost[];
+}
+/**
+ * Run `fn` with evaluation profiling on, and hand back what it returned
+ * alongside the numbers. Nested calls share the outer collector, so a
+ * caller that profiles a whole extraction gets one profile covering every
+ * `evaluate` inside it rather than a profile per call.
+ */
+declare function profileEvaluation<T>(fn: () => T): {
+    result: T;
+    profile: EvaluationProfile;
+};
+/**
+ * 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.
+ */
+declare function profileEvaluationAsync<T>(fn: () => Promise<T>): Promise<{
+    result: T;
+    profile: EvaluationProfile;
+}>;
+/** Render a profile as the table a human reads in a terminal. */
+declare function formatProfile(profile: EvaluationProfile): string;
+
 /** Tuple values. Callers intern richer identities (AST nodes, summaries) to atoms. */
 type Atom = string | number;
 type Tuple = readonly Atom[];
@@ -76,5 +186,27 @@ declare function stratify(rules: Rule[]): Rule[][];
  * proportional to new facts, not all facts.
  */
 declare function evaluate(db: Database, rules: Rule[]): Database;
+/**
+ * Empty these relations, and leave `rules` able to carry on from where
+ * it got to.
+ *
+ * `retract` cannot do this. A fact leaving the database can take away a
+ * conclusion drawn anywhere, so it sends the next run back to the base
+ * facts. A caller here is saying something stronger than "these facts
+ * are gone": nothing outside `relations` was derived from them, so what
+ * is left is already the fixpoint and the next run has only the facts
+ * that arrive after this to work through.
+ *
+ * That is what a demand-driven rule set gives a caller between
+ * 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.
+ *
+ * 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 Literal, type Rule, type Term, type Tuple, constant, evaluate, lit, notLit, 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, variable };

package/dist/index.js

@@ -1,3 +1,303 @@
+// src/profile.ts
+var open = [];
+var isProfiling = () => open.length > 0;
+var ruleKey = (head, body) => `${head} <- ${body.join(", ")}`;
+function addCost(into, key, head, body, ms, derived) {
+  const existing = into.get(key);
+  if (existing === void 0) {
+    into.set(key, { head, body, ms, derived, attempts: 1 });
+    return;
+  }
+  existing.ms += ms;
+  existing.derived += derived;
+  existing.attempts += 1;
+}
+function chargeRule(ruleSet, head, body, ms, derived) {
+  const key = ruleKey(head, body);
+  for (const collector of open) {
+    addCost(collector.rules, key, head, body, ms, derived);
+    addCost(setIn(collector, ruleSet).rules, key, head, body, ms, derived);
+  }
+}
+function chargeEvaluation(ruleSet) {
+  for (const collector of open) {
+    collector.evaluations += 1;
+    setIn(collector, ruleSet).evaluations += 1;
+  }
+}
+function chargeRound(ruleSet) {
+  for (const collector of open) {
+    collector.rounds += 1;
+    setIn(collector, ruleSet).rounds += 1;
+  }
+}
+function setIn(collector, ruleSet) {
+  const existing = collector.ruleSets.get(ruleSet);
+  if (existing !== void 0) {
+    return existing;
+  }
+  const created = {
+    derives: new Set(ruleSet.split(", ")),
+    evaluations: 0,
+    rounds: 0,
+    rules: /* @__PURE__ */ new Map()
+  };
+  collector.ruleSets.set(ruleSet, created);
+  return created;
+}
+function chargeRelationSizes(entries, derivedRelations) {
+  const sizes = [...entries];
+  const derived = [...derivedRelations];
+  for (const collector of open) {
+    for (const [relation, tuples] of sizes) {
+      const seen = collector.relations.get(relation) ?? 0;
+      if (tuples > seen) {
+        collector.relations.set(relation, tuples);
+      }
+    }
+    for (const relation of derived) {
+      collector.derivedRelations.add(relation);
+    }
+  }
+}
+function profileEvaluation(fn) {
+  const mine = openScope();
+  try {
+    return { result: fn(), profile: summarise(mine) };
+  } finally {
+    closeScope(mine);
+  }
+}
+async function profileEvaluationAsync(fn) {
+  const mine = openScope();
+  try {
+    return { result: await fn(), profile: summarise(mine) };
+  } finally {
+    closeScope(mine);
+  }
+}
+function openScope() {
+  const mine = {
+    startedAt: performance.now(),
+    rounds: 0,
+    evaluations: 0,
+    rules: /* @__PURE__ */ new Map(),
+    relations: /* @__PURE__ */ new Map(),
+    derivedRelations: /* @__PURE__ */ new Set(),
+    ruleSets: /* @__PURE__ */ new Map()
+  };
+  open.push(mine);
+  return mine;
+}
+function closeScope(mine) {
+  const at = open.lastIndexOf(mine);
+  if (at !== -1) {
+    open.splice(at, 1);
+  }
+}
+var totalMs = (rules) => {
+  let ms = 0;
+  for (const cost of rules) {
+    ms += cost.ms;
+  }
+  return ms;
+};
+var byCost = (a, b) => b.ms - a.ms;
+function summarise(mine) {
+  return {
+    wallMs: performance.now() - mine.startedAt,
+    datalogMs: totalMs(mine.rules.values()),
+    rounds: mine.rounds,
+    evaluations: mine.evaluations,
+    relations: [...mine.relations].map(([relation, tuples]) => ({
+      relation,
+      tuples,
+      derived: mine.derivedRelations.has(relation)
+    })).sort((a, b) => b.tuples - a.tuples),
+    rules: [...mine.rules.values()].sort(byCost),
+    ruleSets: [...mine.ruleSets.values()].map((set) => ({
+      derives: [...set.derives],
+      ms: totalMs(set.rules.values()),
+      evaluations: set.evaluations,
+      rounds: set.rounds,
+      rules: [...set.rules.values()].sort(byCost)
+    })).sort((a, b) => b.ms - a.ms)
+  };
+}
+var share = (part, whole) => `${whole === 0 ? "0.0" : (part / whole * 100).toFixed(1)}%`.padStart(6);
+function ruleLines(rules, datalogMs) {
+  return rules.slice(0, 20).map((r) => {
+    const ms = `${r.ms.toFixed(0)}ms`.padStart(8);
+    const derived = String(r.derived).padStart(7);
+    return `    ${ms} ${share(r.ms, datalogMs)} ${derived} tuples  ${r.attempts} attempts  ${ruleKey(r.head, r.body)}`;
+  });
+}
+function formatProfile(profile) {
+  const lines = [];
+  lines.push(
+    `datalog: ${profile.datalogMs.toFixed(0)}ms (${share(profile.datalogMs, profile.wallMs).trim()} of ${profile.wallMs.toFixed(0)}ms wall), ${profile.evaluations} evaluations, ${profile.rounds} rounds`
+  );
+  const derivedTuples = profile.relations.filter((r) => r.derived).reduce((sum, r) => sum + r.tuples, 0);
+  lines.push("  tuples by relation (d = derived by a rule):");
+  for (const { relation, tuples, derived } of profile.relations.slice(0, 20)) {
+    const mark = derived ? "d" : " ";
+    const of = derived ? share(tuples, derivedTuples) : "     -";
+    lines.push(`    ${mark} ${String(tuples).padStart(8)} ${of}  ${relation}`);
+  }
+  lines.push("  time by rule:");
+  lines.push(...ruleLines(profile.rules, profile.datalogMs));
+  if (profile.ruleSets.length > 1) {
+    lines.push("  by rule set:");
+    for (const set of profile.ruleSets) {
+      lines.push(
+        `    ${`${set.ms.toFixed(0)}ms`.padStart(8)} ${share(set.ms, profile.datalogMs)}  ${set.evaluations} evaluations, ${set.rounds} rounds  ${set.derives.join(", ")}`
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
+// 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);
+    }
+  };
+  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]
+      });
+    }
+  }
+  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/index.ts
 var variable = (name) => ({ type: "variable", name });
 var constant = (value) => ({ type: "constant", value });
@@ -12,9 +312,8 @@ var notLit = (relation, ...terms) => ({
   negated: true
 });
 var rule = (relation, terms, body) => ({ head: { relation, terms }, body });
-var SEP = "\0";
-var atomKey = (a) => `${typeof a === "number" ? "n" : "s"}${a}`;
-var keyOf = (tuple) => tuple.map(atomKey).join(SEP);
+var atomKey = (a) => typeof a === "number" ? `n${a}:` : `s${a.length}:${a}`;
+var keyOf2 = (tuple) => tuple.map(atomKey).join("");
 function addToBucket(index, key, tuple) {
   const bucket = index.get(key);
   if (bucket === void 0) {
@@ -41,7 +340,7 @@ var Database = class {
   /** Add a fact; returns true when the tuple is new. */
   add(relationName, tuple) {
     const relation = this.relation(relationName);
-    const key = keyOf(tuple);
+    const key = keyOf2(tuple);
     if (relation.keys.has(key)) {
       if (!isDeriving(this)) {
         claimFact(this, relationName, key);
@@ -59,7 +358,7 @@ var Database = class {
     return true;
   }
   has(relationName, tuple) {
-    return this.store.get(relationName)?.keys.has(keyOf(tuple)) ?? false;
+    return this.store.get(relationName)?.keys.has(keyOf2(tuple)) ?? false;
   }
   facts(relationName) {
     return this.store.get(relationName)?.tuples ?? [];
@@ -105,7 +404,7 @@ var Database = class {
     }
     const going = /* @__PURE__ */ new Set();
     for (const tuple of tuples) {
-      const key = keyOf(tuple);
+      const key = keyOf2(tuple);
       if (relation.keys.has(key)) {
         going.add(key);
       }
@@ -117,7 +416,7 @@ var Database = class {
       relation.keys.delete(key);
     }
     relation.tuples = relation.tuples.filter(
-      (tuple) => !going.has(keyOf(tuple))
+      (tuple) => !going.has(keyOf2(tuple))
     );
     relation.indexes.clear();
     forgetFacts(this, relationName, going);
@@ -327,8 +626,40 @@ function evaluate(db, rules) {
     }
   }
 }
+function clearRelations(db, rules, relations) {
+  for (const relation of relations) {
+    db.retract(relation, [...db.facts(relation)]);
+  }
+  const state = statesFor(db).get(signatureOf(rules));
+  if (state !== void 0) {
+    state.marks = currentMarks(db);
+  }
+}
+var signatureOf = (rules) => shapeOf(rules).signature;
+var shapes = /* @__PURE__ */ new WeakMap();
+function shapeOf(rules) {
+  const known = shapes.get(rules);
+  if (known !== void 0) {
+    return known;
+  }
+  const derivedRelations = [...new Set(rules.map((r) => r.head.relation))];
+  const shape = {
+    signature: JSON.stringify(rules),
+    name: [...derivedRelations].sort().join(", "),
+    derivedRelations,
+    strata: stratify(rules)
+  };
+  shapes.set(rules, shape);
+  return shape;
+}
 function runRules(db, rules) {
-  const signature = JSON.stringify(rules);
+  const {
+    signature,
+    name: ruleSetName,
+    derivedRelations,
+    strata
+  } = shapeOf(rules);
+  chargeEvaluation(ruleSetName);
   const states = statesFor(db);
   const state = states.get(signature) ?? {
     marks: null,
@@ -343,7 +674,7 @@ function runRules(db, rules) {
   }
   const derived = state.derived;
   const marks = canResume(rules, state) ? state.marks : void 0;
-  for (const stratum of stratify(rules)) {
+  for (const stratum of strata) {
     let delta = /* @__PURE__ */ new Map();
     const derivedHere = new Set(stratum.map((r) => r.head.relation));
     const record = (relation, tuple) => {
@@ -354,9 +685,29 @@ function runRules(db, rules) {
           ledger = /* @__PURE__ */ new Map();
           derived.set(relation, ledger);
         }
-        ledger.set(keyOf(tuple), tuple);
+        ledger.set(keyOf2(tuple), tuple);
       }
     };
+    const runOneRule = (r, seed, deltaIndex) => {
+      if (!isProfiling()) {
+        for (const tuple of evaluateRule(db, seed, r, deltaIndex)) {
+          record(r.head.relation, tuple);
+        }
+        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);
+      }
+      chargeRule(
+        ruleSetName,
+        r.head.relation,
+        r.body.map((l) => l.negated ? `!${l.relation}` : l.relation),
+        performance.now() - startedAt,
+        db.size(r.head.relation) - before
+      );
+    };
     const applyDelta = (seed, derivedOnly) => {
       for (const r of stratum) {
         const positives = r.body.filter((l) => !l.negated);
@@ -368,9 +719,7 @@ function runRules(db, rules) {
           if ((seed.get(literal.relation) ?? []).length === 0) {
             continue;
           }
-          for (const tuple of evaluateRule(db, seed, r, i)) {
-            record(r.head.relation, tuple);
-          }
+          runOneRule(r, seed, i);
         }
       }
     };
@@ -382,20 +731,27 @@ function runRules(db, rules) {
             all.set(l.relation, db.facts(l.relation));
           }
         }
-        for (const tuple of evaluateRule(db, all, r, -1)) {
-          record(r.head.relation, tuple);
-        }
+        runOneRule(r, all, -1);
       }
+      chargeRound(ruleSetName);
     } else {
       applyDelta(factsSince(db, marks), false);
+      chargeRound(ruleSetName);
     }
     while (delta.size > 0) {
       const lastDelta = delta;
       delta = /* @__PURE__ */ new Map();
       applyDelta(lastDelta, true);
+      chargeRound(ruleSetName);
     }
   }
   state.marks = currentMarks(db);
+  if (isProfiling()) {
+    chargeRelationSizes(
+      db.relationNames().map((name) => [name, db.size(name)]),
+      derivedRelations
+    );
+  }
   return db;
 }
 function addTo(buckets, relation, tuple) {
@@ -408,10 +764,15 @@ function addTo(buckets, relation, tuple) {
 }
 export {
   Database,
+  clearRelations,
   constant,
+  deriveOnDemand,
   evaluate,
+  formatProfile,
   lit,
   notLit,
+  profileEvaluation,
+  profileEvaluationAsync,
   rule,
   stratify,
   variable

package/package.json

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