]> git.hungrycats.org Git - bees/commitdiff
docs: document the plan_src_edge_blocked and plan_src_overlap counters
authorZygo Blaxell <bees@furryterror.org>
Wed, 2 Sep 2026 03:58:55 +0000 (23:58 -0400)
committerZygo Blaxell <bees@furryterror.org>
Sat, 10 Oct 2026 19:00:06 +0000 (15:00 -0400)
Commit 66f12b67e54f19cf9e72e8b2c2e97576b32e63eb
("plan: enforce the src once-only rule inside the covering search")
added these counters without an entry in docs/event-counters.md.

Assisted-by: Claude-Code:claude-opus-5-5
docs/event-counters.md

index ab1fee94b6fe698ea70e73b187e3c7b5cf7746dc..ad822003ca4cfb28a11cfe24a285923fc995402e 100644 (file)
@@ -337,9 +337,11 @@ The `plan` event group consists of events within the `scan_next` planner: choosi
  * `plan_reject_hole_max`: A composed plan was rejected because its hole-punch operation count exceeded `hole-max`.
  * `plan_reject_total_max`: A composed plan was rejected because its total operation count exceeded `total-max`.
  * `plan_snap_extra`: A dst plan's space debt included extra reference cost for unsharing snapshot metadata, because the dst has references in a multi-member snapshot family (`rewrite.snapshot-sharing`).
+ * `plan_src_edge_blocked`: The coverage search skipped a candidate match because its src range is already used by an earlier dedupe in the same plan (each src range may be used once per plan).
  * `plan_src_gap`: A dst plan was abandoned before executing because the src extent's references leave a gap in the matched range, so part of the pair has no src file offset.  Handled like a vanished src ref.
  * `plan_src_gone`: A dst plan was abandoned before executing because a planned source window had no covering ref at all — the ref vanished from the refetched refs list (file range overwritten, file or snapshot deleted) between planning and execution.  Expected filesystem churn; the extent is rescanned in a later cycle.
  * `plan_src_open_fail`: A dst plan was abandoned before executing because every ref covering a planned source window failed to open (deleted files or snapshots lingering in the refs list).  Expected filesystem churn; the extent is rescanned in a later cycle.
+ * `plan_src_overlap`: Plan composition found two selected matches using the same src range.  The coverage search prevents this, so it indicates a bug; the plan is abandoned with an error.
  * `plan_start`: A planner pass over one start extent began.
  * `plan_worse_than_null`: The winning plan had a space debt above the do-nothing floor — an invariant violation guard; for a non-forced start the null floor should always win in that case.