Mehdi Akiki

Rust, explained from the problem you can see

Rust Systems Atlas

A Rust program can compile and still get stuck, use too much memory, or leave a database write uncertain. Start with what you can observe. Follow the explanation, check the example, and see what a useful fix changes.

I am Mehdi Akiki. These guides connect Rust code to the database, runtime, compiler, and operating system it depends on. Each investigation starts with a concrete problem and explains the terms as they become useful.

Start with your problem

You do not need to read the whole atlas. Choose the question closest to yours.

Work behind the explanations

You can also inspect my changes to the Rust compiler and the design of Bitarena, a Rust collection that keeps stable handles while values are added and removed.

147

long-form articles

Each article sits in one map, listed in the article directory below.

694

failure case pages

Symptom-first cases in the Rust Failure Atlas, grouped by failure family.

694

cases with a failing and a repaired fixture

A fixture run shows that the failure reproduces and the repair passes. It does not check the explanation, and performance claims stay conditional.

Seven maps, one system

A failure rarely respects one documentation category. An async Send error can begin in a type, become stored future state, meet a runtime requirement, and surface as a trait diagnostic. The atlas keeps these paths visible.

Failures

Failure Atlas

Symptom-first investigations for failures that depend on timing, target, profile, version, feature graph, linker, or unsafe invariants.

716 entries available in this map

The cases above are from the part of the Failure Atlas that sits below the application layer. Every failure case is listed in the Atlas linked above; related articles are in the article directory below.

Compiler

Compiler and Tooling Atlas

Source-to-binary maps through parsing, expansion, resolution, HIR, THIR, MIR, trait solving, borrow checking, code generation, diagnostics, and rust-analyzer.

Build

Cargo, Build, and Linking Atlas

Feature resolution, MSRV, build scripts, fingerprints, incremental compilation, proc-macro builds, native dependencies, code generation, and linkers.

Async

Async and Concurrency Atlas

Future layout, Send boundaries, cancellation, wakeups, scheduling, cooperative budgets, atomics, backpressure, task ownership, and shutdown.

Memory

Types, Memory, and Unsafe Atlas

Layout, variance, drop checking, pinning, provenance, aliasing, initialization, destruction, trait objects, and the proof obligations behind safe APIs.

Targets

FFI and Target Atlas

ABI contracts, native libraries, WebAssembly, musl, operating systems, architectures, embedded targets, cross-compilation, and host capabilities.

Releases

Release and Compatibility Ledger

Important stable changes translated into affected code, compatibility boundaries, migration checks, and behavior compared across toolchain versions.

Complete article directory

Every published Rust investigation

Long-form Rust articles, grouped by map. The symptom-first failure cases have their own directory in the Rust Failure Atlas.

Failures (22)

Compiler (18)

Build (17)

Async (34)

Memory (45)

Targets (9)

Releases (2)

Claim ledger

Every strong statement needs a way to lose

I separate deterministic claims from source-level constraints and machine-dependent performance hypotheses. Each record names the observation that would prove my explanation incomplete. This prevents an attractive benchmark number from becoming a universal Rust rule.

