Overview

Draxl is an agent-native source annotation layer for deterministic, high-volume concurrent code editing.

It makes syntax identity and ordering explicit in source files. Tools can then address a function, statement, expression, comment, or field by stable node id with no guesswork from nearby text.

insert @f1.body[ah]: @s3 let @p3 z = @e4 (@e6 y + @l2 1);

replace @e3: @e5 z

Those operations say what changed in the program tree: insert a statement into function @f1 and replace expression @e3.

Why Draxl Exists

Agent-produced code volume raises integration cost. Text diffs make tools recover intent from byte ranges, surrounding lines, and formatting context. That recovery breaks down when many branches, forks, and generated edits touch the same files.

Draxl moves the machine interface to semantic targets:

The source stays human-readable. The current Rust profile uses .rs.dx files that lower deterministically to ordinary Rust.

Core Model

Draxl metadata has three parts:

• @id gives a supported syntax node a stable identity.
• [rank] orders siblings inside ranked slots.
• ->anchor attaches detached docs or comments to an existing sibling node id.

@m1 mod demo {
  @d1 /// Add one to x.
  @f1[a] fn add_one(@p1[a] x: @t1 i64) -> @t2 i64 {
    @c1 // Cache the intermediate value.
    @s1[a] let @p2 y = @e1 (@e2 x + @l1 1);
    @s2[b] @e3 y
  }
}

Lowered Rust strips the Draxl metadata:

mod demo {
    /// Add one to x.
    fn add_one(x: i64) -> i64 {
        // Cache the intermediate value.
        let y = (x + 1);
        y
    }
}

What Works Today

The current implementation supports the Rust profile through .rs.dx files. The working surface includes:

• parsing the supported Rust-shaped Draxl syntax
• validating ids, ranks, anchors, and attachment rules
• printing canonical Draxl source
• dumping deterministic JSON for the typed IR
• lowering validated .rs.dx source to Rust
• applying semantic patch streams over ids, slots, anchors, and scalar paths
• checking hard conflicts and initial semantic conflicts between patch streams
• serving workspace-scoped Draxl edit tools over stdio MCP

Reader Path

Start with Quick Start to run the CLI over the example files. Read Syntax next to understand @id, [rank], and ->anchor.

Use Patching for semantic edit streams, Merge for replay and convergence, and Conflicts for hard and semantic conflict reports. Agents covers the MCP workflow.

Architecture describes the Rust workspace crates behind the public behavior.