StructuredMerge Kernel

StructuredMerge provides a Rust kernel and generated bindings for tools that need portable structured-merge contracts, fixture-backed behavior, and embeddable merge components.

The workspace includes the core AST/review contracts, parser substrate support, format-specific merge crates, binary/ZIP planning helpers, provider adapters, and generated host bindings. Rust project tooling, including kettle-rusty, lives in the separate Rust native-layer repository.

Project links:

• Website: https://structuredmerge.org
• Implementations: https://structuredmerge.org/implementations.html
• Specification: https://github.com/structuredmerge/structuredmerge-spec
• Shared fixtures: https://github.com/structuredmerge/structuredmerge-fixtures

The distribution architecture defines how the Rust kernel, parser providers, application bundles, and Alef-generated host adapters fit together.

The mature Ruby implementation is the StructuredMerge behavioral golden master. This Rust implementation is a conformance consumer and currently lags Ruby in behavior and defect fixes. Shared specifications and fixtures are portable evidence admitted from reviewed Ruby behavior; historical Rust behavior does not override Ruby when they disagree.

Names containing parity describe only the dimensions asserted by their cited fixtures. They do not claim complete behavioral equivalence with Ruby unless a versioned conformance profile explicitly says so.

StructuredMerge Rust is a layered crate family. The lower layers provide parser, range, AST, merge, and template contracts; format crates apply those contracts to specific languages and data formats; provider crates bind a format family to a parser or serializer; workflow crates package Rust project maintenance and Git-driver behavior.

Each crate README keeps this section short and links here. This root guide is the implementation inventory for Rust users who need to choose crates, understand backend coverage, or wire a focused backend into a test suite.

The family is intentionally layered:

• tree-haver provides parser portability, backend discovery, byte ranges, and runtime capability reporting.
• ast-merge provides the cross-format merge substrate: shared contracts, diagnostics, review state, and execution reports.
• Family crates such as markdown-merge, yaml-merge, and toml-merge own parser-neutral behavior for one format family.
• Provider crates such as pulldown-cmark-merge, yaml-serde-merge, and pest-toml-merge bind those families to concrete Rust parser libraries.

Add the crates your tool needs:

[dependencies]
ast-merge = "0.1"
tree-haver = "0.1"

Binary and ZIP use StructuredMerge-prefixed package names on crates.io:

structuredmerge-binary-merge = "0.1"
structuredmerge-zip-merge = "0.1"

Rust crate smorg ships the kernel executable smorg and the compatibility alias smorg-rs. Both execute the same kernel commands; no symlink is required. For a local development build:

cargo build -p smorg --locked
target/debug/smorg --help

Existing opt-in Git configurations may continue to use the compatibility alias:

git config merge.smorg-rs.driver 'smorg-rs merge-driver %O %A %B %P'
git config diff.smorg-rs.command 'smorg-rs diff-driver'
smorg-rs conflicts diff path/to/file-with-conflicts.go
smorg-rs languages --gitattributes

This naming change does not approve a default Git-driver switch or establish registry/platform release readiness. smorg NAME ARGS... runs smorg-NAME on PATH, passing arguments and standard streams without a shell. Built-in commands take precedence; missing executables fail explicitly. Language suffixes (rb, go, ts, py) select native-layer CLIs, while cloud names the SaaS client. These commands are not bundled merely because dispatch supports their names. The canonical benchmark merge entry point is smorg benchmark-provider-merge3; the old unlabelled positional form remains supported only by smorg-rs. See the spec repository's CLI_DISPATCH_CONTRACT.md for routing and exit rules. The source directory remains crates/smorg-rs while path-based benchmark mappings and consumers migrate.

merge-driver updates Git's %A file by default, or writes to --output when used outside git. diff-driver accepts both the two-argument local form and the seven- or nine-argument forms Git passes to external diff commands. conflicts diff reports conflict-marker regions in a file that already contains Git conflict markers.

Semantic merge-driver coverage is fixture-backed for JSON. Other language and format paths are git-compatible command surfaces without semantic driver coverage.

Core:

• tree-haver - parser substrate, byte ranges, backend adapters, and binary tree contracts.
• ast-merge - AST merge contracts, diagnostics, planning, review, replay, and nested-merge vocabulary.
• ast-template - template/session transport contracts.

Format libraries:

• plain-merge
• json-merge
• yaml-merge
• toml-merge
• markdown-merge
• ruby-merge
• go-merge
• rust-merge
• typescript-merge
• binary-merge
• zip-merge

Provider crates:

• yaml-serde-merge
• pest-toml-merge
• pulldown-cmark-merge

The Rust crates are developed against the shared StructuredMerge fixtures. Those fixtures encode portable behavior derived from the Ruby golden master and reviewed for cross-runtime use. Conformance checks live in crate tests and in the shared spec/fixture tooling rather than in a static status document.

Common checks:

• mise run check
• cargo test