diff --git a/docs/project-overview.md b/docs/project-overview.md new file mode 100644 index 0000000..6dee7a4 --- /dev/null +++ b/docs/project-overview.md @@ -0,0 +1,82 @@ +## About the Project + +Chase-rs is a Rust implementation of the chase algorithm for reasoning over rules and facts. +It is designed for database-theory style workloads such as: + +- query answering under tuple-generating dependencies +- materializing implied facts from rules +- working with existential rules that create fresh labeled nulls + +The project focuses on correctness first, while still keeping the codebase small, fast, and idiomatic. + +## Main Features + +- Core chase engine for deriving implied facts from rules and an initial instance +- Restricted-chase style active-trigger checks for existential rules +- Automatic generation of labeled nulls for existential variables +- Fluent `RuleBuilder` API for constructing rules in Rust +- Configurable step limit through `chase_with_config` +- Interactive frontend options: + - REPL + - script runner + - local GUI +- Querying and explanation support in the frontend session layer +- Example scripts and Geolog examples for transitive closure, existential rules, and joins + +--- + +## Quickstart + +### 1. Run the example script + +```bash +cargo run -- script examples/scripts/ancestor.chase +``` + +This loads a few `Parent` facts, applies ancestor rules, runs the chase, and prints the derived answers. + +### 2. Open the REPL + +```bash +cargo run -- repl +``` + +In the REPL you can add facts, add rules, run the chase, query results, and ask for explanations. + +### 3. Open the GUI + +```bash +cargo run -- gui +``` + +This starts a local web UI at [http://127.0.0.1:7878](http://127.0.0.1:7878) where you can type the same commands as in the REPL. + +--- + +### Glossary of Important Terms + +- **Atom**: A predicate applied to one or more terms, for example `Parent(alice, bob)`. +- **Fact**: A ground atom, meaning an atom with no variables. Facts are the input database state. +- **Instance**: The set of facts currently known to the chase engine. +- **Rule / TGD**: A tuple-generating dependency of the form `body -> head` that derives new facts when its body matches. +- **Chase**: The process of repeatedly applying rules until no new facts can be derived or a configured step limit is reached. +- **Materialization**: The fully derived instance produced by running the chase. +- **Existential Rule**: A rule whose head contains variables that do not appear in the body. These variables represent values that must be invented. +- **Labeled Null**: A fresh invented value used to satisfy an existential variable during the chase. +- **Restricted Chase**: The chase variant used by default in this project. It avoids redundant applications by checking whether a trigger is still + active. +- **Trigger**: A particular match of a rule body against the current instance. +- **Active Trigger**: A trigger that still requires the rule to fire because its head is not already satisfied. +- **Query**: A conjunctive pattern used to ask for matching facts after, or sometimes before, materialization. +- **Explanation**: A derivation trace that shows why a query answer is present. +- **Termination**: Whether the chase finished normally or stopped because it reached the configured step bound. + +### Example Terms + +- `Parent`, `Ancestor`, and `WorksIn` are example predicates used in the scripts. +- `?X`, `?Y`, and `?Dept` are variables in the frontend command language. +- `alice`, `bob`, and `carol` are constants. + +### Changelog + +* **April 8, 2026** -- The first version of this document was written.