release: v1.108.186 — the ledger stops claiming a channel that never ran

get_ranked_context's fusion exit recorded semantic_used=True on every
ranking-ledger row while building lexical, identity and structural channels
and never a similarity one. Its own _meta.channels listed the three and its
verdict said channels.semantic: "off", so the response and the ledger
disagreed about the same call. Deferred in 1.108.185 because the column feeds
a learned parameter; this is the follow-through.

The flag is derived from the channels actually built rather than hardcoded
False, so a future similarity channel is picked up with no second edit, and
the verdict's semantic_channel now comes off the same derivation.

Flipping it was not sufficient: the ledger is append-only and WeightTuner
learns semantic_weight by splitting rows on that column. Reproduced first —
30 honest lexical rows at 0.80 plus 30 mislabelled fusion rows at 0.40 walked
semantic_weight 0.5 to 0.45 on a ledger whose honest labels decline to move
it. New retrieval/ledger_trust.py holds the one rule, shared by all three
consumers. The rows are exactly identifiable: tool="get_ranked_context_fusion"
is written by no other producer.

Historical rows are excluded and disclosed, neither rewritten nor counted as
semantic-off. A corrective UPDATE was rejected on charter grounds, and folding
them into the off group would move the weight just as far.

Also fixed: regret's vocabulary_gap signal reported "the agent's term doesn't
match a symbol name" on every confident fusion call, because that exit passed
no ledger features either, so identity_hit defaulted to 0 while the identity
channel ran.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: jgravelle

CHANGELOG.md

@@ -2,6 +2,91 @@
 
 All notable changes to jcodemunch-mcp are documented here.
 
