geolog-zeta-fork/README2.md

Geolog Development Notes

This document describes the features and components added to the geolog project (by me, Hassan).

Overview

Geolog is a language for geometric logic - a type theory with semantics in topoi and geometric morphisms, designed as a unified language for database schemas, queries, and migrations.

Components

Core Components (Pre-existing)

• Parser & Lexer (src/lexer.rs, src/parser.rs) - Chumsky-based parser for geolog syntax
• AST (src/ast.rs) - Abstract syntax tree representation
• Core Types (src/core.rs) - Signatures, structures, theories, axioms
• Elaboration (src/elaborate.rs) - Type checking and elaboration
• Store (src/store.rs) - Append-only persistent storage with version control
• REPL (src/repl.rs) - Interactive command-line environment
• Solver (src/solver.rs) - Model enumeration for geometric theories
• Query Engine (src/query/) - Relational algebra backend for queries
• Chase Algorithm (src/query/chase.rs) - Fixpoint computation for axiom closure

Debugger (src/debugger.rs)

Interactive debugger for the chase algorithm providing:

• Step-through execution
• Breakpoints on axiom name patterns
• Variable inspection
• Iteration stepping

Usage in REPL:

:debug-chase <instance> [max_iterations]

GUI Application (src/gui/)

A full-featured graphical interface built with egui.

Current design note:

• The GUI uses a rigid docked layout rather than draggable in-window splitters.
• This was done to reduce hover/drag-induced layout jitter and keep the workspace visually stable.

Building the GUI

# Build with GUI feature
cargo build --features gui

# Run the GUI
cargo run --features gui --bin geolog-gui

# With workspace persistence
cargo run --features gui --bin geolog-gui -- -d ./myproject

# Load a file on startup
cargo run --features gui --bin geolog-gui -- examples/preorder.geolog

GUI Architecture

src/gui/
├── mod.rs                    # Module exports
├── app.rs                    # Main GeologApp (egui::App implementation)
├── state.rs                  # GuiState wrapping ReplState
├── panels/
│   ├── mod.rs
│   ├── browser.rs            # Theory/instance tree browser
│   ├── editor.rs             # Code editor with line numbers
│   ├── inspector.rs          # Detail view for selected items
│   └── console.rs            # Output/error messages
└── visualizations/
    ├── mod.rs
    ├── chase.rs              # Chase step-through visualization
    └── graph.rs              # Relation graph visualization

GUI Features

Browser Panel (Left)

• Tree view of all theories and instances
• Filter/search functionality
• Click to select, right-click for context menu
• Shows counts (sorts, functions, relations, axioms, elements)
• Fixed-width docked sidebar

Editor Panel (Center)

• Multi-line code editor
• Run button (or Ctrl+Enter) to execute code
• Clear button

Inspector Panel (Right)

• Theory details: parameters, sorts, functions, relations, instance fields, axioms
• Instance details: elements by sort, function values, relation tuples, nested instances
• Collapsible sections
• "View Graph" button for instances
• Fixed-width docked sidebar in the main workspace view

Console Panel (Bottom)

• Scrollable message log
• Color-coded messages: info (gray), success (green), error (red), warning (orange)
• Auto-scroll option
• Clear button
• Integrated REPL input with command history (Up/Down arrows)
  • Type :help for commands
  • Type :list to list theories/instances
  • Type :inspect <name> to inspect
  • Type :chase <instance> to run chase
  • Or type geolog code directly
• Fixed-height docked footer

Layout

• Docked workspace layout for stability
• Browser on the left, editor in the center, inspector on the right
• Console fixed at the bottom
• Chase and graph visualizations replace the central workspace when active

Chase Visualization

• Step/Run All/Stop controls
• Events log showing axiom firings with bindings
• Breakpoint management
• Current structure info (elements, relation tuples)
• Mode indicator (Idle/Stepping/Running/Completed)

Graph Visualization

• Nodes represent elements (colored by sort)
• Edges represent relation tuples
• Interactive: drag nodes, zoom (scroll), pan
• Relation filter dropdown
• Reset Layout / Fit buttons
• Hover to see sort name

