geolog-zeta-fork/AGENTS.md

AGENTS.md

This file provides guidance to coding agents collaborating on this repository.

Mission

Geolog is a Rust codebase for geometric logic:

• a parser and pretty-printer for the Geolog language,
• an elaboration layer that turns syntax into core structures,
• a REPL and workspace/persistence layer,
• a chase/query/solver runtime,
• and an optional egui GUI behind the gui Cargo feature.

Priorities, in order:

1. Semantic correctness of theories, instances, queries, and chase behavior.
2. Clear boundaries between parsing, elaboration, core structures, REPL/workspace, and GUI code.
3. Focused, maintainable changes with good regression coverage.
4. Performance only after correctness and testability are preserved.

Core Rucargo run --features gui --bin geolog-guiles

• Use English for code, comments, docs, tests, and commit-facing text.
• Prefer small, targeted changes over broad rewrites.
• Fix root causes rather than layering on ad hoc workarounds.
• Keep modules decoupled: parsing in parser/lexer, semantics in core/elaborate, runtime behavior in repl/query/solver, presentation in gui.
• Do not introduce unnecessary global mutable state.
• Preserve feature gating: GUI code must remain behind the gui feature.
• Avoid adding dependencies unless clearly justified.
• Add comments only when they clarify non-obvious invariants, algorithms, or semantic constraints.

Quick examples:

• Good: add a targeted regression test for a chase bug in an existing GUI or unit test module.
• Good: fix a REPL/workspace bug in src/repl.rs or src/store/ without refactoring unrelated parser code.
• Bad: rewrite the AST/core boundary during a small GUI task.
• Bad: mix GUI presentation logic into core semantic modules.

Repository Layout

• src/lib.rs: crate entrypoint and module exports.
• src/ast.rs, src/lexer.rs, src/parser.rs, src/pretty.rs: syntax pipeline and round-tripping.
• src/core.rs: core semantic data structures such as signatures, theories, and structures.
• src/elaborate/: elaboration from AST into core representations.
• src/repl.rs: REPL state, command handling, and top-level execution flow.
• src/store/: persistence/workspace and storage-related logic.
• src/query/: chase, query compilation, optimization, backend execution.
• src/solver/: solver and tactic logic.
• src/tensor/: tensor-based checking/evaluation support.
• src/gui/: egui GUI state, panels, and visualizations.
• src/bin/geolog.rs: CLI/REPL binary.
• src/bin/geolog-gui.rs: GUI binary (requires --features gui).
• examples/geolog/: sample Geolog programs.
• tests/: integration, regression, unit-style cross-module, and property tests.
• docs/: architecture and syntax documentation.
• proofs/: Lean proofs and formal artifacts.
• fuzz/: fuzzing targets.

Architecture Constraints

• Keep the syntax pipeline clean: text → lexer → parser → AST.
• Keep elaboration separate from parsing and separate from UI code.
• core types should remain usable without the GUI.
• GUI code should orchestrate and present existing behavior, not reimplement semantic logic.
• Workspace/persistence behavior belongs in repl/store, not inside GUI widgets.
• Query/chase behavior changes must preserve observable semantics and existing tests.
• If a change affects persistence or serialization, consider compatibility with existing workspace behavior.

GUI Rules

• The GUI is optional and must compile cleanly only when the gui feature is enabled.
• Prefer fixing GUI bugs in src/gui/state.rs, src/gui/panels/, or src/gui/visualizations/ before touching core logic.
• Keep GUI state transitions explicit and centralized when possible.
• Avoid hard-coding theme assumptions; UI should remain readable in the intended visual style.
• File dialog, editor, browser, inspector, console, and visualization behavior should stay consistent with REPL/workspace state.

Testing Layout Rules

• Prefer unit tests near the code they exercise when there is already a local test module.
• Put broader cross-module coverage in tests/.
• Keep regression tests close to the bug they reproduce when that is the clearest fit.
• Do not add a new testing framework if existing cargo test, property tests, or fuzz targets are sufficient.
• If you move behavior across modules, move or rewrite the relevant tests with it.

Workflow

Before coding:

1. Identify whether the task is parser, elaboration, runtime, persistence, solver/query, or GUI work.
2. Read the touched module and nearby tests first.
3. Check whether the change should live in core/repl/store rather than the GUI.

Implement and validate:

1. Make the smallest change that solves the problem.
2. Add or update tests when behavior changes or a bug is fixed.
3. Run the narrowest relevant command while iterating.
4. Run broader validation once the change is stable.
5. Update docs if user-facing behavior or workflow changed.

Validation Commands

Use the narrowest relevant command first:

• General compile check: cargo check
• Full test suite: cargo test
• GUI compile check: cargo check --features gui --bin geolog-gui
• GUI-related tests: cargo test --features gui
• Single test/module during iteration: cargo test <name>

Formatting:

• Prefer formatting only touched Rust files when the repository is not already fully formatted.
• Avoid reformatting unrelated files as part of a focused bugfix.

Testing Expectations

• No semantic bugfix is complete without appropriate validation.
• Parser/elaboration changes should preserve round-trip and error-reporting behavior where relevant.
• Query/chase/solver changes need explicit coverage because regressions can be subtle.
• GUI bugfixes should get a focused test when practical, especially for state transitions or regressions.
• Keep tests deterministic and focused on observable behavior.

Documentation Expectations

• Update README.md when user workflow, CLI behavior, or GUI usage changes.
• Update docs/ARCHITECTURE.md or docs/SYNTAX.md when architectural or language behavior changes materially.
• If you find stale docs directly related to your change, fix them in the same patch.

Review Guidelines

Review output should be concise and focus on real defects.

• P0: broken build, broken tests, data loss, or incorrect core semantics.
• P1: likely semantic regression, unsafe state transition, missing validation on risky changes.

Use this review format:

1. Severity (P0/P1)
2. File:line
3. Issue
4. Why it matters
5. Minimal fix direction

Do not include style-only feedback or broad praise.