+## [1.108.186] - 2026-07-26 - the ledger stops claiming a channel that never ran
+
+### Fixed
+
+- ⚠ **`get_ranked_context`'s fusion exit recorded `semantic_used=True` on every
+  ranking-ledger row while building no similarity channel.** That exit builds
+  lexical, identity and structural — its own `_meta.channels` lists the three, and
+  since v1.108.185 its verdict reports `channels.semantic: "off"` — so the response
+  and the ledger disagreed about the same call, and the ledger was the one that was
+  wrong. Disclosed as deliberately deferred in v1.108.185 because the column feeds a
+  learned parameter; this is the follow-through.
+
+  The flag is now derived from the channels actually built
+  (`any(ch.name == "similarity" for ch in channels)`) rather than hardcoded to
+  `False`, so adding a similarity channel there picks it up with no second edit —
+  the same shape `search_symbols_fusion` already had. The verdict's
+  `semantic_channel` now comes off the same derivation, so the two cannot diverge
+  again.
+
+- ⚠ **Flipping the flag was necessary and not sufficient: the ledger is
+  append-only.** `WeightTuner` learns a per-repo `semantic_weight` by splitting rows
+  on that column and comparing mean confidence between the groups, so pre-fix rows
+  keep steering it for the whole 90-day recency window. **Reproduced before fixing:
+  30 honest lexical rows at 0.80 confidence plus 30 mislabelled fusion rows at 0.40
+  walked `semantic_weight` from 0.5 to 0.45, on a ledger whose honest labels decline
+  to move it at all.**
+
+  New `retrieval/ledger_trust.py` holds the one rule that says which labels are not
+  evidence, shared by all three consumers rather than copied into each. **The rows
+  are exactly identifiable with no heuristic:** they carry
+  `tool = "get_ranked_context_fusion"`, a value no other producer writes, so a
+  pre-fix row is precisely that tool with `semantic_used = 1` and a post-fix row is
+  the same tool with `0`. A tool-only rule would have discarded the fix's own honest
+  rows.
+
+- ⚠ **`suggest_corrections` was reporting a vocabulary gap on calls where identity
+  matching ran.** Regret's `vocabulary_gap` signal is the conjunction
+  `not identity_hit and semantic_used`, and that exit hardcoded the semantic flag
+  AND passed no ledger features at all — so `identity_hit` defaulted to 0 while the
+  identity channel was one of the three it built. Every confident fusion call was a
+  textbook match for "the agent's term doesn't match a symbol name", and those
+  clusters become config patches shown to the user. Untrusted rows are dropped from
+  that signal.
+
+### Changed
+
+- **The historical rows are excluded, disclosed, and neither rewritten nor counted
+  as semantic-off.** Three options were weighed. A one-time corrective `UPDATE` was
+  rejected on charter grounds, not convenience: the tuner has only ever written the
+  `tuning.jsonc` sidecar and `suggest_corrections` is read-only by charter, so
+  rewriting a user's telemetry rows is a charter change. Letting the 90-day window
+  age them out was also rejected — that is learning from a corpus we know is
+  mislabelled. **Unknown is a third answer, not a vote for `semantic_used=0`:**
+  folding those rows into the OFF group would be the same error mirrored, and it
+  would move the weight just as far. Every consumer that reads the column now
+  discloses the count — `events_semantic_label_unknown` on the tuner's signals and
+  on `analyze_regret`, `semantic_label_unknown` per repo in `analyze_perf --ledger`.
+
+- ⚠ **The exclusion expires, and a drift guard says when.** It is only honest while
+  that exit builds no similarity channel; if one is added, its `semantic_used=1`
+  rows become real evidence and the rule would start discarding good data. A test
+  fails if the exit grows a similarity channel while the rule is still
+  unconditional.
+
+### Notes
+
+- **Real blast radius is small and worth stating plainly.** The ledger is opt-in
+  (`perf_telemetry_enabled`, default `False`), so most installs hold no rows at all
+  and were never affected. Installs that enabled telemetry and used
+  `get_ranked_context(fusion=True)` have mislabelled rows, and for them the learned
+  weight and the correction suggestions were both reading a lie.
+- Compatibility is pinned rather than asserted: a pre-fix ledger stays readable and
+  unrewritten, and the new disclosure keys are absent — not zero — for a caller
+  whose ledger holds no mislabelled row.
+- New `tests/test_v1_108_186.py` (22), including the real-route ledger check, a
+  non-vacuity test for the derivation (patch a channel to be named `similarity` and
+  both the ledger and the verdict must follow), non-vacuity tests that show the same
+  ledger moving the weight and raising the cluster with the guard disabled, and the
+  drift guard. No tool-count change, no `INDEX_VERSION` change, no schema change.
+- Found on the way and deliberately NOT folded in: `get_ranked_context`'s fusion
+  exit passes no `extract_ledger_features` payload, so `top1_score`, `top2_score`
+  and `identity_hit` are defaults rather than measurements on every row it writes;
+  and `token_tracker._ensure_loaded(None)` on the first savings write repins the
+  perf db to `~/.code-index` even when a tool was given a `storage_path`.
+
 ## [1.108.185] - 2026-07-26 - fusion gets a verdict, and fusion can prove absence
 
 ### Fixed

CLAUDE.md

@@ -1,6 +1,6 @@
 [project]
 name = "jcodemunch-mcp"
-version = "1.108.185"
+version = "1.108.186"
 description = "Token-efficient MCP server for source code exploration via tree-sitter AST parsing"
 readme = "README.md"
 requires-python = ">=3.10"

pyproject.toml

