StructuredMerge Spec

Portable specification work for StructuredMerge, derived from the canonical Ruby implementation and expressed for additional runtimes to consume.

StructuredMerge defines portable rules, result shapes, diagnostics, and review/replay vocabulary for tools that merge structured documents. The mature Ruby implementation is the behavioral golden master. Other runtimes consume these contracts and must prove parity for every capability they claim; their historical behavior is not an independent source of authority.

Project links:

• Website: https://structuredmerge.org
• Spec summary: https://structuredmerge.org/spec.html
• Conformance model: https://structuredmerge.org/conformance.html
• Shared fixtures: https://github.com/structuredmerge/structuredmerge-fixtures
• Peer implementations: Go, TypeScript, Rust, Ruby

Core documents

• MERGE_PROVIDER_REGISTRY_CONTRACT.md — merge-behavior registration and immutable snapshots, distinct from parser registration and full capability negotiation.
• TYPED_WORKFLOW_HOST_CONTRACT.md — initial typed host-owned batch boundary, source preparation, validation and remaining binding/runtime gates.
• TYPED_CAPABILITY_MANIFEST_CONTRACT.md — explicit typed kernel profile and parser observations, separate from full workflow-provider negotiation.
• CLI_DISPATCH_CONTRACT.md — shared command grammar, selectors, reports, process/file safety, external dispatch and the positional benchmark exception.
• CONFLICT_REVIEW_PLACEMENT.md — source-backed marker placement for present and absent conflict alternatives, without claiming merged output.
• MERGE_RULESET_INFORMATIONAL_DRAFT_02.md — active informational draft for the merge ruleset vocabulary.
• MERGE_RULESET_INFORMATIONAL_DRAFT_01.md — published baseline retained for stable reference.
• merge-lexicon.md — portable terminology snapshot derived from the active draft.
• LORA_MERGE.md — secondary application note for merge-like workflows above specialized backends.
• RAG_INGESTION_ADAPTER_CONTRACT.md — JSONL/delta/metric contract for stable RAG ingestion handoffs.
• RAG_PILOT_PACKET_CONTRACT.md — v1 customer pilot packet for RAG ingestion deliverables.
• PGVECTOR_PLAN_CONTRACT.md — v1 pgvector/PostgreSQL load-plan contract for RAG chunks.
• PLANNER_PAYLOAD_CONTRACT.md — v1 payload contract for AI planners and future MCP bindings.
• PATCH_ARTIFACT_CONTRACT.md — v1 patch artifact contract for non-mutating apply results.
• slices/slice-1024-normalized-parse-analysis-boundary.md — versioned TreeHaver parse and analysis transport derived from Ruby behavior.
• slices/slice-1025-versioned-merge-operation-envelopes.md — serialized analyze, diff2, directional merge2, and base-aware merge3 envelopes.
• slices/slice-1026-capability-negotiation.md — deterministic merge-provider and TreeHaver parser-backend capability negotiation.
• slices/slice-1027-source-preservation-byte-evidence.md — exact byte-region evidence and hard source-preservation invariants for rendered operations.
• slices/slice-1028-stable-diagnostic-conflict-serialization.md — stable diagnostic causality and structured conflict alternatives, localization, and resolution.
• slices/slice-1029-provider-contract-snapshot-manifest.md — admission, provenance, replay, and native-extension requirements for representative provider snapshots.
• slices/slice-1030-rust-kernel-provider-traits.md — object-safe Rust kernel traits, TreeHaver selection, and in-process/host provider architecture.
• slices/slice-1031-host-provider-boundary-lifecycle.md — coarse Alef host dispatch, registration, ownership, cancellation, and teardown rules.
• slices/slice-1034-ruby-golden-master-baseline.md — pinned Ruby release revision, dependency-lock evidence, callable behavior entry points, and known defects excluded from portable authority.
• slices/slice-1035-ruby-merge-behavior-ownership.md — released Ruby ownership map separating shared ast-merge mechanics, family substrates, parser providers, and adapter layers, with current drift risks called out for review.
• slices/slice-1036-tree-haver-registration-metadata.md — exact backend, language-registration, parser-requirement, selection, snapshot, and candidate trace metadata for the single TreeHaver.parser_for boundary.
• slices/slice-1037-ruby-known-defect-expectations.md — pending Ruby defect evidence that remains outside golden-master authority until explicitly resolved and reviewed for portable promotion.

Slices

The slices/ directory breaks the contract into implementation-facing increments. Early slices cover foundation types, diagnostics/results, plain text analysis, JSON/JSONC parsing, similarity, parser adapters, structural analysis, owner matching, and merge resolution. Later slices capture backend and family substrate boundaries.

Relationship to fixtures

The spec names the vocabulary and expected shapes. The fixture corpus turns that vocabulary into runnable cases that each implementation can consume. A behavior is portable only when it can be expressed through the shared contract and exercised by shared fixtures.

Implementation Alignment

Implementation status is represented by runnable fixture coverage, slice plans, and package tests in the implementation repositories. This repo should not carry a static product-status document; those documents age poorly and drift away from the actual product surfaces.

Non-goals

• Defining one universal merge algorithm.
• Replacing the Ruby golden master with a lowest-common-denominator abstraction.
• Storing language-specific package planning here.
• Replacing review with silent automatic conflict resolution.

Tooling

• tools/ast_merge_fixture_key_parity.py — reports shared diagnostic fixture-key coverage across TypeScript, Go, Rust, and Ruby host tests.
• tools/family_package_fixture_key_parity.py — reports family-package fixture slice coverage across TypeScript, Go, Rust, and Ruby host tests.
• tools/provider_package_fixture_key_parity.py — reports provider-package fixture slice coverage across TypeScript, Go, Rust, and Ruby host tests.
• tools/provider_matching_assertion_audit.py — reports whether provider matching-fixture tests assert unmatched paths as well as matched pairs.
• tools/provider_backend_override_audit.py — reports whether provider packages test unsupported backend override rejection across hosts.