Skip to content
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.py
index 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 1024
needed_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):
return
target_dims = target.dims or target.name_dims
if 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: None
return 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 it
logger.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.py
index 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 asyncio
import json
import sqlite3
from collections.abc import Iterator
@@ -546,6 +547,7 @@ class SdkReembedBackend:
self.data_dir = data_dir
self.root = data_dir.resolve() / "hy-memory" / HY_MEMORY_NAMESPACE
self.persist_directory = self.root / "vector"
+ self._chroma_opened = False
def 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, built
from 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 ProviderKind
profile = 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.py
index 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 asyncio
import hashlib
import os
import threading
-from collections.abc import Callable, Coroutine, Iterable, Mapping
+from collections.abc import Callable, Coroutine, Iterable, Iterator, Mapping
+from contextlib import contextmanager
from dataclasses import dataclass
from pathlib import Path
from 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.py
index 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, active
if 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, identity
return space, _BUILTIN
def _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.py
index 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_pat
assert second._task is None
assert 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_id
diff --git a/memhub/apps/core/tests/test_embedding_switch_sdk_adapter.py b/memhub/apps/core/tests/test_embedding_switch_sdk_adapter.py
index 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 annotations
import asyncio
from pathlib import Path
+import hy_memory
import pytest
from one_memory.embedding_backend import EmbeddingTarget, PhysicalSpace
@@ -269,3 +270,335 @@ def test_a_whole_switch_through_the_real_sdk(tmp_path: Path, monkeypatch) -> Non
states = {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.md
index 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)