@suss/datalog 0.37.1 → 0.38.1

package/dist/index.d.cts

@@ -7,10 +7,10 @@
  * The join asks for that key again on every candidate the rules
  * consider, so what the key costs to work out sets the cost of
  * evaluation. A relation finds a fact by walking a trie of its tuple's
- * atoms, one map hop per column, and the node the walk lands on is the
- * fact itself. Nothing is built to identify a tuple, and a membership
- * test that fails stops at the first column that misses. DESIGN.md says
- * why the walk is over the atoms rather than over interned integers.
+ * atoms, one map hop per column, to the first column where no other
+ * tuple shares the atoms so far. The key is stored there, and the walk
+ * compares the rest of the tuple instead of taking a map per column.
+ * DESIGN.md says why the walk is over the atoms, not interned integers.
  */
 
 /**
@@ -18,10 +18,11 @@
  * nothing to the relation that did not hand it out, and nothing outside
  * this module reads its fields.
  */
-interface FactKey {
+declare class FactKey {
+    readonly tuple: Tuple;
     present: boolean;
     tag: unknown;
-    next: Map<Atom, FactKey> | undefined;
+    constructor(tuple: Tuple);
 }
 /** The facts one relation has, and the tag stored against each. */
 declare class FactIndex {
@@ -40,15 +41,117 @@ declare class FactIndex {
     /** Take the fact away, and the tag with it. */
     remove(key: FactKey): void;
     /**
-     * Drop what is left of a removed tuple's path, up to the first node
-     * another fact still needs. Without this a relation that is retracted
-     * from over and over keeps a node per tuple it ever had.
+     * Drop a removed tuple's key, and any branch left with one key to
+     * tell apart. Without this a relation that is retracted from over and
+     * over keeps a key per tuple it ever had.
      */
     prune(tuple: Tuple): void;
     /** Drop every fact, and whatever was kept in order to find them. */
     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.
@@ -70,13 +173,15 @@ interface Relation {
      * encoding it first would build a string out of every node id on every
      * lookup and buy nothing.
      */
-    columns: (Map<Atom, Tuple[]> | undefined)[];
+    columns: (Map<Atom, Bucket> | 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>;
+    /** 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
@@ -86,6 +191,13 @@ interface CombinedIndex {
     columns: readonly number[];
     root: Map<Atom, unknown>;
 }
+/**
+ * The tuples an index has under one value, in the order they arrived.
+ * Most values in a column of node ids belong to a single tuple, and an
+ * array for each of those cost more than the tuple itself, so a lone
+ * tuple is kept on its own.
+ */
+type Bucket = Tuple | Tuple[];
 
 /**
  * Confidence levels as a tag algebra: how sure the run is of each
@@ -482,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
@@ -500,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
@@ -663,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

@@ -7,10 +7,10 @@
  * The join asks for that key again on every candidate the rules
  * consider, so what the key costs to work out sets the cost of
  * evaluation. A relation finds a fact by walking a trie of its tuple's
- * atoms, one map hop per column, and the node the walk lands on is the
- * fact itself. Nothing is built to identify a tuple, and a membership
- * test that fails stops at the first column that misses. DESIGN.md says
- * why the walk is over the atoms rather than over interned integers.
+ * atoms, one map hop per column, to the first column where no other
+ * tuple shares the atoms so far. The key is stored there, and the walk
+ * compares the rest of the tuple instead of taking a map per column.
+ * DESIGN.md says why the walk is over the atoms, not interned integers.
  */
 
 /**
@@ -18,10 +18,11 @@
  * nothing to the relation that did not hand it out, and nothing outside
  * this module reads its fields.
  */
-interface FactKey {
+declare class FactKey {
+    readonly tuple: Tuple;
     present: boolean;
     tag: unknown;
-    next: Map<Atom, FactKey> | undefined;
+    constructor(tuple: Tuple);
 }
 /** The facts one relation has, and the tag stored against each. */
 declare class FactIndex {
@@ -40,15 +41,117 @@ declare class FactIndex {
     /** Take the fact away, and the tag with it. */
     remove(key: FactKey): void;
     /**
-     * Drop what is left of a removed tuple's path, up to the first node
-     * another fact still needs. Without this a relation that is retracted
-     * from over and over keeps a node per tuple it ever had.
+     * Drop a removed tuple's key, and any branch left with one key to
+     * tell apart. Without this a relation that is retracted from over and
+     * over keeps a key per tuple it ever had.
      */
     prune(tuple: Tuple): void;
     /** Drop every fact, and whatever was kept in order to find them. */
     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.
@@ -70,13 +173,15 @@ interface Relation {
      * encoding it first would build a string out of every node id on every
      * lookup and buy nothing.
      */
-    columns: (Map<Atom, Tuple[]> | undefined)[];
+    columns: (Map<Atom, Bucket> | 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>;
+    /** 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
@@ -86,6 +191,13 @@ interface CombinedIndex {
     columns: readonly number[];
     root: Map<Atom, unknown>;
 }
+/**
+ * The tuples an index has under one value, in the order they arrived.
+ * Most values in a column of node ids belong to a single tuple, and an
+ * array for each of those cost more than the tuple itself, so a lone
+ * tuple is kept on its own.
+ */
+type Bucket = Tuple | Tuple[];
 
 /**
  * Confidence levels as a tag algebra: how sure the run is of each
@@ -482,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
@@ -500,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
@@ -663,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 };