Risk assessment: promoting eio branch to main

[cuihtlauac]

Context

The eio branch carries 157 commits converting Irmin from Lwt to Eio (direct-style with effects). The goal is to retire main (Irmin 3.x / Lwt) and promote eio as the new main (Irmin 4.0.0). This issue documents the gap and the risks involved.

Scale of the gap

Metric	Value
Commits on eio not in main	157
Commits on main not in eio	6 (all already cherry-picked via #2385)
Files changed	401
Lines added / removed	+13,325 / −10,141
OCaml source files changed	256 .ml + 75 .mli

What's reassuring

1. main is fully synced into eio. The 6 main-only commits are already cherry-picked. No merge conflicts expected.
2. CI is green. Last 20 runs all pass (Ubuntu + macOS).
3. The work is substantial and coherent. 7+ contributors, led by @art-w (76 commits). Well-structured migration, not a half-finished experiment.
4. lwt_eio bridge used where needed. irmin-git, irmin-graphql, irmin-mirage, irmin-client, irmin-server all use the bridge layer.

Risks

1. Pending PRs on eio (7 open)

PR	Risk	Notes
#2397 Multicore safety (mutexes/atomics)	Low	CI failure is formatting only (dune fmt), not a build or test issue. Builds and tests pass. 202+/146− across 19 files. See investigation.
#2400 Inline small contents	Medium	Large (3068+/312−, 101 files). CI green. Depends on #2378 / #2390 also open.
#2336 Integrate eio watcher	Low	Integration work
#2379 Energy benchmarks	Low	Benchmarks only
#2368 Lavyek backend (WIP)	Low	Experimental

Note: the eio branch itself has pre-existing lint-fmt issues (8 files) because the GitHub Actions CI (dune.yml) doesn't run dune fmt — only ocaml-ci does, and it only triggers on PRs. A dune fmt commit on eio is needed regardless of #2397.

2. Orphaned PRs on main (14 open)

• Move to eio #2363 ("Move to eio") is the eio migration PR itself — needs closing, not merging.
• Fix qcheck-alcotest dependency in irmin-test.opam #2393 (qcheck-alcotest dep fix, +1/−1) — trivial, should merge or port first.
• 5 ancient PRs (Add Tree.is_val and Tree.Contents.is_val functions #1864, irmin-tezos: simplify the way we serialise nodes #2014, irmin-pack: replace inode's Map by a list of pairs #2042, Add fsync for directory #2132, WIP: irmin-pack.unix: Measure IO activity. #2250) are 2.8–4 years old — candidates for closing. Add fsync for directory #2132 had activity 1 week ago, so someone may care.
• Speed up Store.last-modified by comparing hashes instead of file contents #2335 (speed up last-modified) and irmin_git: fetch_all for fetching all refs of a remote repo #2345 (fetch_all) touch code heavily changed by eio — would need complete rebasing.

3. Pinned dependencies

4 pins point to specific commits on forks, not released opam packages:

Package	Source	Bus-factor risk
irmin-watcher	patricoferris/irmin-watcher	Single maintainer
bisect_ppx	patricoferris/bisect_ppx	Single maintainer
index	mirage/index	Official org
qcheck-stm	lyrm/multicoretests	Less established

All commits verified to exist. But users cannot opam install irmin from the standard repository until these are upstreamed or released.

4. No migration guide

No documentation for downstream consumers explaining how to port from Irmin 3.x (Lwt) to 4.0.0 (Eio). OCaml 5.1.0+ is now a hard requirement.

Suggested plan

Before the switch

• Run dune fmt on the eio branch to fix 8 pre-existing formatting issues.
• Decide on Multicore safety protect shared mutable state with mutexes and atomics #2397 (multicore safety): merge after a dune fmt pass (builds and tests already pass).
• Decide on Inline small contents in nodes (cleaned up) #2400 (inline contents) and its dependency chain (Inline small objects #2378, Inline small contents in nodes #2390): merge or defer.
• Triage the 14 main-targeting PRs. Close ancient ones (Add Tree.is_val and Tree.Contents.is_val functions #1864, irmin-pack: replace inode's Map by a list of pairs #2042, WIP: irmin-pack.unix: Measure IO activity. #2250). Notify authors of Add fsync for directory #2132, Speed up Store.last-modified by comparing hashes instead of file contents #2335, irmin_git: fetch_all for fetching all refs of a remote repo #2345 that main is about to change.
• Merge or port Fix qcheck-alcotest dependency in irmin-test.opam #2393 (trivial qcheck-alcotest fix).

The switch

Safest mechanical approach:

• Rename main → main-v3 (or lwt-legacy)
• Rename eio → main
• Update GitHub default branch
• Retarget any surviving PRs

This avoids a giant merge commit and preserves full history on both branches.

After the switch

• Unpin dependencies as upstream releases land. Track which pins are blocking an opam release.
• Write a CHANGES.md entry documenting the breaking changes and migration path.
• Tag a 4.0.0~beta or similar pre-release so downstream consumers can test.

Bottom line

The gap is large but well-managed. The merge mechanics are safe (eio already contains main). The pending PRs are in better shape than initially assessed — #2397's CI failure is just formatting, not a correctness issue. The remaining risks are the pinned dependencies blocking a clean opam release and the downstream impact on consumers who haven't migrated yet.

[cuihtlauac]

Investigation: PR #2397 CI failure

The ocaml-ci failure on PR #2397 is (lint-fmt) only — a formatting check. All other checks pass (analysis, lint-doc, lint-opam, lower-bound, debian-13-5.3). The GitHub Actions checks (build ubuntu, build macos, block-fixup) also all pass.

This is not a build or test failure.

Root cause

The eio branch's GitHub Actions CI (dune.yml) only builds and tests — it does not run dune fmt. The lint-fmt check comes exclusively from ocaml-ci, which only triggers on PRs. So the eio branch itself has never been tested for formatting compliance, and has accumulated formatting drift.

When PR #2397 was opened against eio, ocaml-ci ran lint-fmt for the first time against that lineage and found issues — some pre-existing on eio, some introduced by the PR.

Pre-existing on eio (not introduced by #2397) — 8 files

File	Issue
src/irmin/hash_intf.ml	doc comment {[ ]} indentation
src/irmin/perms.ml	doc comment {[ ]} indentation
src/irmin/irmin.mli	doc comment {[ ]} indentation
src/irmin-git/commit.ml	line-break around (* FIXME *) comment
test/irmin-graphql/common.mli	doc comment {[ ]} indentation
test/irmin-pack/test_stm/test_stm_irmin_pack.ml	end in formatting
bench/irmin-pack/trace_common.ml	doc comment {[ ]} indentation
src/irmin-cli/cli.ml	end) in formatting

Introduced by PR #2397 — 5 files

File	Issue
src/irmin/indexable_intf.ml	line rewrap in docstring
src/irmin-fs/unix/irmin_fs_unix.ml	try ... with indentation
src/irmin-pack/inode.ml	try ... with indentation
src/irmin-pack/io/stats.ml	short functions not collapsed to one line
src/irmin/tree.ml	try ... with indentation

Caveat

This analysis was done with ocamlformat 0.29.0 while the project pins 0.28.1. The doc-comment {[ ]} indentation changes may be version-specific. The structural changes (try/with, end in, line rewraps) are likely consistent across versions.

Fix

1. A dune fmt commit on the eio branch to fix the 8 pre-existing files.
2. A dune fmt pass in PR Multicore safety protect shared mutable state with mutexes and atomics #2397 on its 5 files.

This should turn ocaml-ci green. The multicore safety changes themselves build and test fine.

[cuihtlauac]

Analysis: Is the Irmin 4 API likely to trigger data races in client applications?

In Irmin 3, concurrency was Lwt (cooperative, single-threaded) with GC in a separate Unix process. In Irmin 4, it's Eio (direct-style with effects, multicore-capable) with GC in a separate domain. The question is whether this shift exposes clients to complex data races.

Short answer: No.

Why Lwt was "safe"

Lwt is cooperative single-threaded concurrency. Data races between fibers within a process are structurally impossible — there's only one OS thread, and context switches only happen at explicit yield points (>>=, Lwt.pause, I/O). The GC ran in a separate Unix process, communicating via files. No shared mutable memory, no races.

What Eio actually changes for a client

Eio fibers within a single domain are cooperatively scheduled — exactly like Lwt. A client that never calls Domain_manager.run gets the same concurrency model as Lwt, just with direct-style syntax. No data races possible.

Races only appear across domains, and Irmin's API is structured so that clients don't need to share mutable state across domains:

Type	Domain-safe?	Why
Repo.t	Yes	Designed to be shared. Backend stores use atomic CAS for branch updates.
Store.t on a persistent branch	Yes	Branch head updates use test_and_set (atomic CAS). Concurrent commits from different domains retry on conflict (up to 13 retries by default).
Store.t on a detached head	No	Uses a mutable ref — but detached heads are a niche pattern (proofs, temporary forks), not the normal path.
Tree.t	Yes	Immutable. Internal lazy caches use Atomic.t.
Commit.t	Yes	Immutable, content-addressed.

The natural client pattern is safe by design:

(* Each domain gets its own store handle to the same repo *)
Eio_main.run @@ fun env ->
  Eio.Switch.run @@ fun sw ->
    let repo = Store.Repo.v config in    (* shared *)
    let store_d1 = Store.main repo in    (* domain 1's handle *)
    let store_d2 = Store.main repo in    (* domain 2's handle *)
    (* Concurrent commits: CAS + retry, no lock needed *)

Where the races were (and why clients don't see them)

PR #2397 found 10 race conditions. Every single one is internal to Irmin's implementation, not in the API contract:

• Buffer.t in append_only_file — concurrent flush/append within irmin-pack I/O
• Hashtbl.t in dict.ml — refill yields on I/O, reader accesses stale table
• Mutable suffix/prefix in file_manager — GC swap races with dispatcher reads
• Global lock table in irmin_fs — find-or-create without synchronization
• Global refs in watch.ml — hook/switch refs accessed from multiple fibers
• Chunks array in chunked_suffix — readers see partial array update during append
• Global store cache in irmin_mem — duplicate instances created concurrently
• Metrics state — non-atomic mutation mode removed
• Dict hashtables — concurrent access during I/O-yielding refill
• GC/batch deadlock — calling GC from batch ~lock:true callback

These are all bugs where Irmin's own fibers (or the GC domain) race against each other on Irmin's internal mutable state. A client calling Store.set or Store.find doesn't need to do anything special — the fix is inside Irmin.

The GC domain interaction

This is the one place where Irmin itself spawns a domain. The design is conservative:

1. Client calls Gc.start_exn ~domain_mgr (explicit, not automatic)
2. GC worker opens the store read-only in a separate domain
3. It communicates results back via a file on disk (JSON), not shared memory
4. Main domain calls Gc.finalise to atomically swap the files (under mutex)

This is essentially the same architecture as Irmin 3's separate-process GC, just with a domain instead of fork. The isolation boundary (read-only access + file-based result) avoids the need for fine-grained synchronization between GC and the main store.

What could actually go wrong

The realistic risk scenarios for a client are:

1. High contention on a single branch from many domains — the CAS retry loop (13 attempts) could exhaust and return Error `Too_many_retries. This is a performance/liveness issue, not a data race. Irmin 3 had the same semantic via Lwt retries.

2. Sharing a detached-head Store.t across domains — this is the one API-level footgun. But detached heads are rarely used and sharing a store handle across domains isn't a natural Eio pattern.

3. Calling GC from within batch ~lock:true — Multicore safety protect shared mutable state with mutexes and atomics #2397 turns this from a deadlock into an explicit error.

4. Not merging Multicore safety protect shared mutable state with mutexes and atomics #2397 — without it, Irmin's internal state (buffers, dicts, file manager) can corrupt under concurrent fiber access even within a single domain, whenever operations yield at I/O points. This is the real risk, not the API design.

Bottom line

The API is well-designed for multicore. The concurrency model is:

• Intra-domain: cooperative fibers, same safety as Lwt
• Inter-domain: share Repo.t, create per-domain store handles, CAS on branches
• GC: isolated domain with file-based communication

A client that follows the natural Eio pattern (one store handle per fiber/domain, shared repo) won't encounter data races. The complexity is contained inside Irmin's implementation — which is exactly where #2397's fixes belong, and why merging it matters even though the API surface is sound.

[cuihtlauac]

Strengthening PR #2397 with model checking and race detection

PR #2397 adds mutexes and atomics to protect shared mutable state. The existing QCheck-STM tests cover high-level store operations (Add, Find, Remove, With_tree) and the LRU cache, but they don't test the lower-level components that #2397 actually fixes — the dict, append-only file buffer, file manager swap, chunked suffix, or watch globals.

Three tools are relevant, each covering different ground.

1. TSan (ThreadSanitizer) — all 6 patterns

OCaml 5 has TSan support (requires a 5.x+tsan switch). Instruments the binary to detect actual data races at runtime. The existing multicore tests in test/irmin-pack/test_multicore.ml (517 lines, 13 concurrent scenarios) and the QCheck-STM tests would all run under TSan. If they pass clean, that's strong evidence that #2397's fixes are correct.

Effort: Low — build with a TSan switch and run the existing test suite.
Guarantee: Detects races that occur during execution. Only as good as test coverage.

2. dscheck (exhaustive interleaving explorer) — 3 lock-free patterns

Systematically explores all thread interleavings using DPOR. Guarantees finding bugs if they exist. Only works with lock-free atomic code — cannot model Eio.Mutex.

Applicable to:

Pattern	File	Why it fits
Atomic suffix/prefix swap	file_manager.ml	Pure Atomic.get/Atomic.set, no mutex
Atomic array replacement	chunked_suffix.ml	Atomic.get/Atomic.set on chunk Array.t Atomic.t
Atomic refs + fetch_and_add	watch.ml	Atomic.set, Atomic.fetch_and_add for counters

Cannot model: append_only_file.ml, dict.ml (Eio.Mutex-based), store.ml (TOCTOU with mutex + atomic).

Effort: Moderate — write ~30-80 lines per test, extracting the atomic pattern into a standalone harness.
Guarantee: Proof-level. If dscheck passes, no interleaving can trigger a bug in the modeled pattern.

3. QCheck-STM (property-based state machine testing) — 5 patterns

Already in the repo. Could be extended to cover the lower-level components:

Pattern	What to model
Dict (dict.ml)	index returns stable unique IDs; find returns what was indexed
Buffer flush/append (append_only_file.ml)	Appended data survives flush; no data loss or duplication
GC start/batch TOCTOU (store.ml)	GC from within batch returns error, never deadlocks
Deadlock prevention (store.ml)	State machine forbids blocked states

Effort: Higher — requires writing models for each component.
Guarantee: Probabilistic. Catches real bugs but doesn't prove absence.

Recommended plan (by priority)

1. Run existing tests under TSan. Highest leverage: low effort, catches everything the test suite exercises. Build with opam switch create 5.3.0+tsan, run the multicore and STM tests.

2. Add dscheck tests for the 3 lock-free patterns. Small, self-contained tests that give proof-level guarantees for the atomic swap/array/counter patterns in file_manager.ml, chunked_suffix.ml, and watch.ml.

3. Extend QCheck-STM to cover dict and append-only file. These are the mutex-protected patterns that dscheck can't reach and TSan might miss if test coverage is thin.

4. QCheck-STM for TOCTOU/deadlock in store.ml — lower priority since the existing store-level STM tests already exercise batch + concurrent operations indirectly.

Summary

Tool	Patterns covered	Guarantee	Effort	In repo?
TSan	All 6	Detects races during execution	Low	No
dscheck	3 (lock-free atomics)	Exhaustive proof	Moderate	No
QCheck-STM	5 (all but global refs)	Probabilistic	Higher	Yes, but only store + LRU

[cuihtlauac]

TSan CI: validated and ready

Proof of concept

We validated that setup-ocaml@v3 + ocaml-option-tsan works on GitHub Actions bare runners. The PoC is at https://github.com/cuihtlauac/tsan-poc (run: https://github.com/cuihtlauac/tsan-poc/actions/runs/24236635971).

TSan correctly detected a textbook data race (int ref shared across two domains) with full OCaml stack traces including source file and line numbers:

WARNING: ThreadSanitizer: data race (pid=7257)
  Write of size 8 at 0x7f3f57dffa40 by thread T1:
    #0 camlDune__exe__Racy.work_273 bin/racy.ml:5
  Previous write of size 8 at 0x7f3f57dffa40 by main thread:
    #0 camlDune__exe__Racy.work_273 bin/racy.ml:5
SUMMARY: ThreadSanitizer: data race bin/racy.ml:5 in camlDune__exe__Racy.work_273

The safe version (using Atomic.t) passed with no warnings.

What's needed for TSan on GitHub Actions

Three things, all proven to work on ubuntu-latest bare runners:

1. sudo apt-get install -y libunwind-dev — system dependency for the TSan runtime
2. sudo sysctl vm.mmap_rnd_bits=28 — reduces ASLR entropy; TSan's shadow memory mapping requires ≤30 bits on x86_64. Modern kernels default to 32. This works because GitHub-hosted runners are bare VMs with passwordless sudo (not containers).
3. ocaml-variants.5.3.0+options,ocaml-option-tsan as the compiler spec for setup-ocaml@v3

Note: opam install dune is needed as an explicit step — setup-ocaml does not install dune automatically in TSan switches.

Why this can't work everywhere

• GitHub Codespaces: vm.mmap_rnd_bits may not be writable.
• GitHub Actions container: jobs: /proc/sys is read-only inside containers, and --privileged is not supported on hosted runners.
• ocaml-ci: No mechanism to configure kernel parameters or custom compiler switches.

GitHub Actions bare runners (no container: key) are the only viable hosted option.

Recommended setup for Irmin

A workflow triggered manually and nightly, not on every push (the TSan switch build takes ~10 minutes cached, tests run 2-7x slower):

name: TSan
on:
  schedule:
    - cron: '0 3 * * *'
  workflow_dispatch: {}

jobs:
  tsan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Install libunwind
        run: sudo apt-get update -y && sudo apt-get install -y libunwind-dev

      - name: Reduce ASLR entropy for TSan
        run: sudo sysctl vm.mmap_rnd_bits=28

      - name: Set up OCaml with TSan
        uses: ocaml/setup-ocaml@v3
        with:
          ocaml-compiler: "ocaml-variants.5.3.0+options,ocaml-option-tsan"

      - name: Install dune
        run: opam install dune

      - name: Install dependencies
        run: opam install . --deps-only --with-test

      - name: Build and test
        run: opam exec -- dune runtest
        timeout-minutes: 60
        env:
          TSAN_OPTIONS: "history_size=6"
          EIO_BACKEND: "posix"

Open question

Whether Irmin's 4 pinned dependencies (irmin-watcher, bisect_ppx, index, qcheck-stm) build cleanly with the TSan compiler. That's the next thing to validate.

[cuihtlauac]

TSan CI: pinned dependencies validated

The open question from the previous comment is answered: all 4 pinned dependencies build cleanly under the TSan compiler.

Run: https://github.com/cuihtlauac/tsan-poc/actions/runs/24237262152

The irmin-pinned-deps job pinned and installed all 4 packages in an OCaml 5.3.0+tsan switch:

• irmin-watcher.dev (patricoferris/irmin-watcher)
• bisect_ppx.dev (patricoferris/bisect_ppx)
• index.dev (mirage/index)
• qcheck-stm.0.10 (lyrm/multicoretests)

No build failures, no compatibility issues. There is no blocker to adding TSan CI to Irmin.

[cuihtlauac]

Suggestion: absorb index and irmin-watcher into the Irmin monorepo

Motivation

Two of the 4 pinned dependencies (index and irmin-watcher) are effectively Irmin-only libraries:

• index: zero consumers outside Irmin. Used exclusively by irmin-pack and irmin-pack-tools.
• irmin-watcher: one external consumer (current_git from the OCurrent ecosystem). The eio branch already pins a fork (patricoferris/irmin-watcher), so current_git can't use the eio version anyway.

Both are currently pinned to specific commits on forks, creating:

• Bus-factor risk (2 pins depend on patricoferris/* forks)
• CI complexity (pins must be kept in sync across multiple opam files)
• Cross-repo coordination overhead (changes to index/watcher and Irmin require separate PRs)

Proposal

Full integration of both libraries into the Irmin monorepo as additional packages. Irmin already has 19 opam packages in one dune workspace — index and irmin-watcher would become packages 20 and 21.

Concretely:

• Move index source into src/index/, keep its own index.opam package
• Move irmin-watcher source into src/irmin-watcher/, keep its own irmin-watcher.opam package
• Remove all 2 pin-depends referencing these packages from Irmin's opam files
• Archive the standalone repos (mirage/index, mirage/irmin-watcher)

Backward compatibility via opam-repository

Each version in opam-repository has its own independent url {} block. Different versions of the same package can point to different repos. This is a standard pattern for packages that move between repos:

packages/irmin-watcher/irmin-watcher.0.5.0/opam   →  url { src: "https://github.com/mirage/irmin-watcher/..." }
packages/irmin-watcher/irmin-watcher.0.6.0/opam   →  url { src: "https://github.com/mirage/irmin/..." }

packages/index/index.1.6.2/opam                   →  url { src: "https://github.com/mirage/index/..." }
packages/index/index.1.7.0/opam                    →  url { src: "https://github.com/mirage/irmin/..." }

current_git (the only external consumer of irmin-watcher) depends on Lwt-era versions and resolves to the old repo. New releases publish from the Irmin repo. No breakage.

What this buys

• 2 fewer pinned dependencies (drops from 4 to 2)
• Atomic changes: a PR can update index/watcher and Irmin together
• Simpler CI: no cross-repo pin coordination
• No fork risk: the patricoferris/* forks become unnecessary for these two packages

[cuihtlauac]

dscheck for exhaustive verification of lock-free patterns

Unlike TSan, dscheck is a regular opam package (v0.5.0, OCaml >= 4.12) — no special compiler, no kernel parameters, no dedicated CI job. Tests run deterministically on a single core in milliseconds and would be part of dune runtest on every push.

How it works

dscheck uses algebraic effects to intercept atomic operations and systematically explore all thread interleavings via DPOR (Dynamic Partial-Order Reduction). If an assertion can fail under any interleaving, dscheck finds it. If it passes, it's a proof — not a probabilistic result.

Constraint

dscheck requires Dscheck.TracedAtomic instead of Stdlib.Atomic. You can't point it at Irmin's source directly — the patterns must be extracted into small standalone test harnesses. But the 3 applicable patterns from #2397 are small enough.

dscheck only works for lock-free code (atomics). It cannot model Eio.Mutex, so only 3 of the 6 patterns in #2397 are covered. The other 3 (mutex-protected) are covered by TSan and QCheck-STM.

Concrete tests for the 3 lock-free patterns

file_manager.ml — suffix/prefix atomic swap during GC:

(* Model: GC swaps suffix while reader accesses it *)
let () =
  let open Dscheck.TracedAtomic in
  trace (fun () ->
    let suffix = make "v1" in
    spawn (fun () -> set suffix "v2");
    spawn (fun () ->
      let v = get suffix in
      assert (v = "v1" || v = "v2")))

chunked_suffix.ml — atomic array replacement:

(* Model: writer appends chunk while reader iterates *)
let () =
  let open Dscheck.TracedAtomic in
  trace (fun () ->
    let chunks = make [| "a" |] in
    spawn (fun () ->
      let old = get chunks in
      set chunks (Array.append old [| "b" |]));
    spawn (fun () ->
      let arr = get chunks in
      let len = Array.length arr in
      assert (len = 1 || len = 2)))

watch.ml — atomic counter:

(* Model: concurrent worker count increment *)
let () =
  let open Dscheck.TracedAtomic in
  trace (fun () ->
    let workers = make 0 in
    spawn (fun () -> set workers (get workers + 1));
    spawn (fun () -> set workers (get workers + 1));
    final (fun () ->
      let n = get workers in
      assert (n >= 0 && n <= 2)))

Integration

Tests would live in test/irmin-pack/dscheck/ with:

(tests
 (names test_file_manager test_chunked_suffix test_watch)
 (libraries dscheck))

And dscheck added as a with-test dependency in the relevant opam files. No pinning — it's a released package.

Coverage summary across all tools

Pattern	dscheck	TSan	QCheck-STM
Atomic swap (file_manager)	Proof	Detects	Partial
Atomic array (chunked_suffix)	Proof	Detects	Partial
Atomic counter (watch)	Proof	Detects	Weak
Mutex + Buffer (append_only_file)	N/A	Detects	Model
Mutex + Hashtbl (dict, irmin_fs, irmin_mem)	N/A	Detects	Model
TOCTOU + deadlock (store)	N/A	Weak	Model

[cuihtlauac]

Proposed roadmap to release Irmin 4.0.0

Superseded by the revised roadmap, which adds irmin-lwt compatibility package, simultaneous Irmin 3.x final release, and Irmin 3.x maintenance policy.

[cuihtlauac]

Assessment of PRs #2132, #2335, #2345

All three target main (Lwt-era code) and touch files that have been completely rewritten on the eio branch. None can be cherry-picked or rebased. The ideas are worth keeping — the code is not.

PR #2132 — "Add fsync for directory" (@icristescu, Nov 2022)

Adds Io.fsync_dir to persist directory metadata after GC creates new files. Small change (+20/−1).

Conflict: total. The 3 files it touches are gone or gutted on eio:

• src/irmin-pack/unix/io_intf.ml — deleted (moved to src/irmin-pack/io/io_intf.ml)
• src/irmin-pack/unix/io.ml — 380 lines of diff
• src/irmin-pack/io/gc_worker.ml — 449 lines of diff

The idea (fsync directory after GC writes) is still valid and would be ~10 lines to reimplement against the eio I/O layer.

Had recent activity (April 3, 2026).

PR #2335 — "Speed up Store.last-modified" (@zazedd, Sep 2024)

Performance fix: compares tree hashes instead of file contents when walking commit history, deduplicates commits in the heap. (+36/−20).

Conflict: total. Both files are among the most changed:

• src/irmin/store.ml — 1231 lines of diff (every function rewritten for direct style)
• src/irmin/store_intf.ml — 763 lines of diff

The algorithm (hash comparison + heap dedup) is sound and portable — just the syntax is completely different. Medium effort to reimplement.

No activity since Sep 2024.

PR #2345 — "irmin_git: fetch_all for all refs" (@zazedd, Oct 2024)

Adds fetch_all to the remote interface, fetching all refs from a git remote instead of one branch. (+50/−0).

Conflict: moderate. The files diverged less (23–31 lines of diff each). The PR adds a new function so there's less overlap with existing code. Main porting work is removing Lwt (>>=, Lwt_list.map_p → direct style).

No activity since Oct 2024.

Recommendation

PR	Idea	Effort to reimplement	Action
#2132	fsync directory after GC	Low (~10 lines)	Reimplement on eio, close old PR
#2335	Hash-based last-modified	Medium (algorithm port)	Notify @zazedd, invite resubmit or reimplement
#2345	fetch_all for git refs	Low-Medium (Lwt removal)	Notify @zazedd, invite resubmit or reimplement

All three should be closed as part of Phase 4 with a comment explaining the branch switch and inviting the authors to resubmit against the new main.

[cuihtlauac]

irmin-lwt: compatibility bridge for Irmin 3.x clients

The problem

Irmin 4.0.0 is a total API break: every function that returned 'a Lwt.t now returns 'a directly. Downstream consumers (Tezos/Octez, current_git, etc.) would need to rewrite all Irmin call sites at once to adopt Irmin 4. That's a high barrier.

Meanwhile, maintaining two full codebases (Irmin 3.x and 4.x) long-term is expensive and unsustainable.

The solution: irmin-lwt

A thin compatibility package that wraps Irmin 4's direct-style API with Lwt.t return types, using lwt_eio as the bridge. This is not speculative — lwt_eio is already used in 6 Irmin 4 packages (irmin-git, irmin-server, irmin-client, irmin-cli, irmin-graphql, libirmin) across 36 source files. The pattern is production-proven.

Concretely:

(* irmin-lwt wraps Irmin 4 direct-style with Lwt.t *)
let find t k = Lwt_eio.run_eio (fun () -> Irmin.Store.find t k)
let set t ~info k v = Lwt_eio.run_eio (fun () -> Irmin.Store.set t ~info k v)
let merge_into ~info x ~into = Lwt_eio.run_eio (fun () -> Irmin.Store.merge_into ~info x ~into)
(* etc. *)

The package would also provide an entry point so Lwt-only callers don't need to manage Eio directly:

(* Client code — minimal change from Irmin 3.x *)
let () =
  Irmin_lwt.run @@ fun () ->
    let* repo = Store.Repo.v_lwt config in
    let* t = Store.main_lwt repo in
    let* value = Store.find_lwt t ["key"] in
    ...

Migration path for downstream consumers

Two steps, at their own pace:

1. Switch irmin → irmin-lwt: same Lwt monadic API, Irmin 4 backend underneath. Minimal code changes (rename imports, use the _lwt entry point). Data format compatible.
2. Drop irmin-lwt → use irmin directly: remove Lwt.t wrappers, switch to direct style. This can happen module-by-module, no big-bang rewrite needed.

What this buys

• No long-term Irmin 3.x maintenance: irmin-lwt is the supported compatibility path, not a frozen 3.x branch
• Single codebase: irmin-lwt is a thin wrapper over Irmin 4, not a fork
• Gradual migration: consumers adopt at their own pace
• Proven pattern: irmin-server/command.ml already does exactly this (50+ Lwt_eio.run_eio calls bridging Lwt server code to Eio store operations)

Caveats

• Callers must run inside an Eio event loop. Irmin_lwt.run would handle this transparently.
• Watch callbacks cross the Lwt/Eio boundary in both directions. This works (irmin-client already does it) but needs care.
• irmin-lwt adds lwt and lwt_eio as hard dependencies. This is expected — Lwt users already have lwt.
• Performance: each Lwt_eio.run_eio call has overhead (context switch between Lwt and Eio schedulers). Negligible for I/O-bound store operations.

[cuihtlauac]

Revised roadmap to release Irmin 4.0.0

Supersedes the earlier roadmap. Key additions: irmin-lwt compatibility package, simultaneous Irmin 3.x final release, and Irmin 3.x maintenance policy.

Phase 1: Get eio branch release-ready

• Run dune fmt on the eio branch (8 pre-existing formatting issues, see investigation)
• Merge Multicore safety protect shared mutable state with mutexes and atomics #2397 (multicore safety) after a dune fmt pass — builds and tests pass, CI failure is formatting only
• Decide on Inline small contents in nodes (cleaned up) #2400 (inline small contents) and its chain (Inline small objects #2378, Inline small contents in nodes #2390): merge or defer to 4.1

Phase 2: Absorb index and irmin-watcher

• Move index source into src/index/, keep index.opam
• Move irmin-watcher source into src/irmin-watcher/, keep irmin-watcher.opam
• Remove all pin-depends for these two packages across Irmin's opam files

This drops pinned dependencies from 4 to 2 (bisect_ppx and qcheck-stm).

Phase 3: Build irmin-lwt compatibility package

• Create src/irmin-lwt/ wrapping Irmin 4's direct-style API with Lwt.t return types via lwt_eio
• Provide Irmin_lwt.run entry point so Lwt-only callers don't manage Eio directly
• Add irmin-lwt.opam with dependencies on irmin, lwt, and lwt_eio
• Test against a representative Irmin 3.x usage pattern to validate the migration path

See irmin-lwt design for details.

Phase 4: Add concurrency testing infrastructure

• Add dscheck tests for the 3 lock-free patterns (file_manager, chunked_suffix, watch) — runs as part of dune runtest, no special CI
• Add TSan GitHub Actions workflow (nightly + manual trigger, see validated setup)
• Optionally extend QCheck-STM to cover dict and append-only file

Phase 5: Triage PRs and prepare the switch

• Close Move to eio #2363 ("Move to eio") — superseded by the branch switch
• Close ancient main-targeting PRs that are no longer relevant (Add Tree.is_val and Tree.Contents.is_val functions #1864, irmin-pack: replace inode's Map by a list of pairs #2042, WIP: irmin-pack.unix: Measure IO activity. #2250)
• Notify authors of Add fsync for directory #2132, Speed up Store.last-modified by comparing hashes instead of file contents #2335, irmin_git: fetch_all for fetching all refs of a remote repo #2345 — invite resubmit against new main (see assessment)
• Merge or port Fix qcheck-alcotest dependency in irmin-test.opam #2393 (trivial qcheck-alcotest fix) if still relevant

Phase 6: The branch switch

• Rename main → main-v3
• Rename eio → main
• Update GitHub default branch
• Retarget any surviving PRs

Phase 7: Simultaneous release

Two releases at the same time:

Irmin 3.x (final release from main-v3):

• Tag a final Irmin 3.x release (e.g., 3.10.0) from main-v3 with current state
• Include a deprecation notice in the changelog pointing to Irmin 4.0.0 and irmin-lwt
• Submit to opam-repository

Irmin 4.0.0 (from main):

• Write CHANGES.md entry for 4.0.0 documenting the Lwt → Eio migration
• Write migration guide covering: remove Lwt.t, thread eio env, per-domain store handles, Eio_main.run entrypoint, and the irmin-lwt two-step migration path
• Tag 4.0.0~beta for downstream consumers to test
• Submit to opam-repository (new irmin-watcher and index versions now point to mirage/irmin)
• Upstream remaining pins (bisect_ppx, qcheck-stm) or document them as known constraints
• Tag 4.0.0 final after beta feedback

Phase 8: Irmin 3.x maintenance policy

Time-boxed, minimal:

• Critical security fixes only — backport to main-v3 if needed
• No new features — all development on Irmin 4
• Duration: 12 months after 4.0.0 final, then main-v3 is archived
• Supported migration path: irmin-lwt (not indefinite 3.x maintenance)

Phase 9: Post-release cleanup

• Update README in mirage/index and mirage/irmin-watcher to say the libraries have moved to mirage/irmin
• Archive mirage/index and mirage/irmin-watcher on GitHub
• Delete the patricoferris/irmin-watcher fork
• Monitor bisect_ppx and qcheck-stm upstreams — remove pins as official releases catch up
• Delete the tsan-poc validation repo (https://github.com/cuihtlauac/tsan-poc)
• Archive main-v3 after the maintenance window closes

What this achieves

Before	After
4 pinned fork dependencies	2 (bisect_ppx, qcheck-stm)
No concurrency testing	dscheck (proof) + TSan (detection) + QCheck-STM (model)
eio as a side branch	main is the Eio codebase
No migration path	irmin-lwt bridge for gradual adoption
No migration documentation	Migration guide + CHANGES.md + opam releases
Indefinite 3.x maintenance burden	Time-boxed (12 months), single codebase going forward
lint-fmt broken on eio	Clean formatting