@@ -0,0 +1,76 @@
+"""Which ``ranking_events`` labels can be believed (v1.108.186).
+
+The ledger is append-only history. When a producer records a column wrongly,
+the fix stops NEW rows from lying but cannot make the OLD rows honest, and
+every consumer that reads the column keeps reading the lie until the recency
+window ages it out. This module is the one place that says which labels are
+untrustworthy, so the three consumers (``retrieval.tuning``,
+``retrieval.regret``, ``tools.analyze_perf``) share a single rule rather than
+three copies drifting apart.
+
+**The mislabel this exists for.** Until v1.108.186,
+``_get_ranked_context_fusion`` recorded ``semantic_used=1`` on every row while
+building only the lexical, identity and structural channels — never a
+similarity channel. Its own ``_meta.channels`` listed the three, and from
+v1.108.185 its verdict reported ``channels.semantic: "off"``, so the response
+and the ledger disagreed about the same call.
+
+**Why the rows are exactly identifiable and no heuristic is needed.** Those
+rows carry ``tool = "get_ranked_context_fusion"``, a value no other producer
+writes. A pre-fix row is therefore precisely
+``(tool == "get_ranked_context_fusion", semantic_used == 1)``, and a post-fix
+row from the same exit is the same tool with ``semantic_used == 0``.
+
+**The label is UNKNOWN, not False.** An untrusted row is not evidence that
+semantic was off; it is evidence that this row cannot say. Consumers put it in
+a third bucket and disclose the count rather than folding it into either side
+— treating unknown as False would be the same class of error in the opposite
+direction.
+
+⚠ **This rule expires when the exit gains a similarity channel.** If
+``_get_ranked_context_fusion`` ever builds one, its ``semantic_used=1`` rows
+become honest and this predicate would start discarding good evidence.
+``tests/test_v1_108_186.py`` carries a drift guard that fails if that exit
+grows a similarity channel while this rule is still unconditional.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+# Column indices into a ranking_events row tuple, as SELECTed by
+# ``token_tracker.ranking_db_query``:
+#   0 ts  1 repo  2 tool  3 query_hash  4 query  5 returned_ids
+#   6 top1_score  7 top2_score  8 confidence  9 semantic_used
+#   10 identity_hit  11 repo_is_stale
+_TOOL = 2
+_SEMANTIC_USED = 9
+
+# (tool, semantic_used-as-bool) pairs whose semantic label is not evidence.
+# Keep this a frozenset of exact pairs: a tool-only rule would also discard the
+# honest post-fix rows, which are the ones a consumer most wants to read.
+_UNTRUSTED_SEMANTIC_LABELS = frozenset({
+    # v1.108.186. Pre-fix rows from get_ranked_context's fusion exit. The exit
+    # built no similarity channel, so a `1` here reflects a hardcoded argument
+    # rather than anything the search did.
+    ("get_ranked_context_fusion", True),
+})
+
+# The tool whose pre-fix rows the rule above covers. Exported so the drift
+# guard names it once rather than restating the string.
+MISLABELLED_FUSION_TOOL = "get_ranked_context_fusion"
+
+
+def semantic_label_is_trustworthy(row: Sequence) -> bool:
+    """True when ``row``'s ``semantic_used`` column is evidence of anything.
+
+    A short row (fewer columns than the ledger SELECT returns) is treated as
+    trustworthy: this predicate exists to refuse a KNOWN lie, and refusing rows
+    it cannot classify would turn a shape surprise into silent data loss.
+    """
+    try:
+        tool = row[_TOOL]
+        semantic_used = bool(row[_SEMANTIC_USED])
+    except (IndexError, TypeError, KeyError):
+        return True
+    return (tool, semantic_used) not in _UNTRUSTED_SEMANTIC_LABELS

src/jcodemunch_mcp/retrieval/ledger_trust.py

@@ -26,6 +26,7 @@
 
 from ..storage import token_tracker as _tt
 from .. import config as _config
+from .ledger_trust import semantic_label_is_trustworthy as _semantic_label_is_trustworthy
 
 # Column indices into a ranking_events row tuple.
 _TS, _REPO, _TOOL, _QH, _QUERY, _RETURNED = 0, 1, 2, 3, 4, 5
@@ -177,11 +178,23 @@ def _detect_stale_at_query(events: list[tuple]) -> list[dict]:
 
 def _detect_vocabulary_gap(by_qh: "dict[str, list[tuple]]") -> list[dict]:
     """Identity miss rescued by semantic search => the agent's term doesn't
