refactor(ir): split L2 relational + converter into asap-l2, slim asap-ir to L3

Per @milind's #57 feedback ("a lot fits into asap-ir"). asap-ir was 3.9k LOC
holding L2 relational + L3 canonical IR + the L2→L3 converter + binder +
resolution. Split along the real (non-cyclic) seam:

- asap-ir (2.3k, was 3.9k): the L3 canonical IR only — query_expr, agg_intent,
  expr_ir, schema, names (+ types, workload).
- asap-l2 (1.6k, new): the L2 relational algebra + the L2→L3 converter —
  relational, lower (convert_root), binder, column_resolution. Depends on asap-ir.

The apparent L2↔L3 module cycles were doc-comment links, not code deps; the
real graph layers cleanly.

Isolation wins:
- asap-sketch and asap-plan now depend on asap-ir alone — they never pull the
  converter/binder machinery (cargo tree: 0 asap-l2 in either).
- Front ends depend on asap-ir (L3 types) + asap-l2 (relational + convert_root).
- Parser quarantine unchanged (promql frontend: 0 datafusion).

Docs (README, design.md §5.1/§6.0/P1, migration-plan) updated: dependency
table, directory tree, and the "why L2 and L3 are separate crates" rationale.

No behavior change; full workspace suite green; clippy --all-targets clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: zz_y

Cargo.lock