Executable check: 7API or method bound: 3Measurement required: 4
  1. RCL-001 · Executable check

    Changing reader chunk size must not change the ordered match IDs or absolute offsets.

    Falsifier: Any read limit produces a different match tuple from one-shot search.

    Evidence: chunk_partition_does_not_change_matches

    Read the article →
  2. RCL-002 · API or method bound

    Compact recognition state does not remove bytes needed by a streaming output contract.

    Falsifier: A replacement or delayed-match API can release unresolved bytes and still reproduce one-shot output for every split.

    Evidence: Longest-match buffer bound plus split-point replacement oracle.

    Read the article →
  3. RCL-003 · Executable check

    Standard, leftmost-first, and leftmost-longest select different valid results for one fixed input.

    Falsifier: The pinned crate returns an identical tuple for all three configured match kinds.

    Evidence: match_kinds_choose_different_documented_results

    Read the article →
  4. RCL-004 · Executable check

    Automaton representation is a real observable build choice, not a synonym for Aho-Corasick.

    Falsifier: Requesting a DFA does not produce a matcher reporting DFA kind.

    Evidence: requested_dfa_kind_is_observable

    Read the article →
  5. RCL-005 · Measurement required

    Linear input complexity does not imply constant per-byte time as the pattern corpus grows.

    Falsifier: Nested pattern sets show invariant build cost, memory, selected strategy, and scan distributions across the declared workload matrix.

    Evidence: Nested corpus benchmark with kind, memory, output count, and cache-sensitive inputs.

    Read the article →
  6. RCL-006 · Measurement required

    Prefilter value changes with candidate density while logical output remains unchanged.

    Falsifier: Enabled and disabled variants have indistinguishable distributions across both rare- and frequent-candidate corpora, or emit different outputs.

    Evidence: prefilter_toggle_preserves_logical_output plus paired corpus benchmark.

    Read the article →
  7. RCL-007 · Measurement required

    Pattern shape and haystack byte distribution predict more than pattern count alone.

    Falsifier: Controlled corpora with equal counts but different rare bytes, prefixes, lengths, and alphabets show no material strategy or performance change.

    Evidence: Five-corpus pattern-shape matrix with corpus hashes.

    Read the article →
  8. RCL-008 · Measurement required

    A loop-carried transition-state dependency can limit a small DFA loop.

    Falsifier: Assembly and counters show no loop-carried address dependency or show another cost dominating the declared hot loop.

    Evidence: Assembly inspection, cache-sized corpus variants, and hardware counters.

    Read the article →
  9. RCL-009 · API or method bound

    A scanner comparison is valid only after output equivalence and workload symmetry are established.

    Falsifier: Two variants with different matches or timed setup still answer the same stated benchmark question.

    Evidence: Ordered match oracle, shared corpus hashes, and declared timed regions.

    Read the article →
  10. RCL-010 · Executable check

    A small prefix family can create more overlapping outputs than input bytes.

    Falsifier: Searching four `a` bytes for `a`, `aa`, and `aaa` does not return nine overlapping matches.

    Evidence: overlapping_prefix_family_has_nine_outputs

    Read the article →
  11. RCL-011 · Executable check

    An arbitrary byte pattern can match inside a valid UTF-8 scalar and yield a range unusable for string slicing.

    Falsifier: The continuation-byte match begins at a valid `str` character boundary.

    Evidence: arbitrary_byte_match_can_split_utf8_scalar

    Read the article →
  12. RCL-012 · API or method bound

    Slices, buffered reads, and memory maps expose bytes through different ownership and materialization boundaries.

    Falsifier: Tracing the declared boundary shows identical ownership, allocation, and source-lifetime behavior for all three inputs.

    Evidence: Boundary trace plus cold and warm end-to-end I/O measurements.

    Read the article →
  13. RCL-013 · Executable check

    One compiled matcher can be shared while independent searches keep local iterator state.

    Falsifier: Scoped threads cannot borrow the matcher concurrently or their independent match counts interfere.

    Evidence: compiled_matcher_is_shared_while_search_state_stays_local

    Read the article →
  14. RCL-014 · Executable check

    An oracle-and-partitions test can make chunk-boundary invariance executable.

    Falsifier: A generated partition cannot be compared through the same ordered result representation.

    Evidence: chunk_partition_does_not_change_matches

    Read the article →

Run the executable claim checks

npm run content:verify-rust-claimsInspect the pinned fixtures →

Evidence

Explanations are connected to evidence

Failure case pages ship fixtures pinned to a toolchain, and the claim ledger above ties each executable claim to a named test. Depending on the case, the evidence is compiler or runtime output, a symbol table, an object header, a link map, or an AddressSanitizer report. A fixture shows that the failure reproduces and that the repair passes. Whether the explanation is right is still an argument, and each case page cites the primary sources it rests on.

  1. 01

    Observe

  2. 02

    Separate

  3. 03

    Reproduce

  4. 04

    Prevent

What each failure case records

Every case page in the Failure Atlas records the same fields, so two cases can be compared directly.

  • observed symptom
  • failure family
  • likely cause and first discriminating check
  • Rust versions
  • targets and profiles
  • failing and repaired fixture, with the toolchain it ran on
  • review date
  • primary sources

Source-level experience

The atlas grows from work, experiments, and upstream reading

I still write and review code directly, including my Rust, Deno, and rust-analyzer open source contributions. The purpose of this atlas is to turn that practice into explanations another engineer can inspect and use.