docs(memory): say what centroidRecallState is NOT, and why it has no caller

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.
This commit is contained in:
2026-11-05 11:55:44 +08:00
parent 44f883745f
commit 16cfdb75d6

View File

@ -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]