@suss/datalog 0.33.1 → 0.34.0

package/README.md

@@ -2,17 +2,17 @@
 
 Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides of every call in a repository and says where the two disagree.
 
-A small semi-naïve Datalog evaluator with stratified negation. This is
-the rules engine behind suss's derived program facts.
+A small semi-naïve Datalog evaluator with stratified negation. suss
+derives its program facts with it.
 
 ## Why suss ships a Datalog engine
 
-Extraction keeps running into 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 everything the `try`
-block throws, transitively), how a wrapper of a wrapper resolves to its
-underlying route. Write each of those as rules over base facts and it
-comes to a few lines you can check by reading them:
+Extraction keeps running into problems that are *fixpoints*. One is
+which functions are reachable from an entry point. Another is what a
+bare `throw err` re-throw can raise, which is the union of everything
+the `try` block throws, transitively. A third is how a wrapper of a
+wrapper resolves to its underlying route. Written as rules over base facts,
+each one comes to a few lines you can check by reading them:
 
 ```ts
 import { Database, evaluate, lit, rule, variable as v } from "@suss/datalog";
@@ -34,16 +34,16 @@ evaluate(db, [
 db.facts("reachable"); // [["main"], ["helper"], ["util"]]
 ```
 
-Termination and soundness are the engine's job, and we prove them once.
-Negation (`notLit`) is *stratified*: a rule set with a negation cycle is
-a hard error at evaluation time, and that is what lets you check a rule
-on its own without thinking about the engine.
+The engine guarantees termination and soundness, and those are proved
+once, for the engine. Negation (`notLit`) is *stratified*: a rule set
+with a negation cycle is a hard error at evaluation time. Because of
+that, you can check a rule on its own without thinking about the engine.
 
-Because rules are plain data, with no DSL strings and no embedded code,
-the same rule set can later run on a faster external engine. Over the
-longer term, an analysis written against a set of facts (`calls`,
-`throws`, `handles`, and so on) does not depend on the language: a
-second language adapter only has to emit the same facts.
+Rules are plain data, without DSL strings or embedded code, so the same
+rule set can later run on a faster external engine. An analysis written
+against a set of facts (`calls`, `throws`, `handles`, and so on) does
+not depend on the language. A second language adapter only has to emit
+the same facts.
 
 ## More