Python
fix(memhub): make the embedding switch work on real graphs and SDK services
alvinfei7df371bb10c1
diff --git a/memhub/apps/core/src/one_memory/embedding_switch.py b/memhub/apps/core/src/one_memory/embedding_switch.pyindex 60e2a3c..011a579 100644--- a/memhub/apps/core/src/one_memory/embedding_switch.py+++ b/memhub/apps/core/src/one_memory/embedding_switch.py@@ -556,13 +556,12 @@ class EmbeddingSwitchService:)total = sum(item.vectors for item in sources)graph_vectors: int | None = None- if self.graph_enabled():- graph = self._graph_path(live)- if graph.exists() and unavailable is None:- try:- graph_vectors = await self.backend.graph_vectors(graph)- except Exception: # noqa: BLE001 - the plan reports what it can- logger.warning("embedding_switch_plan_graph_unreadable", exc_info=True)+ graph = self._graph_path(live)+ if graph.exists() and unavailable is None:+ try:+ graph_vectors = await self.backend.graph_vectors(graph)+ except Exception: # noqa: BLE001 - a client may hold it open: null, not a refusal+ logger.info("embedding_switch_plan_graph_unreadable")dims = identity.dims or 1024needed_bytes = (int((total + (graph_vectors or 0)) * (dims * 4 + _BYTES_PER_VECTOR_OVERHEAD) * 1.5)@@ -1226,8 +1225,10 @@ class EmbeddingSwitchService:target: EmbeddingSpace,embedding: EmbeddingTarget,) -> None:+ # Whatever the mode: a pro home can hold the graph of its ultra days,+ # and it would otherwise be dropped with the old space.source_graph = self._graph_path(source)- if not self.graph_enabled() or not _graph_has_files(source_graph):+ if not _graph_has_files(source_graph):returntarget_dims = target.dims or target.name_dimsif target_dims is None:@@ -1247,8 +1248,11 @@ class EmbeddingSwitchService:release()async def _quiesce(self) -> Callable[[], None]:- """Close every SDK client so the graph can be read; reads wait meanwhile."""- if self.quiesce_clients is None:+ """Close every SDK client so the graph can be read; reads wait meanwhile.++ Only ultra clients hold the graph, so other modes keep serving reads.+ """+ if self.quiesce_clients is None or not self.graph_enabled():return lambda: Nonereturn await self.quiesce_clients()@@ -1292,11 +1296,17 @@ class EmbeddingSwitchService:for user, count in (live_scan.per_user if live_scan else {}).items():if check.per_user.get(user, 0) < count:problems.append(f"user {user!r}: target holds fewer records")- if self.graph_enabled() and _graph_has_files(self._graph_path(source)):+ if _graph_has_files(self._graph_path(source)):dims = target.dims or target.name_dims or 0- graph = await self.backend.verify_graph(- self._graph_path(source), self._graph_path(target), target_dims=dims- )+ # Reads are served between the copy and here: a client may+ # hold the graph again, and the SDK refuses to open it then.+ release = await self._quiesce()+ try:+ graph = await self.backend.verify_graph(+ self._graph_path(source), self._graph_path(target), target_dims=dims+ )+ finally:+ release()report["graph"] = {"ok": graph.ok, "problems": list(graph.problems)}problems.extend(f"graph: {item}" for item in graph.problems)report["problems"] = problems@@ -1417,7 +1427,7 @@ class EmbeddingSwitchService:await self.backend.drop_graph(self._graph_path(target))except ReembedUnavailableError:pass- except Exception: # noqa: BLE001 - leftovers are dropped by the sweep+ except Exception: # noqa: BLE001 - the next start's scan merges and retires itlogger.warning("embedding_switch_rollback_drop_failed", exc_info=True)await asyncio.to_thread(self.spaces.mark_dropped, target.space_id)now = _now().isoformat()diff --git a/memhub/apps/core/src/one_memory/hy_sdk_migration.py b/memhub/apps/core/src/one_memory/hy_sdk_migration.pyindex d128c10..cd51967 100644--- a/memhub/apps/core/src/one_memory/hy_sdk_migration.py+++ b/memhub/apps/core/src/one_memory/hy_sdk_migration.py@@ -11,6 +11,7 @@ read and fill SDK collections through the SDK's re-embed module.from __future__ import annotations+import asyncioimport jsonimport sqlite3from collections.abc import Iterator@@ -546,6 +547,7 @@ class SdkReembedBackend:self.data_dir = data_dirself.root = data_dir.resolve() / "hy-memory" / HY_MEMORY_NAMESPACEself.persist_directory = self.root / "vector"+ self._chroma_opened = Falsedef unavailable_reason(self) -> str | None:missing = [name for name in _REEMBED_API if not hasattr(hy_memory, name)]@@ -559,6 +561,23 @@ class SdkReembedBackend:raise ReembedUnavailableError(reason)return hy_memory+ def _open_chroma_once(self) -> None:+ """Open Chroma once under the client-construction lock.++ Every later open beside the Runtime finds that system. Two first+ opens race over Chroma's unlocked cache, and a client under+ construction lost its stores that way (see `hy_sdk_runtime`).+ """+ if self._chroma_opened or not self.persist_directory.is_dir():+ return+ import chromadb++ from one_memory.hy_sdk_runtime import first_store_open++ with first_store_open(self.data_dir):+ chromadb.PersistentClient(path=str(self.persist_directory))+ self._chroma_opened = True+def _vector_space(self, space: Any) -> Any:return self._sdk().VectorSpace(base_name=space.collection_base,@@ -573,6 +592,7 @@ class SdkReembedBackend:if not self.persist_directory.is_dir():return ()+ await asyncio.to_thread(self._open_chroma_once)found = await self._sdk().scan_vector_spaces(str(self.persist_directory), per_user=per_user)return tuple(ScannedSpace(@@ -587,6 +607,7 @@ class SdkReembedBackend:)async def diff(self, source: Any, target: Any) -> dict[str, int]:+ await asyncio.to_thread(self._open_chroma_once)result = await self._sdk().diff_spaces(self._vector_space(source), self._vector_space(target))@@ -604,6 +625,7 @@ class SdkReembedBackend:) -> None:from one_memory.embedding_backend import ReembedStep+ await asyncio.to_thread(self._open_chroma_once)sdk = self._sdk()def progress(item: Any) -> None:@@ -635,6 +657,7 @@ class SdkReembedBackend:async def verify(self, source: Any, target: Any, *, embedding: Any) -> Any:from one_memory.embedding_backend import VectorCheck+ await asyncio.to_thread(self._open_chroma_once)with self._translated():result = await self._sdk().verify_reembed(self._vector_space(source),@@ -699,6 +722,7 @@ class SdkReembedBackend:return GraphCheck(ok=bool(result.ok), problems=tuple(result.problems))async def drop(self, space: Any) -> None:+ await asyncio.to_thread(self._open_chroma_once)await self._sdk().drop_vector_space(self._vector_space(space))async def drop_graph(self, path: Path) -> None:@@ -711,7 +735,11 @@ class SdkReembedBackend:client embeds with. A remote model gets the SDK's own service, builtfrom the same configuration the Runtime client would use."""- from one_memory.hy_sdk_runtime import LocalOnnxEmbeddingService, build_sdk_config+ from one_memory.hy_sdk_runtime import (+ LocalOnnxEmbeddingService,+ build_sdk_config,+ retrieval_view,+ )from one_memory.model_profiles import ProviderKindprofile = embedding.profile@@ -721,8 +749,12 @@ class SdkReembedBackend:from hy_memory.core.embed_service import EmbedService # type: ignore[import-untyped]return EmbedService(+ # The retrieval view: re-embedding never needs the generation model.build_sdk_config(- profile, embedding.space, api_key=embedding.api_key, data_dir=self.data_dir+ retrieval_view(profile),+ embedding.space,+ api_key=embedding.api_key,+ data_dir=self.data_dir,))diff --git a/memhub/apps/core/src/one_memory/hy_sdk_runtime.py b/memhub/apps/core/src/one_memory/hy_sdk_runtime.pyindex 01c7592..2458431 100644--- a/memhub/apps/core/src/one_memory/hy_sdk_runtime.py+++ b/memhub/apps/core/src/one_memory/hy_sdk_runtime.py@@ -11,7 +11,8 @@ import asyncioimport hashlibimport osimport threading-from collections.abc import Callable, Coroutine, Iterable, Mapping+from collections.abc import Callable, Coroutine, Iterable, Iterator, Mapping+from contextlib import contextmanagerfrom dataclasses import dataclassfrom pathlib import Pathfrom typing import Any, ClassVar, Literal, cast@@ -521,6 +522,20 @@ def acquire_client(_STORE_GATE.notify_all()+@contextmanager+def first_store_open(data_dir: Path) -> Iterator[None]:+ """One opening of this home's stores at a time: Chroma's first open is unlocked.++ The same lock client construction takes, for anything else that opens+ Chroma beside the Runtime (the re-embed functions).+ """+ key = data_dir.resolve()+ with _STORE_GATE:+ constructing = _CONSTRUCTING.setdefault(key, threading.Lock())+ with constructing:+ yield++def hold_stores_offline(data_dir: Path) -> bool:"""Hold this home's SDK stores for offline maintenance; False if a client is open.diff --git a/memhub/apps/core/src/one_memory/sdk_read_handle.py b/memhub/apps/core/src/one_memory/sdk_read_handle.pyindex 8b8cace..ab8d046 100644--- a/memhub/apps/core/src/one_memory/sdk_read_handle.py+++ b/memhub/apps/core/src/one_memory/sdk_read_handle.py@@ -156,7 +156,14 @@ class ActiveProfileReadHandle(SdkClientHandle):if active is not None and self._reads(active, space):return space, activeif space.profile_id is not None and space.profile_revision is not None:- return space, (space.profile_id, space.profile_revision)+ identity = (space.profile_id, space.profile_revision)+ try:+ self.profiles.snapshot(*identity)+ except KeyError:+ # Its endpoint and key went with the profile; the built-in+ # model cannot read these vectors. Say so, never read wrong.+ raise HySdkRuntimeError("embedding_space_profile_missing") from None+ return space, identityreturn space, _BUILTINdef _reads(self, identity: tuple[str, int], space: EmbeddingSpace) -> bool:diff --git a/memhub/apps/core/tests/test_embedding_switch.py b/memhub/apps/core/tests/test_embedding_switch.pyindex 437e9de..33e05d9 100644--- a/memhub/apps/core/tests/test_embedding_switch.py+++ b/memhub/apps/core/tests/test_embedding_switch.py@@ -1036,7 +1036,8 @@ async def test_ultra_mode_builds_a_new_graph_at_the_target_width(tmp_path: Path)assert home.backend.graphs_built == [built]assert (built / "width").read_text() == "1024"assert graph.exists() # the source graph is untouched, kept with the old space- assert quiesced == ["closed", "released"]+ # Once to copy the graph, once to verify it.+ assert quiesced == ["closed", "released", "closed", "released"]async def test_a_job_another_live_core_still_beats_for_is_not_taken_over(tmp_path: Path) -> None:@@ -1055,3 +1056,60 @@ async def test_a_job_another_live_core_still_beats_for_is_not_taken_over(tmp_patassert second._task is Noneassert not second.writes_open()assert second.jobs.get(job_id)["state"] == "preparing"+++def test_a_live_space_whose_profile_was_deleted_says_so_on_read(tmp_path: Path) -> None:+ from one_memory.sdk_read_handle import ActiveProfileReadHandle++ home = Home(tmp_path)+ profile = home.profile(activate=True)+ home.bootstrap()+ home.profiles.delete(profile.profile_id, home.secrets)+ handle = ActiveProfileReadHandle(+ profiles=home.profiles, secrets=home.secrets, data_dir=tmp_path, spaces=home.spaces+ )++ with pytest.raises(HySdkRuntimeError, match="embedding_space_profile_missing"):+ handle._resolve()+++async def test_legacy_collections_block_a_switch_until_they_are_reattached(+ tmp_path: Path, monkeypatch+) -> None:+ home = Home(tmp_path)+ seed_builtin(home)+ target = home.profile()+ monkeypatch.setattr(+ "one_memory.sdk_vector_reattach.legacy_vector_collections",+ lambda _data_dir, _profile: (("one_memory_abc", "memhub_abc"),),+ )++ plan = await home.service().plan(target.profile_id)++ assert "embedding_switch_requires_migration" in plan.blockers+++def test_sdk_migrate_leaves_an_unfinished_switch_alone(tmp_path: Path) -> None:+ """The upgrade path runs the real migration entry on a home mid-switch."""+ from one_memory.sdk_migration_runner import run_startup_migration+ from one_memory.target_schema import bootstrap_fresh_management_schema++ assert bootstrap_fresh_management_schema(tmp_path / "one-memory.sqlite3")+ home = Home(tmp_path)+ live = seed_builtin(home)+ target = home.profile()+ service = home.service()+ job_id = asyncio.run(start(home, service, target))+ service.jobs.update(job_id, state="reembedding")+ before = (home.spaces.list_spaces(), dict(service.jobs.get(job_id)))++ result = run_startup_migration(+ data_dir=tmp_path,+ runtime_build="99",+ sdk_version="2.0.10",+ namespace="governed-v2",+ )++ assert result.state == "not_required"+ assert (home.spaces.list_spaces(), dict(service.jobs.get(job_id))) == before+ assert home.spaces.require_live().space_id == live.space_iddiff --git a/memhub/apps/core/tests/test_embedding_switch_sdk_adapter.py b/memhub/apps/core/tests/test_embedding_switch_sdk_adapter.pyindex a1f98b1..79c5f4e 100644--- a/memhub/apps/core/tests/test_embedding_switch_sdk_adapter.py+++ b/memhub/apps/core/tests/test_embedding_switch_sdk_adapter.py@@ -10,6 +10,7 @@ from __future__ import annotationsimport asynciofrom pathlib import Path+import hy_memoryimport pytestfrom one_memory.embedding_backend import EmbeddingTarget, PhysicalSpace@@ -269,3 +270,335 @@ def test_a_whole_switch_through_the_real_sdk(tmp_path: Path, monkeypatch) -> Nonstates = {space.collection_base: space.state for space in spaces.list_spaces()}assert states[live.collection_base] == "retired"assert states[stray_base] == "retired"+++# ----------------------------------------------------------------------+# Nothing stood in: the SDK's EmbedService over HTTP, real Chroma, real Kuzu+# ----------------------------------------------------------------------+++class _EmbeddingServer:+ """A local OpenAI-compatible `/embeddings` endpoint; counts what it was sent."""++ def __init__(self, width: int) -> None:+ import json+ import threading+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer++ self.width = width+ self.inputs: list[str] = []+ self.dimensions: list[object] = []+ server = self++ class Handler(BaseHTTPRequestHandler):+ def do_POST(self) -> None: # noqa: N802 - http.server's name+ body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))+ texts = body["input"] if isinstance(body["input"], list) else [body["input"]]+ server.inputs.extend(texts)+ server.dimensions.append(body.get("dimensions"))+ payload = json.dumps(+ {+ "object": "list",+ "model": body["model"],+ "data": [+ {+ "object": "embedding",+ "index": index,+ "embedding": [(len(text) % 7 + 1) / 8.0] + [0.5] * (width - 1),+ }+ for index, text in enumerate(texts)+ ],+ "usage": {"prompt_tokens": 1, "total_tokens": 1},+ }+ ).encode()+ self.send_response(200)+ self.send_header("Content-Type", "application/json")+ self.send_header("Content-Length", str(len(payload)))+ self.end_headers()+ self.wfile.write(payload)++ def log_message(self, *_args: object) -> None:+ return++ self._server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)+ self.url = f"http://127.0.0.1:{self._server.server_port}/v1"+ threading.Thread(target=self._server.serve_forever, daemon=True).start()++ def close(self) -> None:+ self._server.shutdown()+ self._server.server_close()+++def _home(tmp_path: Path, *, embedding_provider, embedding_url: str, api_key: str | None):+ from pydantic import SecretStr++ from one_memory.embedding_spaces import EmbeddingSpaceStore+ from one_memory.model_profiles import (+ ModelCapabilities,+ ModelProfileInput,+ ModelProfileStore,+ ProviderKind,+ )+ from one_memory.secrets import InMemorySecretStore++ database = tmp_path / "one-memory.sqlite3"+ secrets = InMemorySecretStore()+ profiles = ModelProfileStore(database)+ spaces = EmbeddingSpaceStore(database)+ created = profiles.create(+ ModelProfileInput(+ name="target",+ provider_kind=ProviderKind.OPENAI_COMPATIBLE,+ base_url=embedding_url,+ model="chat",+ embedding_provider_kind=embedding_provider,+ embedding_base_url=embedding_url,+ embedding_model="stand-in",+ embedding_dimensions=8,+ api_key=SecretStr(api_key) if api_key else None,+ ),+ secrets,+ )+ profiles.record_capabilities(+ created.profile_id,+ expected_revision=created.revision,+ capabilities=ModelCapabilities(+ endpoint_reachable=True,+ model_available=True,+ structured_output=True,+ embedding_available=True,+ ),+ secrets=secrets,+ )+ return database, secrets, profiles, spaces, created+++def _service(database, data_dir, profiles, spaces, secrets, **options):+ from one_memory.embedding_switch import EmbeddingSwitchService++ service = EmbeddingSwitchService(+ database_path=database,+ data_dir=data_dir,+ profiles=profiles,+ spaces=spaces,+ secrets=secrets,+ backend=SdkReembedBackend(data_dir),+ worker_enabled=False,+ **options,+ )+ service.release_scan_hold()+ return service+++async def _switch(service, created) -> object:+ plan = await service.plan(created.profile_id)+ assert plan.needed and not plan.blockers, plan+ job = await service.start_switch(+ created.profile_id,+ expected_revision=created.revision,+ plan_token=plan.plan_token,+ requested_by="cli",+ )+ await service.run(job.job_id)+ finished = service.get_job(job.job_id)+ assert finished.state == "done", (+ finished.error_code,+ service.jobs.get(job.job_id)["verification_json"],+ service.jobs.get(job.job_id)["error_detail"],+ )+ return finished+++def _seed_vectors(data_dir: Path, space) -> None:+ import chromadb++ vector = data_dir / "hy-memory" / "governed-v2" / "vector"+ vector.mkdir(parents=True, exist_ok=True)+ client = chromadb.PersistentClient(path=str(vector))+ memory = client.get_or_create_collection(+ space.collection_names()["memory"], metadata={"hnsw:space": "cosine"}+ )+ memory.add(+ ids=["a", "b"],+ embeddings=[[0.1] * 512, [0.2] * 512],+ documents=["one", "two"],+ metadatas=[{"user_id": "local"}, {"user_id": "hermes-a"}],+ )+++def test_a_switch_embeds_through_the_sdk_service_over_http(tmp_path: Path) -> None:+ from one_memory.model_profiles import ProviderKind++ server = _EmbeddingServer(8)+ try:+ database, secrets, profiles, spaces, created = _home(+ tmp_path,+ embedding_provider=ProviderKind.OPENAI_COMPATIBLE,+ embedding_url=server.url,+ api_key="sk-test",+ )+ _seed_vectors(tmp_path, spaces.bootstrap(None))+ service = _service(database, tmp_path, profiles, spaces, secrets)++ asyncio.run(_switch(service, created))++ assert {"one", "two"} <= set(server.inputs)+ assert set(server.dimensions) == {8}+ finally:+ server.close()+++def test_an_ollama_embedding_needs_no_generation_key_to_re_embed(tmp_path: Path) -> None:+ """A switch only embeds: the generation model's key is not its business."""+ from one_memory.embedding_backend import EmbeddingTarget+ from one_memory.embedding_spaces import embedding_identity+ from one_memory.model_profiles import ProviderKind++ server = _EmbeddingServer(8)+ try:+ _database, secrets, profiles, spaces, created = _home(+ tmp_path,+ embedding_provider=ProviderKind.OLLAMA,+ embedding_url=server.url,+ api_key="sk-test",+ )+ profile = profiles.snapshot(created.profile_id, created.revision)+ identity = embedding_identity(profile)+ target = EmbeddingSpace(+ space_id="t",+ state="building",+ model=identity.model,+ dims=8,+ name_dims=8,+ collection_base=TARGET,+ naming="v2",+ created_at="2026-11-01T00:00:00+00:00",+ )+ backend = SdkReembedBackend(tmp_path)++ # `api_key=None` is what `_embedding_target` resolves for Ollama.+ service = backend._embedding_service(+ EmbeddingTarget(profile=profile, space=target, api_key=None)+ )++ assert asyncio.run(service.embed_batch(["hello"], use_cache=False))[0][1] == 0.5+ finally:+ server.close()+++async def _seed_graph(path: Path, dims: int) -> None:+ from hy_memory.data.graph_store_kuzu import KuzuGraphStore+ from hy_memory.models.memory import MemoryLayer, MemoryNode++ config = hy_memory.MemoryConfig()+ config.graph_store.provider = "kuzu"+ config.graph_store.db_path = str(path)+ config.vector_store.embedding_dims = dims+ store = KuzuGraphStore(config)+ await store.initialize()+ assert store._available+ node = MemoryNode(+ user_id="local",+ agent_id="a",+ session_id="s",+ layer=MemoryLayer.L6_SCHEMA,+ content="plans ahead",+ custom={"retrieval_text": "plans trips weeks ahead"},+ )+ node._graph_embedding = [0.1] * dims+ await store.upsert_memory_node(node)+ await store.close()++[email protected]("mode", ["ultra", "pro"])+def test_a_real_graph_moves_to_the_target_width(tmp_path: Path, mode: str) -> None:+ """In any mode: a pro home's old graph must not be lost with the old space."""+ from one_memory.hy_graph_admin import forget_graph_widths+ from one_memory.model_profiles import ProviderKind++ server = _EmbeddingServer(8)+ try:+ database, secrets, profiles, spaces, created = _home(+ tmp_path,+ embedding_provider=ProviderKind.OPENAI_COMPATIBLE,+ embedding_url=server.url,+ api_key="sk-test",+ )+ live = spaces.bootstrap(None)+ _seed_vectors(tmp_path, live)+ root = tmp_path / "hy-memory" / "governed-v2"+ asyncio.run(_seed_graph(root / "graph", 512))+ service = _service(+ database, tmp_path, profiles, spaces, secrets, graph_enabled=lambda: mode == "ultra"+ )++ asyncio.run(_switch(service, created))++ new = spaces.require_live()+ assert new.graph_dir != "graph" and (root / new.graph_dir).exists()+ assert (root / "graph").exists()+ assert "plans trips weeks ahead" in server.inputs+ forget_graph_widths()+ finally:+ server.close()+++def test_verifying_the_graph_closes_what_reads_reopened(tmp_path: Path) -> None:+ """Reads are served during a switch, so a client may hold the graph again."""+ from one_memory.model_profiles import ProviderKind++ server = _EmbeddingServer(8)+ quiesced: list[str] = []++ async def quiesce():+ quiesced.append("closed")+ return lambda: quiesced.append("released")++ try:+ database, secrets, profiles, spaces, created = _home(+ tmp_path,+ embedding_provider=ProviderKind.OPENAI_COMPATIBLE,+ embedding_url=server.url,+ api_key="sk-test",+ )+ live = spaces.bootstrap(None)+ _seed_vectors(tmp_path, live)+ asyncio.run(_seed_graph(tmp_path / "hy-memory" / "governed-v2" / "graph", 512))+ service = _service(+ database,+ tmp_path,+ profiles,+ spaces,+ secrets,+ graph_enabled=lambda: True,+ quiesce_clients=quiesce,+ )++ asyncio.run(_switch(service, created))++ # Once to copy the graph, once to verify it.+ assert quiesced == ["closed", "released", "closed", "released"]+ finally:+ server.close()+++def test_the_first_chroma_open_waits_for_a_client_under_construction(tmp_path: Path) -> None:+ """Two first opens on one directory race over Chroma's unlocked System cache."""+ import threading++ from one_memory.hy_sdk_runtime import first_store_open++ _seed(tmp_path)+ backend = SdkReembedBackend(tmp_path)+ finished = threading.Event()++ def scan() -> None:+ asyncio.run(backend.scan())+ finished.set()++ with first_store_open(tmp_path):+ thread = threading.Thread(target=scan)+ thread.start()+ assert not finished.wait(0.3)+ thread.join(10)+ assert finished.is_set()diff --git a/memhub/docs/contracts/embedding-switch-v1.md b/memhub/docs/contracts/embedding-switch-v1.mdindex ac9a76c..00deeb2 100644--- a/memhub/docs/contracts/embedding-switch-v1.md+++ b/memhub/docs/contracts/embedding-switch-v1.md@@ -51,9 +51,10 @@ start, follow and cancel. Core implementation: `embedding_switch.py`,next serving Core resumes the job from its state. The upgrade migration(`sdk-migrate`) never touches the switch tables; `sdk-migration-status`reports an open job as `embedding_switch` and does not block on it.-10. **Ultra graph.** With the graph store enabled the switch builds a new graph- at the target width. While it does, every SDK client is closed briefly, so- reads wait for that step.+10. **Graph.** Any graph the live space holds is rebuilt at the target width,+ whatever the mode, so a pro home keeps the graph of its ultra days. In ultra+ every SDK client is closed while the graph is copied and again while it is+ verified, so reads wait for those two steps; the other modes keep reading.## 2. Space registry@@ -121,7 +122,10 @@ Core's shape `{"detail": "<code>"}`; a refusal that computed a plan adds- `sources[0]` is the live space; further entries are strays folded in(`unmerged` = their record count). `users` counts distinct `user_id`s.- `requests` is null for a local target (no cost). `estimate_s` is a rough- guide (local ≈ 60 vectors/s, remote ≈ 200 vectors/s).+ guide (local ≈ 60 vectors/s, remote ≈ 200 vectors/s), not measured.+- `graph_vectors` is null when there is no graph, and also when an SDK client+ holds it open, as in ultra: the estimate and disk figures then leave the graph+ out. The switch still rebuilds it.- A non-empty `blockers` means the switch cannot start (§5.1).### 3.2 Job@@ -227,6 +231,7 @@ the startup scan, or null.| `model_profile_not_found` | 404 | unknown profile || `model_profile_conflict` | 409 | `expected_revision` stale || `embedding_unavailable` | 503 | search, recall, context, library search or ask could not embed the query (remote embedding down). No lexical fallback. |+| `embedding_space_profile_missing` | 503 | the profile that fills the live space was deleted and no active profile has its model and width; activate one that does |### 5.2 Job failure codes (`error_code` on a `rolled_back` job)