feat: credential-signal retirement — explicit mode signal + server-reported threshold gate (nexus-9o6y2.13-.17)

RDR-188 P3, the R5 category-(c) designs. The client voyage key now has
ZERO behavioral influence anywhere:

.13 is_local_mode(): NEW explicit positive signal — pg_credentials
presence (the record that a local service was provisioned) → local,
above the legacy fallback, below service_url (a migrated local→managed
install keeps the stale file; the configured endpoint wins). The legacy
fallback shrinks to chroma-key-only; the voyage clause is DELETED
(Gap 3: blanking the unconsumed key must never flip mode). A
chroma-without-voyage install reclassifies local→cloud deliberately:
half-configured cloud should surface its missing key, not silently go
local. Regression pin: key blanking never changes the mode result.

.14 _voyage_thresholds_active(): the service-mode leg consults the
SERVER's reported embedder family — HttpVectorClient.embedding_mode()
(GET /version, memoized per instance on success; failed probes return
unknown WITHOUT memoizing so recovery re-probes). Thresholds on iff the
engine says voyage. Client-key read deleted; process-global memo +
reset_threshold_gate_cache_for_tests retired (the memo lives on the
handle now). Mutation-verified: hardcoding the gate fails 2 tests.

.15 supervisor plumb: SCOPE DECISION recorded in the plumb block —
engine-bootstrap material per End State 1; engine-owned credential
files rejected (same disk, spawn is already the trust boundary).

.16 sweep: doctor's check-quotas voyage line is INFO-framed (bootstrap/
migration material, never a client-capability warning); mcp mode
diagnostic tracks the new 4-branch precedence (+pg_credentials_found;
voyage_key_found retained as explicitly-informational).

.17 mode-lint tripwires: is_local_mode source must not read the voyage
credential; the threshold gate must consult embedding_mode() and never
get_credential. 200 tests green across the affected suites.

Author: Hellblazer

src/nexus/commands/doctor.py

@@ -2144,9 +2144,16 @@ def _format_quota_report(report: dict) -> str:
 
     # ── Voyage ───────────────────────────────────────────────────────────
     v = report["voyage"]
