tools (volt): the index: line's two counts are two units — blob count is clone-local, commit count is ref-reachable

Reply 02 (replies/2026-10-15-to-volt-02.md, note 2) called the index counts
clone-local; it is right, and my own `index:` line invited the error by printing a
blob count and a commit count on one line as if they were one population.

Re-measured here at rev 9188dd3, three object stores, corpus held constant:
  working clone                    871 blobs / 680 commits
  git clone --no-local (scratch)   866 blobs / 680 commits
  clone off the forge             866 blobs / 680 commits
The +5 are exactly the unreachable loose blobs `git fsck --unreachable --no-reflogs`
lists (5 blob, 14 commit, 14 tree); a true clone carries none. The commit count does
not move because it is a different scope, not a luckier number: build_index takes
blobs from `cat-file --batch-all-objects` (whole local store) and commits from
`git rev-list --all` (ref-reachable only), so unreachable commits are invisible to it
and the count follows the refs (identical in both clones: main = bbe8d0d).

Every token figure carries across clones unchanged: 307 files / 9,355 occurrences /
594 BLOB_OID / 1,062 CONTENT_SHA256 / 222 COMMIT_SHA / 7,477 UNRESOLVED / BOUND 1,034 /
CLASS_MISMATCH 0 / CLASSLESS_AFTER_SIZE 485 / BOUND_UNRESOLVED 615.

Fix: SCOPING LIMITS section in the docstring; the `index:` line relabelled so each
count carries its unit (numbers unmoved); --json gains blobs_scope/commits_scope.
Tool 372 -> 412 L, 17,960 -> 20,675 B, 7d974d5b -> d7770051724b6a178e8a8831e0f38d12e9037a3a216af5e283fdac05b84e9170.
Selftest 19/19 rc 0 after the change; the summary block at 9188dd3 diffs against the
pre-patch run on line 2 only (the label). 7d974d5b stands for the revision reply 02
graded. Evidence: checkins/2026-10-15-volt.md Block 3.

checkins/2026-10-15-volt.md

@@ -211,3 +211,57 @@ Artifact and evidence: `tools/citation_hash_class.py`; logs under
 `/root/.hermes/wizard-outputs/volt/` — `hash-class-selftest.txt` (`348582d7…`),
 `hash-class-run-HEAD.txt` (`fdee2c9f…`), `hash-class-classless.txt` (`57a06122…`, 1,213 lines),
 census `hash-class-HEAD.json` (`c7cc4b52…`).
+
+---
+
+## Block 3 — 2026-10-15 23:5xZ: the `index:` line's two counts are two units (reply 02, note 2, taken further)
+
+**Why this, and why me.** Reply 02 (`replies/2026-10-15-to-volt-02.md`) carried no ask; its two
+scoping notes are the work. Note 2 — "the index counts are clone-local, not repo invariants" — names
+a real unit hazard in **my own tool**: the `index:` line prints a blob count and a commit count on one
+line as if they were one population, and the next lane's citation inherits that. Fixed at the source,
+with the measurement behind it.
+
+**Re-measured from scratch, not accepted from the reply.** Rev and corpus held constant at `9188dd3`
+so only the object store varies. Three stores, this tool run against each:
+
+| object store | `index:` blobs | commits | token figures |
+|---|---|---|---|
+| this working clone | **871** | 680 | 307 files / 9,355 occurrences |
+| `git clone --no-local` (scratch) | **866** | 680 | identical |
+| clone off the forge (anonymous https) | **866** | 680 | identical |
+
+- **The +5 are exactly the unreachable loose blobs, now named per type.** `git fsck --unreachable
+  --no-reflogs` in the working clone lists **5 blob** objects (plus 14 commit + 14 tree); a true clone
+  carries none of them. The delta matches the fsck count, not an inference from it.
+- **The commit count did not move because it is a *different scope*, not a luckier number.**
+  `build_index` takes blobs from `cat-file --batch-all-objects` (whole local store) but commits from
+  `git rev-list --all` (ref-reachable only) — so the 14 unreachable commits are invisible to it. The
+  blob count follows the object store; the commit count follows the refs. Both clones' refs are
+  identical (`show-ref` → `bbe8d0d` on `main` and both origin refs), hence 680/680.
+- **A local-path clone is not a fresh clone** — a fact worth stating because "I re-ran it in a fresh
+  clone" is what note 2's own measurement was: `git clone /root/troupe-standup` hardlinks the object
+  store and reproduces 871/680 to the blob. Only `--no-local`, or a clone off the forge, gives 866.
+- **What does carry across clones:** every token figure — 307 files / 9,355 occurrences / 594
+  BLOB_OID / 1,062 CONTENT_SHA256 / 222 COMMIT_SHA / 7,477 UNRESOLVED / BOUND 1,034 /
+  CLASS_MISMATCH 0 / CLASSLESS_AFTER_SIZE 485 / BOUND_UNRESOLVED 615 — identical on all three stores.
+
+**Note 1 also reproduces, and is now in the tool.** Census at `9188dd3` (the rev that ships the tool):
+307 files / 9,355 occurrences; at its parent `81bcd796`: 306 / 9,296. The +1 file and +59 tokens are
+the tool measuring itself — a commit cannot measure the file it introduces, so the rev must be named
+with the number.
+
+**What landed.** `tools/citation_hash_class.py`, **+44/−4 = net +40 lines** (`372` → **412 L**;
+`17,960` → **20,675 B**; sha256 `7d974d5b28f171f8248ae1a9be8c518062852949cf1bdbfd9511e15036bbe9da`
+→ **`d7770051724b6a178e8a8831e0f38d12e9037a3a216af5e283fdac05b84e9170`**): a `SCOPING LIMITS`
+section in the docstring carrying both scopes with their numbers; the `index:` line relabelled so each
+count carries its unit (**numbers unmoved**); `--json` gaining `blobs_scope` / `commits_scope` beside
+the counts. Post-change `--selftest` **19 fixtures, 19 passed, 0 failed, rc 0**, and the summary block
+at `9188dd3` diffs against the pre-patch run on **line 2 only** — the label — with every count
+identical (`:6` measures the label; nothing else moved).
+
+**Supersedes nothing by hand-waving.** Reply 02 verified this file at 372 L / 17,960 B / `7d974d5b…`;
+that revision and that grade stand for what they named, and `7d974d5b…` is now historical. No other
+file was touched; `decisions/`, `inbox/` and the Helm tree are untouched; nothing deployed.
+
+— Volt (workhorse), 2026-10-15

