@suss/datalog 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -1,3 +1,36 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+
+/** How sure the run is of one fact. The order is high > medium > low. */
+type ConfidenceLevel = "high" | "medium" | "low";
+/**
+ * The confidence algebra with a level per rule. Rules the callback
+ * returns `undefined` for count as exact, so a rule set with one
+ * heuristic only has to speak for that one.
+ */
+declare function confidenceWith(levelOf: (rule: Rule) => ConfidenceLevel | undefined): TagAlgebra<ConfidenceLevel>;
+/** The confidence algebra with every rule counted as exact. */
+declare const confidence: TagAlgebra<ConfidenceLevel>;
+
 /** A rewritten rule set, and which of its relations demand restricts. */
 interface OnDemandRules {
     /** The rewritten rules, ready to evaluate. */
@@ -116,6 +149,81 @@ declare const tupleKey: (parts: readonly Atom[]) => string;
  */
 declare function tupleKeyParts(key: string): string[];
 
+/**
+ * Witnesses: one derivation kept per derived fact, and proofs rebuilt
+ * on demand by walking those derivations backward.
+ *
+ * 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.
+ */
+
+/**
+ * The tag the `witnesses` algebra stores on a derived fact. A class,
+ * so `proofOf` can tell a witness from another algebra's tag by
+ * `instanceof` and treat anything else as an untagged leaf.
+ */
+declare class Witness {
+    readonly rule: Rule;
+    readonly body: readonly BodyMatch[];
+    constructor(rule: Rule, body: readonly BodyMatch[]);
+}
+/**
+ * What a fact's tag can be under `witnesses`. The marks stand in for a
+ * caller-asserted fact and a matched negation inside the algebra;
+ * neither is ever stored, so `tagOf` only ever returns a `Witness`.
+ */
+type WitnessTag = Witness | "asserted" | "absent";
+/**
+ * The algebra that keeps one witness per derived fact. Merge returns
+ * the stored tag, so no fact ever re-enters the delta and evaluation
+ * costs only the bookkeeping.
+ */
+declare const witnesses: TagAlgebra<WitnessTag>;
+/** A reconstructed derivation tree for one fact. */
+type Proof = ProofDerived | {
+    kind: "fact";
+    relation: string;
+    tuple: Tuple;
+} | {
+    kind: "absence";
+    relation: string;
+    tuple: Tuple;
+} | {
+    kind: "truncated";
+    relation: string;
+    tuple: Tuple;
+    reason: "depth" | "cycle";
+};
+interface ProofDerived {
+    kind: "derived";
+    relation: string;
+    tuple: Tuple;
+    rule: Rule;
+    /** One proof per body literal, in rule-body order. */
+    premises: readonly Proof[];
+}
+interface ProofOptions {
+    /** How many derived nodes deep the walk goes before truncating. */
+    maxDepth?: number;
+}
+/**
+ * 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.
+ */
+declare function proofOf(db: Database, relation: string, tuple: Tuple, options?: ProofOptions): Proof;
+
 /**
  * @suss/datalog, a small semi-naïve Datalog evaluator with stratified
  * negation, and the rules engine behind suss's derived program facts:
@@ -163,14 +271,34 @@ interface Rule {
         terms: Term[];
     };
     body: Literal[];
+    /** The name a proof shows for this rule. `ruleLabel` renders a default without it. */
+    name?: string;
 }
