The memory war

1The goal

One keystroke should put your words safely on the remote, and you should be able to keep writing while it publishes. The metric: seconds from :sync to the snackbar, on the real jcalixte/notes clone on the device — not a toy repo, which turned out to understate everything by two orders of magnitude.

2The freeze

That points at the local commit stage. Its staging is O(N_tree) in files and bytes, and here N_tree ≈ 1179 over a 10 MHz bus. The network half is real too, but it doesn't brick the device, so this kaizen takes the freeze first. Everything below was benched on the device; tap a factor for its test and what the measurement said about the current method — most of these sounded right and measured wrong:

3The idea

The winning move is the only candidate whose cost is independent of repo size — so the problem can't come back as the notes tree grows. Everything index-shaped stays O(N_tree) and merely moves the wall.

• chosenO(depth) TreeBuilder splice611 s → ~2–3 s, flat in repo size foreverNever opens the index, never materialises the tree; carries 150 MB of images forward by OID.
• chosenFASTSEEK + 256-word CLMT bufferfar seek 198.7 → 20.4 msConfig, not code — the companion fix. Write-mode files fall back transparently.
• rejectedExplicit-path index stagingremoves the O(N) walk onlyStill calls index.write() — hits the same racy-clean wall.
• rejectedIndex-free write_tree_to—Seeding read_tree(HEAD) is 77 s + OOM. Trades one O(N) for another.
• rejectedesp_map.c window cachehoped ~150–250 ms / writeBuilt, instrumented, 0 hits in 4 runs, removed. The one build made on an unverified cause.
• deferredShrink the repo (images off-card)shrinks N and the cloneThe images are load-bearing for another app. Composes with the splice later.

4What could go wrong

5The change

The whole re-hash wall comes from the index. So the fix removes the index: read each dirty file into a blob, rebuild only its ancestor subtree chain onto HEAD's tree — a handful of objects, no walk, no re-hash, images carried by reference.

# firmware/src/git_sync.rs — stage_and_commit-    let mut index = repo.index()?;-    index.add_all(["*"], DEFAULT, Some(&mut skip_macos_cruft))?;-    index.update_all(["*"], …)?;       // stat 1179 files-    index.write()?;                    // racy-clean re-hash: ~611 s on FAT-    let tree = repo.find_tree(index.write_tree()?)?;+    // splice only the editor's journaled dirty paths onto HEAD's tree —+    // the index never exists; every sibling entry is carried by OID.+    let mut tree = parent.as_ref().map(|c| c.tree()).transpose()?;+    for path in paths {+        let blob = match fs::read(format!("{REPO_DIR}/{path}")) { … };+        tree = Some(repo.find_tree(splice(repo, tree.as_ref(), &parts(path), blob)?)?);+    }

6The push

The commit half was won — but the first real push then died silently, and fixing it took a second localization loop. Five more runs, each with telemetry built for that run. The theme was memory: libgit2 memory-maps its pack files, and on a 562 MB clone those maps alone overran 8 MB of RAM. Each fix bought back headroom and exposed the next ceiling.

min-ever free PSRAM during the push

The nine attempts, and what each one taught:

What it taught

• — Bench the real thing. The toy repo understated everything by ~2 orders of magnitude and hid a total brick.
• — Refute before building. Four explanations fell to measurement, and the only code written for an unverified hunch was the only code wasted.
• — Prefer mechanisms flat in N. The splice can't regress as the tree grows — the fix that stops the problem coming back.
• — The UI must not share a fate with git: a Rust Vec allocation failure aborts, a C malloc failure degrades to a snackbar. Repaints now render into pre-allocated frames.
• — Repo pack layout is a device-performance variable. Five packs vs one is a 32 s marking walk vs 3.5 s — and losing vs winning the keep-alive race.

Result: ∞ → 24.1 s. Still over the ~10 s target — but the failure changed category, from "bricks the device, forever" to "a finite number to shave."