fix(pm): stop --report labelling the arrival depth as "waiters already ahead" (#12782) (#12822)

The depth is read AFTER take_ticket has minted this call's own ticket, so the
recorded value is the arriving run PLUS the waiters ahead of it and its floor
is 1. --report printed it under "queue depth on arrival (waiters already
ahead)", so a completely uncontended fleet read as one waiter deep on every
row, and a reader had no way to tell whether the label or the record was the
wrong one.

The record was never wrong -- announce_arrival already derives
`ahead = depth - 1` from the same number and says "0 ahead of you" on a free
lock -- so this repairs the heading and leaves the recording path byte-for-byte
untouched. Rewriting the field instead would put a meaning boundary through the
middle of a ledger nothing can re-date, which is the mixed-population hazard
--report already has to warn about for `command-exit`.

Measured on a private lock and ledger, one holder plus two waiters: the holder
and the first waiter both record depth=1 (a holder deletes its ticket when it
acquires, so it is not in the queue either), and the second waiter records
depth=2 while its arrival line says "1 ahead of you". That second reading is
why the heading gained a second note: depth=1 is evidence about the QUEUE and
says nothing about whether the lock was held.

Self-test pins the record at its floor (an uncontended acquire records depth=1)
so a later "fix" that subtracts one in the recording path goes red, and pins
that the off-by-one heading is gone rather than merely annotated.

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

scripts/pm/os-verify-lock.sh

@@ -1769,10 +1769,31 @@ mode_report() {
   printf '  n=%s  p50=%s  p90=%s  max=%s\n' \
     "$(wc -l < "${tmp}/held" | tr -d ' ')" "$(pct_of "${tmp}/held" 50)" \
     "$(pct_of "${tmp}/held" 90)" "$(pct_of "${tmp}/held" 100)"
-  printf 'queue depth on arrival (waiters already ahead):\n'
+  # ⚠ THE LABEL, NOT THE RECORD. The field counts the arriving run itself: the
+  # depth is read AFTER `take_ticket` has minted this call's own ticket, so its
+  # floor is 1 and a completely uncontended fleet printed "1 waiter already
+  # ahead" on every row it had. The record was never wrong -- `announce_arrival`
+  # derives `ahead = depth - 1` from the same number and has always said "0
+  # ahead of you" on a free lock -- so the repair is this heading, and ⛔ NOT the
+  # recorded value: rewriting the field would put a meaning boundary through the
+  # middle of the ledger, which is the mixed-population hazard the outcomes
+  # block above already has to warn about for `command-exit`.
+  #
+  # The second ⇒ is the misreading the first one leaves behind. A run that
+  # queued behind a busy holder with nobody in front of it records exactly what
+  # a run that walked up to a free lock records, because a holder deletes its
+  # ticket at the moment it acquires; measured on both paths, both 1. So this
+  # column is evidence about the QUEUE and about nothing else -- `held` and the
+  # outcomes block are where "was the lock busy" is answered.
+  printf 'queue depth on arrival (the arriving run INCLUDED — 1 means nobody was ahead):\n'
   printf '  n=%s  p50=%s  p90=%s  max=%s\n' \
     "$(wc -l < "${tmp}/depth" | tr -d ' ')" "$(pct_of "${tmp}/depth" 50)" \
     "$(pct_of "${tmp}/depth" 90)" "$(pct_of "${tmp}/depth" 100)"
+  printf '  ⇒ waiters already ahead = this minus 1. The depth is read after this call mints\n'
+  printf '    its own ticket, so 1 is the floor, not a waiter.\n'
+  printf '  ⇒ it does not count the HOLDER either — queueing behind a busy lock with nobody\n'
+  printf '    in front of you records 1, exactly as walking up to a free lock does. This\n'
+  printf '    column measures the queue, never whether the lock was held.\n'
 
   # ⭐ The table this whole mechanism exists for. Ranked by TOTAL seconds held,
   # not by the worst single run: the command that decides how much the fleet
@@ -2545,6 +2566,14 @@ mode_self_test() {
     "$(grep -c 'outcome=command-exit' "$realled" 2> /dev/null || true)" 1
   st_case 'and the record carries the wait, the hold and the queue depth' \
     "$(grep -c 'waited=[0-9]* held=[0-9]* depth=' "$realled" 2> /dev/null || true)" 1
+  # ⛔ THE RECORDED FIELD IS PINNED AT ITS FLOOR, on purpose. The run above was
+  # uncontended, and it still records 1, because the depth is read after this
+  # call has minted its own ticket. That is the value `--report`'s heading now
+  # describes, and the repair for the heading being wrong was the heading --
+  # subtracting one HERE instead would read better for a day and then put a
+  # meaning boundary through the middle of a ledger nothing can re-date.
+  st_case 'and the depth it records counts the arriving run itself — floor 1, never 0' \
+    "$(grep -c ' depth=1 ' "$realled" 2> /dev/null || true)" 1
   st_case 'and exactly one record per run, not one per verdict line' \
     "$(wc -l < "$realled" | tr -d ' ')" 1
 
@@ -2578,6 +2607,22 @@ mode_self_test() {
     "$(bash "$SELF" --report 2>&1 | grep -c 'LOWER-BOUNDS that mixture')" 1
   st_case 'and names the newline flattening, which no label length can recover' \
     "$(bash "$SELF" --report 2>&1 | grep -c 'flattened to a space BEFORE the cut')" 1
+  # The arrival-depth heading, which said "waiters already ahead" over a number
+  # whose floor is 1 -- so an idle fleet read as one-deep on every row and a
+  # reader had no way to tell whether the label or the record was the wrong one.
+  # The last case is the one that would have caught it: asserting only that the
+  # true wording is PRESENT would also pass on a report that kept the old
+  # heading beside it, and the defect was a heading, not a missing sentence.
+  local rpt
+  rpt="$(bash "$SELF" --report 2>&1)"
+  st_case 'and --report says the arrival depth counts the arriving run itself' \
+    "$(printf '%s\n' "$rpt" | grep -c 'the arriving run INCLUDED')" 1
+  st_case 'and hands over the conversion rather than leaving it as arithmetic' \
+    "$(printf '%s\n' "$rpt" | grep -c 'waiters already ahead = this minus 1')" 1
+  st_case 'and blocks the next misreading: 1 is not evidence the lock was free' \
+    "$(printf '%s\n' "$rpt" | grep -c 'it does not count the HOLDER either')" 1
+  st_case 'and the off-by-one heading itself is gone, not merely annotated' \
+    "$(printf '%s\n' "$rpt" | grep -c 'waiters already ahead):')" 0
   # A measurement apparatus that can redden a gate has become part of the thing
   # it measures. This is the case that keeps it out of the way.
   st_case 'an unwritable ledger loses records, never runs' \