@suss/datalog 0.31.0 → 0.31.2

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 };