UI Layout

┌─────────────────────────────────────────────────────────────┐
│  File   Edit   View   Chase   Help                          │
├──────────────┬──────────────────────────────┬───────────────┤
│ Browser      │ Editor                       │ Inspector     │
│ ▼ Theories   │ theory Foo {                 │ Chain3        │
│   Preorder   │   X : Sort;                  │ : Preorder    │
│ ▼ Instances  │ }           [Run] [Clear]    │ ▼ Elements    │
│   Chain3     │                              │ ▼ Relations   │
│              │                              │ [View Graph]  │
├──────────────┴──────────────────────────────┴───────────────┤
│ Console                                              [Clear]│
│ > Defined theory Preorder (1 sorts, 1 relations, 2 axioms)  │
│ + Defined instance Chain3 : Preorder (3 elements)          │
│─────────────────────────────────────────────────────────────│
│ geolog> :list                                         [Run] │
└─────────────────────────────────────────────────────────────┘

CLI Commands

REPL Commands

:help [topic]              Show help (topics: syntax, examples)
:quit                      Exit the REPL
:list [target]             List theories/instances
:inspect <name>            Show details of a theory or instance
:source <file>             Load and execute a geolog file
:clear                     Clear the screen
:reset                     Reset all state

# Version Control
:commit [msg]              Commit current changes
:history                   Show commit history

# Instance Mutation
:add <inst> <elem> <sort>  Add element to instance
:assert <inst> <rel> args  Assert relation tuple
:retract <inst> <elem>     Retract element

# Query
:query <inst> <sort>       List all elements of a sort
:explain <inst> <sort>     Show query execution plan
:compile <inst> <sort>     Show RelAlgIR compilation
:chase <inst> [max_iter]   Run chase on instance axioms
:debug-chase <inst> [max]  Run chase with interactive debugger

# Solver
:solve <theory> [budget]   Find model of theory from scratch
:extend <inst> <theory>    Find extension of instance to theory

CLI Usage

# Start REPL (in-memory)
cargo run

# Start REPL with workspace persistence
cargo run -- -d ./myproject

# Load file on startup
cargo run -- examples/preorder.geolog

# Show help
cargo run -- --help

Dependencies

Core Dependencies

• chumsky - Parser combinators
• ariadne - Error reporting
• uuid - Unique identifiers
• rkyv - Zero-copy serialization
• rustyline - Readline for REPL
• indexmap - Ordered hash maps

GUI Dependencies (feature = "gui")

• eframe - egui framework with native window
• egui_extras - Additional egui widgets
• rfd - Native file dialogs

Example

// Define a preorder theory
theory Preorder {
  X : Sort;

  // The ordering relation: x <= y
  leq : [x: X, y: X] -> Prop;

  // Reflexivity: x <= x
  ax/refl : forall x : X.
    |- [x: x, y: x] leq;

  // Transitivity: x <= y and y <= z implies x <= z
  ax/trans : forall x : X, y : X, z : X.
    [x: x, y: y] leq, [x: y, y: z] leq |- [x: x, y: z] leq;
}

// Define an instance with automatic chase
// The 'chase' keyword applies axioms to compute the closure
instance Chain3 : Preorder = chase {
  bot : X;
  mid : X;
  top : X;

  // Assert the basic ordering; chase derives reflexive pairs
  // and transitive closure (bot <= top)
  [x: bot, y: mid] leq;
  [x: mid, y: top] leq;
}

After loading this file, the chase algorithm automatically computes:

• Reflexive pairs: bot <= bot, mid <= mid, top <= top
• Transitive closure: bot <= top

You can also define an instance without chase and run :chase Chain3 manually.

Development

# Check without GUI
cargo check

# Check with GUI
cargo check --features gui

# Run tests
cargo test

# Build release
cargo build --release --features gui

Reviewing And Contributing

• See AGENTS.md for repository-specific coding guidance.
• See REVIEWING.md for a reviewer-oriented map of the codebase and recommended commands.
• If you have just installed, run just --list for common review and validation commands.