-    status = _CHECK if v["api_key_set"] else _WARN
-    key_label = "VOYAGE_API_KEY: set" if v["api_key_set"] else "VOYAGE_API_KEY: absent"
-    lines.append(f"  {status} Voyage AI: {key_label}")
+    # RDR-188 (nexus-9o6y2.16): the client key is engine-bootstrap/migration
+    # material — absence is INFO, not a warning (no client code path consumes
+    # it; the engine's own key state is what matters and doctor's service
+    # checks cover that).
+    key_label = (
+        "VOYAGE_API_KEY: set (engine-bootstrap/migration material)"
+        if v["api_key_set"]
+        else "VOYAGE_API_KEY: absent (client does not consume it; engine key plumbed at spawn)"
+    )
+    lines.append(f"  {_CHECK} Voyage AI: {key_label}")
     lines.append(f"    target rpm (indexer rate limiter):        {v['target_rpm']}")
     for model, caps in v["models"].items():
         lines.append(

src/nexus/config.py

@@ -582,9 +582,19 @@ def is_local_mode() -> bool:
         local (nexus-3k43p: the legacy heuristic below mis-detected a greenfield
         managed user — service_url set, no chroma/voyage key — as local). This
         mirrors ``_resolve_init_mode``'s precedence (NX_LOCAL wins over
-        service_url, which wins over the legacy heuristic).
-      - Otherwise (legacy, pre-6.0): True when **either** CHROMA_API_KEY or
-        VOYAGE_API_KEY is absent.
+        service_url, which wins over the rest). Wins over ``pg_credentials``
+        too: a migrated local→managed install keeps the old file on disk.
+      - ``pg_credentials`` present in the config dir → True — the EXPLICIT
+        positive record that a local service was provisioned (``nx init``
+        local mode; the same signal health.py gates its service checks on).
+        RDR-188 P3.1 (nexus-9o6y2.13): mode comes from explicit install
+        state, not key inference.
+      - Otherwise (legacy, pre-service Chroma era): True when CHROMA_API_KEY
+        is absent. The voyage clause is DELETED (RDR-188 Gap 3): the client
+        no longer consumes the voyage key for anything, so its presence or
+        absence must have ZERO mode influence — a chroma-key-without-voyage
+        install is a half-configured CLOUD install whose missing key should
+        surface loudly, never a silent flip to local.
     """
     nx_local = os.environ.get("NX_LOCAL", "").strip()
     if nx_local == "1":
@@ -593,10 +603,12 @@ def is_local_mode() -> bool:
         return False
     if (get_credential("service_url") or "").strip():
         return False
-    # Auto-detect (legacy): local mode when either cloud credential is missing
-    chroma_key = get_credential("chroma_api_key")
-    voyage_key = get_credential("voyage_api_key")
-    return not (chroma_key and voyage_key)
+    from nexus.db.pg_provision import CREDENTIALS_FILENAME  # noqa: PLC0415 — leaf constant, deferred to keep config import-light
+
+    if (nexus_config_dir() / CREDENTIALS_FILENAME).is_file():
+        return True
+    # Auto-detect (legacy): a Chroma-Cloud key marks a cloud install.
+    return not get_credential("chroma_api_key")
 
 
 # RDR-101 Phase 5c (nexus-o6aa.13) removed ``is_catalog_event_sourced``.

src/nexus/daemon/storage_service_daemon.py

@@ -537,6 +537,15 @@ def _spawn_service(self) -> tuple[subprocess.Popen[bytes], int]:
         # credentials) so `nx daemon service start` works without manual env
         # plumbing. An explicit NX_VOYAGE_API_KEY in the caller's env wins.
         #
+        # SCOPE DECISION (RDR-188 P3.3, bead nexus-9o6y2.15 — End State 1):
+        # this plumb is ENGINE-BOOTSTRAP material, not client consumption.
+        # The voyage key may persist in config.yml on local-service installs
+        # SOLELY as the delivery wire for the engine's own embed+rerank key
+        # at spawn time; zero client code paths consume it (enforced by the
+        # tests/test_rdr188_tripwires.py suite). Engine-owned credential
+        # files were considered and rejected: the key lives on the same disk
+        # either way, and this spawn is already the trust boundary.
+        #
         # nexus-r5f3c: the configured local embed model is the INTENT record.
         # `nx init` (local mode) provisions bge-768 and saves
         # ``local.embed_model``; plumbing an ambient VOYAGE_API_KEY anyway

src/nexus/db/http_vector_client.py

@@ -991,6 +991,36 @@ def put(
     #: never asked to rerank.
     supports_server_rerank: bool = True
 
+    #: Memoized GET /version ``embedding_mode`` (class-level default so
+    #: partially-constructed test instances still resolve; successful probes
+    #: shadow it per-instance). RDR-188 P3.2 (nexus-9o6y2.14).
+    _embedding_mode_memo: str | None = None
+
+    def embedding_mode(self) -> str | None:
+        """The engine's AUTHORITATIVE embedder family from ``GET /version``:
+        ``"voyage"`` or ``"onnx-local"`` (``EmbedderRouter.modeName``).
+
+        RDR-188 P3.2 (nexus-9o6y2.14): this replaces client-key inference as
+        the search threshold gate's signal — thresholds are calibrated for
+        Voyage embeddings, and whether Voyage served the query is a fact
+        about the SERVER, not about which keys sit in client config.
+
+        Memoized per instance on success (the engine's mode is fixed for its
+        process lifetime). A failed probe returns ``None`` WITHOUT memoizing —
+        unknown, not "not voyage" — so a service that was briefly unreachable
+        is re-asked on the next call rather than locking thresholds off.
+        """
+        if self._embedding_mode_memo is None:
+            try:
+                info = _get("/version", tenant=self._tenant)
+            except Exception as exc:  # noqa: BLE001 — probe is advisory; search itself surfaces a down service
+                _log.debug("embedding_mode_probe_failed", error=str(exc))
+                return None
+            mode = info.get("embedding_mode") if isinstance(info, dict) else None
+            if isinstance(mode, str) and mode:
+                self._embedding_mode_memo = mode
+        return self._embedding_mode_memo
+
     def search(
         self,
         query: str,

src/nexus/mcp/core.py

@@ -6532,13 +6532,18 @@ def _resolve_mode_diagnostics() -> dict[str, str | None]:
     live Desktop run leaves a durable on-disk trail in mcp.log instead of
     requiring the divergence to be reproduced first.
 
-    nexus-smd1k (substantive-critic finding): ``is_local_mode()`` has THREE
-    decision branches (explicit ``NX_LOCAL``, ``service_url`` presence,
-    legacy chroma/voyage-key presence) — per the bead's own CLI-vs-GUI
-    divergence evidence, the more likely root cause sits in branch 2 or 3,
-    not branch 1. ``service_url_found``/``chroma_key_found``/
-    ``voyage_key_found`` evidence which credential each branch actually
-    saw, as booleans ONLY — never the credential values themselves.
+    nexus-smd1k (substantive-critic finding): ``is_local_mode()`` has FOUR
+    decision branches since RDR-188 P3.1 (explicit ``NX_LOCAL``,
+    ``service_url`` presence, ``pg_credentials`` presence, legacy
+    chroma-key fallback) — per the bead's own CLI-vs-GUI divergence
+    evidence, the likely root cause sits below branch 1.
+    ``service_url_found``/``pg_credentials_found``/``chroma_key_found``
+    evidence what each branch actually saw, as booleans ONLY — never the
+    credential values. ``voyage_key_found`` is retained as INFORMATIONAL
+    (nexus-9o6y2.16): since RDR-188 the voyage key has ZERO mode
+    influence — it is engine-bootstrap/migration material; the boolean
+    stays because a divergence report that shows it TRUE while mode
+    flips would immediately falsify a suspected key-inference regression.
 
     Never raises: a diagnostic must not block MCP startup. On resolution
     failure returns ``{"mode": "unknown", "error": str(exc)}``.
@@ -6559,7 +6564,9 @@ def _resolve_mode_diagnostics() -> dict[str, str | None]:
             "home": _os.environ.get("HOME", ""),
             "nx_local_env": _os.environ.get("NX_LOCAL", ""),
             "service_url_found": bool(get_credential("service_url")),
+            "pg_credentials_found": (nexus_config_dir() / "pg_credentials").is_file(),
             "chroma_key_found": bool(get_credential("chroma_api_key")),
+            # Informational only — zero mode influence since RDR-188 P3.1.
             "voyage_key_found": bool(get_credential("voyage_api_key")),
         }
     except Exception as exc:  # noqa: BLE001 — diagnostic-only, must never block startup

src/nexus/search_engine.py

@@ -307,37 +307,24 @@ def _voyage_thresholds_active(t3: Any) -> bool:
     that attribute, so filtering silently disabled on every service-mode
     search — the same bug class as the reranker (nexus-xbw0f).
 
-    The fallback preserves the original semantics for HttpVectorClient:
-    Voyage is in use iff NOT local mode (local embeds with bge/MiniLM —
-    Voyage-calibrated thresholds must stay off) AND a Voyage key is
-    configured. Other handles (test fakes, injected stubs) keep the
+    RDR-188 P3.2 (nexus-9o6y2.14): for HttpVectorClient the signal is the
+    SERVER-reported embedder family (``t3.embedding_mode()`` from
+    ``GET /version``) — thresholds on iff the engine embeds with Voyage.
+    The former client-key heuristic is retired with the client's Voyage
+    consumption. Other handles (test fakes, injected stubs) keep the
     attribute-only gate.
     """
     if getattr(t3, "_voyage_client", None) is not None:
         return True
     if not isinstance(t3, HttpVectorClient):
         return False