-declare const rule: (relation: string, terms: Term[], body: Literal[]) => Rule;
+declare const rule: (relation: string, terms: Term[], body: Literal[], name?: string) => Rule;
+/**
+ * The label a proof prints for a rule: the name the caller gave it, or
+ * the head and body relations, as in `path :- path, !blocked`. Two
+ * rules over the same relations get the same default label, which is
+ * why a witness keeps the `Rule` object itself and renders it only
+ * when asked.
+ */
+declare const ruleLabel: (r: Rule) => string;
+/** What `add` did: a new fact, a better tag on an existing one, or nothing. */
+type AddOutcome = "added" | "improved" | "unchanged";
 /** A set of facts per relation, with O(1) membership. */
 declare class Database {
     private readonly store;
     private relation;
-    /** Add a fact; returns true when the tuple is new. */
-    add(relationName: string, tuple: Tuple): boolean;
+    /**
+     * Add a fact, or merge a tag into one already present. A new fact
+     * stores `tag` when one is given. For a fact already present,
+     * `merge` gets the stored tag (undefined when there is none) and the
+     * incoming one; returning anything but the stored value stores the
+     * result and reports "improved".
+     */
+    add(relationName: string, tuple: Tuple, tag?: unknown, merge?: (stored: unknown, incoming: unknown) => unknown): AddOutcome;
+    /** The tag stored for this fact, or undefined when there is none. */
+    tagOf(relationName: string, tuple: Tuple): unknown;
     has(relationName: string, tuple: Tuple): boolean;
     facts(relationName: string): readonly Tuple[];
     /**
@@ -194,6 +322,60 @@ declare class Database {
     size(relationName: string): number;
     relationNames(): string[];
 }
+/**
+ * A provenance semiring (Green, Karvounarakis, Tannen 2007): every
+ * fact may have a tag, a rule firing combines its body facts' tags
+ * into a tag for its conclusion, and a conclusion reached a second
+ * time merges the new tag into the stored one. An algebra is an
+ * optional argument to `evaluate`; rules never mention tags, and
+ * without an algebra the evaluator never touches them.
+ *
+ * `merge` must return the stored tag itself when the new derivation
+ * does not improve on it; any other result is stored and the fact
+ * re-enters the delta. For recursive rule sets merge must be a
+ * bounded meet, or evaluation will not terminate; the engine does
+ * not check this. `undefined` is not a valid tag.
+ */
+interface TagAlgebra<Tag> {
+    /** What a fact nobody tagged contributes, i.e. every caller-asserted fact. */
+    asserted: Tag;
+    /** What a matched negated literal contributes: there is no fact to read. */
+    absent: Tag;
+    /** The head's tag from the body's, in rule-body order, once per derivation. */
+    combine(bodyTags: readonly Tag[], derivation: Derivation): Tag;
+    /**
+     * Set when `combine` never reads `bodyTags`, and the evaluator then
+     * skips looking each body fact's stored tag up. A witness is built
+     * from the derivation alone, and on a large sweep the lookups were
+     * three quarters of the tagged path's cost.
+     */
+    ignoresBodyTags?: boolean;
+    /** The tag to store when a fact is derived again; see the merge contract above. */
+    merge(stored: Tag, incoming: Tag): Tag;
+}
+/**
+ * How one body literal was satisfied: the fact a positive literal
+ * matched, or the grounded tuple that was not in the database when a
+ * negated literal checked, kept so a proof can point at the absence.
+ */
+type BodyMatch = {
+    kind: "fact";
+    relation: string;
+    tuple: Tuple;
+} | {
+    kind: "absence";
+    relation: string;
+    tuple: Tuple;
+};
+/**
+ * One rule firing, handed to `combine` beside the body tags: the rule
+ * as the caller wrote it, and one `BodyMatch` per body literal in
+ * rule-body order. An algebra that only folds tags ignores it.
+ */
+interface Derivation {
+    rule: Rule;
+    body: readonly BodyMatch[];
+}
 /**
  * Assign each derived relation a stratum such that positive
  * dependencies never decrease the stratum and negative dependencies
@@ -207,8 +389,13 @@ declare function stratify(rules: Rule[]): Rule[][];
  * 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.
+ *
+ * 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.
  */
-declare function evaluate(db: Database, rules: Rule[]): Database;
+declare function evaluate<Tag = never>(db: Database, rules: Rule[], algebra?: TagAlgebra<Tag>): Database;
 /**
  * Empty these relations, and leave `rules` able to carry on from where
  * it got to.
@@ -232,4 +419,4 @@ declare function evaluate(db: Database, rules: Rule[]): Database;
  */
 declare function clearRelations(db: Database, rules: Rule[], relations: readonly string[]): void;
 
-export { type Atom, Database, type EvaluationProfile, type Literal, type OnDemandRules, type Rule, type RuleCost, type Term, type Tuple, clearRelations, constant, deriveOnDemand, evaluate, formatProfile, lit, notLit, profileEvaluation, profileEvaluationAsync, rule, stratify, tupleKey, tupleKeyParts, variable };
+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 };