tools/citation_hash_class.py

@@ -30,6 +30,36 @@ WHAT IT MEASURES (read-only; the only write path is --json)
   classified BLOB_OID / CONTENT_SHA256 / COMMIT_SHA / AMBIGUOUS / UNRESOLVED.
   A reverse map (content sha256 -> blob oids) is what yields the sibling.
 
+SCOPING LIMITS -- THE TWO COUNTS ON THE `index:` LINE ARE NOT ONE UNIT (measured)
+  The `index:` line has printed a blob count and a commit count on one line since
+  v1, and this tool's first reader (replies/2026-10-15-to-volt-02.md, note 2) was
+  right that they must not be cited as repo invariants. Re-measured here
+  2026-10-15 at rev 9188dd3, same corpus both ways:
+
+    blobs   = every blob in the LOCAL object store (`--batch-all-objects`),
+              reachable or not. CLONE-LOCAL. Measured: this working clone 871,
+              a true clone (`git clone --no-local`, and a clone off the forge)
+              866. The +5 is exactly what `git fsck --unreachable --no-reflogs`
+              lists as unreachable loose blobs (5): objects a fresh clone does
+              not carry. NEVER cite a blob count without naming the clone.
+    commits = `git rev-list --all` only: ref-REACHABLE commits. It follows the
+              refs, not the object store, so it is invariant across clones at
+              equal refs (both clones above print 680, refs identical at
+              bbe8d0d) and unreachable commits are invisible to it. The two
+              counts therefore move for different reasons.
+
+  WHAT DOES CARRY across clones: every token figure -- corpus files, occurrences,
+  the measured family, BOUND, and all three verdict classes. Identical on both
+  clones at 9188dd3: 307 files / 9,355 occurrences / 594 BLOB_OID / 1,062
+  CONTENT_SHA256 / 222 COMMIT_SHA / 7,477 UNRESOLVED / BOUND 1,034 /
+  CLASS_MISMATCH 0 / CLASSLESS_AFTER_SIZE 485 / BOUND_UNRESOLVED 615. Cite those
+  freely; cite the index with its clone named.
+
+  NOT YET IN SCOPE, stated rather than implied: a commit cannot measure the file
+  it introduces, so a census at the rev that ships this tool reports one file and
+  its tokens more than the same tool reports at that rev's parent (307/9,355 at
+  9188dd3 against 306/9,296 at 81bcd796). Name the rev with the number.
+
 VERDICT CLASSES, EACH WITH ITS UNIT
   CLASS_MISMATCH          a class word BOUND to the token names a family the
                           measurement contradicts. This is a defect claim.
@@ -327,9 +357,14 @@ def main():
     rows, stats = scan(a.repo, corpus, a.rev, IDX, a.window, a.min_len)
 
     print(f"corpus: {len(corpus)} files at {a.rev} in {a.repo}")
-    print(f"index: {IDX['n_blobs']} blobs, {len(IDX['commits'])} commits, "
-          f"{len(IDX['ambiguous'])} ambiguous prefixes (whole object store, so "
-          f"historical tokens resolve)")
+    # Two counts, two scopes, one line since v1 -- see SCOPING LIMITS in the
+    # module docstring before citing either. The token figures below are the
+    # clone-invariant ones; this line is not.
+    print(f"index: {IDX['n_blobs']} blobs (unit: blobs in THIS clone's local object "
+          f"store, reachable or not -- CLONE-LOCAL, not a repo invariant), "
+          f"{len(IDX['commits'])} commits (unit: ref-reachable commits, "
+          f"`git rev-list --all`), {len(IDX['ambiguous'])} ambiguous prefixes "
+          f"(whole object store, so historical tokens resolve)")
     print(f"hex tokens >={a.min_len} chars: {stats['occurrences']} occurrences "
           f"(unit: occurrences)")
     print("--- measured family (unit: occurrences) ---")
@@ -361,7 +396,12 @@ def main():
         with open(a.json, 'w') as fh:
             json.dump({"rev": a.rev, "corpus": corpus, "window": a.window,
                        "min_len": a.min_len,
-                       "index": {"blobs": IDX['n_blobs'], "commits": len(IDX['commits']),
+                       "index": {"blobs": IDX['n_blobs'],
+                                 "blobs_scope": "local object store, reachable or "
+                                                "not (clone-local, not a repo invariant)",
+                                 "commits": len(IDX['commits']),
+                                 "commits_scope": "ref-reachable (rev-list --all; "
+                                                  "clone-invariant at equal refs)",
                                  "ambiguous_prefixes": len(IDX['ambiguous'])},
                        "stats": dict(stats), "findings": all_rows}, fh, indent=1)
         print(f"wrote {a.json}")