@suss/datalog 0.33.0 → 0.34.0

package/dist/index.d.cts

@@ -71,28 +71,35 @@ interface Relation {
      * lookup and buy nothing.
      */
     columns: (Map<Atom, Tuple[]> | undefined)[];
+    /**
+     * Per set of columns, the tuples under each combination of values at
+     * those columns, keyed by a bitmask of the column positions. Built and
+     * kept up to date the same way as `columns`.
+     */
+    combined: Map<number, CombinedIndex>;
+}
+/**
+ * A tree of maps with one level per column in `columns`, lowest position
+ * first, and the matching tuples at the leaves.
+ */
+interface CombinedIndex {
+    columns: readonly number[];
+    root: Map<Atom, unknown>;
 }
 
 /**
  * Confidence levels as a tag algebra: how sure the run is of each
  * derived fact, given how sure it is of the facts and rules behind it.
  *
- * A conclusion is only as sure as its weakest premise, so a rule
- * firing takes the minimum level across its body. A fact reached two
- * ways keeps the better level, so a second derivation merges with
- * maximum. Both are idempotent: ten medium steps come out medium, and
- * that is the intended reading rather than a loss of information.
- *
- * A rule can be a heuristic itself, and then its conclusions should
- * not outrank it however sure its premises are. `confidenceWith`
- * takes a level per rule and folds it into the minimum. The plain
- * `confidence` algebra treats every rule as exact.
+ * A rule firing takes the minimum level across its body, and a fact
+ * reached two ways keeps the better level. Both are idempotent, so ten
+ * medium steps come out medium. A rule that is itself a heuristic caps
+ * its conclusions through `confidenceWith`.
  *
- * An asserted fact without a tag counts as `"high"`: the caller read
- * it directly from its source. To say less, assert the fact with a
- * level: `db.add(relation, tuple, "medium")`. A matched negation also
- * counts as `"high"`, because negation here is exact over the
- * database as computed, not a guess about the world.
+ * An asserted fact without a tag counts as `"high"`; assert it with a
+ * level, as in `db.add(relation, tuple, "medium")`, to say less. A
+ * matched negation also counts as `"high"`, because negation is exact
+ * over the database as computed. DESIGN.md has a worked example.
  */
 
 /** How sure the run is of one fact. The order is high > medium > low. */
