| arm 3b | `limit=M..M`, ioctl resume: in-memory (M-k)..(M-k), total M | 2 | - | not run | - |
| arm 4 | no limit: 0 item updates over pause + resume (bpftrace: `btrfs_search_slot()` on the balance key with ins_len 0, cow 1, robust to inlining); positive control `limit=2`: exactly 2 | 2 | - | not run | - |
| arm 5 | dm-log-writes, `limit=N` to the end, every flush state replayed in order and read with dump-tree: with the item present, R + L in {N, N+1}; counts the N+1 states | 2 | - | not run | - |
+| arm 6 (opt-in) | per-chunk item update fails (-ENOMEM via bpf override): balance ends -12, item deleted, fs writable, no BUG, a new balance starts | 2 | - | not run | - |
| arm `alias` (informational) | `limit=M+2` with M matches: how many relocate (see open items) | - | - | not run | - |
Expected on a kernel without patch 2: arm 1 FAILs (on-disk N, total up
- The cover's "The upper bound never moves, so there is no progress to
track or persist." is now only true of the bound; flagged, not edited.
+### Failure paths of the new item writes (source audit, 2026-11-08)
+
+Context: Siddharth Mishra's v1 "btrfs: overwrite a leftover balance item
+instead of BUG_ON()" (list 11-05) and Qu's objection. Zygo: "balance-resume
+deliberately changes the update pattern, which introduces a new scenario
+that is not a transaction abort." The new writes are W1, patch 1's
+one-time `update_balance_item(…, true)` at resume (only when the recovered
+item was bounded, `bctl->update_item`), and W2, patch 2's per-chunk
+`update_balance_item(…, false)` from `count_limited_chunk()`. Both are
+followed, on any error, by `reset_balance_state()`: `balance_ctl = NULL`,
+`del_balance_item()`, floor = 0, and `btrfs_handle_fs_error()` if the
+delete fails (W1 via `out:` with BTRFS_BALANCE_RESUME, W2 via `goto error`
+-> not paused -> reset).
+
+| Write | Failure | Item afterwards | Balance next | Next ioctl / resume / mount |
+|---|---|---|---|---|
+| W1, W2 | `btrfs_alloc_path()` -ENOMEM | unchanged (W1: as recovered at mount, possibly unbounded legacy; W2: last written limits, maybe uncommitted in the running transaction) | reset: item deleted in a committed transaction | no item, no floor; a new balance starts normally |
+| W1, W2 | `btrfs_start_transaction()` fails: -EROFS (fs error / abort), -ENOMEM; no -ENOSPC (0 items) | unchanged | reset; on an aborted fs the delete fails -> `btrfs_handle_fs_error()` (already set) | fs error: no transaction can start, so no ioctl reaches `insert_balance_item()`'s BUG_ON; next mount recovers the last committed item |
+| W1, W2 | `btrfs_search_slot()` < 0 (COW -ENOSPC/-ENOMEM, -EIO); not an abort | unchanged (part of the path may be COWed, harmless) | handle ended, reset: delete (fallback global rsv); if the delete fails: fs error, forced RO | as above |
+| W1, W2 | `btrfs_search_slot()` == 1: item missing (-ENOENT) | none (only possible after corruption or a bug) | reset: the delete gets -ENOENT -> fs error | fs error; nothing to recover. Pre-existing class |
+| W1, W2 | `set_balance_item()` | cannot fail | - | - |
+| W1 | `btrfs_commit_transaction()` fails with abort | on disk: the item as recovered (before W1) | reset: delete fails -> fs error | next mount recovers the old item and bounds it again; nothing was relocated, so the bound is the same chunks: safe |
+| W1 | commit fails without abort (Qu's class) | new args in the running transaction, uncommitted | reset: the delete joins the same transaction and commits; if that fails too: fs error | no item left without `balance_ctl` on a writable fs: the delete error always sets the fs error. Not worse than `insert_balance_item()` |
+| W2 | `btrfs_end_transaction()` error | only -EROFS on an aborted transaction / fs error (end_transaction does not commit) | reset: delete fails -> fs error | next mount: last committed item; the one-chunk bound holds (committed state is a prefix: removal before its count) |
+| W2 | success, later commit (next relocation) aborts | last committed limits | the relocation error ends it, reset -> fs error | next mount: R + L in {N, N+1} |
+
+Findings:
+
+- No path leaves an item with `balance_ctl == NULL` on a writable,
+ error-free fs: every failed `del_balance_item()` calls
+ `btrfs_handle_fs_error()`, after which `btrfs_start_transaction()` refuses
+ (-EROFS), so `insert_balance_item()` cannot return -EEXIST and
+ `BUG_ON(ret == -EEXIST)` is not reachable from our writes. The remaining
+ route to it is Siddharth's: `insert_balance_item()`'s own commit failing
+ without an abort, with no reset (non-RESUME `out:` only frees bctl).
+ Pre-existing, unchanged by the series; left alone (Qu's objection
+ stands). The `BUG_ON(ret != -EEXIST)` on resume needs the item to vanish
+ while `balance_ctl` stays: only reset deletes, and it clears
+ `balance_ctl` first.
+- The floor is cleared in `reset_balance_state()` even when the delete
+ fails; it is only set with `balance_ctl` (start) or at recovery (where
+ `balance_ctl` is set right after), so it never outlives the balance.
+- No unsafe direction: W2 writes only after processing, so a failure or
+ crash leaves at most the last chunk uncounted (one extra relocation),
+ never a count for a chunk still there; the vrange in W2 is the one
+ already on disk. W1 failing leaves the pre-write item, and nothing has
+ been relocated, so the next mount bounds it to the same chunks.
+- `btrfs_handle_fs_error()` during mount (before SB_BORN, the async resume
+ thread) sets the fs error without forcing RO; transactions still refuse,
+ so the conclusion holds.
+- Changed: W1's failure was silent on the mount-time resume path (the
+ kthread's `btrfs_balance()` return is dropped and `out:` logs nothing),
+ so a paused balance could vanish without a trace. Patch 1 now logs
+ "balance: failed to write the bounded balance item: %d" and says in a
+ comment and the changelog why ending the balance is safe. Behaviour is
+ otherwise unchanged: as for every other error at that point, the balance
+ ends and the item is deleted. An alternative for Zygo: keep the item
+ and leave the balance paused (retryable), at the cost of a new `out:`
+ branch.
+- W2 needed no code change; patch 2's changelog now says the item is
+ deleted on a write failure and what a surviving item holds.
+
+Injection, for phase 2 (all three lane configs: BPF_KPROBE_OVERRIDE=y,
+FUNCTION_ERROR_INJECTION=y, FAULT_INJECTION not set):
+
+- reachable: `bpf_override_return` on `btrfs_search_slot()` and
+ `btrfs_cow_block()` (both ALLOW_ERROR_INJECTION(ERRNO) on all lanes),
+ filtered in bpf to the balance item key with ins_len 0 / cow 1 (W1 and W2
+ are the only such callers); `btrfs_check_leaf()` (ERRNO) to fail the
+ write-time tree check and force a commit abort; dm-flakey / dm `error`
+ table (DM_FLAKEY=y) to fail metadata writes -> abort.
+- not reachable: failslab, fail_make_request and the fail_function debugfs
+ (all need FAULT_INJECTION); `btrfs_start_transaction()`,
+ `btrfs_end_transaction()`, `btrfs_commit_transaction()` and
+ `btrfs_alloc_path()` are not on the allow list, so their failures can
+ only be reached indirectly (abort via dm or the tree checker) or not at
+ all (non-abort commit failure, path -ENOMEM).
+- arm 6 (in the script, opt-in `ARMS=6`): W2, the second per-chunk update
+ gets -ENOMEM from `btrfs_search_slot()`: status -12, item deleted, fs
+ writable, no BUG/WARNING, 2 relocated, a new balance starts. Control:
+ no override fires (FAIL "no injection").
+- planned arm 6b (not written): W1, the same override on a resume whose
+ recovered item was bounded (the legacy test's 6.12-written item, or the
+ reuse layout): the error line, the item deleted, nothing relocated, no
+ BUG; then the abort variant (dm `error` table loaded between the pause
+ and the resume): fs error, the next mount recovers the old item and
+ bounds it to the same chunks.
+- planned arm 6c (not written): W2 + abort, dm `error` table mid-balance:
+ fs error with no BUG; after the remount, R + L in {N, N+1} (arm 5's
+ invariant on a real abort).
+
## Not covered / open
- Patch 1's other bail-outs (cancel, chunk search or relocation errors,