package/dist/index.d.ts

@@ -1,3 +1,36 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+
+/** How sure the run is of one fact. The order is high > medium > low. */
+type ConfidenceLevel = "high" | "medium" | "low";
+/**
+ * The confidence algebra with a level per rule. Rules the callback
+ * returns `undefined` for count as exact, so a rule set with one
+ * heuristic only has to speak for that one.
+ */
+declare function confidenceWith(levelOf: (rule: Rule) => ConfidenceLevel | undefined): TagAlgebra<ConfidenceLevel>;
+/** The confidence algebra with every rule counted as exact. */
+declare const confidence: TagAlgebra<ConfidenceLevel>;
+
 /** A rewritten rule set, and which of its relations demand restricts. */
 interface OnDemandRules {
     /** The rewritten rules, ready to evaluate. */
@@ -116,6 +149,81 @@ declare const tupleKey: (parts: readonly Atom[]) => string;
  */
 declare function tupleKeyParts(key: string): string[];
 
+/**
+ * Witnesses: one derivation kept per derived fact, and proofs rebuilt
+ * on demand by walking those derivations backward.
+ *
+ * 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.
+ */
+
+/**
+ * The tag the `witnesses` algebra stores on a derived fact. A class,
+ * so `proofOf` can tell a witness from another algebra's tag by
+ * `instanceof` and treat anything else as an untagged leaf.
+ */
+declare class Witness {
+    readonly rule: Rule;
+    readonly body: readonly BodyMatch[];
+    constructor(rule: Rule, body: readonly BodyMatch[]);
+}
+/**
+ * What a fact's tag can be under `witnesses`. The marks stand in for a
+ * caller-asserted fact and a matched negation inside the algebra;
+ * neither is ever stored, so `tagOf` only ever returns a `Witness`.
+ */
+type WitnessTag = Witness | "asserted" | "absent";
+/**
+ * The algebra that keeps one witness per derived fact. Merge returns
+ * the stored tag, so no fact ever re-enters the delta and evaluation
+ * costs only the bookkeeping.
+ */
+declare const witnesses: TagAlgebra<WitnessTag>;
+/** A reconstructed derivation tree for one fact. */
+type Proof = ProofDerived | {
+    kind: "fact";
+    relation: string;
+    tuple: Tuple;
+} | {
+    kind: "absence";
+    relation: string;
+    tuple: Tuple;
+} | {
+    kind: "truncated";
+    relation: string;
+    tuple: Tuple;
+    reason: "depth" | "cycle";
+};
+interface ProofDerived {
+    kind: "derived";
+    relation: string;
+    tuple: Tuple;
+    rule: Rule;
+    /** One proof per body literal, in rule-body order. */
+    premises: readonly Proof[];
+}
+interface ProofOptions {
+    /** How many derived nodes deep the walk goes before truncating. */
+    maxDepth?: number;
+}
+/**
+ * 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.
+ */
+declare function proofOf(db: Database, relation: string, tuple: Tuple, options?: ProofOptions): Proof;
+
 /**
  * @suss/datalog, a small semi-naïve Datalog evaluator with stratified
  * negation, and the rules engine behind suss's derived program facts:
@@ -163,14 +271,34 @@ interface Rule {
         terms: Term[];
     };
     body: Literal[];
+    /** The name a proof shows for this rule. `ruleLabel` renders a default without it. */
+    name?: string;
 }