@@ -106,6 +113,21 @@ declare function confidenceWith(levelOf: (rule: Rule) => ConfidenceLevel | undef
 /** The confidence algebra with every rule counted as exact. */
 declare const confidence: TagAlgebra<ConfidenceLevel>;
 
+/**
+ * The magic sets rewrite, which derives only what somebody asked for.
+ * Each derived relation gets a companion relation recording which of its
+ * rows something is waiting on. That companion becomes the first literal
+ * of each rule, and demand travels down each body the way the join binds
+ * variables. The caller lists the relations that must come out complete;
+ * every other derived relation is filled in only as far as those need.
+ *
+ * The rewritten program is positive, so it keeps the semi-naive resume
+ * that a store evaluating after every wave of facts depends on. Demand
+ * is an ordinary fact, so a new question is one more fact arriving, and
+ * `clearRelations` can take the question back once its answer is read.
+ * DESIGN.md has the worked examples and the costs.
+ */
+
 /** One demand relation the rewrite created, and what its rows say. */
 interface Demand {
     /** The relation whose rows are being waited on. */
@@ -155,6 +177,17 @@ interface OnDemandRules {
  */
 declare function deriveOnDemand(rules: Rule[], complete: readonly string[]): OnDemandRules;
 
+/**
+ * Per-rule timing and row counts for an evaluation. A rule's cost is
+ * spread across joins no caller can see, and a CPU profile stops at
+ * `unify` and `lookup` without saying which rule asked for the work, so
+ * the engine records these itself.
+ *
+ * Nothing here runs unless a caller wraps its evaluation in
+ * `profileEvaluation`. The engine checks whether a scope is open once
+ * per rule attempt and once per round, never per tuple, and allocates
+ * only inside that branch, so an unprofiled run pays one check per rule.
+ */
 /** What one rule cost, summed over every attempt across every round. */
 interface RuleCost {
     /** The relation this rule derives. */
@@ -181,8 +214,8 @@ interface AbandonedQuestion {
     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.
+ * How a caller that asks one question at a time got on. `skipped` counts
+ * the questions it never asked because the run's row budget was spent.
  */
 interface QuestionTally {
     asked: number;
@@ -214,11 +247,20 @@ interface RuleSetCost {
     rounds: number;
     rules: RuleCost[];
 }
+/**
+ * The engine entry points a profile times whole. `evaluate` includes the
+ * rules, so what it has past `datalogMs` is the engine's own work: the
+ * round loop and the bookkeeping around it. `clear` is `clearRelations`
+ * emptying relations between questions.
+ */
+type EnginePart = "evaluate" | "clear";
 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. */
+    /** Wall time inside rule evaluation, summed over the rules. */
     datalogMs: number;
+    /** Wall time inside each of the engine's entry points. */
+    engineMs: Record<EnginePart, number>;
     /** Semi-naive rounds, summed over strata. The seed round counts as one. */
     rounds: number;
     /**
@@ -254,8 +296,8 @@ interface EvaluationProfile {
  */
 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.
+ * Count one question from a caller. Pass `outcome` when the question was
+ * abandoned part way or skipped, and leave it out when it was answered.
  */
 declare function chargeQuestion(outcome?: QuestionOutcome): void;
 /**
@@ -281,6 +323,19 @@ 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;
 
+/**
+ * Turns several values into one string key, reversibly.
+ *
+ * A tuple value can be any string a caller interns, so no separator
+ * character is safe to join on. Pick one, and the day a module
+ * specifier or an identifier contains it, two different tuples produce
+ * the same key and a lookup returns the wrong facts. Each part is
+ * written with its own length instead, which no value can forge.
+ *
+ * Any caller that joins values into a map key has the same problem, so
+ * the encoding is exported for them to share.
+ */
+
 declare const tupleKey: (parts: readonly Atom[]) => string;
 /**
  * Throws on a string `tupleKey` did not produce. A key that does not
@@ -296,11 +351,10 @@ declare function tupleKeyParts(key: string): string[];
  * Evaluate under the `witnesses` algebra and every derived fact stores
  * a `Witness`: the rule that fired and one entry per body literal. The
  * merge keeps whatever is already stored, so a fact derived nine ways
- * keeps its first witness and the fixpoint behaves exactly as it does
- * untagged. First-wins means a proof, not the shortest proof; the
- * algebra interface already allows a different merge. `proofOf` walks
- * the stored witnesses into a tree when somebody asks, the way
- * Soufflé's provenance mode does, and never re-runs a rule.
+ * keeps its first witness and the fixpoint runs the same as untagged.
+ * The proof that comes back is therefore valid but may not be the
+ * shortest. `proofOf` walks the stored witnesses into a tree when asked,
+ * the way Soufflé's provenance mode does, and never re-runs a rule.
  */
 
 /**
@@ -356,11 +410,11 @@ interface ProofOptions {
  * Rebuild the proof of one fact from stored witnesses, without
  * re-running any evaluation. A `fact` leaf has no witness: the caller
  * asserted it, or it was derived without the `witnesses` algebra. An
- * `absence` leaf is a tuple missing from the database, at the root
- * when the asked-about fact was never derived, and under a derivation
- * where a negated literal relied on it being missing, reported as
- * evaluation saw it rather than re-checked now. `truncated` is where
- * the depth cap or the cycle guard stopped the walk.
+ * `absence` leaf is a tuple missing from the database. It appears at the
+ * root when the fact asked about was never derived, and under a
+ * derivation where a negated literal relied on it being missing, as
+ * evaluation saw it at the time. `truncated` marks where the depth cap
+ * or the cycle guard stopped the walk.
  */
 declare function proofOf(db: Database, relation: string, tuple: Tuple, options?: ProofOptions): Proof;
 
@@ -431,8 +485,8 @@ declare class Database {
     private relation;
     /**
      * The key this relation gives a tuple, whether or not the fact is
-     * present. Evaluation keys its ledger of derived facts by it; a
-     * caller outside this module has nowhere to spend one.
+     * present. Evaluation keys its ledger of derived facts by it. Nothing
+     * outside this module accepts a key.
      */
     keyFor(relationName: string, tuple: Tuple): FactKey;
     /**
@@ -467,6 +521,12 @@ declare class Database {
      * time. Callers rarely need it.
      */
     retract(relationName: string, tuples: Iterable<Tuple>): number;
+    /**
+     * Remove every fact in a relation, and return how many there were. The
+     * database ends up as `retract` leaves it when handed every tuple, but
+     * nothing looks a tuple up to remove it.
+     */
+    retractAll(relationName: string): number;
     size(relationName: string): number;
     relationNames(): string[];
 }
@@ -524,25 +584,32 @@ interface Derivation {
     rule: Rule;
     body: readonly BodyMatch[];
 }
+/**
+ * The rules that can derive any of `relations`: the ones with such a
+ * head, and every rule behind a relation their bodies read, negated
+ * literals included. Evaluating only these derives the same tuples for
+ * `relations` as evaluating all of `rules`, and skips the relations
+ * nothing asked about.
+ */
+declare function rulesDeriving(rules: readonly Rule[], relations: readonly string[]): Rule[];
 /**
  * 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 above the
+ * strictly increase it, iterating to a 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[][];
 /**
  * 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.
+ * have read so far. The budget counts rows read rather than new tuples.
+ * A question that runs away keeps finding conclusions it already has, so
+ * the tuple count stays flat while the rows read keep growing.
  *
- * 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.
+ * The caller builds one with `rowBudget` and reads `examined` after the
+ * call to learn what the question cost, whether or not it 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;
@@ -576,31 +643,24 @@ declare class BudgetExhausted extends Error {
  * 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.
+ * many rows and throws `BudgetExhausted`. Either way, `budget.examined`
+ * afterwards gives what the evaluation cost.
  */
 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.
- *
- * `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.
+ * Empty these relations and let `rules` resume from its last fixpoint.
  *
- * 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 listed as complete keep their
- * contents, which are the answers a caller has already read.
+ * After `retract`, the next run starts again from the base facts, since
+ * a fact leaving the database can take away a conclusion drawn anywhere.
+ * A caller of this function promises more: nothing outside `relations`
+ * was derived from these facts. What is left is already the fixpoint,
+ * and the next run works through only the facts added after this.
  *
- * Any other rule set over the same database does start over, since a
- * relation it derived from may be one of these.
+ * A demand-driven caller clears `deriveOnDemand`'s demand-driven
+ * relations between questions, and the complete ones keep the answers
+ * already read (DESIGN.md has an example). Any other rule set over the
+ * same database starts over, since it may have derived from these.
  */
 declare function clearRelations(db: Database, rules: Rule[], relations: readonly string[]): void;
 
-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 };
+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, rulesDeriving, stratify, tupleKey, tupleKeyParts, variable, witnesses };

package/dist/index.d.ts

@@ -71,28 +71,35 @@ interface Relation {
      * lookup and buy nothing.
      */
     columns: (Map<Atom, Tuple[]> | undefined)[];
+    /**
+     * Per set of columns, the tuples under each combination of values at
+     * those columns, keyed by a bitmask of the column positions. Built and
+     * kept up to date the same way as `columns`.
+     */
+    combined: Map<number, CombinedIndex>;
+}
+/**
+ * A tree of maps with one level per column in `columns`, lowest position
+ * first, and the matching tuples at the leaves.
+ */
+interface CombinedIndex {
+    columns: readonly number[];
+    root: Map<Atom, unknown>;
 }
 
 /**
  * Confidence levels as a tag algebra: how sure the run is of each
  * derived fact, given how sure it is of the facts and rules behind it.
  *
- * A conclusion is only as sure as its weakest premise, so a rule
- * firing takes the minimum level across its body. A fact reached two
- * ways keeps the better level, so a second derivation merges with
- * maximum. Both are idempotent: ten medium steps come out medium, and
- * that is the intended reading rather than a loss of information.
- *
- * A rule can be a heuristic itself, and then its conclusions should
- * not outrank it however sure its premises are. `confidenceWith`
- * takes a level per rule and folds it into the minimum. The plain
- * `confidence` algebra treats every rule as exact.
+ * A rule firing takes the minimum level across its body, and a fact
+ * reached two ways keeps the better level. Both are idempotent, so ten
+ * medium steps come out medium. A rule that is itself a heuristic caps
+ * its conclusions through `confidenceWith`.
  *
- * An asserted fact without a tag counts as `"high"`: the caller read
- * it directly from its source. To say less, assert the fact with a
- * level: `db.add(relation, tuple, "medium")`. A matched negation also
- * counts as `"high"`, because negation here is exact over the
- * database as computed, not a guess about the world.
+ * An asserted fact without a tag counts as `"high"`; assert it with a
+ * level, as in `db.add(relation, tuple, "medium")`, to say less. A
+ * matched negation also counts as `"high"`, because negation is exact
+ * over the database as computed. DESIGN.md has a worked example.
  */
 
 /** How sure the run is of one fact. The order is high > medium > low. */
@@ -106,6 +113,21 @@ declare function confidenceWith(levelOf: (rule: Rule) => ConfidenceLevel | undef
 /** The confidence algebra with every rule counted as exact. */
 declare const confidence: TagAlgebra<ConfidenceLevel>;
 
+/**
+ * The magic sets rewrite, which derives only what somebody asked for.
+ * Each derived relation gets a companion relation recording which of its
+ * rows something is waiting on. That companion becomes the first literal
+ * of each rule, and demand travels down each body the way the join binds
+ * variables. The caller lists the relations that must come out complete;
+ * every other derived relation is filled in only as far as those need.
+ *
+ * The rewritten program is positive, so it keeps the semi-naive resume
+ * that a store evaluating after every wave of facts depends on. Demand
+ * is an ordinary fact, so a new question is one more fact arriving, and
+ * `clearRelations` can take the question back once its answer is read.
+ * DESIGN.md has the worked examples and the costs.
+ */
+
 /** One demand relation the rewrite created, and what its rows say. */
 interface Demand {
     /** The relation whose rows are being waited on. */
@@ -155,6 +177,17 @@ interface OnDemandRules {
  */
 declare function deriveOnDemand(rules: Rule[], complete: readonly string[]): OnDemandRules;
 
+/**
+ * Per-rule timing and row counts for an evaluation. A rule's cost is
+ * spread across joins no caller can see, and a CPU profile stops at
+ * `unify` and `lookup` without saying which rule asked for the work, so
+ * the engine records these itself.
+ *
+ * Nothing here runs unless a caller wraps its evaluation in
+ * `profileEvaluation`. The engine checks whether a scope is open once
+ * per rule attempt and once per round, never per tuple, and allocates
+ * only inside that branch, so an unprofiled run pays one check per rule.
+ */
 /** What one rule cost, summed over every attempt across every round. */
 interface RuleCost {
     /** The relation this rule derives. */
@@ -181,8 +214,8 @@ interface AbandonedQuestion {
     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.
+ * How a caller that asks one question at a time got on. `skipped` counts
+ * the questions it never asked because the run's row budget was spent.
  */
 interface QuestionTally {
     asked: number;
@@ -214,11 +247,20 @@ interface RuleSetCost {
     rounds: number;
     rules: RuleCost[];
 }
+/**
+ * The engine entry points a profile times whole. `evaluate` includes the
+ * rules, so what it has past `datalogMs` is the engine's own work: the
+ * round loop and the bookkeeping around it. `clear` is `clearRelations`
+ * emptying relations between questions.
+ */
+type EnginePart = "evaluate" | "clear";
 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. */
+    /** Wall time inside rule evaluation, summed over the rules. */
     datalogMs: number;
+    /** Wall time inside each of the engine's entry points. */
+    engineMs: Record<EnginePart, number>;
     /** Semi-naive rounds, summed over strata. The seed round counts as one. */
     rounds: number;
     /**
@@ -254,8 +296,8 @@ interface EvaluationProfile {
  */
 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.
+ * Count one question from a caller. Pass `outcome` when the question was
+ * abandoned part way or skipped, and leave it out when it was answered.
  */
 declare function chargeQuestion(outcome?: QuestionOutcome): void;
 /**
@@ -281,6 +323,19 @@ 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;
 
+/**
+ * Turns several values into one string key, reversibly.
+ *
+ * A tuple value can be any string a caller interns, so no separator
+ * character is safe to join on. Pick one, and the day a module
+ * specifier or an identifier contains it, two different tuples produce
+ * the same key and a lookup returns the wrong facts. Each part is
+ * written with its own length instead, which no value can forge.
+ *
+ * Any caller that joins values into a map key has the same problem, so
+ * the encoding is exported for them to share.
+ */
+
 declare const tupleKey: (parts: readonly Atom[]) => string;
 /**
  * Throws on a string `tupleKey` did not produce. A key that does not
@@ -296,11 +351,10 @@ declare function tupleKeyParts(key: string): string[];
  * Evaluate under the `witnesses` algebra and every derived fact stores
  * a `Witness`: the rule that fired and one entry per body literal. The
  * merge keeps whatever is already stored, so a fact derived nine ways
- * keeps its first witness and the fixpoint behaves exactly as it does
- * untagged. First-wins means a proof, not the shortest proof; the
- * algebra interface already allows a different merge. `proofOf` walks
- * the stored witnesses into a tree when somebody asks, the way
- * Soufflé's provenance mode does, and never re-runs a rule.
+ * keeps its first witness and the fixpoint runs the same as untagged.
+ * The proof that comes back is therefore valid but may not be the
+ * shortest. `proofOf` walks the stored witnesses into a tree when asked,
+ * the way Soufflé's provenance mode does, and never re-runs a rule.
  */
 
 /**
@@ -356,11 +410,11 @@ interface ProofOptions {
  * Rebuild the proof of one fact from stored witnesses, without
  * re-running any evaluation. A `fact` leaf has no witness: the caller
  * asserted it, or it was derived without the `witnesses` algebra. An
- * `absence` leaf is a tuple missing from the database, at the root
- * when the asked-about fact was never derived, and under a derivation
- * where a negated literal relied on it being missing, reported as
- * evaluation saw it rather than re-checked now. `truncated` is where
- * the depth cap or the cycle guard stopped the walk.
+ * `absence` leaf is a tuple missing from the database. It appears at the
+ * root when the fact asked about was never derived, and under a
+ * derivation where a negated literal relied on it being missing, as
+ * evaluation saw it at the time. `truncated` marks where the depth cap
+ * or the cycle guard stopped the walk.
  */
 declare function proofOf(db: Database, relation: string, tuple: Tuple, options?: ProofOptions): Proof;
 
@@ -431,8 +485,8 @@ declare class Database {
     private relation;
     /**
      * The key this relation gives a tuple, whether or not the fact is
-     * present. Evaluation keys its ledger of derived facts by it; a
-     * caller outside this module has nowhere to spend one.
+     * present. Evaluation keys its ledger of derived facts by it. Nothing
+     * outside this module accepts a key.
      */
     keyFor(relationName: string, tuple: Tuple): FactKey;
     /**
@@ -467,6 +521,12 @@ declare class Database {
      * time. Callers rarely need it.
      */
     retract(relationName: string, tuples: Iterable<Tuple>): number;
+    /**
+     * Remove every fact in a relation, and return how many there were. The
+     * database ends up as `retract` leaves it when handed every tuple, but
+     * nothing looks a tuple up to remove it.
+     */
+    retractAll(relationName: string): number;
     size(relationName: string): number;
     relationNames(): string[];
 }
@@ -524,25 +584,32 @@ interface Derivation {
     rule: Rule;
     body: readonly BodyMatch[];
 }
+/**
+ * The rules that can derive any of `relations`: the ones with such a
+ * head, and every rule behind a relation their bodies read, negated
+ * literals included. Evaluating only these derives the same tuples for
+ * `relations` as evaluating all of `rules`, and skips the relations
+ * nothing asked about.
+ */
+declare function rulesDeriving(rules: readonly Rule[], relations: readonly string[]): Rule[];
 /**
  * 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 above the
+ * strictly increase it, iterating to a 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[][];
 /**
  * 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.
+ * have read so far. The budget counts rows read rather than new tuples.
+ * A question that runs away keeps finding conclusions it already has, so
+ * the tuple count stays flat while the rows read keep growing.
  *
- * 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.
+ * The caller builds one with `rowBudget` and reads `examined` after the
+ * call to learn what the question cost, whether or not it 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;
@@ -576,31 +643,24 @@ declare class BudgetExhausted extends Error {
  * 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.
+ * many rows and throws `BudgetExhausted`. Either way, `budget.examined`
+ * afterwards gives what the evaluation cost.
  */
 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.
- *
- * `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.
+ * Empty these relations and let `rules` resume from its last fixpoint.
  *
- * 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 listed as complete keep their
- * contents, which are the answers a caller has already read.
+ * After `retract`, the next run starts again from the base facts, since
+ * a fact leaving the database can take away a conclusion drawn anywhere.
+ * A caller of this function promises more: nothing outside `relations`
+ * was derived from these facts. What is left is already the fixpoint,
+ * and the next run works through only the facts added after this.
  *
- * Any other rule set over the same database does start over, since a
- * relation it derived from may be one of these.
+ * A demand-driven caller clears `deriveOnDemand`'s demand-driven
+ * relations between questions, and the complete ones keep the answers
+ * already read (DESIGN.md has an example). Any other rule set over the
+ * same database starts over, since it may have derived from these.
  */
 declare function clearRelations(db: Database, rules: Rule[], relations: readonly string[]): void;
 
-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 };
+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, rulesDeriving, stratify, tupleKey, tupleKeyParts, variable, witnesses };