@suss/datalog 0.1.0

package/LICENSE

@@ -0,0 +1,205 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable by
+      such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do not
+          modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor has
+      been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format please. Also add information on
+      how to contact you by electronic and paper mail.
+
+      If the program does not interact with users remotely through a computer
+      network, then your name and employer's name (e.g., your institution)
+      is sufficient to fill in the "name of copyright owner" field. Feel
+      free to omit the "name of employer" line if you are in no way affiliated
+      with any institution.
+
+      Copyright 2026 Nimbus Cloud AI LLC
+
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.

package/README.md

@@ -0,0 +1,84 @@
+# @suss/datalog
+
+A small semi-naïve Datalog evaluator with stratified negation. This is
+the rules engine behind suss's derived program facts.
+
+## Why suss carries a Datalog engine
+
+Extraction keeps meeting problems that are naturally *fixpoints*: which
+functions are reachable from an entry point, what a bare `throw err`
+re-throw can actually raise (the union of what everything in the `try`
+block throws, transitively), how a wrapper-of-a-wrapper resolves to its
+underlying route. Expressed as rules over base facts, each analysis is
+a few auditable lines:
+
+```ts
+import { Database, evaluate, lit, rule, variable as v } from "@suss/datalog";
+
+const db = new Database();
+db.add("entry", ["main"]);
+db.add("calls", ["main", "helper"]);
+db.add("calls", ["helper", "util"]);
+
+evaluate(db, [
+  rule("reachable", [v("f")], [lit("entry", v("f"))]),
+  rule(
+    "reachable",
+    [v("g")],
+    [lit("reachable", v("f")), lit("calls", v("f"), v("g"))],
+  ),
+]);
+
+db.facts("reachable"); // [["main"], ["helper"], ["util"]]
+```
+
+Termination and soundness are the engine's job, proven once. Negation
+(`notLit`) is *stratified*: a rule set with a negation cycle is a hard
+error at evaluation time, the property that makes rules safe to audit
+independently of any engine.
+
+Because rules are plain data (no DSL strings, no embedded code), the
+same rule set can later run on a faster external engine, and (the
+longer game) analyses written against fact shapes (`calls`, `throws`,
+`handles`, …) are language-independent: a second language adapter only
+has to emit the same facts.
+
+## Design constraints
+
+1. **Pure TypeScript, zero dependencies.** The npm-shipped CLI cannot
+   require a native binary.
+2. **Rules are data.** `Rule` / `Literal` / `Term` objects, built with
+   `rule` / `lit` / `notLit` / `variable` / `constant`.
+3. **Sound negation only.** Stratification is checked; negated literals
+   must ground all variables from earlier positive literals.
+
+## What it does to stay quick
+
+Semi-naïve iteration keeps per-round work proportional to newly derived
+facts rather than to everything known.
+
+Joins narrow before they scan. Once a literal has any term fixed, either
+written as a constant or bound by an earlier literal, the join looks the
+value up in a per-column index instead of walking the relation. A column
+gets indexed the first time something asks for it and stays current
+after that, so a relation nobody joins on that way carries no index.
+
+`evaluate` picks up where it left off. Call it again with the same rules
+after adding facts and it seeds from the facts you added rather than
+starting the fixpoint over. Callers that interleave "add some facts, ask
+a question" get this without doing anything. Positive rules are monotone,
+so everything derived before still holds.
+
+Negated rules work differently. A new fact can make a negated literal
+stop matching, and the conclusion that rested on it has to go. So a
+re-run with negated rules takes back what the previous pass derived and
+works the answer out again from the base facts. Both paths leave the
+database holding the answer for the facts it has now.
+
+Keep the facts you add and the facts rules derive in separate relations.
+Taking a conclusion back cannot tell one from the other, and the
+separation is how Datalog is normally written anyway.
+
+Extraction-scale fact sets are thousands of tuples. If that changes, the
+rule data model is the stable seam and this evaluator is the replaceable
+part.

package/dist/index.cjs

