ADR-0001: Implementation language: Rust

• Status: Accepted
• Date: 2026-06-10

Context

Margin’s positioning (see BLUEPRINT.md) is explicitly against the runtime weight of the incumbent (Hunk: TypeScript on Bun/Node). The product promises are: single static binary, < 50 ms cold start to first paint, smooth scrolling on 250k-line diffs, and installation without any language runtime. The choice of language is therefore a product decision, not a taste decision.

We also want the contributor pool most likely to show up: the people who build and maintain delta, bat, gitui, difftastic, and ratatui itself.

Decision

Margin is written in Rust, stable channel, unsafe_code = "forbid" workspace-wide. MSRV is pinned in Cargo.toml (rust-version) and follows the policy in ADR-0011 (current stable minus two releases).

Consequences

• Single static binary per target; cargo-dist handles distribution (ADR-0011).
• Startup and scroll performance budgets are achievable without heroics.
• The ecosystem hands us the hard parts: git2, syntect, similar, ratatui, insta.
• Cost: slower iteration than a scripting language, compile times, and a steeper ramp for contributors who don’t know Rust. We mitigate with a pure, small core crate (ADR-0003/0004) where most first contributions land.
• Cost: unsafe_code = "forbid" may need a future ADR exception if a performance hotspot demands it; none is anticipated.

Alternatives considered

• TypeScript (Bun/OpenTUI), like Hunk — would inherit the exact weaknesses we position against: runtime dependency, install friction, JS-class startup.
• Go + bubbletea — viable and fast to write, but heavier binaries, GC pauses are observable in tight render loops, and the diff/highlighting library ecosystem is thinner (no syntect/similar equivalents of the same maturity).
• Zig / C++ — performance is there, ecosystem and contributor funnel are not.