Architecture

Draxl is organized as a Rust workspace split along semantic boundaries. The shared data model, validation, language adapter, patch engine, merge analysis, agent server, and CLI can evolve independently.

The current implementation supports the Rust lower language over .rs.dx files. The architecture already routes through an explicit LowerLanguage dispatch boundary.

Data Flow

source .rs.dx
     |
     v
draxl-parser
     |
     v
draxl-rust parse
     |
     v
draxl-ast::File
     |
     v
draxl-validate
  |      |       |       |
  v      v       v       v
print  lower   patch   merge
  |      |       |       |
  v      v       v       v
draxl-rust adapter services
     |
     v
draxl facade
     |
     v
CLI, Rust callers, MCP tools

Crates

draxl is the public Rust facade. It exposes parse, validate, format, JSON dump, lower, patch, and conflict workflows through one integration surface.

draxl-ast defines the typed IR and shared metadata: stable node ids, ranks, anchors, slots, typed syntax nodes, LowerLanguage, and canonical tree ordering.

draxl-parser dispatches whole-file and fragment parsing to the selected lower language adapter.

draxl-validate owns file-level semantic checks for duplicate ids, rank rules, anchor resolution, and detached docs or comments.

draxl-printer dispatches canonical rendering to the selected adapter and keeps formatting separate from validation.

draxl-rust owns the current Rust profile: .rs.dx parsing, fragment parsing, canonical rendering, lowering to ordinary Rust, Rust import, patch schema, slot/path rules, and semantic merge context.

draxl-patch parses, resolves, and executes semantic patch streams over ids, slots, anchors, and scalar paths.

draxl-merge detects hard conflicts, runs replay convergence checks, extracts semantic conflicts, and emits structured reports.

draxl-agent provides workspace-scoped semantic editing and the stdio MCP server.

draxl-cli exposes the terminal workflows and delegates MCP setup and serving to draxl-agent.

CLI Boundary

The CLI infers LowerLanguage from the source extension for commands that operate on Draxl files. A .rs.dx file selects the Rust profile.

draxl parse <file>
draxl fmt [--in-place] <file>
draxl dump-json <file>
draxl validate <file>
draxl lower <file>
draxl lower-rust <file>
draxl patch [--in-place] <file> <patch-file>
draxl conflicts <file> <left-patch-file> <right-patch-file>
draxl mcp serve [--root <workspace>]
draxl mcp setup --client codex [--root <workspace>] [--print] [--force]

The Rust library API keeps language selection explicit, while compatibility wrappers keep the current Rust-centered call sites compact.

Design Choices

Stable ids live in source. A node can be targeted after formatting, surrounding insertions, and unrelated edits as long as its identity survives.

Ranks make ordered children explicit. A concurrent insert can choose a rank in a parent slot independent of line position.

Anchors make doc and comment ownership explicit when layout leaves attachment ambiguous.

Validation is a first-class phase. Parsing recognizes the supported syntax; validation enforces the invariants that canonical printing, patching, and merge analysis require.

The root draxl crate is the integration surface for Rust callers. The CLI and agent server exercise that same public behavior through command-line and MCP interfaces.