@suss/datalog 0.38.0 → 0.38.1

package/dist/index.d.cts

@@ -50,6 +50,108 @@ declare class FactIndex {
     clear(): void;
 }
 
+/**
+ * What an evaluation looked up, so a caller that cached its answer can
+ * tell later whether a fact that arrived since could change it.
+ *
+ * While `noteReads` runs, every lookup the join makes is noted as the
+ * relation, the column and the value, and a relation read whole is
+ * noted whole. At the end each lookup's facts are counted. The cached
+ * answer is still right when every count is the same and nothing was
+ * retracted from those relations. Without a retraction counts only
+ * grow, so the sum of the counts changes exactly when one of them does.
+ * DESIGN.md explains why a fact no lookup would find cannot change the
+ * answer, and what that asks of the rules.
+ */
+
+/** @internal One relation's reads: the values looked up per column, unless something read it whole. */
+interface RelationReads {
+    whole: boolean;
+    columns: (Set<Atom> | undefined)[];
+}
+/** @internal The join notes its reads here while `noteReads` runs. */
+declare class ReadLog {
+    private readonly skipped;
+    /** Null for a relation the caller said to leave out. */
+    private readonly byRelation;
+    constructor(skipped: ReadonlySet<string>);
+    lookedUp(relation: string, column: number, value: Atom): void;
+    readWhole(relation: string): void;
+    /** Note everything an inner log noted, for an answer cached inside another. */
+    absorb(inner: ReadLog): void;
+    /**
+     * The reads with what each one finds in `db` now. One question looks
+     * up the same values in many columns, so each value is kept once, and
+     * each column keeps a bit per value saying whether it was looked up
+     * there.
+     */
+    counted(db: Database): ReadsNoted;
+    /** @internal Null for a relation the caller said to leave out. */
+    readsOf(relation: string): RelationReads | null;
+}
+/**
+ * Group `g` is the column `columns[g]` of the relation at
+ * `names[groups[g]]`. Its bits start at word `g` times the words one
+ * group takes, and bit `i` says it looked up `values[i]`.
+ */
+interface Lookups {
+    names: readonly string[];
+    groups: readonly number[];
+    columns: readonly number[];
+    values: readonly Atom[];
+    bits: Uint32Array;
+}
+/**
+ * The lookups one evaluation made, and how many facts they found when
+ * it finished. The values are the atoms the facts already contain, so
+ * a value costs a reference, and each column it was looked up in costs
+ * a bit.
+ */
+declare class ReadsNoted {
+    private readonly skipped;
+    private readonly found;
+    private readonly names;
+    private readonly groups;
+    private readonly columns;
+    private readonly values;
+    private readonly bits;
+    private readonly words;
+    private readonly removed;
+    /** The facts in every relation read, when the counts last matched. */
+    private facts;
+    /** Each relation read, found by name the first time a check needs it. */
+    private readonly relations;
+    constructor(db: Database, skipped: ReadonlySet<string>, lookups: Lookups, found: number);
+    /**
+     * Whether every read would find what it found then. A fact left in a
+     * skipped relation would join a question asked now without anything
+     * here having looked it up, so one there makes the answer no. The
+     * counts are taken again only when a relation read has grown.
+     */
+    unchangedIn(db: Database): boolean;
+    private relationAt;
+    private sumOver;
+    /**
+     * The facts the reads find, stopping once past `limit`. With nothing
+     * retracted every count only grows, so passing the old total already
+     * says that one of them grew.
+     */
+    private countIn;
+    private countGroup;
+}
+/**
+ * Run `work` and note what the join and the database's readers look up
+ * in every relation outside `skipped`. A caller skips the
+ * relations it empties after every question, so that the work derives
+ * their facts again and the lookups behind them get noted. The reads
+ * are null when a skipped relation was not empty to begin with, since
+ * the work could then build on facts nothing here looked up.
+ */
+declare function noteReads<T>(db: Database, skipped: ReadonlySet<string>, work: () => T): {
+    value: T;
+    reads: ReadsNoted | null;
+};
+
 /**
  * One relation's facts: which tuples are there, and an index per column
  * so a join that has a value for a column does not scan them all.
@@ -78,6 +180,8 @@ interface Relation {
      * kept up to date the same way as `columns`.
      */
     combined: Map<number, CombinedIndex>;
