From 16cfdb75d6042ee798b805c4fe0cdcd2b1ef1d52 Mon Sep 17 00:00:00 2001
From: jianf <2198972886@qq.com>
Date: Thu, 5 Nov 2026 11:55:44 +0800
Subject: [PATCH] docs(memory): say what centroidRecallState is NOT, and why it
 has no caller
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The C4 slice reported this method as dead code: `grep -rn centroidRecallState lib/`
returned nothing but the definition, and the instruction was "wire it into recall
or delete it — do not leave it as furniture".

Neither, and the reason is worth writing down rather than re-deriving:

- It cannot be wired into recall. It calls `centroidStatus`, whose first line is
  `countVectored` — a COUNT that C3-k forbids on the per-turn pre-step path. The
  scoring path therefore uses `loadCentroid` (one indexed SELECT).
- It should not be deleted. `assertC3RecallUnusable` in test/phase-b-h.test.js
  runs the SAME predicate against every C3 mutant, so this method is what pins
  Go's `LoadCentroid` semantics (`centroid_store.go:179-185`: a zero-sample centre
  is unusable, and the recall side carries no stale bit).

So it is a diagnostic seam, like `StableMem#saveSpaceCentroid`. The name
"Recall-facing projection" was the actual defect — it invites exactly the wiring
C3-k forbids. The name stays (renaming would churn a mutation-shared predicate for
no behavioural gain); the doc now says what it is and what it is not.

Comment only, no behaviour change.

Gates: npm test 300/300, npm run check 12/12.
---
 lib/store.js | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/lib/store.js b/lib/store.js
index f1e4158..49ba4f1 100644
--- a/lib/store.js
+++ b/lib/store.js
@@ -736,10 +736,27 @@ export class BlockStore {
   }
 
   /**
-   * Recall-facing projection of C3 facts. Go `LoadCentroid` returns
-   * `(nil,false,nil)` for every unusable center, including a zero-sample center
-   * (`internal/memory/centroid_store.go:179-185`); it does NOT expose the
-   * operator-only stale bit from `CentroidStatusOf:425-433`.
+   * Projection of C3 facts for a caller that only asks "may I centre?".
+   *
+   * Go `LoadCentroid` returns `(nil,false,nil)` for every unusable center,
+   * including a zero-sample one (`internal/memory/centroid_store.go:179-185`), and
+   * does NOT expose the operator-only stale bit from `CentroidStatusOf:425-433`.
+   * This mirrors that: `available` answers the yes/no question, `stale` is forced
+   * to null, and `reason` still travels for anyone who needs to log why.
+   *
+   * ★ NOT the recall path's entry, despite the name. The scoring path uses
+   * `loadCentroid` (a single indexed SELECT) because this method calls
+   * `centroidStatus`, whose first line is `countVectored` — a COUNT that C3-k
+   * forbids on the per-turn pre-step path. Wiring this into recall would put a
+   * full-space count on every turn.
+   *
+   * So it is a diagnostic seam, in the same category as
+   * `StableMem#saveSpaceCentroid`: no production caller, kept because it pins the
+   * Go semantics (`assertC3RecallUnusable` in test/phase-b-h.test.js runs the same
+   * predicate against every C3 mutant). Recorded here because "defined, never
+   * called" looked identical to the three real dangling-wire bugs found in this
+   * branch — and the only difference worth writing down is this paragraph.
+   *
    * @param {string} fingerprint
    * @param {{queryDim?: number, now?: () => number,
    *   schedule?: (fn: () => void, delayMs: number) => void}} [options]