-    match a symbol name but means one. The strongest novelty signal."""
+    match a symbol name but means one. The strongest novelty signal.
+
+    ⚠ v1.108.186. This signal is the conjunction ``not identity_hit and
+    semantic_used``, which made every pre-fix ``get_ranked_context_fusion`` row a
+    textbook match: that exit hardcoded ``semantic_used=1`` and passed no ledger
+    features at all, so ``identity_hit`` defaulted to 0 while the identity channel
+    was in fact one of the three it built. A confident fusion call therefore
+    reported "the agent's term doesn't match a symbol name" on a call where
+    identity matching ran, and ``suggest_corrections`` turns these clusters into
+    config patches shown to the user. Rows whose semantic label is not evidence
+    cannot support this signal, so they are dropped from it.
+    """
     out = []
     for qh, rows in by_qh.items():
         hits = [r for r in rows
-                if not r[_IDHIT] and r[_SEM]
+                if _semantic_label_is_trustworthy(r)
+                and not r[_IDHIT] and r[_SEM]
                 and r[_CONF] is not None and r[_CONF] >= VOCAB_CONF_FLOOR]
         if len(hits) >= VOCAB_RECUR:
             out.append(_cluster(
@@ -230,6 +243,13 @@ def analyze_regret(
         )
         return base
 
+    # v1.108.186. Disclosed rather than silently dropped: the vocabulary_gap signal
+    # ignores these rows, and a reader comparing `events_analyzed` against the
+    # clusters found deserves to know some rows could not support one of the six.
+    _untrusted = sum(1 for r in events if not _semantic_label_is_trustworthy(r))
+    if _untrusted:
+        base["events_semantic_label_unknown"] = _untrusted
+
     by_qh = _by_query_hash(events)
     clusters: list[dict] = []
     clusters += _detect_requery_churn(by_qh)

src/jcodemunch_mcp/retrieval/regret.py

@@ -16,6 +16,11 @@
 the ledger (default 90 days) rather than the lifetime history, so old
 events can't anchor weights to a query distribution that no longer
 exists (``max_age_days=0`` restores the lifetime read).
+
+v1.108.186: rows whose ``semantic_used`` label is not evidence are excluded
+from both groups and disclosed as ``events_semantic_label_unknown`` — see
+``retrieval.ledger_trust``. Unknown is a third answer here, not a vote for
+``semantic_used=0``.
 """
 
 from __future__ import annotations
@@ -29,6 +34,7 @@
 from typing import Optional
 
 from ..storage import token_tracker as _tt
+from .ledger_trust import semantic_label_is_trustworthy as _semantic_label_is_trustworthy
 
 logger = logging.getLogger(__name__)
 
@@ -177,6 +183,14 @@ def _propose(
 
         confidences_with_sem: list[float] = []
         confidences_without_sem: list[float] = []
+        # v1.108.186. A THIRD bucket, because the answer to "was semantic used on
+        # this row" can be "this row cannot say". Pre-fix `get_ranked_context_fusion`
+        # rows recorded `semantic_used=1` from a hardcoded argument while building no
+        # similarity channel, and the ledger keeps them for the whole recency window.
+        # They are not evidence that semantic was ON, and folding them into the OFF
+        # group would be the same error mirrored — so they are counted, disclosed,
+        # and excluded from both means.
+        unknown_semantic_label = 0
 
         # Schema (column index): 0 ts, 1 repo, 2 tool, 3 query_hash,
         # 4 query, 5 returned_ids, 6 top1, 7 top2, 8 confidence,
@@ -185,6 +199,9 @@ def _propose(
             conf = row[8]
             if conf is None:
                 continue
+            if not _semantic_label_is_trustworthy(row):
+                unknown_semantic_label += 1
+                continue
             sem_used = bool(row[9])
             (confidences_with_sem if sem_used else confidences_without_sem).append(float(conf))
 
@@ -196,6 +213,17 @@ def _propose(
             "mean_confidence_semantic_on": _round(mean_sem_on),
             "mean_confidence_semantic_off": _round(mean_sem_off),
         }
+        if unknown_semantic_label:
+            # Disclosed on every proposal that had to drop rows, including the ones
+            # that then decline to move a weight — a silent exclusion reads as "the
+            # ledger simply had nothing to say".
+            signals["events_semantic_label_unknown"] = unknown_semantic_label
+            signals["semantic_label_unknown_note"] = (
+                "Rows recorded before v1.108.186 by get_ranked_context's fusion exit "
+                "carry semantic_used=1 from a hardcoded argument, not from a "
+                "similarity channel. They are excluded from both groups rather than "
+                "counted as semantic-off, and age out with the recency window."
+            )
 
         new_sem = None
         if mean_sem_on is not None and mean_sem_off is not None:

src/jcodemunch_mcp/retrieval/tuning.py

@@ -18,6 +18,9 @@
 from typing import Optional
 
 from ..storage import token_tracker as _tt
+from ..retrieval.ledger_trust import (
+    semantic_label_is_trustworthy as _semantic_label_is_trustworthy,
+)
 
 
 _DEFAULT_TOP = 20
@@ -78,6 +81,11 @@ def _ledger_summary(rows: list[tuple], top: int) -> dict:
             "stale_events": 0,
             "identity_hits": 0,
             "semantic_used": 0,
+            # v1.108.186. Rows whose semantic_used column is not evidence — see
+            # retrieval.ledger_trust. Counted separately so `semantic_used` stays a
+            # count of rows that mean it, and reported (rather than dropped) because
+            # a shrunken count with no explanation reads as a usage change.
+            "semantic_label_unknown": 0,
         })
         rb["events"] += 1
         if conf is not None:
@@ -87,14 +95,23 @@ def _ledger_summary(rows: list[tuple], top: int) -> dict:
             rb["stale_events"] += 1
         if ident:
             rb["identity_hits"] += 1
-        if sem:
+        if not _semantic_label_is_trustworthy(
+            (ts, repo, tool, qh, query, returned_ids, top1, top2, conf, sem, ident, stale)
+        ):
+            rb["semantic_label_unknown"] += 1
+        elif sem:
             rb["semantic_used"] += 1
         tb = by_tool.setdefault(tool, {"events": 0})
         tb["events"] += 1
     for repo_name, rb in by_repo.items():
         ct = rb.pop("_conf_count", 0)
         total = rb.pop("_conf_total", 0.0)
         rb["avg_confidence"] = round(total / ct, 3) if ct else 0.0
+        # v1.108.186. Present only when there is something to disclose, so a caller
+        # whose ledger holds no mislabelled row sees the byte-identical shape it saw
+        # before. Compatibility here is pinned by a test, not asserted.
+        if not rb.get("semantic_label_unknown"):
+            rb.pop("semantic_label_unknown", None)
     repo_ranked = sorted(by_repo.items(), key=lambda kv: kv[1]["events"], reverse=True)[:top]
     tool_ranked = sorted(by_tool.items(), key=lambda kv: kv[1]["events"], reverse=True)
     return {

src/jcodemunch_mcp/tools/analyze_perf.py

@@ -834,25 +834,26 @@ def _get_tokens_fusion(sym):
         [{"score": item.get("fusion_score")} for item in context_items],
         is_stale=_probe.repo_is_stale,
     )
+    # v1.108.186. This was a hardcoded `semantic_used=True` while the channel list
+    # above builds lexical, identity and structural — never similarity — so every
+    # row this exit has ever written claimed a channel that did not run. Derived
+    # from the channels actually built rather than hardcoded False: if anyone adds a
+    # similarity channel here, the ledger follows without a second edit. Same shape
+    # as `search_symbols_fusion`, which records its real `similarity_used` flag.
+    _semantic_used = any(ch.name == "similarity" for ch in channels)
     _record_ranking_event(
         tool="get_ranked_context_fusion",
         repo=f"{owner}/{name}",
         query=query,
         returned_ids=[c.get("symbol_id", "") for c in context_items],
         confidence=fusion_result["_meta"].get("confidence"),
-        semantic_used=True,
+        semantic_used=_semantic_used,
         repo_is_stale=_probe.repo_is_stale,
     )
 
     # v1.108.185. The last exit in this tool without a verdict. The non-fusion
     # no-candidate return got one in v1.108.179 and the main path has had one since
     # v1.108.166; this branch was simply never revisited.
-    #
-    # ⚠ This exit builds NO similarity channel at all — lexical, identity and
-    # structural only — so `channels.semantic` stays `off`, which is the truth
-    # rather than the `semantic_used=True` the ranking ledger above records for it.
-    # Left alone here: that argument feeds weight tuning and changing it would move
-    # a learned parameter, which is not this change.
     from ..retrieval.verdict import retrieval_verdict_for_index as _rv
     _vres = _rv(
         index,
@@ -866,6 +867,10 @@ def _get_tokens_fusion(sym):
         query_terms=query_terms,
         scope=scope,
         state_before=state_before,
+        # v1.108.186. Same derivation as the ledger row above, so the response and
+        # the ledger cannot disagree about the same call again — which is exactly
+        # what they did while this defaulted to `off` and the ledger said True.
+        semantic_channel="ok" if _semantic_used else "off",
     )
     fusion_result["_meta"]["verdict"] = _vres["verdict"]
     if _vres["negative_evidence"] is not None: