geolog-zeta-fork/notes/001-architecture.md

Architecture

Tech Stack

Language: Rust (2021 edition)

Key Dependencies

Crate	Purpose
chumsky	Parser combinator library
ariadne	Error reporting with source spans
rkyv	Zero-copy serialization
rustyline	REPL readline interface
egglog-union-find	Union-find for congruence closure
roaring	Bitmap library for sparse relations
indexmap	Order-preserving hash maps
memmap2	Memory-mapped file I/O

Testing

• insta — snapshot testing
• proptest — property-based testing
• tempfile — temporary directory management

---

System Layers

┌─────────────────────────────────────────────────────┐
│                    USER INTERFACE                    │
│  REPL (interactive CLI) | Batch file loading         │
├─────────────────────────────────────────────────────┤
│         PARSING LAYER (Lexer → Parser → AST)         │
├─────────────────────────────────────────────────────┤
│           ELABORATION LAYER (AST → Core IR)          │
│  Type checking, name resolution, theory/instance     │
├─────────────────────────────────────────────────────┤
│            CORE LAYER (Typed Representation)         │
│  Signature, Term, Formula, Structure                 │
├─────────────────────────────────────────────────────┤
│              STORAGE LAYER (Persistence)             │
│  Append-only store with version control              │
├─────────────────────────────────────────────────────┤
│            QUERY & SOLVER LAYER (Execution)          │
│  Chase algorithm, congruence closure, model search   │
├─────────────────────────────────────────────────────┤
│         TENSOR ALGEBRA (Axiom Checking)              │
│  Sparse tensor evaluation for axiom validation       │
└─────────────────────────────────────────────────────┘

---

Directory Structure

Path	Purpose
src/bin/geolog.rs	CLI entry point
src/lib.rs	Library root
src/repl.rs	Interactive REPL state machine
src/lexer.rs	Tokenization
src/parser.rs	Token stream → AST
src/ast.rs	Abstract syntax tree types
src/core.rs	Core IR: Signature, Term, Formula, Structure
src/elaborate/	AST → Core elaboration
src/store/	Persistence layer
src/query/	Chase algorithm, relational algebra
src/solver/	SMT-style model enumeration
src/tensor/	Sparse tensor algebra
src/cc.rs	Congruence closure (union-find)
examples/geolog/	30+ example .geolog files
tests/	Test files
docs/	ARCHITECTURE.md, SYNTAX.md
proofs/	Lean4 formalization

---

Key Entry Points

Entry Point	Location
CLI	src/bin/geolog.rs
Parse	src/lib.rs::parse()
REPL	src/repl.rs::ReplState::process_line()
Theory elaboration	elaborate/theory.rs::elaborate_theory()
Instance elaboration	elaborate/instance.rs::elaborate_instance_ctx()
Chase	query/chase.rs::chase_fixpoint_with_cc()
Model enumeration	solver/mod.rs::enumerate_models()

---

REPL Commands

:list, :inspect <name>         - Introspection
:add, :assert, :retract        - Mutations
:query, :explain, :compile     - Query analysis
:chase, :solve, :extend        - Inference
:commit, :history              - Version control
:source <file>                 - Load programs
:help                          - Show help