@@ -0,0 +1,450 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Database: () => Database,
+  constant: () => constant,
+  evaluate: () => evaluate,
+  lit: () => lit,
+  notLit: () => notLit,
+  rule: () => rule,
+  stratify: () => stratify,
+  variable: () => variable
+});
+module.exports = __toCommonJS(index_exports);
+var variable = (name) => ({ type: "variable", name });
+var constant = (value) => ({ type: "constant", value });
+var lit = (relation, ...terms) => ({
+  relation,
+  terms,
+  negated: false
+});
+var notLit = (relation, ...terms) => ({
+  relation,
+  terms,
+  negated: true
+});
+var rule = (relation, terms, body) => ({ head: { relation, terms }, body });
+var SEP = "\0";
+var atomKey = (a) => `${typeof a === "number" ? "n" : "s"}${a}`;
+var keyOf = (tuple) => tuple.map(atomKey).join(SEP);
+function addToBucket(index, key, tuple) {
+  const bucket = index.get(key);
+  if (bucket === void 0) {
+    index.set(key, [tuple]);
+  } else {
+    bucket.push(tuple);
+  }
+}
+var Database = class {
+  store = /* @__PURE__ */ new Map();
+  relation(name) {
+    const existing = this.store.get(name);
+    if (existing !== void 0) {
+      return existing;
+    }
+    const created = {
+      keys: /* @__PURE__ */ new Set(),
+      tuples: [],
+      indexes: /* @__PURE__ */ new Map()
+    };
+    this.store.set(name, created);
+    return created;
+  }
+  /** Add a fact; returns true when the tuple is new. */
+  add(relationName, tuple) {
+    const relation = this.relation(relationName);
+    const key = keyOf(tuple);
+    if (relation.keys.has(key)) {
+      if (!isDeriving(this)) {
+        claimFact(this, relationName, key);
+      }
+      return false;
+    }
+    relation.keys.add(key);
+    relation.tuples.push(tuple);
+    for (const [column, index] of relation.indexes) {
+      const value = tuple[column];
+      if (value !== void 0) {
+        addToBucket(index, atomKey(value), tuple);
+      }
+    }
+    return true;
+  }
+  has(relationName, tuple) {
+    return this.store.get(relationName)?.keys.has(keyOf(tuple)) ?? false;
+  }
+  facts(relationName) {
+    return this.store.get(relationName)?.tuples ?? [];
+  }
+  /**
+   * The facts holding `value` at `column`. A join reaches for this
+   * instead of scanning the whole relation once one of its terms is
+   * already bound.
+   *
+   * A column is indexed the first time somebody asks for it and stays
+   * up to date after that, so a relation nobody joins on this way
+   * carries no index at all.
+   */
+  lookup(relationName, column, value) {
+    const relation = this.store.get(relationName);
+    if (relation === void 0) {
+      return [];
+    }
+    let index = relation.indexes.get(column);
+    if (index === void 0) {
+      index = /* @__PURE__ */ new Map();
+      for (const tuple of relation.tuples) {
+        const at = tuple[column];
+        if (at !== void 0) {
+          addToBucket(index, atomKey(at), tuple);
+        }
+      }
+      relation.indexes.set(column, index);
+    }
+    return index.get(atomKey(value)) ?? [];
+  }
+  /**
+   * Remove facts from a relation. Returns how many were actually there.
+   *
+   * Evaluation uses this to take back what it derived last time when a
+   * rule set uses negation, where a new fact can invalidate an old
+   * conclusion. Callers rarely need it.
+   */
+  retract(relationName, tuples) {
+    const relation = this.store.get(relationName);
+    if (relation === void 0) {
+      return 0;
+    }
+    const going = /* @__PURE__ */ new Set();
+    for (const tuple of tuples) {
+      const key = keyOf(tuple);
+      if (relation.keys.has(key)) {
+        going.add(key);
+      }
+    }
+    if (going.size === 0) {
+      return 0;
+    }
+    for (const key of going) {
+      relation.keys.delete(key);
+    }
+    relation.tuples = relation.tuples.filter(
+      (tuple) => !going.has(keyOf(tuple))
+    );
+    relation.indexes.clear();
+    forgetFacts(this, relationName, going);
+    return going.size;
+  }
+  size(relationName) {
+    return this.store.get(relationName)?.tuples.length ?? 0;
+  }
+  relationNames() {
+    return [...this.store.keys()];
+  }
+};
+function stratify(rules) {
+  const derived = new Set(rules.map((r) => r.head.relation));
+  const stratum = /* @__PURE__ */ new Map();
+  for (const name of derived) {
+    stratum.set(name, 0);
+  }
+  const bound = derived.size + 1;
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const r of rules) {
+      const head = r.head.relation;
+      for (const body of r.body) {
+        if (!derived.has(body.relation)) {
+          continue;
+        }
+        const required = (stratum.get(body.relation) ?? 0) + (body.negated ? 1 : 0);
+        if ((stratum.get(head) ?? 0) < required) {
+          if (required > bound) {
+            throw new Error(
+              `rules are not stratifiable: negation cycle through "${head}"`
+            );
+          }
+          stratum.set(head, required);
+          changed = true;
+        }
+      }
+    }
+  }
+  const maxStratum = Math.max(0, ...stratum.values());
+  const strata = Array.from({ length: maxStratum + 1 }, () => []);
+  for (const r of rules) {
+    strata[stratum.get(r.head.relation) ?? 0].push(r);
+  }
+  return strata.filter((s) => s.length > 0);
+}
+function unify(literal, tuple, bindings) {
+  if (literal.terms.length !== tuple.length) {
+    return null;
+  }
+  let next = null;
+  for (let i = 0; i < literal.terms.length; i++) {
+    const term = literal.terms[i];
+    const value = tuple[i];
+    if (term.type === "constant") {
+      if (term.value !== value) {
+        return null;
+      }
+      continue;
+    }
+    const bound = (next ?? bindings).get(term.name);
+    if (bound === void 0) {
+      next = next ?? new Map(bindings);
+      next.set(term.name, value);
+      continue;
+    }
+    if (bound !== value) {
+      return null;
+    }
+  }
+  return next ?? bindings;
+}
+function groundNegated(literal, bindings) {
+  return literal.terms.map((term) => {
+    if (term.type === "constant") {
+      return term.value;
+    }
+    const bound = bindings.get(term.name);
+    if (bound === void 0) {
+      throw new Error(
+        `unbound variable "${term.name}" in negated literal "${literal.relation}" \u2014 negated literals may only use variables bound by earlier positive literals`
+      );
+    }
+    return bound;
+  });
+}
+function headTuple(head, bindings) {
+  return head.terms.map((term) => {
+    if (term.type === "constant") {
+      return term.value;
+    }
+    const bound = bindings.get(term.name);
+    if (bound === void 0) {
+      throw new Error(
+        `unbound variable "${term.name}" in head of "${head.relation}"`
+      );
+    }
+    return bound;
+  });
+}
+function evaluateRule(db, deltas, r, deltaIndex) {
+  const results = [];
+  const step = (literalIndex, positiveIndex, bindings) => {
+    if (literalIndex === r.body.length) {
+      results.push(headTuple(r.head, bindings));
+      return;
+    }
+    const literal = r.body[literalIndex];
+    if (literal.negated) {
+      if (!db.has(literal.relation, groundNegated(literal, bindings))) {
+        step(literalIndex + 1, positiveIndex, bindings);
+      }
+      return;
+    }
+    const source = positiveIndex === deltaIndex ? deltas.get(literal.relation) ?? [] : boundSource(db, literal, bindings);
+    for (const tuple of source) {
+      const next = unify(literal, tuple, bindings);
+      if (next !== null) {
+        step(literalIndex + 1, positiveIndex + 1, next);
+      }
+    }
+  };
+  step(0, 0, /* @__PURE__ */ new Map());
+  return results;
+}
+function boundSource(db, literal, bindings) {
+  for (let column = 0; column < literal.terms.length; column++) {
+    const term = literal.terms[column];
+    const value = term.type === "constant" ? term.value : bindings.get(term.name);
+    if (value !== void 0) {
+      return db.lookup(literal.relation, column, value);
+    }
+  }
+  return db.facts(literal.relation);
+}
+var evaluated = /* @__PURE__ */ new WeakMap();
+var deriving = /* @__PURE__ */ new Map();
+function isDeriving(db) {
+  return (deriving.get(db) ?? 0) > 0;
+}
+function statesFor(db) {
+  let states = evaluated.get(db);
+  if (states === void 0) {
+    states = /* @__PURE__ */ new Map();
+    evaluated.set(db, states);
+  }
+  return states;
+}
+function claimFact(db, relation, key) {
+  const states = evaluated.get(db);
+  if (states === void 0) {
+    return;
+  }
+  for (const state of states.values()) {
+    state.derived.get(relation)?.delete(key);
+  }
+}
+function forgetFacts(db, relation, keys) {
+  const states = evaluated.get(db);
+  if (states === void 0) {
+    return;
+  }
+  for (const state of states.values()) {
+    state.marks = null;
+    const ledger = state.derived.get(relation);
+    if (ledger !== void 0) {
+      for (const key of keys) {
+        ledger.delete(key);
+      }
+    }
+  }
+}
+var usesNegation = (rules) => rules.some((r) => r.body.some((l) => l.negated));
+function canResume(rules, state) {
+  return !usesNegation(rules) && state.marks !== null;
+}
+function factsSince(db, marks) {
+  const added = /* @__PURE__ */ new Map();
+  for (const name of db.relationNames()) {
+    const all = db.facts(name);
+    const mark = marks.get(name) ?? 0;
+    if (all.length > mark) {
+      added.set(name, all.slice(mark));
+    }
+  }
+  return added;
+}
+function currentMarks(db) {
+  const marks = /* @__PURE__ */ new Map();
+  for (const name of db.relationNames()) {
+    marks.set(name, db.size(name));
+  }
+  return marks;
+}
+function evaluate(db, rules) {
+  deriving.set(db, (deriving.get(db) ?? 0) + 1);
+  try {
+    return runRules(db, rules);
+  } finally {
+    const depth = (deriving.get(db) ?? 1) - 1;
+    if (depth === 0) {
+      deriving.delete(db);
+    } else {
+      deriving.set(db, depth);
+    }
+  }
+}
+function runRules(db, rules) {
+  const signature = JSON.stringify(rules);
+  const states = statesFor(db);
+  const state = states.get(signature) ?? {
+    marks: null,
+    derived: /* @__PURE__ */ new Map()
+  };
+  states.set(signature, state);
+  if (usesNegation(rules)) {
+    for (const [relation, ledger] of state.derived) {
+      db.retract(relation, ledger.values());
+    }
+    state.derived.clear();
+  }
+  const derived = state.derived;
+  const marks = canResume(rules, state) ? state.marks : void 0;
+  for (const stratum of stratify(rules)) {
+    let delta = /* @__PURE__ */ new Map();
+    const derivedHere = new Set(stratum.map((r) => r.head.relation));
+    const record = (relation, tuple) => {
+      if (db.add(relation, tuple)) {
+        addTo(delta, relation, tuple);
+        let ledger = derived.get(relation);
+        if (ledger === void 0) {
+          ledger = /* @__PURE__ */ new Map();
+          derived.set(relation, ledger);
+        }
+        ledger.set(keyOf(tuple), tuple);
+      }
+    };
+    const applyDelta = (seed, derivedOnly) => {
+      for (const r of stratum) {
+        const positives = r.body.filter((l) => !l.negated);
+        for (let i = 0; i < positives.length; i++) {
+          const literal = positives[i];
+          if (derivedOnly && !derivedHere.has(literal.relation)) {
+            continue;
+          }
+          if ((seed.get(literal.relation) ?? []).length === 0) {
+            continue;
+          }
+          for (const tuple of evaluateRule(db, seed, r, i)) {
+            record(r.head.relation, tuple);
+          }
+        }
+      }
+    };
+    if (marks === void 0 || marks === null) {
+      for (const r of stratum) {
+        const all = /* @__PURE__ */ new Map();
+        for (const l of r.body) {
+          if (!l.negated) {
+            all.set(l.relation, db.facts(l.relation));
+          }
+        }
+        for (const tuple of evaluateRule(db, all, r, -1)) {
+          record(r.head.relation, tuple);
+        }
+      }
+    } else {
+      applyDelta(factsSince(db, marks), false);
+    }
+    while (delta.size > 0) {
+      const lastDelta = delta;
+      delta = /* @__PURE__ */ new Map();
+      applyDelta(lastDelta, true);
+    }
+  }
+  state.marks = currentMarks(db);
+  return db;
+}
+function addTo(buckets, relation, tuple) {
+  const bucket = buckets.get(relation);
+  if (bucket === void 0) {
+    buckets.set(relation, [tuple]);
+  } else {
+    bucket.push(tuple);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Database,
+  constant,
+  evaluate,
+  lit,
+  notLit,
+  rule,
+  stratify,
+  variable
+});