-    global _service_thresholds_memo
-    if _service_thresholds_memo is None:
-        # Memoized for the process lifetime (wave review): is_local_mode +
-        # get_credential each re-read config.yml, a per-search file-IO cost.
-        # Mode/credential changes require a process restart — same lifetime
-        # the retired T3Database gave its _voyage_client.
-        from nexus.config import get_credential, is_local_mode  # noqa: PLC0415 — circular-dep avoidance (config)
-
-        _service_thresholds_memo = (
-            not is_local_mode() and bool(get_credential("voyage_api_key"))
-        )
-    return _service_thresholds_memo
-
-
-_service_thresholds_memo: bool | None = None
-
-
-def reset_threshold_gate_cache_for_tests() -> None:
-    """Clear the service-mode threshold-gate memo (test isolation)."""
-    global _service_thresholds_memo
-    _service_thresholds_memo = None
+    # RDR-188 P3.2 (nexus-9o6y2.14): the gate consults the SERVER's reported
+    # embedder family (GET /version, memoized on the client handle) — not the
+    # client's credential file. Removing the now-unconsumed client voyage key
+    # can no longer silently regress search quality (Gap 3), and the signal is
+    # what actually embedded the corpus. Unknown (probe failed) → thresholds
+    # off: never guess Voyage; a down service fails the search itself anyway.
+    return t3.embedding_mode() == "voyage"
 
 
 def _overfetch_multiplier(collection_name: str) -> int:

tests/db/test_http_vector_client_rerank.py

@@ -96,3 +96,40 @@ def test_no_rerank_request_body_and_return_unchanged(client, monkeypatch):
     assert "rerank" not in captured[0]["body"]
     assert "rerank_top_k" not in captured[0]["body"]
     assert rows[0]["id"] == "a"
+
+
+# ── RDR-188 P3.2 (nexus-9o6y2.14): server-reported embedding mode ────────────
+
+
+def test_embedding_mode_reads_version_and_memoizes(client, monkeypatch):
+    calls: list[str] = []
+
+    def fake_get(path, tenant=None):
+        calls.append(path)
+        return {"embedding_mode": "voyage", "embedding_models": ["voyage-code-3"]}
+
+    monkeypatch.setattr(hvc, "_get", fake_get)
+    assert client.embedding_mode() == "voyage"
+    assert client.embedding_mode() == "voyage"
+    assert calls == ["/version"]  # memoized after first success
+
+
+def test_embedding_mode_probe_failure_returns_none_without_memoizing(client, monkeypatch):
+    attempts: list[int] = []
+
+    def failing_get(path, tenant=None):
+        attempts.append(1)
+        raise ConnectionError("service down")
+
+    monkeypatch.setattr(hvc, "_get", failing_get)
+    assert client.embedding_mode() is None
+    # Not memoized: recovery is re-probed, thresholds are not locked off.
+    monkeypatch.setattr(hvc, "_get",
+                        lambda path, tenant=None: {"embedding_mode": "onnx-local"})
+    assert client.embedding_mode() == "onnx-local"
+    assert attempts == [1]
+
+
+def test_embedding_mode_garbage_version_body_is_unknown(client, monkeypatch):
+    monkeypatch.setattr(hvc, "_get", lambda path, tenant=None: ["not", "a", "dict"])
+    assert client.embedding_mode() is None

tests/test_local_mode.py

@@ -49,7 +49,11 @@ class TestIsLocalMode:
             pytest.param({"NX_LOCAL": "0"}, False, id="nx_local_0_overrides"),
             pytest.param({}, True, id="no_credentials"),
             pytest.param({"CHROMA_API_KEY": "k", "VOYAGE_API_KEY": "k"}, False, id="both_keys"),
-            pytest.param({"CHROMA_API_KEY": "k"}, True, id="chroma_only"),
+            # RDR-188 P3.1 (nexus-9o6y2.13): the legacy fallback is chroma-only.
+            # A chroma key marks a Chroma-Cloud install even with no voyage key
+            # (half-configured cloud surfaces its missing key loudly instead of
+            # silently flipping local).
+            pytest.param({"CHROMA_API_KEY": "k"}, False, id="chroma_only_is_cloud"),
             pytest.param({"VOYAGE_API_KEY": "k"}, True, id="voyage_only"),
             # nexus-3k43p: a managed 6.0 user (service_url set, no chroma/voyage
             # key) must NOT be mis-detected as local. service_url presence wins
@@ -68,8 +72,55 @@ def test_is_local_mode(
         for k, v in env.items():
             monkeypatch.setenv(k, v)
         monkeypatch.setenv("HOME", str(tmp_path))
+        monkeypatch.setenv("NEXUS_CONFIG_DIR", str(tmp_path / "cfg"))
         assert is_local_mode() is expected
 
+    def _cfg(self, tmp_path, monkeypatch, *, pg_creds: bool):
+        cfg = tmp_path / "cfg"
+        cfg.mkdir(exist_ok=True)
+        monkeypatch.setenv("NEXUS_CONFIG_DIR", str(cfg))
+        monkeypatch.setenv("HOME", str(tmp_path))
+        for var in ("NX_LOCAL", "CHROMA_API_KEY", "VOYAGE_API_KEY", "NX_SERVICE_URL"):
+            monkeypatch.delenv(var, raising=False)
+        if pg_creds:
+            from nexus.db.pg_provision import CREDENTIALS_FILENAME
+            (cfg / CREDENTIALS_FILENAME).write_text("PGHOST=127.0.0.1\n")
+
+    # ── RDR-188 P3.1 (nexus-9o6y2.13): explicit local signal + no voyage clause ──
+
+    def test_pg_credentials_is_the_explicit_local_signal(self, tmp_path, monkeypatch):
+        """A provisioned local service (pg_credentials present) is LOCAL even
+        when legacy cloud keys sit in the environment (they are migration-
+        source / engine-bootstrap material, not mode signals)."""
+        self._cfg(tmp_path, monkeypatch, pg_creds=True)
+        monkeypatch.setenv("CHROMA_API_KEY", "k")
+        monkeypatch.setenv("VOYAGE_API_KEY", "k")
+        assert is_local_mode() is True
+
+    def test_service_url_beats_pg_credentials(self, tmp_path, monkeypatch):
+        """A migrated local→managed install keeps its old pg_credentials on
+        disk; the configured service_url must win (managed, not local)."""
+        self._cfg(tmp_path, monkeypatch, pg_creds=True)
+        monkeypatch.setenv("NX_SERVICE_URL", "https://m.example")
+        assert is_local_mode() is False
+
+    def test_blanking_voyage_key_never_changes_mode(self, tmp_path, monkeypatch):
+        """Gap 3's regression pin: the client no longer consumes the voyage
+        key (RDR-188), so its presence/absence must have ZERO mode influence
+        in every branch."""
+        self._cfg(tmp_path, monkeypatch, pg_creds=False)
+        monkeypatch.setenv("CHROMA_API_KEY", "k")
+        monkeypatch.setenv("VOYAGE_API_KEY", "k")
+        with_key = is_local_mode()
+        monkeypatch.delenv("VOYAGE_API_KEY")
+        assert is_local_mode() is with_key
+
+        monkeypatch.delenv("CHROMA_API_KEY")
+        monkeypatch.setenv("VOYAGE_API_KEY", "k")
+        with_key_no_chroma = is_local_mode()
+        monkeypatch.delenv("VOYAGE_API_KEY")
+        assert is_local_mode() is with_key_no_chroma
+
 
 class TestDefaultLocalPath:
     @pytest.mark.parametrize(

tests/test_rdr188_tripwires.py

@@ -228,3 +228,35 @@ def fake(q, cols, n_results, t3, where=None, *, rerank=False,
     assert res.exit_code == 0, res.output
     assert "server rerank degraded" in res.output
     assert "engine says no" in res.output
+
+
+# ── 5. P3 mode-lint (nexus-9o6y2.17): retired voyage heuristics stay gone ───
+
+
+def test_is_local_mode_source_has_no_voyage_clause():
+    """.13's deletion, pinned at source level: the mode decision must never
+    again read the voyage credential."""
+    src = (_SRC / "config.py").read_text()
+    start = src.index("def is_local_mode(")
+    end = src.index("\ndef ", start + 10)
+    body = src[start:end]
+    # The docstring legitimately EXPLAINS the deletion; the lint targets the
+    # credential-read token itself.
+    assert 'get_credential("voyage' not in body, (
+        "is_local_mode() reads the voyage credential again — RDR-188 P3.1 "
+        "deleted key inference from the mode decision"
+    )
+
+
+def test_threshold_gate_source_reads_server_mode_not_client_key():
+    """.14's rewrite, pinned: the service-mode threshold gate consults the
+    server's embedding_mode, never the client credential file."""
+    src = (_SRC / "search_engine.py").read_text()
+    start = src.index("def _voyage_thresholds_active(")
+    end = src.index("\ndef ", start + 10)
+    body = src[start:end]
+    assert "embedding_mode()" in body
+    assert "get_credential" not in body, (
+        "_voyage_thresholds_active reads client credentials again — the "
+        "signal is the SERVER's reported embedder family (RDR-188 P3.2)"
+    )