@suss/datalog 0.21.1 → 0.22.0

package/README.md

@@ -313,6 +313,24 @@ Keep the facts you add and the facts the rules derive in separate
 relations. Taking a conclusion back cannot tell one from the other, and
 splitting them is how people normally write Datalog anyway.
 
+### Reading what the rules are waiting on
+
+Demand is also something a caller can read. `program.demands` lists
+each demand relation with the relation it is for and which of that
+relation's columns a demand row fixes, in column order:
+
+```ts
+program.demands;
+// [{ relation: "reaches", bound: [true, false], demand: "wanted:reaches" }]
+db.facts("wanted:reaches"); // [["a"], ["b"], ["c"]]
+```
+
+A caller that loads its base facts lazily uses this to find out what to
+load next. Evaluate, read the demand rows on the relation whose base
+facts come from somewhere else, fetch those, evaluate again, and stop
+when no demand row is new. The rules then decide what gets loaded, and
+the caller never has to guess how far a chain runs.
+
 Extraction-scale fact sets run to thousands of tuples. If that changes,
 the rule data model is the part that stays and this evaluator is the
 part you replace.

package/dist/index.cjs

@@ -117,6 +117,7 @@ function deriveOnDemand(rules, complete) {
   const demandOn = (relation, adornment) => `wanted:${nameOf(relation, adornment)}`;
   const rewritten = [];
   const demandDriven = /* @__PURE__ */ new Set();
+  const demands = [];
   const already = /* @__PURE__ */ new Set();
   const emit = (r) => {
     const key = JSON.stringify(r);
@@ -129,6 +130,11 @@ function deriveOnDemand(rules, complete) {
     if (anyBound(adorned.adornment)) {
       demandDriven.add(nameOf(adorned.relation, adorned.adornment));
       demandDriven.add(demandOn(adorned.relation, adorned.adornment));
+      demands.push({
+        relation: adorned.relation,
+        bound: adorned.adornment,
+        demand: demandOn(adorned.relation, adorned.adornment)
+      });
     }
     for (const written of rulesByHead.get(adorned.relation) ?? []) {
       const r = boundFirst(written, adorned.adornment);
@@ -169,7 +175,7 @@ function deriveOnDemand(rules, complete) {
     }
   }
   demandRewrites.add(rewritten);
-  return { rules: rewritten, demandDriven: [...demandDriven] };
+  return { rules: rewritten, demandDriven: [...demandDriven], demands };
 }
 var sameLiteral = (premises, conclusion) => premises.length === 1 && JSON.stringify(premises[0]) === JSON.stringify(conclusion);
 function boundFirst(r, headAdornment) {

package/dist/index.d.cts

@@ -31,6 +31,18 @@ declare function confidenceWith(levelOf: (rule: Rule) => ConfidenceLevel | undef
 /** The confidence algebra with every rule counted as exact. */
 declare const confidence: TagAlgebra<ConfidenceLevel>;
 
+/** One demand relation the rewrite created, and what its rows say. */
+interface Demand {
+    /** The relation whose rows are being waited on. */
+    relation: string;
+    /** Which columns of that relation a demand row fixes. */
+    bound: readonly boolean[];
+    /**
+     * The demand relation's name. Each of its rows lists the bound
+     * columns' values, in the relation's column order.
+     */
+    demand: string;
+}
 /** A rewritten rule set, and which of its relations demand restricts. */
 interface OnDemandRules {
     /** The rewritten rules, ready to evaluate. */
@@ -43,6 +55,13 @@ interface OnDemandRules {
      * answers.
      */
     demandDriven: string[];
+    /**
+     * The demand relations by what they ask for, so a caller can read
+     * what the rules are waiting on and go and get it: a store that
+     * loads facts lazily reads the demand on a module's exports and
+     * extracts that module.
+     */
+    demands: Demand[];
 }
 /**
  * Rewrite `rules` so the relations listed in `complete` still come out
@@ -419,4 +438,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 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 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 };

package/dist/index.d.ts

@@ -31,6 +31,18 @@ declare function confidenceWith(levelOf: (rule: Rule) => ConfidenceLevel | undef
 /** The confidence algebra with every rule counted as exact. */
 declare const confidence: TagAlgebra<ConfidenceLevel>;
 
+/** One demand relation the rewrite created, and what its rows say. */
+interface Demand {
+    /** The relation whose rows are being waited on. */
+    relation: string;
+    /** Which columns of that relation a demand row fixes. */
+    bound: readonly boolean[];
+    /**
+     * The demand relation's name. Each of its rows lists the bound
+     * columns' values, in the relation's column order.
+     */
+    demand: string;
+}
 /** A rewritten rule set, and which of its relations demand restricts. */
 interface OnDemandRules {
     /** The rewritten rules, ready to evaluate. */
@@ -43,6 +55,13 @@ interface OnDemandRules {
      * answers.
      */
     demandDriven: string[];
+    /**
+     * The demand relations by what they ask for, so a caller can read
+     * what the rules are waiting on and go and get it: a store that
+     * loads facts lazily reads the demand on a module's exports and
+     * extracts that module.
+     */
+    demands: Demand[];
 }
 /**
  * Rewrite `rules` so the relations listed in `complete` still come out
@@ -419,4 +438,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 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 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 };

package/dist/index.js

@@ -71,6 +71,7 @@ function deriveOnDemand(rules, complete) {
   const demandOn = (relation, adornment) => `wanted:${nameOf(relation, adornment)}`;
   const rewritten = [];
   const demandDriven = /* @__PURE__ */ new Set();
+  const demands = [];
   const already = /* @__PURE__ */ new Set();
   const emit = (r) => {
     const key = JSON.stringify(r);
@@ -83,6 +84,11 @@ function deriveOnDemand(rules, complete) {
     if (anyBound(adorned.adornment)) {
       demandDriven.add(nameOf(adorned.relation, adorned.adornment));
       demandDriven.add(demandOn(adorned.relation, adorned.adornment));
+      demands.push({
+        relation: adorned.relation,
+        bound: adorned.adornment,
+        demand: demandOn(adorned.relation, adorned.adornment)
+      });
     }
     for (const written of rulesByHead.get(adorned.relation) ?? []) {
       const r = boundFirst(written, adorned.adornment);
@@ -123,7 +129,7 @@ function deriveOnDemand(rules, complete) {
     }
   }
   demandRewrites.add(rewritten);
-  return { rules: rewritten, demandDriven: [...demandDriven] };
+  return { rules: rewritten, demandDriven: [...demandDriven], demands };
 }
 var sameLiteral = (premises, conclusion) => premises.length === 1 && JSON.stringify(premises[0]) === JSON.stringify(conclusion);
 function boundFirst(r, headAdornment) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/datalog",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "type": "module",
   "description": "A small semi-naïve Datalog evaluator with stratified negation — the rules engine behind suss's derived program facts.",
   "keywords": [