package/dist/index.d.cts

@@ -0,0 +1,80 @@
+/** Tuple values. Callers intern richer identities (AST nodes, summaries) to atoms. */
+type Atom = string | number;
+type Tuple = readonly Atom[];
+/** A term in a rule literal: a variable to bind or a constant to match. */
+type Term = {
+    type: "variable";
+    name: string;
+} | {
+    type: "constant";
+    value: Atom;
+};
+/** Shorthand constructors — rules stay readable without a parser. */
+declare const variable: (name: string) => Term;
+declare const constant: (value: Atom) => Term;
+interface Literal {
+    relation: string;
+    terms: Term[];
+    /**
+     * Negation-as-failure. A negated literal matches when no fact in the
+     * (fully evaluated, lower-stratum) relation unifies with it. Every
+     * variable in a negated literal must be bound by a positive literal
+     * earlier in the body.
+     */
+    negated: boolean;
+}
+declare const lit: (relation: string, ...terms: Term[]) => Literal;
+declare const notLit: (relation: string, ...terms: Term[]) => Literal;
+interface Rule {
+    head: {
+        relation: string;
+        terms: Term[];
+    };
+    body: Literal[];
+}
+declare const rule: (relation: string, terms: Term[], body: Literal[]) => Rule;
+/** 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;
+    has(relationName: string, tuple: Tuple): boolean;
+    facts(relationName: string): readonly Tuple[];
+    /**
+     * The facts holding `value` at `column`. A join reaches for this
+     * instead of scanning the whole relation once one of its terms is
+     * already bound.
+     *
+     * A column is indexed the first time somebody asks for it and stays
+     * up to date after that, so a relation nobody joins on this way
+     * carries no index at all.
+     */
+    lookup(relationName: string, column: number, value: Atom): readonly Tuple[];
+    /**
+     * Remove facts from a relation. Returns how many were actually there.
+     *
+     * Evaluation uses this to take back what it derived last time when a
+     * rule set uses negation, where a new fact can invalidate an old
+     * conclusion. Callers rarely need it.
+     */
+    retract(relationName: string, tuples: Iterable<Tuple>): number;
+    size(relationName: string): number;
+    relationNames(): string[];
+}
+/**
+ * Assign each derived relation a stratum such that positive
+ * dependencies never decrease the stratum and negative dependencies
+ * strictly increase it. Iterates to fixpoint; a stratum exceeding the
+ * relation count means a negation cycle — not stratifiable, hard error.
+ */
+declare function stratify(rules: Rule[]): Rule[][];
+/**
+ * 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.
+ */
+declare function evaluate(db: Database, rules: Rule[]): Database;
+
+export { type Atom, Database, type Literal, type Rule, type Term, type Tuple, constant, evaluate, lit, notLit, rule, stratify, variable };

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/** Tuple values. Callers intern richer identities (AST nodes, summaries) to atoms. */
+type Atom = string | number;
+type Tuple = readonly Atom[];
+/** A term in a rule literal: a variable to bind or a constant to match. */
+type Term = {
+    type: "variable";
+    name: string;
+} | {
+    type: "constant";
+    value: Atom;
+};
+/** Shorthand constructors — rules stay readable without a parser. */
+declare const variable: (name: string) => Term;
+declare const constant: (value: Atom) => Term;
+interface Literal {
+    relation: string;
+    terms: Term[];
+    /**
+     * Negation-as-failure. A negated literal matches when no fact in the
+     * (fully evaluated, lower-stratum) relation unifies with it. Every
+     * variable in a negated literal must be bound by a positive literal
+     * earlier in the body.
+     */
+    negated: boolean;
+}
+declare const lit: (relation: string, ...terms: Term[]) => Literal;
+declare const notLit: (relation: string, ...terms: Term[]) => Literal;
+interface Rule {
+    head: {
+        relation: string;
+        terms: Term[];
+    };
+    body: Literal[];
+}
+declare const rule: (relation: string, terms: Term[], body: Literal[]) => Rule;
+/** 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;
+    has(relationName: string, tuple: Tuple): boolean;
+    facts(relationName: string): readonly Tuple[];
+    /**
+     * The facts holding `value` at `column`. A join reaches for this
+     * instead of scanning the whole relation once one of its terms is
+     * already bound.
+     *
+     * A column is indexed the first time somebody asks for it and stays
+     * up to date after that, so a relation nobody joins on this way
+     * carries no index at all.
+     */
+    lookup(relationName: string, column: number, value: Atom): readonly Tuple[];
+    /**
+     * Remove facts from a relation. Returns how many were actually there.
+     *
+     * Evaluation uses this to take back what it derived last time when a
+     * rule set uses negation, where a new fact can invalidate an old
+     * conclusion. Callers rarely need it.
+     */
+    retract(relationName: string, tuples: Iterable<Tuple>): number;
+    size(relationName: string): number;
+    relationNames(): string[];
+}
+/**
+ * Assign each derived relation a stratum such that positive
+ * dependencies never decrease the stratum and negative dependencies
+ * strictly increase it. Iterates to fixpoint; a stratum exceeding the
+ * relation count means a negation cycle — not stratifiable, hard error.
+ */
+declare function stratify(rules: Rule[]): Rule[][];
+/**
+ * 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.
+ */
+declare function evaluate(db: Database, rules: Rule[]): Database;
+
+export { type Atom, Database, type Literal, type Rule, type Term, type Tuple, constant, evaluate, lit, notLit, rule, stratify, variable };