@@ -1,6 +1,7 @@
 [workspace]
 members = [
     "crates/ir",
+    "crates/l2",
     "crates/sketch",
     "crates/plan",
     "crates/frontend-promql",

Cargo.toml

@@ -39,38 +39,40 @@ runtime coupling.
 
 | Crate | Role | Depends on | ~LOC |
 |---|---|---|---|
-| **`asap-ir`** | L2 relational + L3 canonical IR + L2→L3 converter, binder, resolution, schema, expr, workload types | *(nothing — no query-language deps)* | 3,900 |
+| **`asap-ir`** | **L3 canonical IR only** — `QueryExpr` + `AggIntent` + scalar expr IR + schema + names | *(nothing — no query-language deps)* | 2,300 |
+| `asap-l2` | L2 per-language relational algebra + the L2→L3 converter (`convert_root`, binder, column resolution) | `asap-ir` | 1,600 |
 | `asap-sketch` | L4 sketch-bound IR (`SketchExpr`) | `asap-ir` | 240 |
 | `asap-plan` | optimizer layer — CSE (landed); cost-model / boundary / canonicalize (stubs) | `asap-ir` | 290 |
-| `asap-frontend-promql` | PromQL L1→L2 | `asap-ir`, **promql-parser** | 1,030 |
-| `asap-frontend-sql` | SQL L1→L2 | `asap-ir`, **datafusion** | 1,130 |
+| `asap-frontend-promql` | PromQL L1→L2 | `asap-ir`, `asap-l2`, **promql-parser** | 1,030 |
+| `asap-frontend-sql` | SQL L1→L2 | `asap-ir`, `asap-l2`, **datafusion** | 1,130 |
 | `asap-lower` | facade re-exporting both front ends | the two `frontend-*` crates | 15 |
 | `asap-e2e` | cross-language integration tests | `asap-frontend-promql` | 40 |
 
-Splitting the front ends **quarantines their parsers**: a caller that needs
-only PromQL depends on `asap-frontend-promql` and never compiles DataFusion,
-and vice-versa (verified with `cargo tree`). `asap-lower` is the convenience
-facade for callers that want both.
+Two isolation wins fall out of this:
+- **The front ends quarantine their parsers** — a caller that needs only PromQL depends on `asap-frontend-promql` and never compiles DataFusion, and vice-versa (verified with `cargo tree`). `asap-lower` is the facade for callers that want both.
+- **L3-only consumers stay lean** — `asap-sketch` and `asap-plan` depend on `asap-ir` alone, so they never pull the L2 relational tree, the converter, or the binder (`asap-l2`). Only the front ends, which actually *lower* queries, need `asap-l2`.
 
 ### Directory structure
 
 ```
 crates/
-├── ir/                             # asap-ir — the shared IR (largest crate)
+├── ir/                             # asap-ir — L3 canonical IR (the shared vocabulary)
 │   └── src/
 │       ├── lib.rs
 │       ├── types.rs                #   AccuracyTarget, …
 │       ├── workload.rs             #   QueryWorkload / QueryLanguage / SqlDialect (front-end input)
 │       └── intent_algebra/
-│           ├── relational.rs       #   L2: per-language relational tree the front ends emit
 │           ├── query_expr.rs       #   L3: canonical QueryExpr — the IR everything pivots on
 │           ├── agg_intent.rs       #   L3: AggIntent vocabulary (Sum/Quantile/Rate/TopK/…)
-│           ├── expr_ir.rs          #   scalar expr IR (L2Expr / L3Expr)
-│           ├── lower.rs            #   L2→L3 converter (convert_root)
-│           ├── binder.rs           #   positional name-resolution seed
-│           ├── column_resolution.rs
+│           ├── expr_ir.rs          #   scalar expr IR (L2Expr / L3Expr / ColumnRef)
 │           ├── schema.rs           #   per-edge Schema + unique-keys
-│           └── names.rs
+│           └── names.rs            #   BindingName / QueryId
+├── l2/                             # asap-l2 — L2 relational algebra + L2→L3 converter
+│   └── src/
+│       ├── relational.rs           #   L2: per-language relational tree the front ends emit
+│       ├── lower.rs                #   L2→L3 converter (convert_root)
+│       ├── binder.rs               #   positional name-resolution seed
+│       └── column_resolution.rs
 ├── sketch/                         # asap-sketch — L4 sketch IR: expr / schema / sketch
 ├── plan/                           # asap-plan — optimizer: cse.rs (landed)
 │   └── src/                        #   + cost_model.rs / boundary.rs / canonicalize.rs (stubs)
@@ -83,13 +85,14 @@ crates/
 # deployment-model-* crates, control-proto, and the bin/ entrypoints.
 ```
 
-**Why `asap-ir` holds the most.** L2 (the per-language relational tree) and L3
-(the canonical intent algebra) live in one crate because the **L2→L3 converter
-needs both** — front ends only *emit* L2, they don't own it. Its modules
-(`relational` / `query_expr` / `agg_intent` / `schema` / `binder` / …) are
-cleanly separated and could split into their own crates later if the crate
-grows unwieldy; for now they share one compilation unit to keep the converter's
-tight coupling in-crate.
+**Why L2 and L3 are separate crates.** `asap-ir` is the canonical L3 IR — the
+vocabulary every downstream layer pivots on. The L2 relational tree and the
+L2→L3 converter live in `asap-l2` because only the *front ends* need them: they
+emit L2 and call `convert_root`. Keeping them out of `asap-ir` means the
+optimizer (`asap-plan`), the sketch IR (`asap-sketch`), and any future
+L3-consuming layer compile against a lean core without the converter/binder
+machinery. (The converter co-locates with L2 rather than L3 because it owns the
+L2 tree definition and only *reads* L3.)
 
 *(Planned.)* A new deployment model will land by adding one crate with `rules.rs` (pick L4 rules) + `topology.rs` + an emitter, plus one line in `bin/asap-controller/main.rs` — no changes to the IR crates.
 

README.md

@@ -7,6 +7,7 @@ edition = "2021"
 # in asap-ir. Pulls the PromQL parser only — never DataFusion.
 [dependencies]
 asap-ir = { path = "../ir" }
+asap-l2 = { path = "../l2" }
 
 # Private mirror of GreptimeTeam/promql-parser (Apache-2.0). `main` tracks
 # upstream; our `asap` branch carries the local patches.

crates/frontend-promql/Cargo.toml

@@ -1,6 +1,6 @@
 use std::fmt;
 
-use asap_ir::intent_algebra::ConvertError;
+use asap_l2::ConvertError;
 
 /// Errors from lowering a PromQL query (L1 parse → L2 → shared L2→L3 convert).
 ///

crates/frontend-promql/src/error.rs

@@ -1,16 +1,17 @@
 //! PromQL front end: L1 (parse via `promql-parser`) → L2 relational, then the
-//! shared L2→L3 [`convert_root`](asap_ir::intent_algebra::convert_root).
+//! shared L2→L3 [`convert_root`](asap_l2::convert_root).
 //!
 //! Emits the per-language
-//! [`relational::QueryExpr`](asap_ir::intent_algebra::relational); the shared
-//! converter runs the [`Binder`](asap_ir::intent_algebra::Binder) for
+//! [`relational::QueryExpr`](asap_l2::relational); the shared
+//! converter runs the [`Binder`](asap_l2::Binder) for
 //! positional name resolution. Depends on the PromQL parser only — never on the
 //! SQL / DataFusion stack.
 
 pub mod error;
 pub mod promql;
 
-use asap_ir::intent_algebra::{convert_root, QueryExpr};
+use asap_ir::intent_algebra::QueryExpr;
+use asap_l2::convert_root;
 use asap_ir::types::AccuracyTarget;
 use asap_ir::workload::{QueryLanguage, QueryWorkload};
 

crates/frontend-promql/src/lib.rs

@@ -4,7 +4,7 @@
 //! - **L2 (per-language tree)** is built here: the walk interprets PromQL
 //!   semantics (range vectors, aggregate operators, label matchers) and emits
 //!   the language-flavored [`relational::QueryExpr`] the controller's L2→L3
-//!   converter ([`convert_root`](asap_ir::intent_algebra::convert_root))
+//!   converter ([`convert_root`](asap_l2::convert_root))
 //!   consumes. Canonicalisation (window-over-aggregate fold, GROUP-BY →
 //!   positional `Aggregate.by`, positional name binding) happens in that
 //!   converter, not here.
@@ -44,7 +44,7 @@ use promql_parser::parser::{
 use asap_ir::intent_algebra::query_expr::{
     BinaryOpKind, GroupSide, VectorGrouping, VectorMatch, VectorMatchKind,
 };
-use asap_ir::intent_algebra::relational::{
+use asap_l2::relational::{
     AggFunc, AggItem, L2SortKey, QueryExpr as L2, SourceSpec,
 };
 use asap_ir::intent_algebra::{ArithOp, ColumnRef, CompareOp, L2Expr, L3Scalar};

crates/frontend-promql/src/promql.rs

@@ -7,6 +7,7 @@ edition = "2021"
 # shared L2→L3 converter in asap-ir. Pulls DataFusion only — never promql-parser.
 [dependencies]
 asap-ir = { path = "../ir" }
+asap-l2 = { path = "../l2" }
 datafusion = "43"
 
 [dev-dependencies]

crates/frontend-sql/Cargo.toml

@@ -1,6 +1,6 @@
 use std::fmt;
 
-use asap_ir::intent_algebra::ConvertError;
+use asap_l2::ConvertError;
 
 /// Errors from lowering a SQL query (L1 parse + plan via DataFusion → L2 →
 /// shared L2→L3 convert).

crates/frontend-sql/src/error.rs

@@ -1,16 +1,17 @@
 //! SQL front end: L1 (parse + plan via DataFusion) → L2 relational, then the
-//! shared L2→L3 [`convert_root`](asap_ir::intent_algebra::convert_root).
+//! shared L2→L3 [`convert_root`](asap_l2::convert_root).
 //!
 //! Emits the per-language
-//! [`relational::QueryExpr`](asap_ir::intent_algebra::relational); the shared
-//! converter runs the [`Binder`](asap_ir::intent_algebra::Binder) for
+//! [`relational::QueryExpr`](asap_l2::relational); the shared
+//! converter runs the [`Binder`](asap_l2::Binder) for
 //! positional name resolution. Depends on DataFusion only — never on the PromQL
 //! parser.
 
 pub mod error;
 pub mod sql;
 
-use asap_ir::intent_algebra::{convert_root, QueryExpr};
+use asap_ir::intent_algebra::QueryExpr;
+use asap_l2::convert_root;
 use asap_ir::types::AccuracyTarget;
 use asap_ir::workload::{QueryLanguage, QueryWorkload, SqlDialect};