+    /** How many facts have ever been retracted, which `ReadsNoted` checks before trusting a count. */
+    removed: number;
 }
 /**
  * A tree of maps with one level per column in `columns`, lowest position
@@ -490,6 +594,8 @@ type AddOutcome = "added" | "improved" | "unchanged";
 /** A set of facts per relation, with O(1) membership. */
 declare class Database {
     private readonly store;
+    /** @internal Where reads are noted while `noteReads` runs. */
+    readLog: ReadLog | null;
     private relation;
     /**
      * The key this relation gives a tuple, whether or not the fact is
@@ -508,6 +614,8 @@ declare class Database {
     /** The tag stored for this fact, or undefined when there is none. */
     tagOf(relationName: string, tuple: Tuple): unknown;
     has(relationName: string, tuple: Tuple): boolean;
+    /** A fact matching the whole tuple agrees on its first column, so that lookup is enough to note. */
+    private noteTupleRead;
     facts(relationName: string): readonly Tuple[];
     /**
      * The facts with `value` at `column`. Once one of a literal's terms
@@ -671,4 +779,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 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 };
+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, ReadsNoted, 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, noteReads, profileEvaluation, profileEvaluationAsync, proofOf, rowBudget, rule, ruleLabel, rulesDeriving, stratify, tupleKey, tupleKeyParts, variable, witnesses };

package/dist/index.d.ts

@@ -50,6 +50,108 @@ declare class FactIndex {
     clear(): void;
 }
 
+/**
+ * What an evaluation looked up, so a caller that cached its answer can
+ * tell later whether a fact that arrived since could change it.
+ *
+ * While `noteReads` runs, every lookup the join makes is noted as the
+ * relation, the column and the value, and a relation read whole is
+ * noted whole. At the end each lookup's facts are counted. The cached
+ * answer is still right when every count is the same and nothing was
+ * retracted from those relations. Without a retraction counts only
+ * grow, so the sum of the counts changes exactly when one of them does.
+ * DESIGN.md explains why a fact no lookup would find cannot change the
+ * answer, and what that asks of the rules.
+ */
+
+/** @internal One relation's reads: the values looked up per column, unless something read it whole. */
+interface RelationReads {
+    whole: boolean;
+    columns: (Set<Atom> | undefined)[];
+}
+/** @internal The join notes its reads here while `noteReads` runs. */
+declare class ReadLog {
+    private readonly skipped;
+    /** Null for a relation the caller said to leave out. */
+    private readonly byRelation;
+    constructor(skipped: ReadonlySet<string>);
+    lookedUp(relation: string, column: number, value: Atom): void;
+    readWhole(relation: string): void;
+    /** Note everything an inner log noted, for an answer cached inside another. */
+    absorb(inner: ReadLog): void;
+    /**
+     * The reads with what each one finds in `db` now. One question looks
+     * up the same values in many columns, so each value is kept once, and
+     * each column keeps a bit per value saying whether it was looked up
+     * there.
+     */
+    counted(db: Database): ReadsNoted;
+    /** @internal Null for a relation the caller said to leave out. */
+    readsOf(relation: string): RelationReads | null;
+}
+/**
+ * Group `g` is the column `columns[g]` of the relation at
+ * `names[groups[g]]`. Its bits start at word `g` times the words one
+ * group takes, and bit `i` says it looked up `values[i]`.
+ */
+interface Lookups {
+    names: readonly string[];
+    groups: readonly number[];
+    columns: readonly number[];
+    values: readonly Atom[];
+    bits: Uint32Array;
+}
+/**
+ * The lookups one evaluation made, and how many facts they found when
+ * it finished. The values are the atoms the facts already contain, so
+ * a value costs a reference, and each column it was looked up in costs
+ * a bit.
+ */
+declare class ReadsNoted {
+    private readonly skipped;
+    private readonly found;
+    private readonly names;
+    private readonly groups;
+    private readonly columns;
+    private readonly values;
+    private readonly bits;
+    private readonly words;
+    private readonly removed;
+    /** The facts in every relation read, when the counts last matched. */
+    private facts;
+    /** Each relation read, found by name the first time a check needs it. */
+    private readonly relations;
+    constructor(db: Database, skipped: ReadonlySet<string>, lookups: Lookups, found: number);
+    /**
+     * Whether every read would find what it found then. A fact left in a
+     * skipped relation would join a question asked now without anything
+     * here having looked it up, so one there makes the answer no. The
+     * counts are taken again only when a relation read has grown.
+     */
+    unchangedIn(db: Database): boolean;
+    private relationAt;
+    private sumOver;
+    /**
+     * The facts the reads find, stopping once past `limit`. With nothing
+     * retracted every count only grows, so passing the old total already
+     * says that one of them grew.
+     */
+    private countIn;
+    private countGroup;
+}
+/**
+ * Run `work` and note what the join and the database's readers look up
+ * in every relation outside `skipped`. A caller skips the
+ * relations it empties after every question, so that the work derives
+ * their facts again and the lookups behind them get noted. The reads
+ * are null when a skipped relation was not empty to begin with, since
+ * the work could then build on facts nothing here looked up.
+ */
+declare function noteReads<T>(db: Database, skipped: ReadonlySet<string>, work: () => T): {
+    value: T;
+    reads: ReadsNoted | null;
+};
+
 /**
  * One relation's facts: which tuples are there, and an index per column
  * so a join that has a value for a column does not scan them all.
@@ -78,6 +180,8 @@ interface Relation {
      * kept up to date the same way as `columns`.
      */
     combined: Map<number, CombinedIndex>;
+    /** How many facts have ever been retracted, which `ReadsNoted` checks before trusting a count. */
+    removed: number;
 }
 /**
  * A tree of maps with one level per column in `columns`, lowest position
@@ -490,6 +594,8 @@ type AddOutcome = "added" | "improved" | "unchanged";
 /** A set of facts per relation, with O(1) membership. */
 declare class Database {
     private readonly store;
+    /** @internal Where reads are noted while `noteReads` runs. */
+    readLog: ReadLog | null;
     private relation;
     /**
      * The key this relation gives a tuple, whether or not the fact is
@@ -508,6 +614,8 @@ declare class Database {
     /** The tag stored for this fact, or undefined when there is none. */
     tagOf(relationName: string, tuple: Tuple): unknown;
     has(relationName: string, tuple: Tuple): boolean;
+    /** A fact matching the whole tuple agrees on its first column, so that lookup is enough to note. */
+    private noteTupleRead;
     facts(relationName: string): readonly Tuple[];
     /**
      * The facts with `value` at `column`. Once one of a literal's terms
@@ -671,4 +779,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 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 };
+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, ReadsNoted, 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, noteReads, profileEvaluation, profileEvaluationAsync, proofOf, rowBudget, rule, ruleLabel, rulesDeriving, stratify, tupleKey, tupleKeyParts, variable, witnesses };