package/dist/index.js

@@ -0,0 +1,418 @@
+// src/index.ts
+var variable = (name) => ({ type: "variable", name });
+var constant = (value) => ({ type: "constant", value });
+var lit = (relation, ...terms) => ({
+  relation,
+  terms,
+  negated: false
+});
+var notLit = (relation, ...terms) => ({
+  relation,
+  terms,
+  negated: true
+});
+var rule = (relation, terms, body) => ({ head: { relation, terms }, body });
+var SEP = "\0";
+var atomKey = (a) => `${typeof a === "number" ? "n" : "s"}${a}`;
+var keyOf = (tuple) => tuple.map(atomKey).join(SEP);
+function addToBucket(index, key, tuple) {
+  const bucket = index.get(key);
+  if (bucket === void 0) {
+    index.set(key, [tuple]);
+  } else {
+    bucket.push(tuple);
+  }
+}
+var Database = class {
+  store = /* @__PURE__ */ new Map();
+  relation(name) {
+    const existing = this.store.get(name);
+    if (existing !== void 0) {
+      return existing;
+    }
+    const created = {
+      keys: /* @__PURE__ */ new Set(),
+      tuples: [],
+      indexes: /* @__PURE__ */ new Map()
+    };
+    this.store.set(name, created);
+    return created;
+  }
+  /** Add a fact; returns true when the tuple is new. */
+  add(relationName, tuple) {
+    const relation = this.relation(relationName);
+    const key = keyOf(tuple);
+    if (relation.keys.has(key)) {
+      if (!isDeriving(this)) {
+        claimFact(this, relationName, key);
+      }
+      return false;
+    }
+    relation.keys.add(key);
+    relation.tuples.push(tuple);
+    for (const [column, index] of relation.indexes) {
+      const value = tuple[column];
+      if (value !== void 0) {
+        addToBucket(index, atomKey(value), tuple);
+      }
+    }
+    return true;
+  }
+  has(relationName, tuple) {
+    return this.store.get(relationName)?.keys.has(keyOf(tuple)) ?? false;
+  }
+  facts(relationName) {
+    return this.store.get(relationName)?.tuples ?? [];
+  }
+  /**
+   * The facts holding `value` at `column`. A join reaches for this
+   * instead of scanning the whole relation once one of its terms is
+   * already bound.
+   *
+   * A column is indexed the first time somebody asks for it and stays
+   * up to date after that, so a relation nobody joins on this way
+   * carries no index at all.
+   */
+  lookup(relationName, column, value) {
+    const relation = this.store.get(relationName);
+    if (relation === void 0) {
+      return [];
+    }
+    let index = relation.indexes.get(column);
+    if (index === void 0) {
+      index = /* @__PURE__ */ new Map();
+      for (const tuple of relation.tuples) {
+        const at = tuple[column];
+        if (at !== void 0) {
+          addToBucket(index, atomKey(at), tuple);
+        }
+      }
+      relation.indexes.set(column, index);
+    }
+    return index.get(atomKey(value)) ?? [];
+  }
+  /**
+   * Remove facts from a relation. Returns how many were actually there.
+   *
+   * Evaluation uses this to take back what it derived last time when a
+   * rule set uses negation, where a new fact can invalidate an old
+   * conclusion. Callers rarely need it.
+   */
+  retract(relationName, tuples) {
+    const relation = this.store.get(relationName);
+    if (relation === void 0) {
+      return 0;
+    }
+    const going = /* @__PURE__ */ new Set();
+    for (const tuple of tuples) {
+      const key = keyOf(tuple);
+      if (relation.keys.has(key)) {
+        going.add(key);
+      }
+    }
+    if (going.size === 0) {
+      return 0;
+    }
+    for (const key of going) {
+      relation.keys.delete(key);
+    }
+    relation.tuples = relation.tuples.filter(
+      (tuple) => !going.has(keyOf(tuple))
+    );
+    relation.indexes.clear();
+    forgetFacts(this, relationName, going);
+    return going.size;
+  }
+  size(relationName) {
+    return this.store.get(relationName)?.tuples.length ?? 0;
+  }
+  relationNames() {
+    return [...this.store.keys()];
+  }
+};
+function stratify(rules) {
+  const derived = new Set(rules.map((r) => r.head.relation));
+  const stratum = /* @__PURE__ */ new Map();
+  for (const name of derived) {
+    stratum.set(name, 0);
+  }
+  const bound = derived.size + 1;
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const r of rules) {
+      const head = r.head.relation;
+      for (const body of r.body) {
+        if (!derived.has(body.relation)) {
+          continue;
+        }
+        const required = (stratum.get(body.relation) ?? 0) + (body.negated ? 1 : 0);
+        if ((stratum.get(head) ?? 0) < required) {
+          if (required > bound) {
+            throw new Error(
+              `rules are not stratifiable: negation cycle through "${head}"`
+            );
+          }
+          stratum.set(head, required);
+          changed = true;
+        }
+      }
+    }
+  }
+  const maxStratum = Math.max(0, ...stratum.values());
+  const strata = Array.from({ length: maxStratum + 1 }, () => []);
+  for (const r of rules) {
+    strata[stratum.get(r.head.relation) ?? 0].push(r);
+  }
+  return strata.filter((s) => s.length > 0);
+}
+function unify(literal, tuple, bindings) {
+  if (literal.terms.length !== tuple.length) {
+    return null;
+  }
+  let next = null;
+  for (let i = 0; i < literal.terms.length; i++) {
+    const term = literal.terms[i];
+    const value = tuple[i];
+    if (term.type === "constant") {
+      if (term.value !== value) {
+        return null;
+      }
+      continue;
+    }
+    const bound = (next ?? bindings).get(term.name);
+    if (bound === void 0) {
+      next = next ?? new Map(bindings);
+      next.set(term.name, value);
+      continue;
+    }
+    if (bound !== value) {
+      return null;
+    }
+  }
+  return next ?? bindings;
+}
+function groundNegated(literal, bindings) {
+  return literal.terms.map((term) => {
+    if (term.type === "constant") {
+      return term.value;
+    }
+    const bound = bindings.get(term.name);
+    if (bound === void 0) {
+      throw new Error(
+        `unbound variable "${term.name}" in negated literal "${literal.relation}" \u2014 negated literals may only use variables bound by earlier positive literals`
+      );
+    }
+    return bound;
+  });
+}
+function headTuple(head, bindings) {
+  return head.terms.map((term) => {
+    if (term.type === "constant") {
+      return term.value;
+    }
+    const bound = bindings.get(term.name);
+    if (bound === void 0) {
+      throw new Error(
+        `unbound variable "${term.name}" in head of "${head.relation}"`
+      );
+    }
+    return bound;
+  });
+}
+function evaluateRule(db, deltas, r, deltaIndex) {
+  const results = [];
+  const step = (literalIndex, positiveIndex, bindings) => {
+    if (literalIndex === r.body.length) {
+      results.push(headTuple(r.head, bindings));
+      return;
+    }
+    const literal = r.body[literalIndex];
+    if (literal.negated) {
+      if (!db.has(literal.relation, groundNegated(literal, bindings))) {
+        step(literalIndex + 1, positiveIndex, bindings);
+      }
+      return;
+    }
+    const source = positiveIndex === deltaIndex ? deltas.get(literal.relation) ?? [] : boundSource(db, literal, bindings);
+    for (const tuple of source) {
+      const next = unify(literal, tuple, bindings);
+      if (next !== null) {
+        step(literalIndex + 1, positiveIndex + 1, next);
+      }
+    }
+  };
+  step(0, 0, /* @__PURE__ */ new Map());
+  return results;
+}
+function boundSource(db, literal, bindings) {
+  for (let column = 0; column < literal.terms.length; column++) {
+    const term = literal.terms[column];
+    const value = term.type === "constant" ? term.value : bindings.get(term.name);
+    if (value !== void 0) {
+      return db.lookup(literal.relation, column, value);
+    }
+  }
+  return db.facts(literal.relation);
+}
+var evaluated = /* @__PURE__ */ new WeakMap();
+var deriving = /* @__PURE__ */ new Map();
+function isDeriving(db) {
+  return (deriving.get(db) ?? 0) > 0;
+}
+function statesFor(db) {
+  let states = evaluated.get(db);
+  if (states === void 0) {
+    states = /* @__PURE__ */ new Map();
+    evaluated.set(db, states);
+  }
+  return states;
+}
+function claimFact(db, relation, key) {
+  const states = evaluated.get(db);
+  if (states === void 0) {
+    return;
+  }
+  for (const state of states.values()) {
+    state.derived.get(relation)?.delete(key);
+  }
+}
+function forgetFacts(db, relation, keys) {
+  const states = evaluated.get(db);
+  if (states === void 0) {
+    return;
+  }
+  for (const state of states.values()) {
+    state.marks = null;
+    const ledger = state.derived.get(relation);
+    if (ledger !== void 0) {
+      for (const key of keys) {
+        ledger.delete(key);
+      }
+    }
+  }
+}
+var usesNegation = (rules) => rules.some((r) => r.body.some((l) => l.negated));
+function canResume(rules, state) {
+  return !usesNegation(rules) && state.marks !== null;
+}
+function factsSince(db, marks) {
+  const added = /* @__PURE__ */ new Map();
+  for (const name of db.relationNames()) {
+    const all = db.facts(name);
+    const mark = marks.get(name) ?? 0;
+    if (all.length > mark) {
+      added.set(name, all.slice(mark));
+    }
+  }
+  return added;
+}
+function currentMarks(db) {
+  const marks = /* @__PURE__ */ new Map();
+  for (const name of db.relationNames()) {
+    marks.set(name, db.size(name));
+  }
+  return marks;
+}
+function evaluate(db, rules) {
+  deriving.set(db, (deriving.get(db) ?? 0) + 1);
+  try {
+    return runRules(db, rules);
+  } finally {
+    const depth = (deriving.get(db) ?? 1) - 1;
+    if (depth === 0) {
+      deriving.delete(db);
+    } else {
+      deriving.set(db, depth);
+    }
+  }
+}
+function runRules(db, rules) {
+  const signature = JSON.stringify(rules);
+  const states = statesFor(db);
+  const state = states.get(signature) ?? {
+    marks: null,
+    derived: /* @__PURE__ */ new Map()
+  };
+  states.set(signature, state);
+  if (usesNegation(rules)) {
+    for (const [relation, ledger] of state.derived) {
+      db.retract(relation, ledger.values());
+    }
+    state.derived.clear();
+  }
+  const derived = state.derived;
+  const marks = canResume(rules, state) ? state.marks : void 0;
+  for (const stratum of stratify(rules)) {
+    let delta = /* @__PURE__ */ new Map();
+    const derivedHere = new Set(stratum.map((r) => r.head.relation));
+    const record = (relation, tuple) => {
+      if (db.add(relation, tuple)) {
+        addTo(delta, relation, tuple);
+        let ledger = derived.get(relation);
+        if (ledger === void 0) {
+          ledger = /* @__PURE__ */ new Map();
+          derived.set(relation, ledger);
+        }
+        ledger.set(keyOf(tuple), tuple);
+      }
+    };
+    const applyDelta = (seed, derivedOnly) => {
+      for (const r of stratum) {
+        const positives = r.body.filter((l) => !l.negated);
+        for (let i = 0; i < positives.length; i++) {
+          const literal = positives[i];
+          if (derivedOnly && !derivedHere.has(literal.relation)) {
+            continue;
+          }
+          if ((seed.get(literal.relation) ?? []).length === 0) {
+            continue;
+          }
+          for (const tuple of evaluateRule(db, seed, r, i)) {
+            record(r.head.relation, tuple);
+          }
+        }
+      }
+    };
+    if (marks === void 0 || marks === null) {
+      for (const r of stratum) {
+        const all = /* @__PURE__ */ new Map();
+        for (const l of r.body) {
+          if (!l.negated) {
+            all.set(l.relation, db.facts(l.relation));
+          }
+        }
+        for (const tuple of evaluateRule(db, all, r, -1)) {
+          record(r.head.relation, tuple);
+        }
+      }
+    } else {
+      applyDelta(factsSince(db, marks), false);
+    }
+    while (delta.size > 0) {
+      const lastDelta = delta;
+      delta = /* @__PURE__ */ new Map();
+      applyDelta(lastDelta, true);
+    }
+  }
+  state.marks = currentMarks(db);
+  return db;
+}
+function addTo(buckets, relation, tuple) {
+  const bucket = buckets.get(relation);
+  if (bucket === void 0) {
+    buckets.set(relation, [tuple]);
+  } else {
+    bucket.push(tuple);
+  }
+}
+export {
+  Database,
+  constant,
+  evaluate,
+  lit,
+  notLit,
+  rule,
+  stratify,
+  variable
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@suss/datalog",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A small semi-naïve Datalog evaluator with stratified negation — the rules engine behind suss's derived program facts.",
+  "keywords": [
+    "suss",
+    "datalog",
+    "fixpoint",
+    "static-analysis"
+  ],
+  "license": "Apache-2.0",
+  "author": "Nimbus Cloud AI LLC",
+  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/datalog#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nimbuscloud-ai/suss.git",
+    "directory": "packages/datalog"
+  },
+  "bugs": {
+    "url": "https://github.com/nimbuscloud-ai/suss/issues"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "fast-check": "^3.23.1",
+    "tsup": "*",
+    "typescript": "*",
+    "vitest": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}