-declare const rule: (relation: string, terms: Term[], body: Literal[]) => Rule;
+declare const rule: (relation: string, terms: Term[], body: Literal[], name?: string) => Rule;
+/**
+ * The label a proof prints for a rule: the name the caller gave it, or
+ * the head and body relations, as in `path :- path, !blocked`. Two
+ * rules over the same relations get the same default label, which is
+ * why a witness keeps the `Rule` object itself and renders it only
+ * when asked.
+ */
+declare const ruleLabel: (r: Rule) => string;
+/** What `add` did: a new fact, a better tag on an existing one, or nothing. */
+type AddOutcome = "added" | "improved" | "unchanged";
 /** A set of facts per relation, with O(1) membership. */
 declare class Database {
     private readonly store;
     private relation;
-    /** Add a fact; returns true when the tuple is new. */
-    add(relationName: string, tuple: Tuple): boolean;
+    /**
+     * Add a fact, or merge a tag into one already present. A new fact
+     * stores `tag` when one is given. For a fact already present,
+     * `merge` gets the stored tag (undefined when there is none) and the
+     * incoming one; returning anything but the stored value stores the
+     * result and reports "improved".
+     */
+    add(relationName: string, tuple: Tuple, tag?: unknown, merge?: (stored: unknown, incoming: unknown) => unknown): AddOutcome;
+    /** The tag stored for this fact, or undefined when there is none. */
+    tagOf(relationName: string, tuple: Tuple): unknown;
     has(relationName: string, tuple: Tuple): boolean;
     facts(relationName: string): readonly Tuple[];
     /**
@@ -194,6 +322,60 @@ declare class Database {
     size(relationName: string): number;
     relationNames(): string[];
 }
+/**
+ * A provenance semiring (Green, Karvounarakis, Tannen 2007): every
+ * fact may have a tag, a rule firing combines its body facts' tags
+ * into a tag for its conclusion, and a conclusion reached a second
+ * time merges the new tag into the stored one. An algebra is an
+ * optional argument to `evaluate`; rules never mention tags, and
+ * without an algebra the evaluator never touches them.
+ *
+ * `merge` must return the stored tag itself when the new derivation
+ * does not improve on it; any other result is stored and the fact
+ * re-enters the delta. For recursive rule sets merge must be a
+ * bounded meet, or evaluation will not terminate; the engine does
+ * not check this. `undefined` is not a valid tag.
+ */
+interface TagAlgebra<Tag> {
+    /** What a fact nobody tagged contributes, i.e. every caller-asserted fact. */
+    asserted: Tag;
+    /** What a matched negated literal contributes: there is no fact to read. */
+    absent: Tag;
+    /** The head's tag from the body's, in rule-body order, once per derivation. */
+    combine(bodyTags: readonly Tag[], derivation: Derivation): Tag;
+    /**
+     * Set when `combine` never reads `bodyTags`, and the evaluator then
+     * skips looking each body fact's stored tag up. A witness is built
+     * from the derivation alone, and on a large sweep the lookups were
+     * three quarters of the tagged path's cost.
+     */
+    ignoresBodyTags?: boolean;
+    /** The tag to store when a fact is derived again; see the merge contract above. */
+    merge(stored: Tag, incoming: Tag): Tag;
+}
+/**
+ * How one body literal was satisfied: the fact a positive literal
+ * matched, or the grounded tuple that was not in the database when a
+ * negated literal checked, kept so a proof can point at the absence.
+ */
+type BodyMatch = {
+    kind: "fact";
+    relation: string;
+    tuple: Tuple;
+} | {
+    kind: "absence";
+    relation: string;
+    tuple: Tuple;
+};
+/**
+ * One rule firing, handed to `combine` beside the body tags: the rule
+ * as the caller wrote it, and one `BodyMatch` per body literal in
+ * rule-body order. An algebra that only folds tags ignores it.
+ */
+interface Derivation {
+    rule: Rule;
+    body: readonly BodyMatch[];
+}
 /**
  * Assign each derived relation a stratum such that positive
  * dependencies never decrease the stratum and negative dependencies
@@ -207,8 +389,13 @@ declare function stratify(rules: Rule[]): Rule[][];
  * 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.
+ *
+ * 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.
  */
-declare function evaluate(db: Database, rules: Rule[]): Database;
+declare function evaluate<Tag = never>(db: Database, rules: Rule[], algebra?: TagAlgebra<Tag>): Database;
 /**
  * Empty these relations, and leave `rules` able to carry on from where
  * it got to.
@@ -232,4 +419,4 @@ declare function evaluate(db: Database, rules: Rule[]): Database;
  */
 declare function clearRelations(db: Database, rules: Rule[], relations: readonly string[]): void;
 
-export { type Atom, Database, type EvaluationProfile, type Literal, type OnDemandRules, type Rule, type RuleCost, type Term, type Tuple, clearRelations, constant, deriveOnDemand, evaluate, formatProfile, lit, notLit, profileEvaluation, profileEvaluationAsync, rule, stratify, tupleKey, tupleKeyParts, variable };
+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 };