@suss/datalog 0.31.0 → 0.31.1

package/dist/index.cjs

@@ -20,8 +20,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BudgetExhausted: () => BudgetExhausted,
   Database: () => Database,
   Witness: () => Witness,
+  chargeAbandoned: () => chargeAbandoned,
+  chargeQuestion: () => chargeQuestion,
   clearRelations: () => clearRelations,
   confidence: () => confidence,
   confidenceWith: () => confidenceWith,
@@ -34,6 +37,7 @@ __export(index_exports, {
   profileEvaluation: () => profileEvaluation,
   profileEvaluationAsync: () => profileEvaluationAsync,
   proofOf: () => proofOf,
+  rowBudget: () => rowBudget,
   rule: () => rule,
   ruleLabel: () => ruleLabel,
   stratify: () => stratify,
@@ -231,21 +235,43 @@ function bodyAdornments(r, headAdornment, derives) {
 var open = [];
 var isProfiling = () => open.length > 0;
 var ruleKey = (head, body) => `${head} <- ${body.join(", ")}`;
-function addCost(into, key, head, body, ms, derived) {
+function addCost(into, key, head, body, ms, derived, examined) {
   const existing = into.get(key);
   if (existing === void 0) {
-    into.set(key, { head, body, ms, derived, attempts: 1 });
+    into.set(key, { head, body, ms, derived, examined, attempts: 1 });
     return;
   }
   existing.ms += ms;
   existing.derived += derived;
+  existing.examined += examined;
   existing.attempts += 1;
 }
-function chargeRule(ruleSet, head, body, ms, derived) {
+function chargeRule(ruleSet, head, body, ms, derived, examined) {
   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);
+    addCost(collector.rules, key, head, body, ms, derived, examined);
+    addCost(
+      setIn(collector, ruleSet).rules,
+      key,
+      head,
+      body,
+      ms,
+      derived,
+      examined
+    );
+  }
+}
+function chargeAbandoned(question, examined) {
+  for (const collector of open) {
+    collector.abandoned.push({ question, examined });
+  }
+}
+function chargeQuestion(outcome) {
+  for (const collector of open) {
+    collector.questions.asked += 1;
+    if (outcome !== void 0) {
+      collector.questions[outcome] += 1;
+    }
   }
 }
 function chargeEvaluation(ruleSet) {
@@ -254,6 +280,13 @@ function chargeEvaluation(ruleSet) {
     setIn(collector, ruleSet).evaluations += 1;
   }
 }
+function chargeEvaluationRows(examined) {
+  for (const collector of open) {
+    if (examined > collector.largestEvaluation) {
+      collector.largestEvaluation = examined;
+    }
+  }
+}
 function chargeRound(ruleSet) {
   for (const collector of open) {
     collector.rounds += 1;
@@ -313,7 +346,10 @@ function openScope() {
     rules: /* @__PURE__ */ new Map(),
     relations: /* @__PURE__ */ new Map(),
     derivedRelations: /* @__PURE__ */ new Set(),
-    ruleSets: /* @__PURE__ */ new Map()
+    ruleSets: /* @__PURE__ */ new Map(),
+    abandoned: [],
+    largestEvaluation: 0,
+    questions: { asked: 0, abandoned: 0, skipped: 0 }
   };
   open.push(mine);
   return mine;
@@ -331,6 +367,13 @@ var totalMs = (rules) => {
   }
   return ms;
 };
+var totalExamined = (rules) => {
+  let rows = 0;
+  for (const cost of rules) {
+    rows += cost.examined;
+  }
+  return rows;
+};
 var byCost = (a, b) => b.ms - a.ms;
 function summarise(mine) {
   return {
@@ -338,6 +381,10 @@ function summarise(mine) {
     datalogMs: totalMs(mine.rules.values()),
     rounds: mine.rounds,
     evaluations: mine.evaluations,
+    examined: totalExamined(mine.rules.values()),
+    largestEvaluation: mine.largestEvaluation,
+    abandoned: [...mine.abandoned],
+    questions: { ...mine.questions },
     relations: [...mine.relations].map(([relation, tuples]) => ({
       relation,
       tuples,
@@ -358,14 +405,26 @@ 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)}`;
+    const examined = String(r.examined).padStart(9);
+    return `    ${ms} ${share(r.ms, datalogMs)} ${derived} tuples ${examined} rows read  ${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`
+    `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, ${profile.examined} rows read (${profile.largestEvaluation} in the biggest evaluation)`
   );
+  const { asked, abandoned, skipped } = profile.questions;
+  if (asked > 0) {
+    lines.push(
+      `  ${asked} questions under a site: ${abandoned} given up part way, ${skipped} never put once the run's rows were spent`
+    );
+  }
+  for (const given of profile.abandoned) {
+    lines.push(
+      `  gave up on ${given.question} after reading ${given.examined} rows`
+    );
+  }
   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)) {
@@ -838,7 +897,22 @@ function planBodyOrder(r, deltaAt) {
   }
   return order;
 }
-function evaluateRule(db, deltas, r, deltaIndex) {
+var rowBudget = (limit) => ({
+  examined: 0,
+  limit
+});
+var OUT_OF_BUDGET = /* @__PURE__ */ Symbol("datalog row budget exhausted");
+var BudgetExhausted = class extends Error {
+  constructor(ruleSet, examined) {
+    super(`gave up after reading ${examined} rows without settling`);
+    this.ruleSet = ruleSet;
+    this.examined = examined;
+    this.name = "BudgetExhausted";
+  }
+  ruleSet;
+  examined;
+};
+function evaluateRule(db, deltas, r, deltaIndex, budget) {
   const results = [];
   const { deltaAt, order } = bodyPlan(r, deltaIndex);
   const step = (orderIndex, bindings) => {
@@ -856,6 +930,10 @@ function evaluateRule(db, deltas, r, deltaIndex) {
     }
     const source = literalIndex === deltaAt ? deltas.get(literal.relation) ?? [] : boundSource(db, literal, bindings);
     for (const tuple of source) {
+      budget.examined++;
+      if (budget.examined > budget.limit) {
+        throw OUT_OF_BUDGET;
+      }
       const next = unify(literal, tuple, bindings);
       if (next !== NO_MATCH) {
         step(orderIndex + 1, next);
@@ -884,7 +962,7 @@ function boundSource(db, literal, bindings) {
   return narrowest ?? db.facts(literal.relation);
 }
 var EMPTY_TAGS = [];
-function evaluateRuleTagged(db, deltas, r, deltaIndex, algebra) {
+function evaluateRuleTagged(db, deltas, r, deltaIndex, algebra, budget) {
   const results = [];
   const bodyTags = [];
   const bodyMatches = [];
@@ -922,6 +1000,7 @@ function evaluateRuleTagged(db, deltas, r, deltaIndex, algebra) {
     }
     const source = positiveIndex === deltaIndex ? deltas.get(literal.relation) ?? [] : boundSource(db, literal, bindings);
     for (const tuple of source) {
+      budget.examined++;
       const next = unify(literal, tuple, bindings);
       if (next !== NO_MATCH) {
         if (readsTags) {
@@ -1005,15 +1084,18 @@ function currentMarks(db) {
   }
   return marks;
 }
-function evaluate(db, rules, algebra) {
+function evaluate(db, rules, algebra, budget) {
   if (algebra !== void 0 && isDemandRewritten(rules)) {
     throw new Error(
       "cannot evaluate demand-rewritten rules with a tag algebra: tags would follow the demand-transformed rules rather than the ones the caller wrote"
     );
   }
+  if (algebra !== void 0 && budget !== void 0) {
+    throw new Error("cannot evaluate with both a tag algebra and a row budget");
+  }
   deriving.set(db, (deriving.get(db) ?? 0) + 1);
   try {
-    return runRules(db, rules, algebra);
+    return runRules(db, rules, algebra, budget);
   } finally {
     const depth = (deriving.get(db) ?? 1) - 1;
     if (depth === 0) {
@@ -1063,13 +1145,19 @@ function storedMergeFor(algebra) {
     return stored === void 0 && merged === algebra.asserted ? void 0 : merged;
   };
 }
-function runRules(db, rules, algebra) {
+function runRules(db, rules, algebra, given) {
   const {
     signature,
     name: ruleSetName,
     derivedRelations,
     strata
   } = shapeOf(rules);
+  const budget = given ?? {
+    examined: 0,
+    limit: Number.POSITIVE_INFINITY
+  };
+  const startedAt = budget.examined;
+  const addedHere = given === void 0 ? null : [];
   chargeEvaluation(ruleSetName);
   const states = statesFor(db);
   const state = states.get(signature) ?? {
@@ -1091,10 +1179,11 @@ function runRules(db, rules, algebra) {
       derived.set(relation, ledger);
     }
     ledger.set(keyOf2(tuple), tuple);
+    addedHere?.push([relation, tuple]);
   };
   const mergeStored = algebra === void 0 ? void 0 : storedMergeFor(algebra);
   const marks = canResume(rules, state) ? state.marks : void 0;
-  for (const stratum of strata) {
+  const runStratum = (stratum) => {
     let delta = /* @__PURE__ */ new Map();
     const derivedHere = new Set(stratum.map((r) => r.head.relation));
     const record = (relation, tuple) => {
@@ -1120,13 +1209,14 @@ function runRules(db, rules, algebra) {
           seed,
           r,
           deltaIndex,
-          algebra
+          algebra,
+          budget
         )) {
           recordTagged(r.head.relation, found.tuple, found.tag);
         }
         return;
       }
-      for (const tuple of evaluateRule(db, seed, r, deltaIndex)) {
+      for (const tuple of evaluateRule(db, seed, r, deltaIndex, budget)) {
         record(r.head.relation, tuple);
       }
     };
@@ -1135,15 +1225,17 @@ function runRules(db, rules, algebra) {
         deriveInto(r, seed, deltaIndex);
         return;
       }
-      const startedAt = performance.now();
+      const startedAt2 = performance.now();
       const before = db.size(r.head.relation);
+      const readBefore = budget.examined;
       deriveInto(r, seed, deltaIndex);
       chargeRule(
         ruleSetName,
         r.head.relation,
         r.body.map(literalName),
-        performance.now() - startedAt,
-        db.size(r.head.relation) - before
+        performance.now() - startedAt2,
+        db.size(r.head.relation) - before,
+        budget.examined - readBefore
       );
     };
     const applyDelta = (seed, derivedOnly) => {
@@ -1188,7 +1280,24 @@ function runRules(db, rules, algebra) {
       applyDelta(lastDelta, true);
       chargeRound(ruleSetName);
     }
+  };
+  const readHere = () => budget.examined - startedAt;
+  try {
+    for (const stratum of strata) {
+      runStratum(stratum);
+    }
+  } catch (error) {
+    if (error !== OUT_OF_BUDGET) {
+      throw error;
+    }
+    for (const [relation, tuples] of byRelation(addedHere ?? [])) {
+      db.retract(relation, tuples);
+    }
+    state.marks = null;
+    chargeEvaluationRows(readHere());
+    throw new BudgetExhausted(ruleSetName, readHere());
   }
+  chargeEvaluationRows(readHere());
   state.marks = currentMarks(db);
   if (isProfiling()) {
     chargeRelationSizes(
@@ -1198,6 +1307,13 @@ function runRules(db, rules, algebra) {
   }
   return db;
 }
+function byRelation(added) {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const [relation, tuple] of added) {
+    addTo(buckets, relation, tuple);
+  }
+  return buckets;
+}
 function addTo(buckets, relation, tuple) {
   const bucket = buckets.get(relation);
   if (bucket === void 0) {
@@ -1208,8 +1324,11 @@ function addTo(buckets, relation, tuple) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BudgetExhausted,
   Database,
   Witness,
+  chargeAbandoned,
+  chargeQuestion,
   clearRelations,
   confidence,
   confidenceWith,
@@ -1222,6 +1341,7 @@ function addTo(buckets, relation, tuple) {
   profileEvaluation,
   profileEvaluationAsync,
   proofOf,
+  rowBudget,
   rule,
   ruleLabel,
   stratify,

package/dist/index.d.cts

@@ -90,9 +90,32 @@ interface RuleCost {
     ms: number;
     /** Tuples this rule added that no earlier derivation had reached. */
     derived: number;
+    /**
+     * Rows the join read for this rule. A rule that examines a hundred
+     * thousand rows to derive a dozen tuples is doing a walk somebody
+     * meant to be a lookup, and `derived` alone never shows that.
+     */
+    examined: number;
     /** How many times the rule was evaluated, over all rounds and deltas. */
     attempts: number;
 }
+/** A question the engine gave up on, and how much it had read by then. */
+interface AbandonedQuestion {
+    /** What the caller was asking, in whatever words the caller uses. */
+    question: string;
+    examined: number;
+}
+/**
+ * How a caller that asks one question at a time got on. `skipped` are
+ * the ones it never put, because what it had already spent was gone.
+ */
+interface QuestionTally {
+    asked: number;
+    abandoned: number;
+    skipped: number;
+}
+/** How one question ended, for the tally. */
+type QuestionOutcome = keyof Omit<QuestionTally, "asked">;
 /**
  * How big a relation grew. `derived` separates the relations rules
  * concluded from the base facts an adapter emitted, because "derive fewer
@@ -130,6 +153,18 @@ interface EvaluationProfile {
      * corpus size is worth more attention than the rule table.
      */
     evaluations: number;
+    /** Rows every join read, summed over every rule set. */
+    examined: number;
+    /**
+     * The most rows any one `evaluate` call read. A caller that asks a
+     * question at a time sizes a per-question budget off this, where the
+     * total only says how many questions it asked.
+     */
+    largestEvaluation: number;
+    /** Every question abandoned on its budget, in the order they were given up. */
+    abandoned: AbandonedQuestion[];
+    /** How many questions a one-at-a-time caller asked, and how they went. */
+    questions: QuestionTally;
     /** Final tuple count per relation, largest first. */
     relations: RelationSize[];
     /** Per-rule cost across every rule set, most expensive first. */
@@ -137,6 +172,17 @@ interface EvaluationProfile {
     /** The same time, split by the rule set that spent it. */
     ruleSets: RuleSetCost[];
 }
+/**
+ * Note that a question was given up on. A caller reading this in a
+ * profile is looking at the reason an answer came back empty, so the
+ * question is recorded in the caller's own words.
+ */
+declare function chargeAbandoned(question: string, examined: number): void;
+/**
+ * Note that a caller put one question. `outcome` says whether it was
+ * given up part way or never put at all; leave it out when it answered.
+ */
+declare function chargeQuestion(outcome?: QuestionOutcome): void;
 /**
  * Run `fn` with evaluation profiling on, and hand back what it returned
  * alongside the numbers. Nested calls share the outer collector, so a
@@ -403,18 +449,54 @@ interface Derivation {
  * stratified, so this throws.
  */
 declare function stratify(rules: Rule[]): Rule[][];
+/**
+ * How many rows the joins of one evaluation may read, and how many they
+ * have read so far. Counting rows rather than new tuples is what catches
+ * a question that walks: the walk finds the same conclusions over and
+ * over, so nothing new arrives while the reading runs away.
+ *
+ * The caller builds one with `rowBudget` and reads `examined` back after
+ * the call, which is how it learns what a question cost whether or not
+ * the question settled. An evaluation with no budget gets a limit of
+ * Infinity, so the hot loop does the same increment and the same
+ * compare either way.
+ */
+interface RowBudget {
+    examined: number;
+    limit: number;
+}
+/** A budget for one evaluation, ready to hand to `evaluate`. */
+declare const rowBudget: (limit: number) => RowBudget;
+/**
+ * What `evaluate` throws when a row budget runs out.
+ *
+ * By the time this reaches a caller the database is back where it
+ * started: every fact that evaluation derived has been retracted, and
+ * the rule set will start over from the base facts next time rather
+ * than from a delta that was never worked through. The caller's own
+ * facts, the question it asked among them, are still there for it to
+ * take back.
+ */
+declare class BudgetExhausted extends Error {
+    readonly ruleSet: string;
+    readonly examined: number;
+    constructor(ruleSet: string, examined: number);
+}
 /**
  * Evaluate `rules` over `db` to fixpoint, adding derived facts in
  * place. Rules are stratified first; within a stratum, semi-naïve
- * iteration joins each rule against the last round's delta so work is
- * proportional to new facts, not all facts.
+ * iteration joins each rule against the last round's delta, so work
+ * is proportional to new facts rather than to all facts.
  *
  * With an `algebra`, every derivation also tags its conclusion (see
- * `TagAlgebra`). Supply the same algebra on every evaluation of a rule
- * set over a database: a resumed run derives only from the new facts,
- * so it tags only what those reach.
+ * `TagAlgebra`). Supply the same algebra every time over one
+ * database: a resumed run tags only what the new facts reach.
+ *
+ * With a `budget`, evaluation gives up once its joins have read that
+ * many rows and throws `BudgetExhausted`. Either way the budget says
+ * afterwards what the evaluation cost.
  */
-declare function evaluate<Tag = never>(db: Database, rules: Rule[], algebra?: TagAlgebra<Tag>): Database;
+declare function evaluate<Tag = never>(db: Database, rules: Rule[], algebra?: TagAlgebra<Tag>, budget?: RowBudget): Database;
 /**
  * Empty these relations, and leave `rules` able to carry on from where
  * it got to.
@@ -438,4 +520,4 @@ declare function evaluate<Tag = never>(db: Database, rules: Rule[], algebra?: Ta
  */
 declare function clearRelations(db: Database, rules: Rule[], relations: readonly string[]): void;
 
-export { type AddOutcome, type Atom, type BodyMatch, type ConfidenceLevel, Database, type Demand, type Derivation, type EvaluationProfile, type Literal, type OnDemandRules, type Proof, type ProofDerived, type ProofOptions, type Rule, type RuleCost, type TagAlgebra, type Term, type Tuple, Witness, type WitnessTag, clearRelations, confidence, confidenceWith, constant, deriveOnDemand, evaluate, formatProfile, lit, notLit, profileEvaluation, profileEvaluationAsync, proofOf, rule, ruleLabel, stratify, tupleKey, tupleKeyParts, variable, witnesses };
+export { type AbandonedQuestion, type AddOutcome, type Atom, type BodyMatch, BudgetExhausted, type ConfidenceLevel, Database, type Demand, type Derivation, type EvaluationProfile, type Literal, type OnDemandRules, type Proof, type ProofDerived, type ProofOptions, type QuestionOutcome, type QuestionTally, type RowBudget, type Rule, type RuleCost, type TagAlgebra, type Term, type Tuple, Witness, type WitnessTag, chargeAbandoned, chargeQuestion, clearRelations, confidence, confidenceWith, constant, deriveOnDemand, evaluate, formatProfile, lit, notLit, profileEvaluation, profileEvaluationAsync, proofOf, rowBudget, rule, ruleLabel, stratify, tupleKey, tupleKeyParts, variable, witnesses };

package/dist/index.d.ts

@@ -90,9 +90,32 @@ interface RuleCost {
     ms: number;
     /** Tuples this rule added that no earlier derivation had reached. */
     derived: number;
+    /**
+     * Rows the join read for this rule. A rule that examines a hundred
+     * thousand rows to derive a dozen tuples is doing a walk somebody
+     * meant to be a lookup, and `derived` alone never shows that.
+     */
+    examined: number;
     /** How many times the rule was evaluated, over all rounds and deltas. */
     attempts: number;
 }
+/** A question the engine gave up on, and how much it had read by then. */
+interface AbandonedQuestion {
+    /** What the caller was asking, in whatever words the caller uses. */
+    question: string;
+    examined: number;
+}
+/**
+ * How a caller that asks one question at a time got on. `skipped` are
+ * the ones it never put, because what it had already spent was gone.
+ */
+interface QuestionTally {
+    asked: number;
+    abandoned: number;
+    skipped: number;
+}
+/** How one question ended, for the tally. */
+type QuestionOutcome = keyof Omit<QuestionTally, "asked">;
 /**
  * How big a relation grew. `derived` separates the relations rules
  * concluded from the base facts an adapter emitted, because "derive fewer
@@ -130,6 +153,18 @@ interface EvaluationProfile {
      * corpus size is worth more attention than the rule table.
      */
     evaluations: number;
+    /** Rows every join read, summed over every rule set. */
+    examined: number;
+    /**
+     * The most rows any one `evaluate` call read. A caller that asks a
+     * question at a time sizes a per-question budget off this, where the
+     * total only says how many questions it asked.
+     */
+    largestEvaluation: number;
+    /** Every question abandoned on its budget, in the order they were given up. */
+    abandoned: AbandonedQuestion[];
+    /** How many questions a one-at-a-time caller asked, and how they went. */
+    questions: QuestionTally;
     /** Final tuple count per relation, largest first. */
     relations: RelationSize[];
     /** Per-rule cost across every rule set, most expensive first. */
@@ -137,6 +172,17 @@ interface EvaluationProfile {
     /** The same time, split by the rule set that spent it. */
     ruleSets: RuleSetCost[];
 }
+/**
+ * Note that a question was given up on. A caller reading this in a
+ * profile is looking at the reason an answer came back empty, so the
+ * question is recorded in the caller's own words.
+ */
+declare function chargeAbandoned(question: string, examined: number): void;
+/**
+ * Note that a caller put one question. `outcome` says whether it was
+ * given up part way or never put at all; leave it out when it answered.
+ */
+declare function chargeQuestion(outcome?: QuestionOutcome): void;
 /**
  * Run `fn` with evaluation profiling on, and hand back what it returned
  * alongside the numbers. Nested calls share the outer collector, so a
@@ -403,18 +449,54 @@ interface Derivation {
  * stratified, so this throws.
  */
 declare function stratify(rules: Rule[]): Rule[][];
+/**
+ * How many rows the joins of one evaluation may read, and how many they
+ * have read so far. Counting rows rather than new tuples is what catches
+ * a question that walks: the walk finds the same conclusions over and
+ * over, so nothing new arrives while the reading runs away.
+ *
+ * The caller builds one with `rowBudget` and reads `examined` back after
+ * the call, which is how it learns what a question cost whether or not
+ * the question settled. An evaluation with no budget gets a limit of
+ * Infinity, so the hot loop does the same increment and the same
+ * compare either way.
+ */
+interface RowBudget {
+    examined: number;
+    limit: number;
+}
+/** A budget for one evaluation, ready to hand to `evaluate`. */
+declare const rowBudget: (limit: number) => RowBudget;
+/**
+ * What `evaluate` throws when a row budget runs out.
+ *
+ * By the time this reaches a caller the database is back where it
+ * started: every fact that evaluation derived has been retracted, and
+ * the rule set will start over from the base facts next time rather
+ * than from a delta that was never worked through. The caller's own
+ * facts, the question it asked among them, are still there for it to
+ * take back.
+ */
+declare class BudgetExhausted extends Error {
+    readonly ruleSet: string;
+    readonly examined: number;
+    constructor(ruleSet: string, examined: number);
+}
 /**
  * Evaluate `rules` over `db` to fixpoint, adding derived facts in
  * place. Rules are stratified first; within a stratum, semi-naïve
- * iteration joins each rule against the last round's delta so work is
- * proportional to new facts, not all facts.
+ * iteration joins each rule against the last round's delta, so work
+ * is proportional to new facts rather than to all facts.
  *
  * With an `algebra`, every derivation also tags its conclusion (see
- * `TagAlgebra`). Supply the same algebra on every evaluation of a rule
- * set over a database: a resumed run derives only from the new facts,
- * so it tags only what those reach.
+ * `TagAlgebra`). Supply the same algebra every time over one
+ * database: a resumed run tags only what the new facts reach.
+ *
+ * With a `budget`, evaluation gives up once its joins have read that
+ * many rows and throws `BudgetExhausted`. Either way the budget says
+ * afterwards what the evaluation cost.
  */
-declare function evaluate<Tag = never>(db: Database, rules: Rule[], algebra?: TagAlgebra<Tag>): Database;
+declare function evaluate<Tag = never>(db: Database, rules: Rule[], algebra?: TagAlgebra<Tag>, budget?: RowBudget): Database;
 /**
  * Empty these relations, and leave `rules` able to carry on from where
  * it got to.
@@ -438,4 +520,4 @@ declare function evaluate<Tag = never>(db: Database, rules: Rule[], algebra?: Ta
  */
 declare function clearRelations(db: Database, rules: Rule[], relations: readonly string[]): void;
 
-export { type AddOutcome, type Atom, type BodyMatch, type ConfidenceLevel, Database, type Demand, type Derivation, type EvaluationProfile, type Literal, type OnDemandRules, type Proof, type ProofDerived, type ProofOptions, type Rule, type RuleCost, type TagAlgebra, type Term, type Tuple, Witness, type WitnessTag, clearRelations, confidence, confidenceWith, constant, deriveOnDemand, evaluate, formatProfile, lit, notLit, profileEvaluation, profileEvaluationAsync, proofOf, rule, ruleLabel, stratify, tupleKey, tupleKeyParts, variable, witnesses };
+export { type AbandonedQuestion, type AddOutcome, type Atom, type BodyMatch, BudgetExhausted, type ConfidenceLevel, Database, type Demand, type Derivation, type EvaluationProfile, type Literal, type OnDemandRules, type Proof, type ProofDerived, type ProofOptions, type QuestionOutcome, type QuestionTally, type RowBudget, type Rule, type RuleCost, type TagAlgebra, type Term, type Tuple, Witness, type WitnessTag, chargeAbandoned, chargeQuestion, clearRelations, confidence, confidenceWith, constant, deriveOnDemand, evaluate, formatProfile, lit, notLit, profileEvaluation, profileEvaluationAsync, proofOf, rowBudget, rule, ruleLabel, stratify, tupleKey, tupleKeyParts, variable, witnesses };

package/dist/index.js

@@ -185,21 +185,43 @@ function bodyAdornments(r, headAdornment, derives) {
 var open = [];
 var isProfiling = () => open.length > 0;
 var ruleKey = (head, body) => `${head} <- ${body.join(", ")}`;
-function addCost(into, key, head, body, ms, derived) {
+function addCost(into, key, head, body, ms, derived, examined) {
   const existing = into.get(key);
   if (existing === void 0) {
-    into.set(key, { head, body, ms, derived, attempts: 1 });
+    into.set(key, { head, body, ms, derived, examined, attempts: 1 });
     return;
   }
   existing.ms += ms;
   existing.derived += derived;
+  existing.examined += examined;
   existing.attempts += 1;
 }
-function chargeRule(ruleSet, head, body, ms, derived) {
+function chargeRule(ruleSet, head, body, ms, derived, examined) {
   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);
+    addCost(collector.rules, key, head, body, ms, derived, examined);
+    addCost(
+      setIn(collector, ruleSet).rules,
+      key,
+      head,
+      body,
+      ms,
+      derived,
+      examined
+    );
+  }
+}
+function chargeAbandoned(question, examined) {
+  for (const collector of open) {
+    collector.abandoned.push({ question, examined });
+  }
+}
+function chargeQuestion(outcome) {
+  for (const collector of open) {
+    collector.questions.asked += 1;
+    if (outcome !== void 0) {
+      collector.questions[outcome] += 1;
+    }
   }
 }
 function chargeEvaluation(ruleSet) {
@@ -208,6 +230,13 @@ function chargeEvaluation(ruleSet) {
     setIn(collector, ruleSet).evaluations += 1;
   }
 }
+function chargeEvaluationRows(examined) {
+  for (const collector of open) {
+    if (examined > collector.largestEvaluation) {
+      collector.largestEvaluation = examined;
+    }
+  }
+}
 function chargeRound(ruleSet) {
   for (const collector of open) {
     collector.rounds += 1;
@@ -267,7 +296,10 @@ function openScope() {
     rules: /* @__PURE__ */ new Map(),
     relations: /* @__PURE__ */ new Map(),
     derivedRelations: /* @__PURE__ */ new Set(),
-    ruleSets: /* @__PURE__ */ new Map()
+    ruleSets: /* @__PURE__ */ new Map(),
+    abandoned: [],
+    largestEvaluation: 0,
+    questions: { asked: 0, abandoned: 0, skipped: 0 }
   };
   open.push(mine);
   return mine;
@@ -285,6 +317,13 @@ var totalMs = (rules) => {
   }
   return ms;
 };
+var totalExamined = (rules) => {
+  let rows = 0;
+  for (const cost of rules) {
+    rows += cost.examined;
+  }
+  return rows;
+};
 var byCost = (a, b) => b.ms - a.ms;
 function summarise(mine) {
   return {
@@ -292,6 +331,10 @@ function summarise(mine) {
     datalogMs: totalMs(mine.rules.values()),
     rounds: mine.rounds,
     evaluations: mine.evaluations,
+    examined: totalExamined(mine.rules.values()),
+    largestEvaluation: mine.largestEvaluation,
+    abandoned: [...mine.abandoned],
+    questions: { ...mine.questions },
     relations: [...mine.relations].map(([relation, tuples]) => ({
       relation,
       tuples,
@@ -312,14 +355,26 @@ 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)}`;
+    const examined = String(r.examined).padStart(9);
+    return `    ${ms} ${share(r.ms, datalogMs)} ${derived} tuples ${examined} rows read  ${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`
+    `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, ${profile.examined} rows read (${profile.largestEvaluation} in the biggest evaluation)`
   );
+  const { asked, abandoned, skipped } = profile.questions;
+  if (asked > 0) {
+    lines.push(
+      `  ${asked} questions under a site: ${abandoned} given up part way, ${skipped} never put once the run's rows were spent`
+    );
+  }
+  for (const given of profile.abandoned) {
+    lines.push(
+      `  gave up on ${given.question} after reading ${given.examined} rows`
+    );
+  }
   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)) {
@@ -792,7 +847,22 @@ function planBodyOrder(r, deltaAt) {
   }
   return order;
 }
-function evaluateRule(db, deltas, r, deltaIndex) {
+var rowBudget = (limit) => ({
+  examined: 0,
+  limit
+});
+var OUT_OF_BUDGET = /* @__PURE__ */ Symbol("datalog row budget exhausted");
+var BudgetExhausted = class extends Error {
+  constructor(ruleSet, examined) {
+    super(`gave up after reading ${examined} rows without settling`);
+    this.ruleSet = ruleSet;
+    this.examined = examined;
+    this.name = "BudgetExhausted";
+  }
+  ruleSet;
+  examined;
+};
+function evaluateRule(db, deltas, r, deltaIndex, budget) {
   const results = [];
   const { deltaAt, order } = bodyPlan(r, deltaIndex);
   const step = (orderIndex, bindings) => {
@@ -810,6 +880,10 @@ function evaluateRule(db, deltas, r, deltaIndex) {
     }
     const source = literalIndex === deltaAt ? deltas.get(literal.relation) ?? [] : boundSource(db, literal, bindings);
     for (const tuple of source) {
+      budget.examined++;
+      if (budget.examined > budget.limit) {
+        throw OUT_OF_BUDGET;
+      }
       const next = unify(literal, tuple, bindings);
       if (next !== NO_MATCH) {
         step(orderIndex + 1, next);
@@ -838,7 +912,7 @@ function boundSource(db, literal, bindings) {
   return narrowest ?? db.facts(literal.relation);
 }
 var EMPTY_TAGS = [];
-function evaluateRuleTagged(db, deltas, r, deltaIndex, algebra) {
+function evaluateRuleTagged(db, deltas, r, deltaIndex, algebra, budget) {
   const results = [];
   const bodyTags = [];
   const bodyMatches = [];
@@ -876,6 +950,7 @@ function evaluateRuleTagged(db, deltas, r, deltaIndex, algebra) {
     }
     const source = positiveIndex === deltaIndex ? deltas.get(literal.relation) ?? [] : boundSource(db, literal, bindings);
     for (const tuple of source) {
+      budget.examined++;
       const next = unify(literal, tuple, bindings);
       if (next !== NO_MATCH) {
         if (readsTags) {
@@ -959,15 +1034,18 @@ function currentMarks(db) {
   }
   return marks;
 }
-function evaluate(db, rules, algebra) {
+function evaluate(db, rules, algebra, budget) {
   if (algebra !== void 0 && isDemandRewritten(rules)) {
     throw new Error(
       "cannot evaluate demand-rewritten rules with a tag algebra: tags would follow the demand-transformed rules rather than the ones the caller wrote"
     );
   }
+  if (algebra !== void 0 && budget !== void 0) {
+    throw new Error("cannot evaluate with both a tag algebra and a row budget");
+  }
   deriving.set(db, (deriving.get(db) ?? 0) + 1);
   try {
-    return runRules(db, rules, algebra);
+    return runRules(db, rules, algebra, budget);
   } finally {
     const depth = (deriving.get(db) ?? 1) - 1;
     if (depth === 0) {
@@ -1017,13 +1095,19 @@ function storedMergeFor(algebra) {
     return stored === void 0 && merged === algebra.asserted ? void 0 : merged;
   };
 }
-function runRules(db, rules, algebra) {
+function runRules(db, rules, algebra, given) {
   const {
     signature,
     name: ruleSetName,
     derivedRelations,
     strata
   } = shapeOf(rules);
+  const budget = given ?? {
+    examined: 0,
+    limit: Number.POSITIVE_INFINITY
+  };
+  const startedAt = budget.examined;
+  const addedHere = given === void 0 ? null : [];
   chargeEvaluation(ruleSetName);
   const states = statesFor(db);
   const state = states.get(signature) ?? {
@@ -1045,10 +1129,11 @@ function runRules(db, rules, algebra) {
       derived.set(relation, ledger);
     }
     ledger.set(keyOf2(tuple), tuple);
+    addedHere?.push([relation, tuple]);
   };
   const mergeStored = algebra === void 0 ? void 0 : storedMergeFor(algebra);
   const marks = canResume(rules, state) ? state.marks : void 0;
-  for (const stratum of strata) {
+  const runStratum = (stratum) => {
     let delta = /* @__PURE__ */ new Map();
     const derivedHere = new Set(stratum.map((r) => r.head.relation));
     const record = (relation, tuple) => {
@@ -1074,13 +1159,14 @@ function runRules(db, rules, algebra) {
           seed,
           r,
           deltaIndex,
-          algebra
+          algebra,
+          budget
         )) {
           recordTagged(r.head.relation, found.tuple, found.tag);
         }
         return;
       }
-      for (const tuple of evaluateRule(db, seed, r, deltaIndex)) {
+      for (const tuple of evaluateRule(db, seed, r, deltaIndex, budget)) {
         record(r.head.relation, tuple);
       }
     };
@@ -1089,15 +1175,17 @@ function runRules(db, rules, algebra) {
         deriveInto(r, seed, deltaIndex);
         return;
       }
-      const startedAt = performance.now();
+      const startedAt2 = performance.now();
       const before = db.size(r.head.relation);
+      const readBefore = budget.examined;
       deriveInto(r, seed, deltaIndex);
       chargeRule(
         ruleSetName,
         r.head.relation,
         r.body.map(literalName),
-        performance.now() - startedAt,
-        db.size(r.head.relation) - before
+        performance.now() - startedAt2,
+        db.size(r.head.relation) - before,
+        budget.examined - readBefore
       );
     };
     const applyDelta = (seed, derivedOnly) => {
@@ -1142,7 +1230,24 @@ function runRules(db, rules, algebra) {
       applyDelta(lastDelta, true);
       chargeRound(ruleSetName);
     }
+  };
+  const readHere = () => budget.examined - startedAt;
+  try {
+    for (const stratum of strata) {
+      runStratum(stratum);
+    }
+  } catch (error) {
+    if (error !== OUT_OF_BUDGET) {
+      throw error;
+    }
+    for (const [relation, tuples] of byRelation(addedHere ?? [])) {
+      db.retract(relation, tuples);
+    }
+    state.marks = null;
+    chargeEvaluationRows(readHere());
+    throw new BudgetExhausted(ruleSetName, readHere());
   }
+  chargeEvaluationRows(readHere());
   state.marks = currentMarks(db);
   if (isProfiling()) {
     chargeRelationSizes(
@@ -1152,6 +1257,13 @@ function runRules(db, rules, algebra) {
   }
   return db;
 }
+function byRelation(added) {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const [relation, tuple] of added) {
+    addTo(buckets, relation, tuple);
+  }
+  return buckets;
+}
 function addTo(buckets, relation, tuple) {
   const bucket = buckets.get(relation);
   if (bucket === void 0) {
@@ -1161,8 +1273,11 @@ function addTo(buckets, relation, tuple) {
   }
 }
 export {
+  BudgetExhausted,
   Database,
   Witness,
+  chargeAbandoned,
+  chargeQuestion,
   clearRelations,
   confidence,
   confidenceWith,
@@ -1175,6 +1290,7 @@ export {
   profileEvaluation,
   profileEvaluationAsync,
   proofOf,
+  rowBudget,
   rule,
   ruleLabel,
   stratify,

package/package.json

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