refactor: adopt workspace layout

.github/workflows/build.yml

@@ -5,10 +5,10 @@ on:
       - main
   pull_request:
     paths:
-      - rust/**
+      - crates/**
+      - Cargo.toml
+      - Cargo.lock
       - .github/workflows/build.yml
-      - rust/lance-graph/Cargo.toml
-      - rust/lance-graph/Cargo.lock
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
@@ -36,17 +36,17 @@ jobs:
           rustup default ${{ matrix.toolchain }}
       - uses: Swatinem/rust-cache@v2
         with:
-          workspaces: rust/lance-graph
+          workspaces: crates/lance-graph
           cache-targets: false
       - name: Install dependencies
         run: |
           sudo apt update
           sudo apt install -y protobuf-compiler
       - name: Build
-        run: cargo build --manifest-path rust/lance-graph/Cargo.toml
+        run: cargo build --manifest-path crates/lance-graph/Cargo.toml
       - name: Build tests
-        run: cargo test --manifest-path rust/lance-graph/Cargo.toml --no-run
+        run: cargo test --manifest-path crates/lance-graph/Cargo.toml --no-run
       - name: Run tests
-        run: cargo test --manifest-path rust/lance-graph/Cargo.toml
+        run: cargo test --manifest-path crates/lance-graph/Cargo.toml
       - name: Check benchmarks
-        run: cargo check --manifest-path rust/lance-graph/Cargo.toml --benches
+        run: cargo check --manifest-path crates/lance-graph/Cargo.toml --benches

.github/workflows/python-test.yml

@@ -6,7 +6,9 @@ on:
   pull_request:
     paths:
       - python/**
-      - rust/lance-graph/**
+      - crates/lance-graph/**
+      - Cargo.toml
+      - Cargo.lock
       - .github/workflows/python-test.yml
 
 concurrency:

.github/workflows/release.yml

@@ -120,7 +120,7 @@ jobs:
     - name: Update Cargo lock version (when version changes)
       if: inputs.release_type != 'current'
       run: |
-        cargo check --manifest-path rust/lance-graph/Cargo.toml
+        cargo check --manifest-path crates/lance-graph/Cargo.toml
         cargo check --manifest-path python/Cargo.toml
 
     - name: Create release commit (when version changes)

.github/workflows/rust-publish.yml

@@ -27,6 +27,7 @@ env:
 
 jobs:
   publish:
+    if: github.event_name != 'pull_request'
     runs-on: ubuntu-24.04
     timeout-minutes: 60
     steps:
@@ -50,5 +51,5 @@ jobs:
         with:
           registry-token: ${{ secrets.CARGO_REGISTRY_TOKEN }}
           args: "--all-features"
-          path: rust/lance-graph
+          path: crates/lance-graph
           dry-run: ${{ github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && github.event.inputs.mode == 'dry_run') }}

.github/workflows/rust-test.yml

@@ -5,10 +5,10 @@ on:
       - main
   pull_request:
     paths:
-      - rust/**
-      - .github/workflows/rust-test.yml
+      - crates/**
       - Cargo.toml
       - Cargo.lock
+      - .github/workflows/rust-test.yml
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
@@ -37,18 +37,18 @@ jobs:
           rustup default ${{ matrix.toolchain }}
       - uses: Swatinem/rust-cache@v2
         with:
-          workspaces: rust/lance-graph
+          workspaces: crates/lance-graph
           cache-targets: false
       - name: Install dependencies
         run: |
           sudo apt update
           sudo apt install -y protobuf-compiler
       - name: Build tests
-        run: cargo test --manifest-path rust/lance-graph/Cargo.toml --no-run
+        run: cargo test --manifest-path crates/lance-graph/Cargo.toml --no-run
       - name: Run unit tests
-        run: cargo test --manifest-path rust/lance-graph/Cargo.toml --lib
+        run: cargo test --manifest-path crates/lance-graph/Cargo.toml --lib
       - name: Run doc tests
-        run: cargo test --manifest-path rust/lance-graph/Cargo.toml --doc
+        run: cargo test --manifest-path crates/lance-graph/Cargo.toml --doc
 
   test-with-coverage:
     runs-on: ubuntu-24.04
@@ -61,7 +61,7 @@ jobs:
           rustup default stable
       - uses: Swatinem/rust-cache@v2
         with:
-          workspaces: rust/lance-graph
+          workspaces: crates/lance-graph
           cache-targets: false
       - name: Install dependencies
         run: |
@@ -71,7 +71,7 @@ jobs:
         uses: taiki-e/install-action@cargo-llvm-cov
       - name: Run tests with coverage
         run: |
-          cargo llvm-cov --manifest-path rust/lance-graph/Cargo.toml --lcov --output-path lcov.info
+          cargo llvm-cov --manifest-path crates/lance-graph/Cargo.toml --lcov --output-path lcov.info
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v4
         with:

.github/workflows/style.yml

@@ -5,10 +5,10 @@ on:
       - main
   pull_request:
     paths:
-      - rust/**
+      - crates/**
+      - Cargo.toml
+      - Cargo.lock
       - .github/workflows/style.yml
-      - rust/lance-graph/Cargo.toml
-      - rust/lance-graph/Cargo.lock
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
@@ -28,7 +28,7 @@ jobs:
         with:
           components: rustfmt
       - name: Check formatting
-        run: cargo fmt --manifest-path rust/lance-graph/Cargo.toml -- --check
+        run: cargo fmt --manifest-path crates/lance-graph/Cargo.toml -- --check
 
   clippy:
     runs-on: ubuntu-24.04
@@ -37,13 +37,13 @@ jobs:
       - uses: actions/checkout@v4
       - uses: Swatinem/rust-cache@v2
         with:
-          workspaces: rust/lance-graph
+          workspaces: crates/lance-graph
       - name: Install dependencies
         run: |
           sudo apt update
           sudo apt install -y protobuf-compiler
       - name: Clippy
-        run: cargo clippy --manifest-path rust/lance-graph/Cargo.toml --all-targets -- -D warnings
+        run: cargo clippy --manifest-path crates/lance-graph/Cargo.toml --all-targets -- -D warnings
 
   typos:
     name: Spell Check
@@ -52,4 +52,4 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
       - name: Check spelling
-        uses: crate-ci/typos@v1.26.0
+        uses: crate-ci/typos@v1.26.0

AGENTS.md

@@ -1,13 +1,13 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-- `rust/lance-graph/` hosts the Rust Cypher engine; keep new modules under `src/` and co-locate helpers inside `query/` or feature-specific submodules.
+- `crates/lance-graph/` hosts the Rust Cypher engine; keep new modules under `src/` and co-locate helpers inside `query/` or feature-specific submodules.
 - `python/src/` contains the PyO3 bridge; `python/python/lance_graph/` holds the pure-Python facade and packaging metadata.
 - `python/python/tests/` stores functional tests; mirror new features with targeted cases here and in the corresponding Rust module.
 - `examples/` demonstrates Cypher usage; update or add examples when introducing new public APIs.
 
 ## Build, Test, and Development Commands
-- `cargo check` / `cargo test --all` (run inside `rust/lance-graph`) validate Rust code paths.
+- `cargo check` / `cargo test --all` (run inside `crates/lance-graph`) validate Rust code paths.
 - `cargo bench --bench graph_execution` measures performance-critical changes; include shortened runs with `--warm-up-time 1`.
 - `uv venv --python 3.11 .venv` and `uv pip install -e '.[tests]'` bootstrap the Python workspace.
 - `maturin develop` rebuilds the extension after Rust edits; `pytest python/python/tests/ -v` exercises Python bindings.

Cargo.toml

@@ -0,0 +1,8 @@
+[workspace]
+members = [
+    "crates/lance-graph",
+]
+exclude = [
+    "python",
+]
+resolver = "2"

README.md

@@ -4,11 +4,14 @@ Lance Graph is a Cypher-capable graph query engine built in Rust with Python bin
 
 This repository contains:
 
-- `rust/lance-graph` – the Cypher-capable query engine implemented in Rust
+- `crates/lance-graph` – the Cypher-capable query engine implemented in Rust
 - `python/` – PyO3 bindings and Python packages:
   - `lance_graph` – thin wrapper around the Rust query engine
   - `knowledge_graph` – Lance-backed knowledge graph CLI, API, and utilities
 
+See `docs/project_structure.md` for the proposed workspace-based structure from
+issue #92.
+
 ## Prerequisites
 
 - Rust toolchain (1.82 or newer recommended)
@@ -18,7 +21,7 @@ This repository contains:
 ## Rust crate quick start
 
 ```bash
-cd rust/lance-graph
+cd crates/lance-graph
 cargo check
 cargo test
 ```
@@ -147,7 +150,7 @@ working solely on the bindings.
   - protoc: install `protobuf-compiler` (Debian/Ubuntu: `sudo apt-get install -y protobuf-compiler`).
   - Optional: gnuplot for Criterion's gnuplot backend; otherwise the plotters backend is used.
 
-- Run (from `rust/lance-graph`):
+- Run (from `crates/lance-graph`):
 
 ```bash
 cargo bench --bench graph_execution
@@ -157,8 +160,8 @@ cargo bench --bench graph_execution -- --warm-up-time 1 --measurement-time 2 --s
 ```
 
 - Reports:
-  - Global index: `rust/lance-graph/target/criterion/report/index.html`
-  - Group index: `rust/lance-graph/target/criterion/cypher_execution/report/index.html`
+  - Global index: `crates/lance-graph/target/criterion/report/index.html`
+  - Group index: `crates/lance-graph/target/criterion/cypher_execution/report/index.html`
 
 - Typical results (x86_64, quick run: warm-up 1s, measurement 2s, sample size 10):
 

rust/lance-graph/CONTRIBUTING.md → crates/lance-graph/CONTRIBUTING.md

@@ -4,11 +4,11 @@ Contributing (Rust crate)
 Before pushing or opening a PR, please verify Rust code formatting matches CI:
 
 ```bash
-cargo fmt --manifest-path rust/lance-graph/Cargo.toml -- --check
+cargo fmt --manifest-path crates/lance-graph/Cargo.toml -- --check
 ```
 
 If the check fails, format the code locally:
 
 ```bash
-cargo fmt --manifest-path rust/lance-graph/Cargo.toml
+cargo fmt --manifest-path crates/lance-graph/Cargo.toml
 ```

docs/project_structure.md

@@ -0,0 +1,60 @@
+Project Structure Proposal (Issue #92)
+======================================
+
+This document captures a pragmatic "proper" structure for lance-graph based on
+issue #92. It focuses on clearer separation of concerns, a Cargo workspace, and
+first-class Python bindings.
+
+Goals
+-----
+- Keep lightweight crates usable without pulling in heavy dependencies.
+- Allow custom graph-native operators without forcing everything through SQL.
+- Make Python bindings and examples first-class citizens.
+
+Current Layout (after refactor)
+-------------------------------
+- `crates/lance-graph/` hosts the Rust engine crate.
+- `python/` contains PyO3 bindings plus the `lance_graph` and
+  `knowledge_graph` Python packages.
+- `examples/` holds simple Cypher usage examples.
+
+Proposed Layout (Workspace)
+---------------------------
+The issue recommends moving to a Cargo workspace to split functionality and
+avoid pulling DataFusion/Tokio into every consumer:
+
+```
+lance-graph/
+├── Cargo.toml              # Workspace definition
+├── README.md               # Unified docs
+├── docs/                   # ADRs + design notes
+├── crates/
+│   ├── lance-graph/         # Facade crate (re-exports)
+│   ├── lance-graph-core/    # AST + schema types (no heavy deps)
+│   └── lance-graph-planner/ # Cypher -> LogicalPlan
+├── python/                  # PyO3 + Python packages
+└── examples/                # End-to-end examples
+```
+
+Why this helps
+--------------
+- `lance-graph-core` can be reused by tooling and schema validators without
+  DataFusion or Tokio.
+- `lance-graph-planner` keeps translation logic isolated for easier evolution.
+- A future `lance-graph-physical` crate can be introduced once we have
+  substantial graph-native kernels (traversal, vector search).
+- The facade crate offers a stable public API while allowing internal churn.
+
+Suggested Migration Steps
+-------------------------
+1. Add a top-level `Cargo.toml` workspace and move the existing Rust crate into
+   `crates/lance-graph/` without changing its internal module layout.
+2. Extract AST + schema types into `crates/lance-graph-core/` and update
+   references.
+3. Split the planner (`Cypher -> LogicalPlan`) into `lance-graph-planner`.
+4. Refactor the Simple executor so it lives in the workspace cleanly (either
+   inside the facade crate or as a `lance-graph-simple` crate).
+5. Update `python/Cargo.toml` to depend on the workspace crates.
+6. Add ADRs for each step under `docs/` to document tradeoffs.
+7. Update GitHub workflows to match the new workspace paths (build, test,
+   release/publish), otherwise releases will fail.

python/Cargo.toml

@@ -15,7 +15,7 @@ arrow-array = "56.2"
 arrow-schema = "56.2"
 arrow-ipc = "56.2"
 futures = "0.3"
-lance-graph = { path = "../rust/lance-graph" }
+lance-graph = { path = "../crates/lance-graph" }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 pyo3 = { version = "0.25", features = ["extension-module", "abi3-py39", "py-clone"] }