Python
feat(memhub): switch the embedding model safely in Core
alvinfeie87d6305bebf
diff --git a/memhub/apps/core/src/one_memory/api.py b/memhub/apps/core/src/one_memory/api.pyindex 5c396ba..8de9c54 100644--- a/memhub/apps/core/src/one_memory/api.py+++ b/memhub/apps/core/src/one_memory/api.py@@ -71,6 +71,9 @@ from one_memory.diagnostic_log import (reset_trace_id,resource_snapshot,)+from one_memory.embedding_health import EMBEDDING_UNAVAILABLE, EmbeddingUnavailableError+from one_memory.embedding_spaces import EmbeddingSpaceStore+from one_memory.embedding_switch import EmbeddingSwitchJob, EmbeddingSwitchServicefrom one_memory.exception_reporting import (install_asyncio_exception_handler,install_threading_excepthook,@@ -237,6 +240,7 @@ from one_memory.model_profiles import (ModelProfilePatch,ModelProfileStore,ModelProfileUnavailableError,+ ProviderKind,)from one_memory.model_request_audit import (AuditedModelTransport,@@ -330,6 +334,10 @@ class HealthResponse(BaseModel):# failed steps are named so a stuck recovery is visible without a log.recovery: Literal["pending", "running", "done", "failed"] = "done"recovery_failed_steps: tuple[str, ...] = ()+ # An embedding switch or a startup merge of stray spaces, while one runs+ # (`{kind, state, percent, eta_s}`): the loading screen and the status+ # line read it. Reads are served throughout; model writes are paused.+ embedding_switch: dict[str, object] | None = Noneclass BackupRequest(BaseModel):@@ -666,6 +674,9 @@ class MemoryProcessingSummary(BaseModel):#: R10: the SDK mode and System 2 state. Optional so older readers and#: test doubles stay valid; Core always sends it.pipeline: "PipelineStatus | None" = None+ #: The running embedding switch or merge, `{job_id, kind, state, percent,+ #: eta_s}`; None when none runs. Model writes wait while it is set.+ embedding_switch: dict[str, object] | None = Noneclass MemoryModeState(BaseModel):@@ -1044,6 +1055,16 @@ def create_app(# state, so initialize it before authority selection.app.state.secret_store = secret_store or KeyringSecretStore()app.state.model_profile_store = ModelProfileStore(database_path)+ # The live embedding space, pinned before any SDK client opens.+ # A home this build has not seen registers the space it already+ # uses, under the name it already has (`EmbeddingSpaceStore.bootstrap`).+ app.state.embedding_spaces = EmbeddingSpaceStore(database_path)+ active_identity = app.state.model_profile_store.active_identity()+ app.state.embedding_spaces.bootstrap(+ app.state.model_profile_store.snapshot(*active_identity)+ if active_identity is not None+ else None+ )app.state.sdk_data_plane_migrations = SdkDataPlaneMigrationStore(database_path)app.state.memory_authority = app.state.sdk_data_plane_migrations.authority()_record_startup_authority(@@ -1280,6 +1301,8 @@ def create_app(sedimentation_enabled=lambda: _config_store(app).sedimentation_enabled(),memory_mode=lambda: _memory_mode(app),memory_features=lambda: _memory_features(app),+ spaces=app.state.embedding_spaces,+ writes_open=lambda: _embedding_writes_open(app),)app.state.sdk_memory_runtime = SdkMemoryRuntime(coordinator=app.state.sdk_write_coordinator,@@ -1288,6 +1311,7 @@ def create_app(extraction_settings=app.state.extraction_settings_store,data_dir=runtime_settings.data_dir,memory_mode=lambda: _memory_mode(app),+ writes_open=lambda: _embedding_writes_open(app),)app.state.evolve_state_store = EvolveStateStore(runtime_settings.data_dir)app.state.evolve_service = EvolveService(@@ -1342,6 +1366,10 @@ def create_app(async with app.state.sedimentation_lock, source_lock:if not _config_store(app).sedimentation_enabled():raise RuntimeError("model_sedimentation_disabled")+ if not _embedding_writes_open(app):+ # Re-checked at the last boundary: a switch that began+ # after the claim keeps this job queued, unsent.+ raise RuntimeError("embedding_switch_in_progress")if not _source_writes_on(app, source_id):raise RuntimeError("model_content_source_disabled")return await mark_invoked()@@ -1393,6 +1421,64 @@ def create_app(source_claim_enabled=lambda source_id: _sedimentation_claim_enabled(app, source_id),)app.state.memory_write_drain = memory_write_drain++ async def embedding_writes_drained() -> bool:+ """No model write runs: none past its claim, none holding a client."""+ await asyncio.to_thread(memory_write_queue.reclaim_expired)+ running, _ = await asyncio.to_thread(app.state.sdk_memory_runtime.active_depths)+ in_use = cast(SdkWriteCoordinator, app.state.sdk_write_coordinator).in_use()+ return running == 0 and in_use == 0++ async def quiesce_sdk_clients() -> Callable[[], None]:+ """Close every SDK client and hold the stores, for the graph re-embed."""+ deadline = time.monotonic() + 120+ while True:+ await _read_handle(app).close_idle()+ await app.state.sdk_write_coordinator.close_idle()+ if hold_stores_offline(runtime_settings.data_dir):+ return lambda: release_stores(runtime_settings.data_dir)+ if time.monotonic() >= deadline:+ raise RuntimeError("embedding_switch_clients_busy")+ await asyncio.sleep(0.2)++ async def after_embedding_commit(job: EmbeddingSwitchJob) -> None:+ from one_memory.hy_graph_admin import forget_graph_widths++ forget_graph_widths()+ _read_handle(app).health.forget()+ if job.kind == "switch" and job.target_profile_id is not None:+ profile = await asyncio.to_thread(+ _model_profile_store(app).require,+ job.target_profile_id,+ _secret_store(app),+ )+ await asyncio.to_thread(+ app.state.memory_task_store.rebind_unstarted_profile, profile+ )+ await asyncio.to_thread(memory_write_queue.readmit_model_profile_waiters)+ _resume_sedimentation(app)+ _start_backfill(app)++ from one_memory.embedding_switch import default_reembed_backend++ app.state.embedding_switch = EmbeddingSwitchService(+ database_path=database_path,+ data_dir=runtime_settings.data_dir,+ profiles=app.state.model_profile_store,+ spaces=app.state.embedding_spaces,+ secrets=app.state.secret_store,+ backend=default_reembed_backend(runtime_settings.data_dir),+ drain_idle=embedding_writes_drained,+ on_commit=after_embedding_commit,+ quiesce_clients=quiesce_sdk_clients,+ # Only ultra keeps a graph; its width follows the space.+ graph_enabled=lambda: _memory_mode(app) == "ultra",+ worker_enabled=runtime_settings.embedding_switch_worker,+ drain_timeout_s=runtime_settings.embedding_switch_drain_timeout_seconds,+ )+ if app.state.memory_authority is not MemoryAuthority.SDK:+ # Only an SDK-authority home has SDK spaces to scan and merge.+ app.state.embedding_switch.release_scan_hold()# Started by `recover_after_ready`: a running drain claims jobs and# holds the single writer, which the rest of startup still needs.app.state.memory_write_drain_task = None@@ -1631,6 +1717,12 @@ def create_app(repair.coding_rows,)+ async def resume_embedding_spaces() -> None:+ try:+ await app.state.embedding_switch.recover()+ finally:+ app.state.embedding_switch.start_retention()+async def start_write_drain() -> None:app.state.memory_write_drain_task = watched_task(asyncio.get_running_loop(),@@ -1719,6 +1811,13 @@ def create_app(# Before the drain: the repair restores metadata the# queued writes are read back against.await step("sdk_metadata_repair", repair_sdk_metadata)+ # Before the drain too: resume an unfinished embedding+ # switch (an App update may have stopped it), or scan for+ # stray spaces and start merging them. Until this decides,+ # the write gate holds every model write back; reads are+ # served from the live space throughout.+ if sdk:+ await step("embedding_spaces", resume_embedding_spaces)await step("write_drain", start_write_drain)if sdk:await step("evolve_schedule", start_evolve_schedule)@@ -1821,6 +1920,8 @@ def create_app(await app.state.evolve_scheduler.shutdown()await app.state.evolve_service.shutdown()await app.state.memory_graph_backfill.shutdown()+ # The job stays where it is; the next start resumes it.+ await app.state.embedding_switch.shutdown()await app.state.sdk_memory_runtime.shutdown()await app.state.sdk_write_coordinator.close()if app.state.sdk_client_handle is not None:@@ -1906,6 +2007,9 @@ def create_app(from one_memory.call_event_routes import call_event_routerapp.include_router(call_event_router(protected))+ from one_memory.embedding_switch_routes import embedding_switch_router++ app.include_router(embedding_switch_router(protected))app.add_middleware(CORSMiddleware,@@ -1999,6 +2103,12 @@ def create_app(},)+ @app.exception_handler(EmbeddingUnavailableError)+ async def embedding_unavailable(_: Request, _error: EmbeddingUnavailableError) -> JSONResponse:+ # No lexical fallback: a search that cannot embed its query fails,+ # and says why, so the App can show it (top-right toast).+ return JSONResponse(status_code=503, content={"detail": EMBEDDING_UNAVAILABLE})+@app.exception_handler(sqlite3.OperationalError)async def sqlite_error(request: Request, error: sqlite3.OperationalError) -> JSONResponse:record_database_error("core.api", error, route_path=request.url.path)@@ -2044,6 +2154,7 @@ def create_app(),recovery=getattr(app.state, "recovery", "pending"),recovery_failed_steps=getattr(app.state, "recovery_failed_steps", ()),+ embedding_switch=_embedding_switch_summary(app),)@app.get("/health", response_model=HealthResponse, include_in_schema=False)@@ -3322,6 +3433,7 @@ def create_app(profile_id: str,request: ModelProfilePatch,) -> ModelProfile:+ _refuse_embedding_edit_during_switch(app, profile_id, request)try:return _model_profile_store(app).update(profile_id,@@ -3342,25 +3454,62 @@ def create_app(@app.post("/api/v1/model-profiles/{profile_id}/activate",- response_model=ModelProfile,+ response_model=None,dependencies=protected,)- async def activate_model_profile(profile_id: str) -> ModelProfile:+ async def activate_model_profile(profile_id: str) -> Any:# Asynchronous for the sake of what follows the activation: scheduling# work needs the event loop this coroutine runs on, and a synchronous# path operation is handed to a worker thread that has none. Activating# with any evidence already imported — the ordinary order, since# importing comes first — used to fail here outright.+ #+ # Activation never changes the embedding space by itself. A profile+ # with the live space's model and width (a generation-only change, or+ # another endpoint for the same model) activates as before. Another+ # embedding on a home with no vector at all moves the space in the+ # same transaction. Anything else answers 409 `embedding_switch_required`+ # with the plan: `POST /api/v1/embedding-switches` carries it out.+ from one_memory.embedding_switch import EmbeddingSwitchError+ from one_memory.embedding_switch_routes import refusal++ switch = _embedding_switch(app)try:- profile = await asyncio.to_thread(- _model_profile_store(app).activate,- profile_id,- _secret_store(app),- )+ # The refusals activation always made come first, with their codes.+ await asyncio.to_thread(_store_activation_preflight, app, profile_id)+ plan = await switch.plan(profile_id)+ except KeyError:+ raise HTTPException(status_code=404, detail="model_profile_not_found") from None+ except ModelProfileUnavailableError as error:+ raise HTTPException(status_code=409, detail=str(error)) from None+ except EmbeddingSwitchError as error:+ if error.code == "model_profile_not_found":+ raise HTTPException(status_code=404, detail="model_profile_not_found") from None+ return refusal(error.code, plan=error.plan)+ if "embedding_switch_running" in plan.blockers:+ return refusal("embedding_switch_running", plan=plan)+ try:+ if plan.needed:+ return refusal("embedding_switch_required", plan=plan)+ if plan.reason == "empty_home":+ await asyncio.to_thread(switch.activate_empty_home, profile_id)+ profile = await asyncio.to_thread(+ _model_profile_store(app).require, profile_id, _secret_store(app)+ )+ else:+ profile = await asyncio.to_thread(+ _model_profile_store(app).activate,+ profile_id,+ _secret_store(app),+ )except KeyError:raise HTTPException(status_code=404, detail="model_profile_not_found") from Noneexcept ModelProfileUnavailableError as error:raise HTTPException(status_code=409, detail=str(error)) from None+ except ModelProfileConflictError:+ raise HTTPException(status_code=409, detail="model_profile_conflict") from None+ except EmbeddingSwitchError as error:+ return refusal(error.code)# D75: work queued for the previous model continues with this one.# Only tasks that never reached the model are re-bound.await asyncio.to_thread(app.state.memory_task_store.rebind_unstarted_profile, profile)@@ -3933,6 +4082,7 @@ def create_app(if request.task is not None and request.kind in {"chat", "fact"}:raise HTTPException(status_code=422, detail="memory_task_requires_experience")namespace = _namespace_kwargs(request.kind, request.variant)+ _refuse_write_during_embedding_switch(app)try:async with app.state.sdk_write_coordinator.use_client() as client:# `update` takes no user: read the memory first and refuse@@ -3988,6 +4138,7 @@ def create_app(user_id: str = Query(default=DEFAULT_USER_ID, pattern=USER_ID_PATTERN),) -> Response:_check_memory_namespace(kind, variant)+ _refuse_write_during_embedding_switch(app)try:async with app.state.sdk_write_coordinator.use_client() as client:# `delete` takes no user. Another user's memory is answered@@ -4296,6 +4447,7 @@ def create_app(in_flight_count=in_flight_count,metrics=ProcessingMetrics.model_validate(store.processing_metrics()),pipeline=_pipeline_status(app),+ embedding_switch=_embedding_switch_summary(app),)@app.get(@@ -4545,6 +4697,7 @@ def create_app(assumption that cost a live graph once was made in code, not by a user."""supervisor = _sdk_memory_runtime(app)+ _refuse_write_during_embedding_switch(app)try:outcome = await supervisor.decide_graph_width(request.decision)except HySdkError as error:@@ -5768,6 +5921,7 @@ def _sdk_client_handle(app: FastAPI) -> SdkClientHandle:data_dir=cast(Settings, app.state.settings).data_dir,memory_mode=lambda: _memory_mode(app),features=lambda: _memory_features(app),+ spaces=getattr(app.state, "embedding_spaces", None),)app.state.sdk_client_handle = handlereturn handle@@ -5868,6 +6022,10 @@ def _pipeline_status(app: FastAPI) -> PipelineStatus | None:)+def _read_handle(app: FastAPI) -> ActiveProfileReadHandle:+ return cast(ActiveProfileReadHandle, _sdk_client_handle(app))++def _log_skipped_sdk_memories(count: int) -> None:if count:logger.warning("sdk_memory_invalid_rows_skipped count=%d", count)@@ -6123,6 +6281,7 @@ def _sedimentation_claim_enabled(app: FastAPI, source_id: str) -> bool:return (_config_store(app).sedimentation_enabled()+ and _embedding_writes_open(app)and (_memory_mode(app) == "lite" or _model_profile_store(app).active_identity() is not None)and _history_import_gate_released(app)and _source_writes_on(app, source_id)@@ -6137,6 +6296,74 @@ def _user_evolving(app: FastAPI, user_id: str) -> bool:return bool(callable(evolving) and evolving(user_id))+def _embedding_switch(app: FastAPI) -> EmbeddingSwitchService:+ return cast(EmbeddingSwitchService, app.state.embedding_switch)+++def _embedding_writes_open(app: FastAPI) -> bool:+ """False while an embedding switch or merge runs, or the startup scan has not decided.++ Intake is not affected: conversations keep being queued, and sediment+ into the live space once the gate opens again.+ """+ switch = getattr(app.state, "embedding_switch", None)+ return switch is None or switch.writes_open()+++def _embedding_switch_summary(app: FastAPI) -> dict[str, object] | None:+ switch = getattr(app.state, "embedding_switch", None)+ if switch is None:+ return None+ try:+ return cast(EmbeddingSwitchService, switch).summary()+ except sqlite3.Error:+ return None+++def _refuse_write_during_embedding_switch(app: FastAPI) -> None:+ """Direct edits and deletes wait for the switch: 409, never a write into the old space."""+ if not _embedding_writes_open(app):+ raise HTTPException(status_code=409, detail="embedding_switch_in_progress")+++_EMBEDDING_PATCH_FIELDS = frozenset(+ {"embedding_model", "embedding_provider_kind", "embedding_base_url", "embedding_dimensions"}+)+++def _refuse_embedding_edit_during_switch(+ app: FastAPI, profile_id: str, patch: ModelProfilePatch+) -> None:+ """The profiles a running switch reads from or commits to keep their embedding."""+ if not (_EMBEDDING_PATCH_FIELDS & patch.model_fields_set):+ return+ switch = getattr(app.state, "embedding_switch", None)+ if switch is None:+ return+ row = cast(EmbeddingSwitchService, switch).jobs.open_job()+ if row is None:+ return+ active = _model_profile_store(app).active_identity()+ if profile_id == row["target_profile_id"] or (active is not None and active[0] == profile_id):+ raise HTTPException(status_code=409, detail="embedding_switch_running")+++def _store_activation_preflight(app: FastAPI, profile_id: str) -> None:+ """The checks `ModelProfileStore.activate` makes, for the empty-home path."""+ profile = _model_profile_store(app).require(profile_id, _secret_store(app))+ if profile.provider_kind in {ProviderKind.HY_DEFAULT, ProviderKind.ANTHROPIC}:+ raise ModelProfileUnavailableError("model_provider_not_supported")+ if not profile.embedding_model:+ raise ModelProfileUnavailableError("embedding_model_required")+ capabilities = profile.capabilities+ if not (+ capabilities.endpoint_reachable+ and capabilities.model_available+ and capabilities.embedding_available+ ):+ raise ModelProfileUnavailableError("model_profile_probe_required")++def _history_import_gate_released(app: FastAPI) -> bool:"""Hold first sedimentation until every accepted history import is terminal."""diff --git a/memhub/apps/core/src/one_memory/cli.py b/memhub/apps/core/src/one_memory/cli.pyindex f52cd08..354a820 100644--- a/memhub/apps/core/src/one_memory/cli.py+++ b/memhub/apps/core/src/one_memory/cli.py@@ -35,7 +35,7 @@ import re # noqa: E402import time # noqa: E402from collections.abc import Iterator, Sequence # noqa: E402from pathlib import Path # noqa: E402-from typing import TextIO # noqa: E402+from typing import Any, TextIO # noqa: E402from one_memory.config import load_settings # noqa: E402from one_memory.runtime_client import RuntimeStatus, inspect_runtime # noqa: E402@@ -609,6 +609,14 @@ def _sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:else:state = "required"document = {"schema_version": 1, "authority": authority.value, "state": state}+ from one_memory.embedding_switch import read_open_job++ # Informational. An unfinished embedding switch never makes a+ # migration required or blocks it: the upgrade installs, `sdk-migrate`+ # leaves the switch's tables alone, and the new Core resumes the job.+ switch = read_open_job(database_path)+ if switch is not None:+ document["embedding_switch"] = switchfrom one_memory.sdk_migration_log import write_migration_logwrite_migration_log(@@ -616,7 +624,15 @@ def _sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:writer="core-sdk-migration-status",event="status.probed",outcome="succeeded",- details={"authority": document["authority"], "state": document["state"]},+ details={+ "authority": document["authority"],+ "state": document["state"],+ **(+ {"embedding_switch": document["embedding_switch"]}+ if "embedding_switch" in document+ else {}+ ),+ },)if as_json:stream.write(f"{json.dumps(document, ensure_ascii=False)}\n")@@ -696,6 +712,12 @@ def _refuse_unmigrated_home(data_dir: Path) -> None:raise SystemExit(SDK_MIGRATION_REQUIRED_EXIT)+def _without_embedding_switch(settings: Any) -> Any:+ """The maintenance Core's settings: it never resumes or runs a switch."""+ copy = getattr(settings, "model_copy", None)+ return copy(update={"embedding_switch_worker": False}) if callable(copy) else settings++def serve(*, maintenance: bool = False) -> None:import uvicorn@@ -740,7 +762,8 @@ def serve(*, maintenance: bool = False) -> None:if launcher is not None:ParentWatchdog(launcher).start()application = create_app(- settings,+ # Only the serving Core runs or resumes an embedding switch.+ _without_embedding_switch(settings) if maintenance else settings,manage_runtime=not maintenance,)if maintenance:diff --git a/memhub/apps/core/src/one_memory/config.py b/memhub/apps/core/src/one_memory/config.pyindex 4f8543e..ca603cb 100644--- a/memhub/apps/core/src/one_memory/config.py+++ b/memhub/apps/core/src/one_memory/config.py@@ -45,6 +45,11 @@ class Settings(BaseSettings):model_request_limit: int | None = Field(default=None, ge=1, le=100_000)model_request_body_byte_limit: int = Field(default=24_576, ge=1)model_request_output_token_limit: int = Field(default=16_384, ge=1)+ # The embedding switch worker (and the startup merge). The maintenance+ # Core turns it off: only the serving Core may resume or run a switch.+ embedding_switch_worker: bool = True+ # How long a switch waits for model writes already past their claim.+ embedding_switch_drain_timeout_seconds: float = Field(default=600, gt=0)@field_validator("development_origin")@classmethoddiff --git a/memhub/apps/core/src/one_memory/context_routes.py b/memhub/apps/core/src/one_memory/context_routes.pyindex e6b9ab0..f4b42db 100644--- a/memhub/apps/core/src/one_memory/context_routes.py+++ b/memhub/apps/core/src/one_memory/context_routes.py@@ -19,6 +19,7 @@ from one_memory.context_models import (SdkMemoryContextItem,SdkRawContextItem,)+from one_memory.embedding_health import EMBEDDING_UNAVAILABLE, EmbeddingUnavailableErrorfrom one_memory.external_memory_access import external_accessfrom one_memory.hy_runtime_config import HY_MEMORY_READERfrom one_memory.hy_sdk_runtime import sdk_relevance_floor@@ -263,6 +264,10 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:)await record(final, timed_out=True)return final+ for lane in (raw_items, memory_items):+ if isinstance(lane, EmbeddingUnavailableError):+ # No lexical fallback: the query could not be embedded.+ raise HTTPException(503, EMBEDDING_UNAVAILABLE)partial = isinstance(raw_items, Exception) or isinstance(memory_items, Exception)raw_candidates = (() if isinstance(raw_items, Exception) else cast(tuple[SdkContextItem, ...], raw_items)diff --git a/memhub/apps/core/src/one_memory/embedding_backend.py b/memhub/apps/core/src/one_memory/embedding_backend.pynew file mode 100644index 0000000..212ae50--- /dev/null+++ b/memhub/apps/core/src/one_memory/embedding_backend.py@@ -0,0 +1,180 @@+"""What the embedding switch needs from the SDK's re-embed module, in Core terms.++The switch worker, the startup merge and the retention sweep only talk to a+`ReembedBackend`. The production one (`hy_sdk_migration.SdkReembedBackend`)+is the single place that calls `hy_memory`'s re-embed functions; tests use+an in-memory one. Every space is named explicitly -- collection names and+graph paths -- and nothing here derives a name from a provider or endpoint.+"""++from __future__ import annotations++from collections.abc import Callable, Mapping+from dataclasses import dataclass, field+from pathlib import Path+from typing import Protocol++from one_memory.embedding_spaces import EmbeddingSpace, space_collection_names+from one_memory.model_profiles import ModelProfileSnapshot+++class ReembedUnavailableError(RuntimeError):+ """The installed SDK has no re-embed module (before hy-memory 2.0.10)."""++ def __init__(self, code: str = "sdk_reembed_unavailable") -> None:+ super().__init__(code)+ self.code = code+++class ReembedCancelledError(RuntimeError):+ """A cancel was seen at a batch boundary; every finished batch is written."""+++class EmbeddingWidthError(RuntimeError):+ """The embedding service returned vectors of another width than the target's."""+++@dataclass(frozen=True)+class PhysicalSpace:+ """One space's collections, named explicitly."""++ collection_base: str+ name_dims: int | None+ #: The width of the vectors in it, or to be written to it.+ dims: int | None+ model: str | None = None+ #: Explicit role -> collection name; None derives them from the base.+ collections: Mapping[str, str] | None = None++ def names(self) -> dict[str, str]:+ if self.collections is not None:+ return dict(self.collections)+ return space_collection_names(self.collection_base, self.name_dims)++ @classmethod+ def of(cls, space: EmbeddingSpace) -> PhysicalSpace:+ return cls(+ collection_base=space.collection_base,+ name_dims=space.name_dims,+ dims=space.dims if space.dims is not None else space.name_dims,+ model=space.model,+ )+++@dataclass(frozen=True)+class ScannedSpace:+ """A space found in the vector store, grouped from its collection names."""++ collection_base: str+ name_dims: int | None+ #: The stored width when every non-empty role agrees.+ width: int | None+ counts: Mapping[str, int]+ collections: Mapping[str, str]+ per_user: Mapping[str, int] = field(default_factory=dict)++ @property+ def vectors(self) -> int:+ return sum(self.counts.values())++ @property+ def key(self) -> tuple[str, int]:+ return (self.collection_base, self.name_dims or 0)++ def physical(self) -> PhysicalSpace:+ return PhysicalSpace(+ collection_base=self.collection_base,+ name_dims=self.name_dims,+ dims=self.width if self.width is not None else self.name_dims,+ collections=dict(self.collections),+ )+++@dataclass(frozen=True)+class ReembedStep:+ """Progress of one role (vectors) or table (graph)."""++ phase: str+ role: str+ done: int+ total: int+ embedded: int = 0+ reused: int = 0+ kept: int = 0+++@dataclass(frozen=True)+class VectorCheck:+ per_role: Mapping[str, Mapping[str, int]]+ #: Target records per metadata `user_id`.+ per_user: Mapping[str, int]+ problems: tuple[str, ...]+ warnings: tuple[str, ...] = ()+ self_recall_hits: int = 0+ self_recall_samples: int = 0+++@dataclass(frozen=True)+class GraphCheck:+ ok: bool+ problems: tuple[str, ...] = ()+++@dataclass(frozen=True)+class EmbeddingTarget:+ """The embedding that fills a space: the profile to reach it, and its key."""++ profile: ModelProfileSnapshot+ space: EmbeddingSpace+ api_key: str | None+++Cancel = Callable[[], bool]+OnStep = Callable[[ReembedStep], None]+++class ReembedBackend(Protocol):+ def unavailable_reason(self) -> str | None:+ """None when re-embedding works; otherwise the code that says why not."""++ async def scan(self, *, per_user: bool = False) -> tuple[ScannedSpace, ...]:+ """Every space with collections in the home's vector store. Read-only."""++ async def diff(self, source: PhysicalSpace, target: PhysicalSpace) -> dict[str, int]:+ """Per role, how many ids the source holds that the target does not."""++ async def reembed(+ self,+ source: PhysicalSpace,+ target: PhysicalSpace,+ *,+ embedding: EmbeddingTarget,+ cancel: Cancel,+ on_step: OnStep,+ batch_size: int = 64,+ ) -> None:+ """Embed every source record the target lacks into the target. Target wins."""++ async def verify(+ self, source: PhysicalSpace, target: PhysicalSpace, *, embedding: EmbeddingTarget+ ) -> VectorCheck: ...++ async def graph_vectors(self, path: Path) -> int | None:+ """Embeddings a graph holds, or None when there is no graph there."""++ async def reembed_graph(+ self,+ source: Path,+ target: Path,+ *,+ embedding: EmbeddingTarget,+ target_dims: int,+ cancel: Cancel,+ on_step: OnStep,+ ) -> None: ...++ async def verify_graph(self, source: Path, target: Path, *, target_dims: int) -> GraphCheck: ...++ async def drop(self, space: PhysicalSpace) -> None: ...++ async def drop_graph(self, path: Path) -> None: ...diff --git a/memhub/apps/core/src/one_memory/embedding_health.py b/memhub/apps/core/src/one_memory/embedding_health.pynew file mode 100644index 0000000..c11ce09--- /dev/null+++ b/memhub/apps/core/src/one_memory/embedding_health.py@@ -0,0 +1,147 @@+"""`embedding_unavailable`: a search that could not embed its query says so.++With a remote embedding model, every search embeds the query through that+service. When the service is down, the SDK swallows the failure and answers+with no hits, which reads as "you have no such memory". There is no lexical+fallback (owner decision): the search fails with the explicit code+`embedding_unavailable`, the API answers 503 with that code, and the App+shows a toast.++The check is only made when a search came back empty or raised, so a working+service costs nothing on searches that find something. It sends one tiny+embedding request to the same endpoint, model and width the read client+uses; the answer is remembered briefly so a burst of searches sends one.+"""++from __future__ import annotations++import threading+import time+from collections.abc import Callable, Mapping+from typing import Any++import httpx++from one_memory.http_client import create_client+from one_memory.hy_sdk_types import HySdkError+from one_memory.model_profiles import ModelProfileSnapshot, ProviderKind++EMBEDDING_UNAVAILABLE = "embedding_unavailable"+_OK_TTL_S = 30.0+_FAILED_TTL_S = 10.0+_TIMEOUT_S = 8.0+++def _no_transport() -> httpx.BaseTransport | None:+ return None+++#: Tests replace this to answer the check without a network.+transport_factory: Callable[[], httpx.BaseTransport | None] = _no_transport+++class EmbeddingUnavailableError(HySdkError):+ """The live space's embedding service did not answer; search cannot run."""++ def __init__(self) -> None:+ super().__init__(EMBEDDING_UNAVAILABLE)+++class EmbeddingHealth:+ """Whether a remote embedding answers, remembered for a few seconds."""++ def __init__(self) -> None:+ self._lock = threading.Lock()+ self._known: dict[tuple[str, str, int | None], tuple[bool, float]] = {}++ def available(+ self,+ profile: ModelProfileSnapshot,+ *,+ endpoint: str | None,+ name_dims: int | None,+ api_key: str | None,+ ) -> bool:+ provider = profile.embedding_provider_kind or profile.provider_kind+ if provider is ProviderKind.LOCAL_ONNX or endpoint is None:+ return True+ model = profile.embedding_model or ""+ key = (endpoint, model, name_dims)+ now = time.monotonic()+ with self._lock:+ known = self._known.get(key)+ if known is not None and known[1] > now:+ return known[0]+ ok = _answers(+ endpoint,+ model=model,+ name_dims=name_dims,+ api_key="ollama" if provider is ProviderKind.OLLAMA else api_key,+ )+ with self._lock:+ self._known[key] = (ok, now + (_OK_TTL_S if ok else _FAILED_TTL_S))+ return ok++ def forget(self) -> None:+ with self._lock:+ self._known.clear()+++def _answers(endpoint: str, *, model: str, name_dims: int | None, api_key: str | None) -> bool:+ body: dict[str, Any] = {"model": model, "input": ["ping"]}+ if name_dims:+ body["dimensions"] = name_dims+ headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}+ transport = transport_factory()+ try:+ with create_client(+ timeout=_TIMEOUT_S,+ **({"transport": transport} if transport is not None else {}),+ ) as client:+ response = client.post(f"{endpoint.rstrip('/')}/embeddings", json=body, headers=headers)+ if response.status_code != 200:+ return False+ data = response.json().get("data")+ return bool(isinstance(data, list) and data and data[0].get("embedding"))+ except (httpx.HTTPError, ValueError, AttributeError):+ return False+++def has_hits(result: object) -> bool:+ """Whether an SDK search result holds any hit, whatever its scene's shape."""+ if not isinstance(result, Mapping):+ return bool(result)+ for key in ("memories", "facts", "experiences"):+ value = result.get(key)+ if isinstance(value, list) and value:+ return True+ if isinstance(value, Mapping) and any(+ isinstance(item, list) and item for item in value.values()+ ):+ return True+ return False+++class EmbeddingGuardedClient:+ """An SDK client whose `search` reports a dead embedding instead of nothing.++ Everything else is the client's own attribute, unchanged.+ """++ def __init__(self, client: Any, available: Callable[[], bool]) -> None:+ self._client = client+ self._available = available++ def search(self, *args: Any, **kwargs: Any) -> Any:+ try:+ result = self._client.search(*args, **kwargs)+ except Exception:+ if not self._available():+ raise EmbeddingUnavailableError() from None+ raise+ if not has_hits(result) and not self._available():+ raise EmbeddingUnavailableError()+ return result++ def __getattr__(self, name: str) -> Any:+ return getattr(self._client, name)diff --git a/memhub/apps/core/src/one_memory/embedding_spaces.py b/memhub/apps/core/src/one_memory/embedding_spaces.pynew file mode 100644index 0000000..2616e59--- /dev/null+++ b/memhub/apps/core/src/one_memory/embedding_spaces.py@@ -0,0 +1,554 @@+"""Which embedding space the home reads and writes: an explicit registry.++The SDK names its vector collections after `vector_store.collection_name`+and the configured width, so the space used to follow whatever the active+profile hashed to (`_collection_base`). Any change to that identity -- a+probe recording the measured width, a new endpoint -- silently opened new,+empty collections beside the old ones, and nothing carried the memories over.++The live space is pinned here instead, in the main Core database beside the+model profiles, so a switch commits the new space and the profile that fills+it in one transaction. The identity of a space is its embedding model and+width only: a new endpoint or provider serving the same model at the same+width keeps the space.++Existing homes keep their collections byte-for-byte. The first start registers+the space the active profile (or the built-in model) already opened under its+existing four-attribute name; only spaces created by a switch use the+model-and-width name. A space whose width was never declared ("auto") keeps+its unsuffixed name and only records the width it was measured at.+"""++from __future__ import annotations++import hashlib+import sqlite3+from collections.abc import Iterator, Mapping+from contextlib import contextmanager+from datetime import UTC, datetime, timedelta+from pathlib import Path+from typing import Literal+from uuid import uuid4++from pydantic import BaseModel, ConfigDict++from one_memory.database import take_the_write_lock_first+from one_memory.database_access import main_database+from one_memory.embedding_assets import BUILTIN_EMBEDDING_DIMENSIONS, BUILTIN_EMBEDDING_MODEL+from one_memory.memory_server.migrations import embedding_spaces_ddl+from one_memory.model_profiles import ModelProfileSnapshot, ProviderKind++#: How long a space replaced by a switch or folded in by a merge is kept.+RETIRED_SPACE_RETENTION = timedelta(days=14)++SpaceState = Literal["live", "building", "stray", "retired", "dropped"]+SpaceNaming = Literal["legacy", "v2", "discovered"]++#: Every vector collection one space consists of, as the SDK names them.+VECTOR_ROLES = (+ "memory",+ "entities",+ "coding_keys",+ "coding_keys_cv",+ "working_facts",+ "working_facts_cv",+)++#: The graph directory of the first space; later spaces get their own.+DEFAULT_GRAPH_DIR = "graph"++EMBEDDING_SPACES_SCHEMA = embedding_spaces_ddl()+++#: Bumped by every registry write in this process, so cached live rows are+#: reread after a change made through any connection (a probe's, a commit's).+_CHANGES = [0]+++def _changed() -> None:+ _CHANGES[0] += 1+++class EmbeddingSpaceError(RuntimeError):+ """A registry refusal with a stable, product-facing code."""++ def __init__(self, code: str) -> None:+ super().__init__(code)+ self.code = code+++class EmbeddingIdentity(BaseModel):+ """What makes two vectors comparable: the model and the width.++ `dims=None` is a width nobody declared or measured yet; it matches any+ width, because the collection it names was opened without one.+ """++ model_config = ConfigDict(frozen=True, extra="forbid")++ model: str+ dims: int | None = None++ def matches(self, other: EmbeddingIdentity) -> bool:+ if self.model != other.model:+ return False+ return self.dims is None or other.dims is None or self.dims == other.dims+++class EmbeddingSpace(BaseModel):+ """One embedding space: the physical collections and graph one model fills."""++ model_config = ConfigDict(frozen=True, extra="forbid")++ space_id: str+ state: SpaceState+ #: None only for a space found on disk that no registry row named.+ model: str | None = None+ #: The vector width stored in this space, once known.+ dims: int | None = None+ #: The width the collection names and embedding requests carry. None is+ #: an "auto" space: unsuffixed names and no `dimensions` request field.+ name_dims: int | None = None+ collection_base: str+ naming: SpaceNaming = "legacy"+ graph_dir: str | None = DEFAULT_GRAPH_DIR+ provider_kind: str | None = None+ #: The profile version whose embedding fills this space; None = built-in.+ profile_id: str | None = None+ profile_revision: int | None = None+ #: Vectors counted the last time the space was scanned.+ vectors: int | None = None+ created_at: str+ live_since: str | None = None+ retired_at: str | None = None+ keep_until: str | None = None+ dropped_at: str | None = None++ @property+ def identity(self) -> EmbeddingIdentity | None:+ if self.model is None:+ return None+ return EmbeddingIdentity(model=self.model, dims=self.dims)++ @property+ def builtin(self) -> bool:+ return self.provider_kind == ProviderKind.LOCAL_ONNX.value and self.profile_id is None++ def collection_names(self) -> dict[str, str]:+ return space_collection_names(self.collection_base, self.name_dims)+++def space_collection_names(base: str, name_dims: int | None) -> dict[str, str]:+ """The SDK's physical collection name per role for one space.++ Mirrors `VectorStoreBase` (the `_<dims>` suffix), the entity store and the+ coding stores. The SDK's own `vector_space_names` is checked against this+ in the migration adapter when the installed SDK provides it.+ """+ suffix = f"_{name_dims}" if name_dims else ""+ return {+ "memory": f"{base}{suffix}",+ "entities": f"{base}{suffix}_entities",+ "coding_keys": f"{base}_coding_keys{suffix}",+ "coding_keys_cv": f"{base}_coding_keys_cv{suffix}",+ "working_facts": f"{base}_working_facts{suffix}",+ "working_facts_cv": f"{base}_working_facts_cv{suffix}",+ }+++def embedding_identity(profile: ModelProfileSnapshot) -> EmbeddingIdentity:+ """The embedding identity a profile asks for: model name and width only."""+ provider = profile.embedding_provider_kind or profile.provider_kind+ local = provider is ProviderKind.LOCAL_ONNX+ model = profile.embedding_model or (BUILTIN_EMBEDDING_MODEL if local else None)+ if not model:+ raise EmbeddingSpaceError("hy_sdk_embedding_model_required")+ dims = profile.embedding_dimensions+ if local and dims is None:+ dims = BUILTIN_EMBEDDING_DIMENSIONS+ return EmbeddingIdentity(model=model, dims=dims)+++def v2_collection_base(identity: EmbeddingIdentity, generation: int = 0) -> str:+ """The base name a switch gives a new space: model and width, nothing else."""+ digest = hashlib.sha256(f"{identity.model}\0{identity.dims or 'auto'}".encode()).hexdigest()+ base = f"memhub_e_{digest[:16]}"+ return f"{base}_g{generation}" if generation else base+++def graph_dir_for(space_id: str) -> str:+ return f"graph-{space_id[:8]}"+++def derived_space(profile: ModelProfileSnapshot) -> EmbeddingSpace:+ """The space `profile` opened before the registry existed, under its old name.++ Never stored as is: bootstrap stores it, and offline tools that run beside+ a home with no registry yet read through it.+ """+ from one_memory.hy_sdk_runtime import legacy_collection_base++ provider = profile.embedding_provider_kind or profile.provider_kind+ identity = embedding_identity(profile)+ builtin = profile.profile_id == _BUILTIN_PROFILE_ID+ return EmbeddingSpace(+ space_id="derived",+ state="live",+ model=identity.model,+ dims=identity.dims,+ name_dims=identity.dims,+ collection_base=legacy_collection_base(profile),+ naming="legacy",+ graph_dir=DEFAULT_GRAPH_DIR,+ provider_kind=provider.value,+ profile_id=None if builtin else profile.profile_id,+ profile_revision=None if builtin else profile.revision,+ created_at=_now(),+ )+++_BUILTIN_PROFILE_ID = "builtin-retrieval"+++def _now() -> str:+ return datetime.now(UTC).isoformat()+++def _row(row: sqlite3.Row | Mapping[str, object]) -> EmbeddingSpace:+ return EmbeddingSpace.model_validate(dict(row))+++def ensure_schema(connection: sqlite3.Connection) -> None:+ connection.executescript(EMBEDDING_SPACES_SCHEMA)+++def registry_present(connection: sqlite3.Connection) -> bool:+ return (+ connection.execute(+ "SELECT 1 FROM sqlite_master WHERE type='table' AND name='embedding_spaces'"+ ).fetchone()+ is not None+ )+++def live_space_in(connection: sqlite3.Connection) -> EmbeddingSpace | None:+ if not registry_present(connection):+ return None+ previous = connection.row_factory+ connection.row_factory = sqlite3.Row+ try:+ row = connection.execute("SELECT * FROM embedding_spaces WHERE state='live'").fetchone()+ finally:+ connection.row_factory = previous+ return _row(row) if row is not None else None+++def read_live_space(database_path: Path) -> EmbeddingSpace | None:+ """The live space, read only, or None for a home with no registry yet."""+ if not database_path.is_file():+ return None+ with main_database(database_path).read(row_factory=sqlite3.Row) as connection:+ return live_space_in(connection)+++class EmbeddingSpaceStore:+ """The `embedding_spaces` table of the main Core database."""++ def __init__(self, database_path: Path) -> None:+ self.database_path = database_path+ #: The live row, read once per change: every read and write asks for+ #: it. Only this process writes the registry while Core serves.+ self._live_cache: tuple[int, EmbeddingSpace] | None = None+ with self._connect(writing=True) as connection:+ ensure_schema(connection)++ def invalidate(self) -> None:+ _changed()++ @contextmanager+ def _connect(+ self, *, writing: bool = False, lock_first: bool = True+ ) -> Iterator[sqlite3.Connection]:+ database = main_database(self.database_path)+ checkout = (+ database.write(row_factory=sqlite3.Row)+ if writing+ else database.read(row_factory=sqlite3.Row)+ )+ with checkout as connection, connection:+ if writing and lock_first:+ take_the_write_lock_first(connection)+ yield connection++ @contextmanager+ def transaction(self) -> Iterator[sqlite3.Connection]:+ """One `BEGIN IMMEDIATE` on the main database, committed on success."""+ _changed()+ try:+ with self._connect(writing=True, lock_first=False) as connection:+ connection.execute("BEGIN IMMEDIATE")+ yield connection+ finally:+ _changed()++ def live(self) -> EmbeddingSpace | None:+ generation = _CHANGES[0]+ cached = self._live_cache+ if cached is not None and cached[0] == generation:+ return cached[1]+ with self._connect() as connection:+ space = live_space_in(connection)+ self._live_cache = (generation, space) if space is not None else None+ return space++ def require_live(self) -> EmbeddingSpace:+ space = self.live()+ if space is None:+ raise EmbeddingSpaceError("embedding_space_not_bootstrapped")+ return space++ def get(self, space_id: str) -> EmbeddingSpace | None:+ with self._connect() as connection:+ row = connection.execute(+ "SELECT * FROM embedding_spaces WHERE space_id=?", (space_id,)+ ).fetchone()+ return _row(row) if row is not None else None++ def list_spaces(self, *, include_dropped: bool = False) -> list[EmbeddingSpace]:+ with self._connect() as connection:+ rows = connection.execute(+ "SELECT * FROM embedding_spaces "+ + ("" if include_dropped else "WHERE state != 'dropped' ")+ + "ORDER BY created_at, space_id"+ ).fetchall()+ return [_row(row) for row in rows]++ def bootstrap(self, active: ModelProfileSnapshot | None) -> EmbeddingSpace:+ """Register the space this home already uses, once, under its existing name.++ `active` is the active profile, or None for the built-in model. The+ collection name is derived exactly as before the registry, so nothing+ on disk moves.+ """+ from one_memory.hy_sdk_runtime import builtin_retrieval_snapshot++ with self.transaction() as connection:+ existing = live_space_in(connection)+ if existing is not None:+ return existing+ derived = derived_space(active or builtin_retrieval_snapshot())+ space = derived.model_copy(+ update={"space_id": str(uuid4()), "live_since": derived.created_at}+ )+ _insert(connection, space)+ return space++ def record_width(self, space_id: str, dims: int) -> EmbeddingSpace:+ """A relabel: the space's stored width is now known. Names never change."""+ with self.transaction() as connection:+ record_width_in(connection, space_id, dims)+ space = self.get(space_id)+ if space is None: # pragma: no cover - the row was just updated+ raise EmbeddingSpaceError("embedding_space_not_found")+ return space++ def record_vectors(self, counts: Mapping[str, int]) -> None:+ """Cache the vector count per space id from the last scan (display only)."""+ if not counts:+ return+ _changed()+ with self._connect(writing=True) as connection:+ connection.executemany(+ "UPDATE embedding_spaces SET vectors=? WHERE space_id=?",+ [(count, space_id) for space_id, count in counts.items()],+ )++ def register_stray(+ self,+ *,+ collection_base: str,+ name_dims: int | None,+ dims: int | None,+ vectors: int,+ ) -> EmbeddingSpace:+ """Name a non-empty space the scan found that no row described."""+ with self.transaction() as connection:+ row = connection.execute(+ "SELECT * FROM embedding_spaces WHERE collection_base=? "+ "AND COALESCE(name_dims,0)=? AND state != 'dropped'",+ (collection_base, name_dims or 0),+ ).fetchone()+ if row is not None:+ return _row(row)+ space = EmbeddingSpace(+ space_id=str(uuid4()),+ state="stray",+ dims=dims,+ name_dims=name_dims,+ collection_base=collection_base,+ naming="discovered",+ graph_dir=None,+ vectors=vectors,+ created_at=_now(),+ )+ _insert(connection, space)+ return space++ def mark_dropped(self, space_id: str) -> None:+ _changed()+ with self._connect(writing=True) as connection:+ connection.execute(+ "UPDATE embedding_spaces SET state='dropped', dropped_at=? "+ "WHERE space_id=? AND state IN ('retired','building')",+ (_now(), space_id),+ )++ def expired(self, *, now: datetime | None = None) -> list[EmbeddingSpace]:+ moment = (now or datetime.now(UTC)).isoformat()+ with self._connect() as connection:+ rows = connection.execute(+ "SELECT * FROM embedding_spaces WHERE state='retired' "+ "AND keep_until IS NOT NULL AND keep_until <= ?",+ (moment,),+ ).fetchall()+ return [_row(row) for row in rows]+++def registry_for(profiles: object) -> EmbeddingSpaceStore | None:+ """The registry beside a profile store, or None for a store with no database."""+ path = getattr(profiles, "database_path", None)+ return EmbeddingSpaceStore(path) if isinstance(path, Path) else None+++def _insert(connection: sqlite3.Connection, space: EmbeddingSpace) -> None:+ values = space.model_dump()+ columns = ", ".join(values)+ marks = ", ".join("?" for _ in values)+ connection.execute(+ f"INSERT INTO embedding_spaces ({columns}) VALUES ({marks})",+ tuple(values.values()),+ )+++def insert_space_in(connection: sqlite3.Connection, space: EmbeddingSpace) -> None:+ _changed()+ _insert(connection, space)+++def record_width_in(connection: sqlite3.Connection, space_id: str, dims: int) -> None:+ _changed()+ changed = connection.execute(+ "UPDATE embedding_spaces SET dims=? WHERE space_id=? AND (dims IS NULL OR dims=?)",+ (dims, space_id, dims),+ )+ if changed.rowcount != 1:+ raise EmbeddingSpaceError("embedding_space_width_conflict")+++def space_in(connection: sqlite3.Connection, space_id: str) -> EmbeddingSpace | None:+ previous = connection.row_factory+ connection.row_factory = sqlite3.Row+ try:+ row = connection.execute(+ "SELECT * FROM embedding_spaces WHERE space_id=?", (space_id,)+ ).fetchone()+ finally:+ connection.row_factory = previous+ return _row(row) if row is not None else None+++def spaces_in(connection: sqlite3.Connection) -> list[EmbeddingSpace]:+ previous = connection.row_factory+ connection.row_factory = sqlite3.Row+ try:+ rows = connection.execute("SELECT * FROM embedding_spaces").fetchall()+ finally:+ connection.row_factory = previous+ return [_row(row) for row in rows]+++def set_state_in(+ connection: sqlite3.Connection,+ space_id: str,+ *,+ state: SpaceState,+ expected: tuple[SpaceState, ...],+ now: datetime | None = None,+) -> None:+ """Move one space between states, refusing any it was not expected in."""+ _changed()+ moment = now or datetime.now(UTC)+ updates: dict[str, object] = {"state": state}+ if state == "live":+ updates["live_since"] = moment.isoformat()+ elif state == "retired":+ updates["retired_at"] = moment.isoformat()+ updates["keep_until"] = (moment + RETIRED_SPACE_RETENTION).isoformat()+ elif state == "dropped":+ updates["dropped_at"] = moment.isoformat()+ assignments = ", ".join(f"{column}=?" for column in updates)+ marks = ",".join("?" for _ in expected)+ changed = connection.execute(+ f"UPDATE embedding_spaces SET {assignments} WHERE space_id=? AND state IN ({marks})",+ (*updates.values(), space_id, *expected),+ )+ if changed.rowcount != 1:+ raise EmbeddingSpaceError("embedding_space_state_changed")+++def next_v2_base(+ connection: sqlite3.Connection,+ identity: EmbeddingIdentity,+ *,+ stored_names: frozenset[str],+) -> str:+ """A base for a new space no registry row and no stored collection uses.++ Switching back to a model whose retired space is still kept gets a fresh+ `_g<n>` base, so stale retired vectors are never mixed with fresh ones.+ """+ used = {space.collection_base for space in spaces_in(connection)}+ generation = 0+ while True:+ base = v2_collection_base(identity, generation)+ names = space_collection_names(base, identity.dims).values()+ if base not in used and not any(name in stored_names for name in names):+ return base+ generation += 1+++def probe_width_allowed(+ connection: sqlite3.Connection,+ profile_id: str,+ width: int,+ *,+ data_dir: Path,+) -> bool:+ """Whether a probe may record `width` on a profile without moving the space.++ A profile that fills the live space (the active one, or the one the space+ was built with) may record its measured width only when it is the+ space's: equal to the width already known, or -- for an "auto" space+ whose width was never recorded -- equal to the width Chroma stored, or+ any width when nothing is stored yet. That is a relabel; the names never+ change. Any other width needs a switch (B2: it used to silently open a+ new, empty collection). Every other profile records what it measured.+ """+ live = live_space_in(connection)+ if live is None:+ return True+ active = connection.execute(+ "SELECT profile_id FROM model_profiles WHERE is_active=1"+ ).fetchone()+ fills_live = live.profile_id == profile_id or (active is not None and active[0] == profile_id)+ if not fills_live:+ return True+ if live.dims is not None:+ return live.dims == width+ from one_memory.sdk_vector_reattach import stored_collection_width++ stored = stored_collection_width(data_dir, live.collection_names()["memory"])+ if stored is not None and stored != width:+ return False+ record_width_in(connection, live.space_id, width)+ return Truediff --git a/memhub/apps/core/src/one_memory/embedding_switch.py b/memhub/apps/core/src/one_memory/embedding_switch.pynew file mode 100644index 0000000..60e2a3c--- /dev/null+++ b/memhub/apps/core/src/one_memory/embedding_switch.py@@ -0,0 +1,1647 @@+"""Switching the embedding model without losing a memory.++A change of embedding identity (model or width) never takes effect by itself.+It becomes a *switch job*: model writes pause (intake keeps queueing), every+vector of every user is re-embedded from the stored text into a new space,+the copy is verified, and one SQLite transaction makes the new space live,+retires the old one and activates the target profile. Reads keep serving the+old space until that commit.++The same machinery runs a *merge*. Every Core start scans the vector store;+a non-empty space that is neither live nor known to the registry (left by an+earlier build that wrote one collection and read another) is re-embedded into+the live space with the live embedder. The live space's records win: a merge+only adds the ids it lacks. A merged stray is retired like a switched-away+space, kept 14 days, then dropped.++Jobs live in the main Core database beside the profiles and the registry,+with a heartbeat and an owner pid. A Core that stops mid-job -- quit, crash,+an App update installing a new build -- resumes it on its next start: every+step is idempotent (a re-embed skips ids the target already holds; the commit+is one transaction that either happened or did not).+"""++from __future__ import annotations++import asyncio+import hashlib+import json+import logging+import os+import shutil+import sqlite3+import time+from collections.abc import Awaitable, Callable, Iterator+from contextlib import contextmanager+from dataclasses import dataclass, field+from datetime import UTC, datetime, timedelta+from pathlib import Path+from typing import Any, Literal, cast+from uuid import uuid4++from pydantic import BaseModel, ConfigDict, Field++from one_memory.database import take_the_write_lock_first+from one_memory.database_access import main_database+from one_memory.embedding_backend import (+ EmbeddingTarget,+ EmbeddingWidthError,+ PhysicalSpace,+ ReembedBackend,+ ReembedCancelledError,+ ReembedStep,+ ReembedUnavailableError,+ ScannedSpace,+)+from one_memory.embedding_spaces import (+ DEFAULT_GRAPH_DIR,+ EmbeddingSpace,+ EmbeddingSpaceError,+ EmbeddingSpaceStore,+ derived_space,+ embedding_identity,+ graph_dir_for,+ insert_space_in,+ live_space_in,+ next_v2_base,+ set_state_in,+)+from one_memory.hy_runtime_config import HY_MEMORY_NAMESPACE+from one_memory.memory_server.migrations import embedding_switch_jobs_ddl+from one_memory.model_profiles import (+ ModelProfileSnapshot,+ ModelProfileStore,+ ProviderKind,+)+from one_memory.secrets import SecretStore, SecretStoreUnavailableError++logger = logging.getLogger(__name__)++JobKind = Literal["switch", "merge"]+JobState = Literal[+ "preparing",+ "reembedding",+ "verifying",+ "committing",+ "done",+ "failed",+ "rolled_back",+]+#: States in which model writes stay paused. `failed` is the rollback in+#: progress: writes resume only once the old space is certainly intact.+OPEN_STATES: tuple[JobState, ...] = (+ "preparing",+ "reembedding",+ "verifying",+ "committing",+ "failed",+)+TERMINAL_STATES: tuple[JobState, ...] = ("done", "rolled_back")+CANCELLABLE_STATES: tuple[JobState, ...] = ("preparing", "reembedding", "verifying")++HEARTBEAT_SECONDS = 5.0+#: A job whose owner stopped beating this long ago belongs to nobody.+STALE_HEARTBEAT = timedelta(seconds=60)+PROGRESS_WRITE_SECONDS = 2.0+DEFAULT_DRAIN_TIMEOUT_SECONDS = 600.0+#: Rounds of a re-embed that failed on the embedding service; each resumes+#: where the last stopped, so a flaky endpoint costs at most one batch.+REEMBED_ATTEMPTS = 3+REEMBED_RETRY_SECONDS = (5.0, 15.0)+#: Rough throughput for the estimate shown before a switch (vectors/second).+_LOCAL_RATE = 60.0+_REMOTE_RATE = 200.0+_BYTES_PER_VECTOR_OVERHEAD = 2_500+_DISK_RESERVE = 200 * 1024 * 1024++JOBS_SCHEMA = embedding_switch_jobs_ddl()+++class EmbeddingSwitchError(RuntimeError):+ """A refusal with a stable code; `plan` rides along when one was computed."""++ def __init__(self, code: str, *, plan: EmbeddingSwitchPlan | None = None) -> None:+ super().__init__(code)+ self.code = code+ self.plan = plan+++class SwitchProgress(BaseModel):+ """What the App's banner and loading screen draw."""++ model_config = ConfigDict(extra="forbid")++ phase: Literal["prepare", "vectors", "graph", "verify", "commit", "rollback", "done"] = (+ "prepare"+ )+ done: int = 0+ total: int = 0+ percent: float = 0.0+ embedded: int = 0+ reused: int = 0+ kept: int = 0+ role: str | None = None+ #: Which source space is being folded in (1-based) out of how many.+ source_index: int = 0+ sources: int = 0+ rate_per_s: float | None = None+ eta_s: int | None = None+ updated_at: str | None = None+++class SpaceSummary(BaseModel):+ model_config = ConfigDict(extra="forbid")++ space_id: str | None+ model: str | None+ dims: int | None+ collection_base: str+ vectors: int | None = None+++class EmbeddingSwitchJob(BaseModel):+ model_config = ConfigDict(extra="forbid")++ job_id: str+ kind: JobKind+ state: JobState+ source: SpaceSummary+ target: SpaceSummary+ stray_space_ids: list[str]+ target_profile_id: str | None+ target_revision: int | None+ requested_by: str+ progress: SwitchProgress+ cancel_requested: bool+ error_code: str | None+ attempt: int+ created_at: str+ updated_at: str+ finished_at: str | None+++class PlannedSource(BaseModel):+ model_config = ConfigDict(extra="forbid")++ space_id: str | None+ collection_base: str+ dims: int | None+ vectors: int+ #: Ids a stray holds that the live space lacks; None for the live space.+ unmerged: int | None = None+++class EmbeddingSwitchPlan(BaseModel):+ """Everything the confirmation dialog shows; no side effects."""++ model_config = ConfigDict(extra="forbid")++ needed: bool+ reason: Literal["embedding_identity_changed", "same_embedding", "empty_home"]+ plan_token: str+ source: SpaceSummary+ target: SpaceSummary+ target_profile_id: str+ target_revision: int+ target_provider_kind: str+ target_local: bool+ sources: list[PlannedSource] = Field(default_factory=list)+ total_vectors: int = 0+ users: int | None = None+ graph_vectors: int | None = None+ estimate_s: int | None = None+ requests: int | None = None+ disk_bytes_needed: int = 0+ disk_bytes_free: int | None = None+ retention_days: int = 14+ blockers: list[str] = Field(default_factory=list)+++@dataclass+class _Live:+ """Progress kept in memory and written at most every few seconds."""++ progress: SwitchProgress+ cancel: bool = False+ last_write: float = 0.0+ started: float = field(default_factory=time.monotonic)+ base_done: int = 0+++def _now() -> datetime:+ return datetime.now(UTC)+++class EmbeddingSwitchStore:+ """The `embedding_switch_jobs` table of the main Core database."""++ def __init__(self, database_path: Path) -> None:+ self.database_path = database_path+ with self._connect(writing=True) as connection:+ connection.executescript(JOBS_SCHEMA)++ @contextmanager+ def _connect(self, *, writing: bool = False) -> Iterator[sqlite3.Connection]:+ database = main_database(self.database_path)+ checkout = (+ database.write(row_factory=sqlite3.Row)+ if writing+ else database.read(row_factory=sqlite3.Row)+ )+ with checkout as connection, connection:+ if writing:+ take_the_write_lock_first(connection)+ yield connection++ def open_job(self) -> sqlite3.Row | None:+ with self._connect() as connection:+ return open_job_in(connection)++ def get(self, job_id: str) -> sqlite3.Row | None:+ with self._connect() as connection:+ return cast(+ sqlite3.Row | None,+ connection.execute(+ "SELECT * FROM embedding_switch_jobs WHERE job_id=?", (job_id,)+ ).fetchone(),+ )++ def last_finished(self) -> sqlite3.Row | None:+ with self._connect() as connection:+ return cast(+ sqlite3.Row | None,+ connection.execute(+ "SELECT * FROM embedding_switch_jobs WHERE state IN ('done','rolled_back') "+ "ORDER BY finished_at DESC LIMIT 1"+ ).fetchone(),+ )++ def update(self, job_id: str, **values: object) -> None:+ values["updated_at"] = _now().isoformat()+ assignments = ", ".join(f"{column}=?" for column in values)+ with self._connect(writing=True) as connection:+ connection.execute(+ f"UPDATE embedding_switch_jobs SET {assignments} WHERE job_id=?",+ (*values.values(), job_id),+ )++ def claim(self, job_id: str, *, pid: int) -> None:+ self.update(job_id, owner_pid=pid, heartbeat_at=_now().isoformat())++ def beat(self, job_id: str, *, pid: int) -> None:+ with self._connect(writing=True) as connection:+ connection.execute(+ "UPDATE embedding_switch_jobs SET heartbeat_at=? WHERE job_id=? AND owner_pid=?",+ (_now().isoformat(), job_id, pid),+ )+++def open_job_in(connection: sqlite3.Connection) -> sqlite3.Row | None:+ if (+ connection.execute(+ "SELECT 1 FROM sqlite_master WHERE type='table' AND name='embedding_switch_jobs'"+ ).fetchone()+ is None+ ):+ return None+ previous = connection.row_factory+ connection.row_factory = sqlite3.Row+ try:+ return cast(+ sqlite3.Row | None,+ connection.execute(+ "SELECT * FROM embedding_switch_jobs WHERE state NOT IN ('done','rolled_back')"+ ).fetchone(),+ )+ finally:+ connection.row_factory = previous+++def read_open_job(database_path: Path) -> dict[str, object] | None:+ """The unfinished job, read only: for `sdk-migration-status` beside Core."""+ if not database_path.is_file():+ return None+ with main_database(database_path).read(row_factory=sqlite3.Row) as connection:+ row = open_job_in(connection)+ if row is None:+ return None+ return {"job_id": row["job_id"], "kind": row["kind"], "state": row["state"]}+++class EmbeddingSwitchService:+ """Plans, starts, runs, resumes and cancels switches and merges for one home."""++ def __init__(+ self,+ *,+ database_path: Path,+ data_dir: Path,+ profiles: ModelProfileStore,+ spaces: EmbeddingSpaceStore,+ secrets: SecretStore,+ backend: ReembedBackend,+ drain_idle: Callable[[], Awaitable[bool]] | None = None,+ on_commit: Callable[[EmbeddingSwitchJob], Awaitable[None]] | None = None,+ quiesce_clients: Callable[[], Awaitable[Callable[[], None]]] | None = None,+ graph_enabled: Callable[[], bool] = lambda: False,+ worker_enabled: bool = True,+ drain_timeout_s: float = DEFAULT_DRAIN_TIMEOUT_SECONDS,+ ) -> None:+ self.database_path = database_path+ self.data_dir = data_dir+ self.root = data_dir.resolve() / "hy-memory" / HY_MEMORY_NAMESPACE+ self.profiles = profiles+ self.spaces = spaces+ self.secrets = secrets+ self.backend = backend+ self.jobs = EmbeddingSwitchStore(database_path)+ self.drain_idle = drain_idle or _always_idle+ self.on_commit = on_commit+ self.quiesce_clients = quiesce_clients+ self.graph_enabled = graph_enabled+ self.worker_enabled = worker_enabled+ self.drain_timeout_s = drain_timeout_s+ self.pid = os.getpid()+ #: "pending" until the startup scan decided, then "done"/"failed"/"unavailable".+ self.scan_state: Literal["pending", "scanning", "done", "failed", "unavailable"] = "pending"+ self.scan_error: str | None = None+ self._scan_hold = True+ self._live: dict[str, _Live] = {}+ self._task: asyncio.Task[None] | None = None+ self._heartbeat: asyncio.Task[None] | None = None+ self._open_cache: bool = self.jobs.open_job() is not None+ self._lock = asyncio.Lock()+ self._retention: asyncio.Task[None] | None = None++ # ------------------------------------------------------------------+ # The write gate+ # ------------------------------------------------------------------++ def writes_open(self) -> bool:+ """False while a job runs or the startup scan has not decided yet."""+ return not self._open_cache and not self._scan_hold++ def pause_reason(self) -> str | None:+ if self._open_cache:+ return "embedding_switch_in_progress"+ if self._scan_hold:+ return "embedding_scan_pending"+ return None++ def release_scan_hold(self) -> None:+ self._scan_hold = False++ # ------------------------------------------------------------------+ # Reading state+ # ------------------------------------------------------------------++ def current(self) -> dict[str, object]:+ row = self.jobs.open_job()+ job = self._job(row) if row is not None else None+ last = self.jobs.last_finished()+ phase = (+ "running"+ if job is not None+ else ("scanning" if self.scan_state in {"pending", "scanning"} else "idle")+ )+ return {+ "schema_version": 1,+ "phase": phase,+ "writes_paused": not self.writes_open(),+ "scan_state": self.scan_state,+ "scan_error": self.scan_error,+ "job": job.model_dump() if job is not None else None,+ "last_finished": self._job(last).model_dump() if last is not None else None,+ }++ def get_job(self, job_id: str) -> EmbeddingSwitchJob | None:+ row = self.jobs.get(job_id)+ return self._job(row) if row is not None else None++ def summary(self) -> dict[str, object] | None:+ """One line for `/memory-processing` and `/health`."""+ row = self.jobs.open_job()+ if row is None:+ if self.scan_state in {"pending", "scanning"}:+ return {"kind": "merge", "state": "scanning", "percent": 0.0, "eta_s": None}+ return None+ job = self._job(row)+ return {+ "job_id": job.job_id,+ "kind": job.kind,+ "state": job.state,+ "percent": job.progress.percent,+ "eta_s": job.progress.eta_s,+ }++ def _job(self, row: sqlite3.Row) -> EmbeddingSwitchJob:+ live = self._live.get(row["job_id"])+ progress = (+ live.progress+ if live is not None+ else SwitchProgress.model_validate(json.loads(row["progress_json"] or "{}"))+ )+ source = self.spaces.get(row["source_space_id"])+ target = self.spaces.get(row["target_space_id"])+ return EmbeddingSwitchJob(+ job_id=row["job_id"],+ kind=row["kind"],+ state=row["state"],+ source=_summary(source, row["source_space_id"]),+ target=_summary(target, row["target_space_id"]),+ stray_space_ids=list(json.loads(row["stray_space_ids"] or "[]")),+ target_profile_id=row["target_profile_id"],+ target_revision=row["target_revision"],+ requested_by=row["requested_by"],+ progress=progress,+ cancel_requested=bool(row["cancel_requested"]) or bool(live and live.cancel),+ error_code=row["error_code"],+ attempt=int(row["attempt"]),+ created_at=row["created_at"],+ updated_at=row["updated_at"],+ finished_at=row["finished_at"],+ )++ # ------------------------------------------------------------------+ # Planning+ # ------------------------------------------------------------------++ async def plan(+ self, profile_id: str, *, expected_revision: int | None = None+ ) -> EmbeddingSwitchPlan:+ """What switching to `profile_id` would do. Reads only."""+ target = await asyncio.to_thread(self._target_snapshot, profile_id, expected_revision)+ live = await asyncio.to_thread(self.spaces.require_live)+ try:+ identity = embedding_identity(target)+ except EmbeddingSpaceError:+ raise EmbeddingSwitchError("embedding_model_required") from None+ provider = target.embedding_provider_kind or target.provider_kind+ local = provider is ProviderKind.LOCAL_ONNX+ blockers: list[str] = []+ if await asyncio.to_thread(self.jobs.open_job) is not None:+ blockers.append("embedding_switch_running")+ source_summary = _summary(live, live.space_id)+ target_summary = SpaceSummary(+ space_id=None,+ model=identity.model,+ dims=identity.dims,+ collection_base="",+ )+ base: dict[str, Any] = {+ "source": source_summary,+ "target": target_summary,+ "target_profile_id": target.profile_id,+ "target_revision": target.revision,+ "target_provider_kind": provider.value,+ "target_local": local,+ }+ if live.identity is not None and identity.matches(live.identity):+ return EmbeddingSwitchPlan(+ needed=False,+ reason="same_embedding",+ plan_token=_token({"same": live.space_id, **_identity_key(target)}),+ blockers=blockers,+ **base,+ )+ if await self._home_is_empty():+ return EmbeddingSwitchPlan(+ needed=False,+ reason="empty_home",+ plan_token=_token({"empty": live.space_id, **_identity_key(target)}),+ blockers=blockers,+ **base,+ )+ unavailable = self.backend.unavailable_reason()+ if unavailable is not None:+ blockers.append(unavailable)+ if identity.dims is None:+ blockers.append("embedding_dimensions_unknown")+ if not await asyncio.to_thread(self._probed, target):+ blockers.append("embedding_probe_required")+ if await asyncio.to_thread(self._legacy_vectors_waiting, live):+ blockers.append("embedding_switch_requires_migration")+ sources: list[PlannedSource] = []+ users: int | None = None+ if unavailable is None:+ scanned = await self.backend.scan(per_user=True)+ live_scan = _find(scanned, live)+ sources.append(+ PlannedSource(+ space_id=live.space_id,+ collection_base=live.collection_base,+ dims=live.dims,+ vectors=live_scan.vectors if live_scan else 0,+ )+ )+ for scan, space in await self._strays(scanned, live):+ sources.append(+ PlannedSource(+ space_id=space.space_id if space else None,+ collection_base=scan.collection_base,+ dims=scan.width,+ vectors=scan.vectors,+ unmerged=scan.vectors,+ )+ )+ folded = {item.collection_base for item in sources}+ users = len(+ {+ user+ for scan in scanned+ if scan.collection_base in folded+ for user, count in scan.per_user.items()+ if count+ }+ )+ 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)+ dims = identity.dims or 1024+ needed_bytes = (+ int((total + (graph_vectors or 0)) * (dims * 4 + _BYTES_PER_VECTOR_OVERHEAD) * 1.5)+ + _DISK_RESERVE+ )+ free = _free_bytes(self.root)+ if free is not None and free < needed_bytes:+ blockers.append("insufficient_disk_space")+ work = total + (graph_vectors or 0)+ rate = _LOCAL_RATE if local else _REMOTE_RATE+ token = _token(+ {+ "source": live.space_id,+ "target": _identity_key(target),+ "sources": [(item.collection_base, item.vectors) for item in sources],+ }+ )+ return EmbeddingSwitchPlan(+ needed=True,+ reason="embedding_identity_changed",+ plan_token=token,+ sources=sources,+ total_vectors=total,+ users=users,+ graph_vectors=graph_vectors,+ estimate_s=int(work / rate) + 1 if work else 0,+ requests=None if local else -(-work // 64),+ disk_bytes_needed=needed_bytes,+ disk_bytes_free=free,+ blockers=blockers,+ **base,+ )++ def _target_snapshot(+ self, profile_id: str, expected_revision: int | None+ ) -> ModelProfileSnapshot:+ profile = self.profiles.get(profile_id, self.secrets)+ if profile is None:+ raise EmbeddingSwitchError("model_profile_not_found")+ if expected_revision is not None and profile.revision != expected_revision:+ raise EmbeddingSwitchError("model_profile_conflict")+ return self.profiles.snapshot(profile_id, profile.revision)++ def _probed(self, target: ModelProfileSnapshot) -> bool:+ profile = self.profiles.get(target.profile_id, self.secrets)+ return bool(+ profile is not None+ and profile.revision == target.revision+ and profile.capabilities.embedding_available+ and profile.capabilities.endpoint_reachable+ and profile.capabilities.model_available+ )++ def _legacy_vectors_waiting(self, live: EmbeddingSpace) -> bool:+ from one_memory.sdk_vector_reattach import legacy_vector_collections++ profile = self.embedding_profile(live)[0]+ try:+ return bool(legacy_vector_collections(self.data_dir, profile))+ except Exception: # noqa: BLE001 - an unreadable store is not a blocker+ return False++ async def _home_is_empty(self) -> bool:+ """No vector anywhere, no graph, no write in flight: nothing to carry over."""+ if self.backend.unavailable_reason() is None:+ if any(scan.vectors for scan in await self.backend.scan()):+ return False+ else:+ from one_memory.sdk_vector_reattach import filled_collection_names++ if await asyncio.to_thread(filled_collection_names, self.data_dir):+ return False+ return await asyncio.to_thread(self._nothing_else_held)++ def _nothing_else_held(self) -> bool:+ live = self.spaces.live()+ if live is not None and _graph_has_files(self._graph_path(live)):+ return False+ with main_database(self.database_path).read() as connection:+ try:+ running = connection.execute(+ "SELECT COUNT(*) FROM memory_write_jobs WHERE state='running'"+ ).fetchone()[0]+ except sqlite3.OperationalError:+ running = 0+ return not running++ async def _strays(+ self, scanned: tuple[ScannedSpace, ...], live: EmbeddingSpace+ ) -> list[tuple[ScannedSpace, EmbeddingSpace | None]]:+ """Non-empty spaces neither live nor retired: what a merge folds in.++ A retired space is excluded on purpose: its records are already in the+ live space, and folding it in again would bring back what was deleted+ since. Legacy `one_memory_*` collections belong to `sdk-migrate`.+ """+ known = {+ (space.collection_base, space.name_dims or 0): space+ for space in await asyncio.to_thread(self.spaces.list_spaces)+ }+ out: list[tuple[ScannedSpace, EmbeddingSpace | None]] = []+ for scan in scanned:+ if not scan.vectors or scan.key == (live.collection_base, live.name_dims or 0):+ continue+ if not scan.collection_base.startswith("memhub_"):+ continue+ space = known.get(scan.key)+ if space is not None and space.state not in {"stray"}:+ continue+ out.append((scan, space))+ return out++ # ------------------------------------------------------------------+ # Starting a switch+ # ------------------------------------------------------------------++ async def start_switch(+ self,+ profile_id: str,+ *,+ expected_revision: int,+ plan_token: str,+ requested_by: str,+ ) -> EmbeddingSwitchJob:+ async with self._lock:+ plan = await self.plan(profile_id, expected_revision=expected_revision)+ if "embedding_switch_running" in plan.blockers:+ raise EmbeddingSwitchError("embedding_switch_running", plan=plan)+ if plan.plan_token != plan_token:+ raise EmbeddingSwitchError("embedding_switch_plan_stale", plan=plan)+ if not plan.needed:+ raise EmbeddingSwitchError("embedding_switch_not_needed", plan=plan)+ if plan.blockers:+ raise EmbeddingSwitchError(plan.blockers[0], plan=plan)+ target = await asyncio.to_thread(self._target_snapshot, profile_id, expected_revision)+ scanned = await self.backend.scan()+ live = await asyncio.to_thread(self.spaces.require_live)+ strays = [+ await asyncio.to_thread(self._register_stray, scan, space)+ for scan, space in await self._strays(scanned, live)+ ]+ stored = frozenset(name for scan in scanned for name in scan.collections.values())+ job_id = await asyncio.to_thread(+ self._insert_switch, plan, target, live, strays, stored, requested_by+ )+ self._open_cache = True+ self._spawn(job_id)+ job = self.get_job(job_id)+ assert job is not None+ return job++ def _register_stray(self, scan: ScannedSpace, space: EmbeddingSpace | None) -> EmbeddingSpace:+ if space is not None:+ return space+ return self.spaces.register_stray(+ collection_base=scan.collection_base,+ name_dims=scan.name_dims,+ dims=scan.width,+ vectors=scan.vectors,+ )++ def _insert_switch(+ self,+ plan: EmbeddingSwitchPlan,+ target: ModelProfileSnapshot,+ live: EmbeddingSpace,+ strays: list[EmbeddingSpace],+ stored: frozenset[str],+ requested_by: str,+ ) -> str:+ identity = embedding_identity(target)+ provider = target.embedding_provider_kind or target.provider_kind+ now = _now().isoformat()+ job_id = str(uuid4())+ space_id = str(uuid4())+ with self.spaces.transaction() as connection:+ if open_job_in(connection) is not None:+ raise EmbeddingSwitchError("embedding_switch_running")+ current_live = live_space_in(connection)+ if current_live is None or current_live.space_id != live.space_id:+ raise EmbeddingSwitchError("embedding_switch_plan_stale")+ space = EmbeddingSpace(+ space_id=space_id,+ state="building",+ model=identity.model,+ dims=identity.dims,+ name_dims=identity.dims,+ collection_base=next_v2_base(connection, identity, stored_names=stored),+ naming="v2",+ graph_dir=graph_dir_for(space_id),+ provider_kind=provider.value,+ profile_id=target.profile_id,+ profile_revision=target.revision,+ created_at=now,+ )+ insert_space_in(connection, space)+ active = connection.execute(+ "SELECT profile_id FROM model_profiles WHERE is_active=1"+ ).fetchone()+ connection.execute(+ "INSERT INTO embedding_switch_jobs (job_id, kind, state, source_space_id, "+ "target_space_id, stray_space_ids, target_profile_id, target_revision, "+ "prior_profile_id, requested_by, plan_json, progress_json, created_at, "+ "updated_at, owner_pid, heartbeat_at) "+ "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",+ (+ job_id,+ "switch",+ "preparing",+ live.space_id,+ space_id,+ json.dumps([stray.space_id for stray in strays]),+ target.profile_id,+ target.revision,+ active[0] if active is not None else None,+ requested_by,+ plan.model_dump_json(),+ SwitchProgress(sources=1 + len(strays)).model_dump_json(),+ now,+ now,+ self.pid,+ now,+ ),+ )+ self.spaces.invalidate()+ return job_id++ def _insert_merge(self, live: EmbeddingSpace, strays: list[EmbeddingSpace]) -> str:+ now = _now().isoformat()+ job_id = str(uuid4())+ with self.spaces.transaction() as connection:+ if open_job_in(connection) is not None:+ raise EmbeddingSwitchError("embedding_switch_running")+ connection.execute(+ "INSERT INTO embedding_switch_jobs (job_id, kind, state, source_space_id, "+ "target_space_id, stray_space_ids, requested_by, plan_json, progress_json, "+ "created_at, updated_at, owner_pid, heartbeat_at) "+ "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)",+ (+ job_id,+ "merge",+ "preparing",+ live.space_id,+ live.space_id,+ json.dumps([stray.space_id for stray in strays]),+ "startup",+ json.dumps({"strays": [stray.space_id for stray in strays]}),+ SwitchProgress(sources=len(strays)).model_dump_json(),+ now,+ now,+ self.pid,+ now,+ ),+ )+ return job_id++ def activate_empty_home(self, profile_id: str) -> EmbeddingSpace:+ """Activate a profile with another embedding on a home holding no vector.++ Nothing needs re-embedding, so there is no job: one transaction makes+ the profile's space live and activates the profile. The space keeps+ the name every earlier build would give it, so an onboarding that+ picks a custom embedding stays readable after a downgrade.+ """+ profile = self.profiles.get(profile_id, self.secrets)+ if profile is None:+ raise EmbeddingSwitchError("model_profile_not_found")+ snapshot = self.profiles.snapshot(profile_id, profile.revision)+ derived = derived_space(snapshot)+ now = _now()+ with self.spaces.transaction() as connection:+ if open_job_in(connection) is not None:+ raise EmbeddingSwitchError("embedding_switch_running")+ secret_ref = connection.execute(+ "SELECT secret_ref FROM model_profiles WHERE profile_id=?", (profile_id,)+ ).fetchone()+ current = live_space_in(connection)+ if current is not None:+ set_state_in(+ connection, current.space_id, state="dropped", expected=("live",), now=now+ )+ connection.execute(+ "UPDATE embedding_spaces SET state='dropped', dropped_at=? "+ "WHERE collection_base=? AND COALESCE(name_dims,0)=? AND state != 'dropped'",+ (now.isoformat(), derived.collection_base, derived.name_dims or 0),+ )+ space = derived.model_copy(+ update={+ "space_id": str(uuid4()),+ "created_at": now.isoformat(),+ "live_since": now.isoformat(),+ }+ )+ insert_space_in(connection, space)+ ModelProfileStore.activate_in_connection(+ connection,+ snapshot,+ expected_secret_ref=secret_ref[0] if secret_ref is not None else None,+ )+ self.spaces.invalidate()+ return space++ # ------------------------------------------------------------------+ # Startup: resume, or scan and merge+ # ------------------------------------------------------------------++ async def recover(self) -> None:+ """Resume an unfinished job, or scan for strays and start a merge.++ Called before the write drain starts; until it decides, the gate+ holds every model write back (`embedding_scan_pending`).+ """+ try:+ row = await asyncio.to_thread(self.jobs.open_job)+ if row is not None:+ self._open_cache = True+ if self.worker_enabled and _owned_elsewhere(row, self.pid):+ # Another live Core still beats for it: never two workers.+ logger.warning(+ "embedding_switch_owned_elsewhere job_id=%s owner_pid=%s",+ row["job_id"],+ row["owner_pid"],+ )+ elif self.worker_enabled:+ logger.info(+ "embedding_switch_resuming job_id=%s kind=%s state=%s",+ row["job_id"],+ row["kind"],+ row["state"],+ )+ self._spawn(row["job_id"])+ self.scan_state = "done"+ return+ await self.scan_and_merge()+ finally:+ self.release_scan_hold()++ async def scan_and_merge(self) -> str | None:+ """The startup scan. Returns the merge job it started, if any."""+ reason = self.backend.unavailable_reason()+ if reason is not None:+ self.scan_state, self.scan_error = "unavailable", reason+ return None+ if not self.worker_enabled:+ self.scan_state = "done"+ return None+ self.scan_state = "scanning"+ try:+ live = await asyncio.to_thread(self.spaces.require_live)+ scanned = await self.backend.scan()+ live_scan = _find(scanned, live)+ counts = {live.space_id: live_scan.vectors if live_scan else 0}+ if live_scan is not None and live.dims is None and live_scan.width is not None:+ # A relabel: an "auto" space now knows its width. Names stay.+ live = await asyncio.to_thread(+ self.spaces.record_width, live.space_id, live_scan.width+ )+ unmerged: list[EmbeddingSpace] = []+ for scan, space in await self._strays(scanned, live):+ stray = await asyncio.to_thread(self._register_stray, scan, space)+ counts[stray.space_id] = scan.vectors+ missing = sum(+ (await self.backend.diff(scan.physical(), self._physical(live))).values()+ )+ if missing:+ unmerged.append(stray)+ logger.info(+ "embedding_stray_space_found base=%s vectors=%d unmerged=%d",+ scan.collection_base,+ scan.vectors,+ missing,+ )+ else:+ # Nothing it holds is missing: retire it without a job.+ await asyncio.to_thread(self._retire_strays, [stray.space_id])+ await asyncio.to_thread(self.spaces.record_vectors, counts)+ self.scan_state = "done"+ if not unmerged:+ return None+ job_id = await asyncio.to_thread(self._insert_merge, live, unmerged)+ except Exception as error:+ self.scan_state = "failed"+ self.scan_error = getattr(error, "code", None) or type(error).__name__+ logger.warning(+ "embedding_space_scan_failed error_type=%s", type(error).__name__, exc_info=True+ )+ return None+ self._open_cache = True+ self._spawn(job_id)+ return job_id++ def _retire_strays(self, space_ids: list[str]) -> None:+ with self.spaces.transaction() as connection:+ for space_id in space_ids:+ set_state_in(connection, space_id, state="retired", expected=("stray",))+ self.spaces.invalidate()++ # ------------------------------------------------------------------+ # Cancel+ # ------------------------------------------------------------------++ def cancel(self, job_id: str) -> EmbeddingSwitchJob:+ row = self.jobs.get(job_id)+ if row is None:+ raise EmbeddingSwitchError("embedding_switch_not_found")+ if row["state"] not in CANCELLABLE_STATES:+ raise EmbeddingSwitchError("embedding_switch_not_cancellable")+ self.jobs.update(job_id, cancel_requested=1)+ live = self._live.get(job_id)+ if live is not None:+ live.cancel = True+ job = self.get_job(job_id)+ assert job is not None+ return job++ # ------------------------------------------------------------------+ # The worker+ # ------------------------------------------------------------------++ def _spawn(self, job_id: str) -> None:+ if not self.worker_enabled:+ return+ if self._task is not None and not self._task.done():+ return+ self._task = asyncio.get_running_loop().create_task(+ self.run(job_id), name="one-memory-embedding-switch"+ )++ async def wait(self) -> None:+ """Until the running worker (if any) stops. For tests and shutdown."""+ task = self._task+ if task is not None:+ await asyncio.gather(task, return_exceptions=True)++ async def shutdown(self) -> None:+ for task in (self._task, self._heartbeat, self._retention):+ if task is not None and not task.done():+ task.cancel()+ for task in (self._task, self._heartbeat, self._retention):+ if task is not None:+ await asyncio.gather(task, return_exceptions=True)++ async def run(self, job_id: str) -> None:+ """Drive one job to `done` or `rolled_back`, from whatever state it is in."""+ await asyncio.to_thread(self.jobs.claim, job_id, pid=self.pid)+ row = await asyncio.to_thread(self.jobs.get, job_id)+ if row is None:+ return+ live = _Live(+ progress=SwitchProgress.model_validate(json.loads(row["progress_json"] or "{}")),+ cancel=bool(row["cancel_requested"]),+ )+ self._live[job_id] = live+ self._heartbeat = asyncio.get_running_loop().create_task(self._beat(job_id))+ try:+ await self._drive(job_id)+ finally:+ self._heartbeat.cancel()+ await asyncio.gather(self._heartbeat, return_exceptions=True)+ self._live.pop(job_id, None)+ self._open_cache = await asyncio.to_thread(self.jobs.open_job) is not None++ async def _beat(self, job_id: str) -> None:+ while True:+ await asyncio.sleep(HEARTBEAT_SECONDS)+ try:+ await asyncio.to_thread(self.jobs.beat, job_id, pid=self.pid)+ except Exception: # noqa: BLE001 - a missed beat is not a failure+ logger.debug("embedding_switch_heartbeat_failed", exc_info=True)++ async def _drive(self, job_id: str) -> None:+ while True:+ row = await asyncio.to_thread(self.jobs.get, job_id)+ if row is None or row["state"] in TERMINAL_STATES:+ return+ state = row["state"]+ if state == "failed":+ await self._rollback(row)+ continue+ try:+ if self._cancelled(job_id) and state in CANCELLABLE_STATES:+ raise ReembedCancelledError("embedding_switch_cancelled")+ if state == "preparing":+ await self._prepare(row)+ next_state: JobState = "reembedding"+ elif state == "reembedding":+ await self._reembed(row)+ next_state = "verifying"+ elif state == "verifying":+ await self._verify(row)+ next_state = "committing"+ elif state == "committing":+ await self._commit(row)+ continue+ else: # pragma: no cover - CHECK constraint+ raise EmbeddingSwitchError("embedding_switch_state_unknown")+ except asyncio.CancelledError:+ # Core is stopping: the job resumes from this state next start.+ await asyncio.to_thread(self._flush, job_id)+ raise+ except Exception as error:+ code = _failure_code(error)+ logger.warning(+ "embedding_switch_failed job_id=%s state=%s code=%s error_type=%s",+ job_id,+ state,+ code,+ type(error).__name__,+ )+ await asyncio.to_thread(+ self.jobs.update,+ job_id,+ state="failed",+ error_code=code,+ error_detail=type(error).__name__,+ )+ continue+ await asyncio.to_thread(self._flush, job_id)+ await asyncio.to_thread(self.jobs.update, job_id, state=next_state)++ def _cancelled(self, job_id: str) -> bool:+ live = self._live.get(job_id)+ if live is not None and live.cancel:+ return True+ row = self.jobs.get(job_id)+ cancelled = bool(row is not None and row["cancel_requested"])+ if cancelled and live is not None:+ live.cancel = True+ return cancelled++ # -- preparing -------------------------------------------------------++ async def _prepare(self, row: sqlite3.Row) -> None:+ self._set_progress(row["job_id"], phase="prepare")+ if row["kind"] == "switch":+ await asyncio.to_thread(self._check_target, row)+ deadline = time.monotonic() + self.drain_timeout_s+ while not await self.drain_idle():+ if self._cancelled(row["job_id"]):+ raise ReembedCancelledError("embedding_switch_cancelled")+ if time.monotonic() >= deadline:+ raise EmbeddingSwitchError("writes_did_not_drain")+ await asyncio.sleep(0.5)++ def _check_target(self, row: sqlite3.Row) -> None:+ profile = self.profiles.get(row["target_profile_id"], self.secrets)+ if profile is None or profile.revision != row["target_revision"]:+ raise EmbeddingSwitchError("target_profile_changed")++ # -- reembedding -----------------------------------------------------++ async def _reembed(self, row: sqlite3.Row) -> None:+ job_id = row["job_id"]+ source, target, strays = await asyncio.to_thread(self._job_spaces, row)+ embedding = await asyncio.to_thread(self._embedding_target, target, row)+ target_physical = self._physical(target)+ if target_physical.dims is None:+ raise EmbeddingSwitchError("embedding_dimensions_unknown")+ sources: list[PhysicalSpace] = []+ if row["kind"] == "switch":+ # The live space first, so its records win over any stray's.+ sources.append(self._physical(source))+ sources.extend(self._physical(stray) for stray in strays)+ scanned = await self.backend.scan()+ totals = []+ for item in sources:+ found = next(+ (+ scan+ for scan in scanned+ if scan.key == (item.collection_base, item.name_dims or 0)+ ),+ None,+ )+ totals.append(found.vectors if found else 0)+ live = self._live[job_id]+ grand_total = sum(totals)+ live.base_done = 0+ live.started = time.monotonic()+ for index, item in enumerate(sources):+ self._set_progress(+ job_id,+ phase="vectors",+ source_index=index + 1,+ sources=len(sources),+ total=grand_total,+ done=live.base_done,+ )+ await self._reembed_one(job_id, item, target_physical, embedding, grand_total)+ live.base_done += totals[index]+ if row["kind"] == "switch":+ await self._reembed_graph(job_id, source, target, embedding)+ self._set_progress(job_id, phase="verify", done=grand_total, total=grand_total)++ async def _reembed_one(+ self,+ job_id: str,+ source: PhysicalSpace,+ target: PhysicalSpace,+ embedding: EmbeddingTarget,+ grand_total: int,+ ) -> None:+ live = self._live[job_id]+ role_done: dict[str, int] = {}+ counters: dict[str, tuple[int, int, int]] = {}++ def on_step(step: ReembedStep) -> None:+ role_done[step.role] = step.done+ counters[step.role] = (step.embedded, step.reused, step.kept)+ done = live.base_done + sum(role_done.values())+ embedded = sum(value[0] for value in counters.values())+ elapsed = max(time.monotonic() - live.started, 1e-3)+ rate = embedded / elapsed if embedded else None+ remaining = max(grand_total - done, 0)+ self._set_progress(+ job_id,+ phase="vectors",+ role=step.role,+ done=done,+ total=grand_total,+ embedded=embedded,+ reused=sum(value[1] for value in counters.values()),+ kept=sum(value[2] for value in counters.values()),+ rate_per_s=round(rate, 1) if rate else None,+ eta_s=int(remaining / rate) if rate else None,+ )++ for attempt in range(REEMBED_ATTEMPTS):+ try:+ await self.backend.reembed(+ source,+ target,+ embedding=embedding,+ cancel=lambda: self._cancel_flag(job_id),+ on_step=on_step,+ )+ return+ except (ReembedCancelledError, EmbeddingWidthError, ReembedUnavailableError):+ raise+ except Exception:+ if attempt + 1 >= REEMBED_ATTEMPTS:+ raise+ delay = REEMBED_RETRY_SECONDS[min(attempt, len(REEMBED_RETRY_SECONDS) - 1)]+ logger.warning(+ "embedding_switch_reembed_retry job_id=%s attempt=%d delay_s=%.0f",+ job_id,+ attempt + 1,+ delay,+ exc_info=True,+ )+ await asyncio.sleep(delay)++ def _cancel_flag(self, job_id: str) -> bool:+ live = self._live.get(job_id)+ return bool(live and live.cancel)++ async def _reembed_graph(+ self,+ job_id: str,+ source: EmbeddingSpace,+ target: EmbeddingSpace,+ embedding: EmbeddingTarget,+ ) -> None:+ source_graph = self._graph_path(source)+ if not self.graph_enabled() or not _graph_has_files(source_graph):+ return+ target_dims = target.dims or target.name_dims+ if target_dims is None:+ raise EmbeddingSwitchError("embedding_dimensions_unknown")+ self._set_progress(job_id, phase="graph", role=None)+ release = await self._quiesce()+ try:+ await self.backend.reembed_graph(+ source_graph,+ self._graph_path(target),+ embedding=embedding,+ target_dims=target_dims,+ cancel=lambda: self._cancel_flag(job_id),+ on_step=lambda step: self._set_progress(job_id, phase="graph", role=step.role),+ )+ finally:+ 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:+ return lambda: None+ return await self.quiesce_clients()++ # -- verifying -------------------------------------------------------++ async def _verify(self, row: sqlite3.Row) -> None:+ job_id = row["job_id"]+ self._set_progress(job_id, phase="verify")+ source, target, strays = await asyncio.to_thread(self._job_spaces, row)+ target_physical = self._physical(target)+ problems: list[str] = []+ report: dict[str, Any] = {"strays": {}}+ for stray in strays:+ missing = await self.backend.diff(self._physical(stray), target_physical)+ report["strays"][stray.space_id] = missing+ if sum(missing.values()):+ problems.append(f"stray {stray.collection_base}: {sum(missing.values())} missing")+ if row["kind"] == "switch":+ embedding = await asyncio.to_thread(self._embedding_target, target, row)+ source_physical = self._physical(source)+ check = await self.backend.verify(source_physical, target_physical, embedding=embedding)+ report.update(+ {+ "per_role": {key: dict(value) for key, value in check.per_role.items()},+ "per_user": dict(check.per_user),+ "warnings": list(check.warnings),+ "self_recall": [check.self_recall_hits, check.self_recall_samples],+ }+ )+ if not strays:+ problems.extend(check.problems)+ else:+ # Strays add ids the source does not have; only a lost,+ # changed or mis-sized record is a failure.+ for role, values in check.per_role.items():+ for label in ("missing", "mismatched", "bad_dims"):+ if values.get(label):+ problems.append(f"{role}: {values[label]} {label}")+ scanned = await self.backend.scan(per_user=True)+ live_scan = _find(scanned, source)+ 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)):+ 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+ )+ report["graph"] = {"ok": graph.ok, "problems": list(graph.problems)}+ problems.extend(f"graph: {item}" for item in graph.problems)+ report["problems"] = problems+ await asyncio.to_thread(+ self.jobs.update, job_id, verification_json=json.dumps(report, sort_keys=True)+ )+ if problems:+ raise EmbeddingSwitchError("embedding_verification_failed")++ # -- committing ------------------------------------------------------++ async def _commit(self, row: sqlite3.Row) -> None:+ job_id = row["job_id"]+ self._set_progress(job_id, phase="commit")+ await asyncio.to_thread(self._flush, job_id)+ await asyncio.to_thread(self.jobs.update, job_id, state="committing")+ try:+ await asyncio.to_thread(self._commit_transaction, job_id)+ except Exception as error:+ await asyncio.to_thread(+ self.jobs.update,+ job_id,+ state="failed",+ error_code=_failure_code(error),+ error_detail=type(error).__name__,+ )+ return+ self._open_cache = False+ job = self.get_job(job_id)+ logger.info("embedding_switch_committed job_id=%s kind=%s", job_id, row["kind"])+ if job is not None and self.on_commit is not None:+ try:+ await self.on_commit(job)+ except Exception: # noqa: BLE001 - the commit stands; the hooks are follow-ups+ logger.warning("embedding_switch_post_commit_failed", exc_info=True)++ def _commit_transaction(self, job_id: str) -> None:+ """One transaction: the new space live, the old one retired, the profile active.++ A failure anywhere rolls back all of it; nothing outside SQLite is+ touched, because no collection is renamed at commit.+ """+ now = _now()+ before = self.jobs.get(job_id)+ profile = (+ self.profiles.snapshot(before["target_profile_id"], before["target_revision"])+ if before is not None and before["kind"] == "switch"+ else None+ )+ with self.spaces.transaction() as connection:+ previous = connection.row_factory+ connection.row_factory = sqlite3.Row+ try:+ row = connection.execute(+ "SELECT * FROM embedding_switch_jobs WHERE job_id=?", (job_id,)+ ).fetchone()+ finally:+ connection.row_factory = previous+ if row is None or row["state"] != "committing":+ raise EmbeddingSwitchError("embedding_switch_state_changed")+ if not row["verification_json"]:+ raise EmbeddingSwitchError("embedding_verification_missing")+ for stray_id in json.loads(row["stray_space_ids"] or "[]"):+ set_state_in(connection, stray_id, state="retired", expected=("stray",), now=now)+ if row["kind"] == "switch":+ if profile is None:+ raise EmbeddingSwitchError("embedding_switch_state_changed")+ current = connection.execute(+ "SELECT revision, secret_ref FROM model_profiles WHERE profile_id=?",+ (row["target_profile_id"],),+ ).fetchone()+ if current is None or current[0] != row["target_revision"]:+ raise EmbeddingSwitchError("target_profile_changed")+ set_state_in(+ connection, row["source_space_id"], state="retired", expected=("live",), now=now+ )+ set_state_in(+ connection,+ row["target_space_id"],+ state="live",+ expected=("building",),+ now=now,+ )+ ModelProfileStore.activate_in_connection(+ connection, profile, expected_secret_ref=current[1]+ )+ connection.execute(+ "UPDATE embedding_switch_jobs SET state='done', finished_at=?, updated_at=?, "+ "progress_json=? WHERE job_id=?",+ (+ now.isoformat(),+ now.isoformat(),+ self._final_progress(job_id).model_dump_json(),+ job_id,+ ),+ )+ self.spaces.invalidate()++ def _final_progress(self, job_id: str) -> SwitchProgress:+ live = self._live.get(job_id)+ progress = live.progress if live is not None else SwitchProgress()+ return progress.model_copy(+ update={"phase": "done", "percent": 100.0, "eta_s": 0, "updated_at": _now().isoformat()}+ )++ # -- rollback --------------------------------------------------------++ async def _rollback(self, row: sqlite3.Row) -> None:+ """Drop what the job built. The source was never written; it stays live."""+ job_id = row["job_id"]+ self._set_progress(job_id, phase="rollback")+ if row["kind"] == "switch":+ target = await asyncio.to_thread(self.spaces.get, row["target_space_id"])+ if target is not None and target.state == "building":+ try:+ await self.backend.drop(self._physical(target))+ if _graph_has_files(self._graph_path(target)):+ await self.backend.drop_graph(self._graph_path(target))+ except ReembedUnavailableError:+ pass+ except Exception: # noqa: BLE001 - leftovers are dropped by the sweep+ logger.warning("embedding_switch_rollback_drop_failed", exc_info=True)+ await asyncio.to_thread(self.spaces.mark_dropped, target.space_id)+ now = _now().isoformat()+ await asyncio.to_thread(self.jobs.update, job_id, state="rolled_back", finished_at=now)+ self._open_cache = False+ logger.info("embedding_switch_rolled_back job_id=%s code=%s", job_id, row["error_code"])++ # ------------------------------------------------------------------+ # Retention+ # ------------------------------------------------------------------++ def start_retention(self, *, interval_s: float = 24 * 60 * 60) -> None:+ if self._retention is None or self._retention.done():+ self._retention = asyncio.get_running_loop().create_task(+ self._retention_loop(interval_s), name="one-memory-embedding-retention"+ )++ async def _retention_loop(self, interval_s: float) -> None:+ while True:+ try:+ dropped = await self.sweep_retired()+ if dropped:+ logger.info("embedding_retired_spaces_dropped count=%d", len(dropped))+ except asyncio.CancelledError:+ raise+ except Exception: # noqa: BLE001 - tried again tomorrow+ logger.warning("embedding_retention_sweep_failed", exc_info=True)+ await asyncio.sleep(interval_s)++ async def sweep_retired(self, *, now: datetime | None = None) -> list[str]:+ """Drop every retired space past its keep-until date. Never the live one."""+ if self.backend.unavailable_reason() is not None:+ return []+ dropped: list[str] = []+ for space in await asyncio.to_thread(self.spaces.expired, now=now):+ await self.drop_space(space.space_id)+ dropped.append(space.space_id)+ return dropped++ async def drop_space(self, space_id: str) -> EmbeddingSpace:+ """Delete a retired space's collections and graph now (the user's cleanup)."""+ space = await asyncio.to_thread(self.spaces.get, space_id)+ if space is None or space.state == "dropped":+ raise EmbeddingSwitchError("embedding_space_not_found")+ if space.state != "retired":+ raise EmbeddingSwitchError("embedding_space_not_retired")+ await self.backend.drop(self._physical(space))+ live = await asyncio.to_thread(self.spaces.live)+ if space.graph_dir and (live is None or live.graph_dir != space.graph_dir):+ graph = self._graph_path(space)+ if _graph_has_files(graph):+ await self.backend.drop_graph(graph)+ await asyncio.to_thread(self.spaces.mark_dropped, space_id)+ dropped = await asyncio.to_thread(self.spaces.get, space_id)+ assert dropped is not None+ return dropped++ # ------------------------------------------------------------------+ # Helpers+ # ------------------------------------------------------------------++ def _job_spaces(+ self, row: sqlite3.Row+ ) -> tuple[EmbeddingSpace, EmbeddingSpace, list[EmbeddingSpace]]:+ source = self.spaces.get(row["source_space_id"])+ target = self.spaces.get(row["target_space_id"])+ if source is None or target is None:+ raise EmbeddingSwitchError("embedding_space_not_found")+ strays = []+ for space_id in json.loads(row["stray_space_ids"] or "[]"):+ stray = self.spaces.get(space_id)+ if stray is not None and stray.state == "stray":+ strays.append(stray)+ return source, target, strays++ def _physical(self, space: EmbeddingSpace) -> PhysicalSpace:+ return PhysicalSpace.of(space)++ def _graph_path(self, space: EmbeddingSpace) -> Path:+ return self.root / (space.graph_dir or DEFAULT_GRAPH_DIR)++ def embedding_profile(self, space: EmbeddingSpace) -> tuple[ModelProfileSnapshot, bool]:+ """The profile version whose embedding fills `space`, and whether it is active."""+ from one_memory.hy_sdk_runtime import builtin_retrieval_snapshot++ identity = self.profiles.active_identity()+ if identity is not None and space.identity is not None:+ active = self.profiles.snapshot(*identity)+ if embedding_identity(active).matches(space.identity):+ return active, True+ if space.profile_id is not None and space.profile_revision is not None:+ try:+ return self.profiles.snapshot(space.profile_id, space.profile_revision), False+ except KeyError:+ pass+ return builtin_retrieval_snapshot(), False++ def _embedding_target(self, space: EmbeddingSpace, row: sqlite3.Row) -> EmbeddingTarget:+ if row["kind"] == "switch":+ profile = self.profiles.snapshot(row["target_profile_id"], row["target_revision"])+ else:+ profile = self.embedding_profile(space)[0]+ key: str | None = None+ provider = profile.embedding_provider_kind or profile.provider_kind+ if provider is ProviderKind.OPENAI_COMPATIBLE:+ try:+ key = self.profiles.resolve_snapshot_secret(+ profile.profile_id, profile.revision, self.secrets+ )+ except SecretStoreUnavailableError:+ raise EmbeddingSwitchError("secure_storage_unavailable") from None+ if key is None:+ raise EmbeddingSwitchError("model_secret_unavailable")+ if space.dims is None and space.name_dims is None:+ identity = embedding_identity(profile)+ if identity.dims is not None:+ space = space.model_copy(update={"dims": identity.dims})+ return EmbeddingTarget(profile=profile, space=space, api_key=key)++ def _set_progress(self, job_id: str, **values: Any) -> None:+ live = self._live.get(job_id)+ if live is None:+ return+ update = {key: value for key, value in values.items() if key in SwitchProgress.model_fields}+ progress = live.progress.model_copy(update=update)+ if progress.total:+ progress = progress.model_copy(+ update={"percent": round(min(progress.done / progress.total, 1.0) * 100, 1)}+ )+ live.progress = progress.model_copy(update={"updated_at": _now().isoformat()})+ if time.monotonic() - live.last_write >= PROGRESS_WRITE_SECONDS:+ live.last_write = time.monotonic()+ try:+ self.jobs.update(job_id, progress_json=live.progress.model_dump_json())+ except Exception: # noqa: BLE001 - progress is advisory+ logger.debug("embedding_switch_progress_write_failed", exc_info=True)++ def _flush(self, job_id: str) -> None:+ live = self._live.get(job_id)+ if live is not None:+ self.jobs.update(job_id, progress_json=live.progress.model_dump_json())+++async def _always_idle() -> bool:+ return True+++def _find(scanned: tuple[ScannedSpace, ...], space: EmbeddingSpace) -> ScannedSpace | None:+ key = (space.collection_base, space.name_dims or 0)+ return next((scan for scan in scanned if scan.key == key), None)+++def _summary(space: EmbeddingSpace | None, space_id: str) -> SpaceSummary:+ if space is None:+ return SpaceSummary(space_id=space_id, model=None, dims=None, collection_base="")+ return SpaceSummary(+ space_id=space.space_id,+ model=space.model,+ dims=space.dims if space.dims is not None else space.name_dims,+ collection_base=space.collection_base,+ vectors=space.vectors,+ )+++def _identity_key(profile: ModelProfileSnapshot) -> dict[str, object]:+ identity = embedding_identity(profile)+ return {+ "profile_id": profile.profile_id,+ "revision": profile.revision,+ "model": identity.model,+ "dims": identity.dims,+ }+++def _token(value: object) -> str:+ return hashlib.sha256(json.dumps(value, sort_keys=True, default=str).encode()).hexdigest()[:24]+++def _free_bytes(path: Path) -> int | None:+ probe = path+ while not probe.exists() and probe != probe.parent:+ probe = probe.parent+ try:+ return shutil.disk_usage(probe).free+ except OSError:+ return None+++def _graph_has_files(path: Path) -> bool:+ return path.exists()+++def _failure_code(error: BaseException) -> str:+ if isinstance(error, ReembedCancelledError):+ return "embedding_switch_cancelled"+ if isinstance(error, EmbeddingWidthError):+ return "embedding_dimensions_mismatch"+ code = getattr(error, "code", None)+ if isinstance(code, str) and code:+ return code+ if isinstance(error, EmbeddingSpaceError):+ return error.code+ return "embedding_service_failed"+++def default_reembed_backend(data_dir: Path) -> ReembedBackend:+ """The SDK-backed re-embed functions for this home (tests replace this)."""+ from one_memory.hy_sdk_migration import SdkReembedBackend++ return SdkReembedBackend(data_dir)+++def _owned_elsewhere(row: sqlite3.Row, pid: int) -> bool:+ """Whether another process that is alive beat for this job within a minute."""+ owner = row["owner_pid"]+ if owner is None or int(owner) == pid or not row["heartbeat_at"]:+ return False+ beat = datetime.fromisoformat(row["heartbeat_at"])+ if _now() - beat > STALE_HEARTBEAT:+ return False+ try:+ os.kill(int(owner), 0)+ except ProcessLookupError:+ return False+ except PermissionError:+ return True+ return Truediff --git a/memhub/apps/core/src/one_memory/embedding_switch_routes.py b/memhub/apps/core/src/one_memory/embedding_switch_routes.pynew file mode 100644index 0000000..1b5d492--- /dev/null+++ b/memhub/apps/core/src/one_memory/embedding_switch_routes.py@@ -0,0 +1,161 @@+"""HTTP surface of the embedding switch: spaces, plans, jobs, cleanup.++The contract the App and the CLI build on is+`memhub/docs/contracts/embedding-switch-v1.md`. Errors keep Core's shape,+`{"detail": "<code>"}`; a refusal that computed a plan also carries it as+`"plan"`, so a client can show the confirmation without asking again.+"""++from __future__ import annotations++import asyncio+from collections.abc import Sequence+from typing import Any, cast++from fastapi import APIRouter, Request, Response+from fastapi.params import Depends+from fastapi.responses import JSONResponse+from pydantic import BaseModel, ConfigDict, Field++from one_memory.embedding_backend import ReembedUnavailableError+from one_memory.embedding_spaces import EmbeddingSpaceError+from one_memory.embedding_switch import (+ EmbeddingSwitchError,+ EmbeddingSwitchPlan,+ EmbeddingSwitchService,+)++#: HTTP status per refusal code; anything not listed is a 409.+_STATUS = {+ "model_profile_not_found": 404,+ "embedding_switch_not_found": 404,+ "embedding_space_not_found": 404,+ "sdk_reembed_unavailable": 503,+ "secure_storage_unavailable": 503,+ "insufficient_disk_space": 507,+}+++class EmbeddingSwitchPlanRequest(BaseModel):+ model_config = ConfigDict(extra="forbid")++ profile_id: str = Field(min_length=1, max_length=128)+ expected_revision: int | None = Field(default=None, ge=1)+++class EmbeddingSwitchStartRequest(BaseModel):+ model_config = ConfigDict(extra="forbid")++ profile_id: str = Field(min_length=1, max_length=128)+ expected_revision: int = Field(ge=1)+ plan_token: str = Field(min_length=1, max_length=128)+ requested_by: str = Field(default="app", pattern=r"^(app|cli)$")+++def refusal(code: str, *, plan: EmbeddingSwitchPlan | None = None) -> JSONResponse:+ content: dict[str, Any] = {"detail": code}+ if plan is not None:+ content["plan"] = plan.model_dump(mode="json")+ return JSONResponse(status_code=_STATUS.get(code, 409), content=content)+++def _service(request: Request) -> EmbeddingSwitchService:+ return cast(EmbeddingSwitchService, request.app.state.embedding_switch)+++def embedding_switch_router(dependencies: Sequence[Depends]) -> APIRouter:+ router = APIRouter(dependencies=dependencies)++ @router.get("/api/v1/embedding-spaces")+ async def list_embedding_spaces(request: Request) -> dict[str, object]:+ """The registry and what the vector store holds, space by space."""+ service = _service(request)+ spaces = await asyncio.to_thread(service.spaces.list_spaces)+ live = next((space for space in spaces if space.state == "live"), None)+ scanned: list[dict[str, object]] | None = None+ scan_error = service.backend.unavailable_reason()+ if scan_error is None:+ try:+ found = await service.backend.scan()+ except Exception as error: # noqa: BLE001 - the registry still answers+ scan_error = getattr(error, "code", None) or "embedding_space_scan_failed"+ else:+ known = {(space.collection_base, space.name_dims or 0): space for space in spaces}+ scanned = [+ {+ "collection_base": item.collection_base,+ "name_dims": item.name_dims,+ "width": item.width,+ "vectors": item.vectors,+ "counts": dict(item.counts),+ "space_id": known[item.key].space_id if item.key in known else None,+ "state": known[item.key].state if item.key in known else "unregistered",+ }+ for item in found+ ]+ return {+ "schema_version": 1,+ "live_space_id": live.space_id if live is not None else None,+ "spaces": [space.model_dump(mode="json") for space in spaces],+ "scanned": scanned,+ "scan_error": scan_error,+ }++ @router.delete("/api/v1/embedding-spaces/{space_id}", response_model=None)+ async def delete_embedding_space(space_id: str, request: Request) -> Any:+ """Clean up a retired space now instead of after its 14 days."""+ try:+ space = await _service(request).drop_space(space_id)+ except (EmbeddingSwitchError, EmbeddingSpaceError, ReembedUnavailableError) as error:+ return refusal(error.code)+ except RuntimeError as error:+ if "held open" in str(error):+ return refusal("embedding_space_in_use")+ raise+ return {"schema_version": 1, "space": space.model_dump(mode="json")}++ @router.post("/api/v1/embedding-switches/plan", response_model=None)+ async def plan_embedding_switch(value: EmbeddingSwitchPlanRequest, request: Request) -> Any:+ try:+ plan = await _service(request).plan(+ value.profile_id, expected_revision=value.expected_revision+ )+ except EmbeddingSwitchError as error:+ return refusal(error.code, plan=error.plan)+ return plan.model_dump(mode="json")++ @router.post("/api/v1/embedding-switches", status_code=202, response_model=None)+ async def start_embedding_switch(value: EmbeddingSwitchStartRequest, request: Request) -> Any:+ try:+ job = await _service(request).start_switch(+ value.profile_id,+ expected_revision=value.expected_revision,+ plan_token=value.plan_token,+ requested_by=value.requested_by,+ )+ except EmbeddingSwitchError as error:+ return refusal(error.code, plan=error.plan)+ return job.model_dump(mode="json")++ @router.get("/api/v1/embedding-switches/current")+ async def current_embedding_switch(request: Request, response: Response) -> dict[str, object]:+ """Polled by the loading screen, the banner and `memhub models switch status`."""+ response.headers["Cache-Control"] = "no-store"+ return await asyncio.to_thread(_service(request).current)++ @router.get("/api/v1/embedding-switches/{job_id}", response_model=None)+ async def get_embedding_switch(job_id: str, request: Request) -> Any:+ job = await asyncio.to_thread(_service(request).get_job, job_id)+ if job is None:+ return refusal("embedding_switch_not_found")+ return job.model_dump(mode="json")++ @router.post("/api/v1/embedding-switches/{job_id}/cancel", response_model=None)+ async def cancel_embedding_switch(job_id: str, request: Request) -> Any:+ try:+ job = await asyncio.to_thread(_service(request).cancel, job_id)+ except EmbeddingSwitchError as error:+ return refusal(error.code)+ return job.model_dump(mode="json")++ return routerdiff --git a/memhub/apps/core/src/one_memory/hy_graph_admin.py b/memhub/apps/core/src/one_memory/hy_graph_admin.pyindex 7e1c169..0c07173 100644--- a/memhub/apps/core/src/one_memory/hy_graph_admin.py+++ b/memhub/apps/core/src/one_memory/hy_graph_admin.py@@ -94,11 +94,15 @@ def inspect_profile_graph_width(api_key: str | None,data_dir: Path,mode: str | None = None,+ graph_dir: str = "graph",) -> GraphWidthMismatch | None:- """Inspect the graph path and width selected by the active profile."""+ """Inspect the graph path and width selected by the active profile.++ `graph_dir` is the live embedding space's graph (`embedding_spaces`).+ """del api_keyreturn _inspect_graph_width(- _profile_graph_path(data_dir, mode),+ _profile_graph_path(data_dir, mode, graph_dir),_profile_embedding_width(profile),)@@ -110,11 +114,12 @@ def decide_profile_graph_width(data_dir: Path,decision: GraphWidthDecision,mode: str | None = None,+ graph_dir: str = "graph",) -> GraphWidthOutcome:"""Apply the user's decision to the active profile's graph."""del api_keyconfig = _GraphAdminConfig(- graph_store=_GraphStoreConfig(str(_profile_graph_path(data_dir, mode))),+ graph_store=_GraphStoreConfig(str(_profile_graph_path(data_dir, mode, graph_dir))),embedder=_EmbeddingWidthConfig(_profile_embedding_width(profile)),)return apply_graph_width_decision(@@ -204,6 +209,12 @@ _GRAPH_WIDTH_CACHE: dict[str, int | None] = {}_GRAPH_WIDTH_LOCK = threading.Lock()+def forget_graph_widths() -> None:+ """Drop every remembered width: an embedding switch moved the graph."""+ with _GRAPH_WIDTH_LOCK:+ _GRAPH_WIDTH_CACHE.clear()++def _graph_embedding_width(db_path: Path) -> int | None:"""Read the Memory embedding width directly from Kuzu's schema."""try:@@ -252,9 +263,9 @@ def _inspect_graph_width()-def _profile_graph_path(data_dir: Path, mode: str | None = None) -> Path:+def _profile_graph_path(data_dir: Path, mode: str | None = None, graph_dir: str = "graph") -> Path:ultra = mode == "ultra" if mode is not None else graph_store_enabled()- name = "graph" if ultra else "graph-disabled"+ name = graph_dir if ultra else "graph-disabled"return data_dir / "hy-memory" / HY_MEMORY_NAMESPACE / namediff --git a/memhub/apps/core/src/one_memory/hy_sdk_migration.py b/memhub/apps/core/src/one_memory/hy_sdk_migration.pyindex 1e858aa..d128c10 100644--- a/memhub/apps/core/src/one_memory/hy_sdk_migration.py+++ b/memhub/apps/core/src/one_memory/hy_sdk_migration.py@@ -3,6 +3,10 @@Runtime product code must use public ``HyMemoryClient`` methods. The startupmigration boundary is the isolated exception: all writers are stopped, so itmay copy, restore and repair SDK-owned local stores.++The embedding switch is the second such boundary: model writes are paused+while it re-embeds one space into another (`SdkReembedBackend`), so it may+read and fill SDK collections through the SDK's re-embed module."""from __future__ import annotations@@ -10,13 +14,14 @@ from __future__ import annotationsimport jsonimport sqlite3from collections.abc import Iterator-from contextlib import closing+from contextlib import closing, contextmanagerfrom dataclasses import dataclass, fieldfrom datetime import UTC, datetime, timedeltafrom pathlib import Pathfrom typing import Any-from hy_memory import ( # type: ignore[import-untyped]+import hy_memory # type: ignore[import-untyped]+from hy_memory import (DataPlaneRestore,DataPlaneSnapshot,restore_local_data_plane,@@ -497,7 +502,7 @@ def _ensure_coding_schema(path: Path) -> None:CodingMemoryStore,)- # Relies on the pinned SDK's internals (hy-memory==2.0.9 is pinned exactly).+ # Relies on the pinned SDK's internals (hy-memory==2.0.10 is pinned exactly).store = CodingMemoryStore.__new__(CodingMemoryStore)store._db_path = str(path)store._conn = None@@ -511,3 +516,225 @@ def _ensure_coding_schema(path: Path) -> None:def _batches[T](values: list[T] | tuple[T, ...]) -> Iterator[tuple[T, ...]]:for start in range(0, len(values), _BATCH):yield tuple(values[start : start + _BATCH])+++# The SDK functions the embedding switch needs. They arrived in hy-memory+# 2.0.10; an older SDK reports `sdk_reembed_unavailable` instead of failing.+_REEMBED_API = (+ "VectorSpace",+ "scan_vector_spaces",+ "diff_spaces",+ "reembed_vector_space",+ "verify_reembed",+ "drop_vector_space",+ "reembed_graph",+ "verify_graph_reembed",+ "drop_graph",+ "ReembedCancelled",+)+++class SdkReembedBackend:+ """`ReembedBackend` over `hy_memory`'s re-embed module, for one home.++ Runs beside live SDK clients: the vector functions open Chroma with the+ SDK's own settings, so they share its client system. The graph functions+ refuse a graph a live client holds open; the switch closes them first.+ """++ def __init__(self, data_dir: Path) -> None:+ self.data_dir = data_dir+ self.root = data_dir.resolve() / "hy-memory" / HY_MEMORY_NAMESPACE+ self.persist_directory = self.root / "vector"++ def unavailable_reason(self) -> str | None:+ missing = [name for name in _REEMBED_API if not hasattr(hy_memory, name)]+ return "sdk_reembed_unavailable" if missing else None++ def _sdk(self) -> Any:+ from one_memory.embedding_backend import ReembedUnavailableError++ reason = self.unavailable_reason()+ if reason is not None:+ raise ReembedUnavailableError(reason)+ return hy_memory++ def _vector_space(self, space: Any) -> Any:+ return self._sdk().VectorSpace(+ base_name=space.collection_base,+ dims=space.dims,+ persist_directory=str(self.persist_directory),+ model=space.model,+ collections=space.names(),+ )++ async def scan(self, *, per_user: bool = False) -> tuple[Any, ...]:+ from one_memory.embedding_backend import ScannedSpace++ if not self.persist_directory.is_dir():+ return ()+ found = await self._sdk().scan_vector_spaces(str(self.persist_directory), per_user=per_user)+ return tuple(+ ScannedSpace(+ collection_base=str(item.base_name),+ name_dims=item.dims,+ width=item.width,+ counts={role: int(entry.count) for role, entry in item.roles.items()},+ collections={role: str(entry.name) for role, entry in item.roles.items()},+ per_user=dict(item.per_user) if per_user else {},+ )+ for item in found+ )++ async def diff(self, source: Any, target: Any) -> dict[str, int]:+ result = await self._sdk().diff_spaces(+ self._vector_space(source), self._vector_space(target)+ )+ return {role: len(ids) for role, ids in result.missing.items()}++ async def reembed(+ self,+ source: Any,+ target: Any,+ *,+ embedding: Any,+ cancel: Any,+ on_step: Any,+ batch_size: int = 64,+ ) -> None:+ from one_memory.embedding_backend import ReembedStep++ sdk = self._sdk()++ def progress(item: Any) -> None:+ on_step(+ ReembedStep(+ phase="vectors",+ role=str(item.role),+ done=int(item.done),+ total=int(item.total),+ embedded=int(item.embedded),+ reused=int(item.reused),+ kept=int(getattr(item, "kept", 0)),+ )+ )++ with self._translated():+ await sdk.reembed_vector_space(+ self._vector_space(source),+ self._vector_space(target),+ embedding=self._embedding_service(embedding),+ batch_size=batch_size,+ cancel=cancel,+ on_progress=progress,+ # The target wins: an id it already holds is never touched, so+ # a resumed run continues and a merge never overwrites live data.+ skip_existing=True,+ )++ async def verify(self, source: Any, target: Any, *, embedding: Any) -> Any:+ from one_memory.embedding_backend import VectorCheck++ with self._translated():+ result = await self._sdk().verify_reembed(+ self._vector_space(source),+ self._vector_space(target),+ embedding=self._embedding_service(embedding),+ )+ return VectorCheck(+ per_role={role: dict(values) for role, values in result.per_role.items()},+ per_user=dict(result.per_user),+ problems=tuple(result.problems),+ warnings=tuple(result.warnings),+ self_recall_hits=int(result.self_recall_hits),+ self_recall_samples=int(result.self_recall_samples),+ )++ async def graph_vectors(self, path: Path) -> int | None:+ if not path.exists():+ return None+ # Not re-exported at the package root; the module is the SDK's own.+ plan = await self._sdk().reembed.plan_graph_reembed(path)+ return int(plan.vectors)++ async def reembed_graph(+ self,+ source: Path,+ target: Path,+ *,+ embedding: Any,+ target_dims: int,+ cancel: Any,+ on_step: Any,+ ) -> None:+ from one_memory.embedding_backend import ReembedStep++ def progress(item: Any) -> None:+ on_step(+ ReembedStep(+ phase="graph",+ role=str(item.table),+ done=int(item.done),+ total=int(item.total),+ embedded=int(item.embedded),+ )+ )++ with self._translated():+ await self._sdk().reembed_graph(+ source,+ target,+ embedding=self._embedding_service(embedding),+ target_dims=target_dims,+ cancel=cancel,+ on_progress=progress,+ # A resumed switch rebuilds the copy from the untouched source.+ overwrite=True,+ )++ async def verify_graph(self, source: Path, target: Path, *, target_dims: int) -> Any:+ from one_memory.embedding_backend import GraphCheck++ result = await self._sdk().verify_graph_reembed(source, target, target_dims=target_dims)+ return GraphCheck(ok=bool(result.ok), problems=tuple(result.problems))++ async def drop(self, space: Any) -> None:+ await self._sdk().drop_vector_space(self._vector_space(space))++ async def drop_graph(self, path: Path) -> None:+ await self._sdk().drop_graph(path)++ def _embedding_service(self, embedding: Any) -> Any:+ """The service that computes a target space's vectors.++ The built-in model is MemHub's ONNX service, exactly what the Runtime+ 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.model_profiles import ProviderKind++ profile = embedding.profile+ provider = profile.embedding_provider_kind or profile.provider_kind+ if provider is ProviderKind.LOCAL_ONNX:+ return LocalOnnxEmbeddingService()+ from hy_memory.core.embed_service import EmbedService # type: ignore[import-untyped]++ return EmbedService(+ build_sdk_config(+ profile, embedding.space, api_key=embedding.api_key, data_dir=self.data_dir+ )+ )++ @contextmanager+ def _translated(self) -> Iterator[None]:+ """SDK refusals as the Core errors the switch classifies."""+ from one_memory.embedding_backend import EmbeddingWidthError, ReembedCancelledError++ sdk = self._sdk()+ try:+ yield+ except sdk.ReembedCancelled:+ raise ReembedCancelledError("embedding_switch_cancelled") from None+ except hy_memory.EmbeddingDimensionMismatchError as error:+ raise EmbeddingWidthError("embedding_dimensions_mismatch") from errordiff --git a/memhub/apps/core/src/one_memory/hy_sdk_runtime.py b/memhub/apps/core/src/one_memory/hy_sdk_runtime.pyindex 84f5ecb..01c7592 100644--- a/memhub/apps/core/src/one_memory/hy_sdk_runtime.py+++ b/memhub/apps/core/src/one_memory/hy_sdk_runtime.py@@ -14,7 +14,7 @@ import threadingfrom collections.abc import Callable, Coroutine, Iterable, Mappingfrom dataclasses import dataclassfrom pathlib import Path-from typing import Any, ClassVar+from typing import Any, ClassVar, Literal, castfrom hy_memory import ( # type: ignore[import-untyped]AmbiguousMemoryIdError as AmbiguousMemoryIdError, # re-export for api.py@@ -29,6 +29,13 @@ from one_memory.embedding_assets import (BUILTIN_EMBEDDING_DIMENSIONS,BUILTIN_EMBEDDING_MODEL,)+from one_memory.embedding_spaces import (+ DEFAULT_GRAPH_DIR,+ EmbeddingSpace,+ EmbeddingSpaceError,+ derived_space,+ embedding_identity,+)from one_memory.hy_graph_admin import (GraphWidthMismatchError,effective_memory_mode,@@ -54,6 +61,10 @@ BUILTIN_RETRIEVAL_PROFILE_ID = "builtin-retrieval"_LOCAL_ONNX_PLACEHOLDER_URL = "http://127.0.0.1/local-onnx"DEFAULT_RELEVANCE_FLOOR = 0.35+#: The SDK's memory modes. A mode never changes a collection name: the space+#: names the collections, the mode only which stores the client opens.+MemoryMode = Literal["lite", "pro", "ultra"]+@dataclassclass _RuntimeEntry:@@ -176,6 +187,7 @@ class SdkClientHandle:api_key: str | None,data_dir: Path,http_transport_factory: Callable[[], Any] | None = None,+ space: EmbeddingSpace | None = None,mode: str | None = None,features: FeatureOverrides = (),) -> None:@@ -183,30 +195,65 @@ class SdkClientHandle:self._api_key = api_keyself._data_dir = data_dirself._http_transport_factory = http_transport_factory+ self._space = space#: The SDK mode this handle's client is built with, fixed for its life.self.mode = mode or effective_memory_mode()#: The SDK features set on its config (`memory_features`), fixed likewise.self.features = featuresself._lease: ClientLease | None = None+ self._constructing: asyncio.Future[ClientLease] | None = Noneself._lock = asyncio.Lock()+ @property+ def profile(self) -> ModelProfileSnapshot:+ return self._profile++ @property+ def space(self) -> EmbeddingSpace | None:+ return self._space++ @property+ def api_key(self) -> str | None:+ return self._api_key+async def client(self) -> HyMemoryClient:if self._lease is not None:return self._lease.clientasync with self._lock:if self._lease is None:- self._lease = await asyncio.to_thread(- acquire_client,- self._profile,- api_key=self._api_key,- data_dir=self._data_dir,- http_transport_factory=self._http_transport_factory,- mode=self.mode,- features=self.features,+ constructing = asyncio.ensure_future(+ asyncio.to_thread(+ _acquire_for_handle,+ self._profile,+ self._space,+ api_key=self._api_key,+ data_dir=self._data_dir,+ http_transport_factory=self._http_transport_factory,+ mode=self.mode,+ features=self.features,+ ))+ self._constructing = constructing+ try:+ self._lease = await asyncio.shield(constructing)+ except asyncio.CancelledError:+ # The construction thread runs on. Keep what it builds, so+ # `close` releases it instead of leaving its runtime open.+ constructing.add_done_callback(self._keep)+ raisereturn self._lease.client+ def _keep(self, constructing: asyncio.Future[ClientLease]) -> None:+ if constructing.cancelled() or constructing.exception() is not None:+ return+ if self._lease is None:+ self._lease = constructing.result()+async def close(self) -> None:+ constructing = self._constructing+ if constructing is not None and not constructing.done():+ # A construction a cancelled caller left behind: wait for its lease.+ await asyncio.gather(constructing, return_exceptions=True)async with self._lock:lease, self._lease = self._lease, Noneif lease is not None:@@ -301,31 +348,38 @@ def apply_sdk_features(def build_sdk_config(profile: ModelProfileSnapshot,+ space: EmbeddingSpace | None = None,+ mode: MemoryMode | None = None,*,api_key: str | None,data_dir: Path,features: Mapping[str, bool] | Iterable[tuple[str, bool]] = (),) -> MemoryConfig:- """Map a model snapshot to SDK models, endpoints, backends, and local paths.-- `features` (`memory_features`) are set on top; with none the config is+ """Map a model snapshot and its embedding space to an SDK configuration.++ `space` names the collections and the graph; the profile only says how to+ reach the models. A profile whose embedding identity (model and width) is+ not the space's raises `embedding_space_mismatch` instead of opening new,+ empty collections. Without `space`, the space the profile opened before+ the registry existed is used: offline tools on a home with no registry.+ `mode` never changes a name, and neither do `features`+ (`memory_features`), which are set on top; with none the config isexactly what it was before the setting existed."""+ if mode is not None and mode not in {"lite", "pro", "ultra"}:+ raise HySdkRuntimeError("hy_sdk_memory_mode_invalid")generation_endpoint, generation_key = _generation_access(profile, api_key)embedding_provider = profile.embedding_provider_kind or profile.provider_kindembedding_service_is_local = embedding_provider is ProviderKind.LOCAL_ONNX- embedding_model = profile.embedding_model or (- BUILTIN_EMBEDDING_MODEL if embedding_service_is_local else None- )- if not embedding_model:- raise HySdkRuntimeError("hy_sdk_embedding_model_required")- dimensions: int | None+ try:+ identity = embedding_identity(profile)+ except EmbeddingSpaceError as error:+ raise HySdkRuntimeError(error.code) from Noneif embedding_service_is_local:embedding_endpoint = Noneembedding_key = None- dimensions = profile.embedding_dimensions or BUILTIN_EMBEDDING_DIMENSIONSelse:- # Never the generation endpoint: the collection name hashes this one.+ # Never the generation endpoint: a remote embedding has its own.embedding_endpoint = _openai_endpoint(embedding_provider, profile.embedding_base_url)embedding_key = "ollama" if embedding_provider is ProviderKind.OLLAMA else api_keyif embedding_provider is ProviderKind.OPENAI_COMPATIBLE and not embedding_key:@@ -335,13 +389,18 @@ def build_sdk_config(ProviderKind.OLLAMA,}:raise HySdkRuntimeError("hy_sdk_embedding_provider_unsupported")- dimensions = profile.embedding_dimensions+ if space is None:+ space = derived_space(profile)+ elif space.identity is None or not identity.matches(space.identity):+ raise HySdkRuntimeError("embedding_space_mismatch")+ # The width the space was opened with: its names carry it, and a remote+ # request sends it as `dimensions`. An "auto" space sends none, as before.+ dimensions = space.name_dims+ embedding_model = identity.modelroot = data_dir.resolve() / "hy-memory" / "governed-v2"root.mkdir(parents=True, exist_ok=True)- collection = _collection_base(- embedding_provider, embedding_endpoint, embedding_model, dimensions- )+ collection = space.collection_basellm: dict[str, Any] = {"provider": "openai",@@ -379,7 +438,7 @@ def build_sdk_config(},"graph_store": {"provider": "kuzu",- "db_path": str(root / "graph"),+ "db_path": str(root / (space.graph_dir or DEFAULT_GRAPH_DIR)),"url": None,"username": None,"password": None,@@ -396,8 +455,33 @@ def build_sdk_config(return apply_sdk_features(config, features)+def _acquire_for_handle(+ profile: ModelProfileSnapshot,+ space: EmbeddingSpace | None,+ *,+ api_key: str | None,+ data_dir: Path,+ http_transport_factory: Callable[[], Any] | None,+ mode: str | None,+ features: FeatureOverrides = (),+) -> ClientLease:+ # `acquire_client` is looked up at call time, so a stand-in replaces every+ # construction. A handle without a space keeps the call it always made.+ named: dict[str, Any] = {"space": space} if space is not None else {}+ return acquire_client(+ profile,+ api_key=api_key,+ data_dir=data_dir,+ http_transport_factory=http_transport_factory,+ mode=mode,+ features=features,+ **named,+ )++def acquire_client(profile: ModelProfileSnapshot,+ space: EmbeddingSpace | None = None,*,api_key: str | None,data_dir: Path,@@ -407,11 +491,11 @@ def acquire_client() -> ClientLease:"""Construct a public SDK client and return its explicit runtime lease.- `mode` is the SDK pipeline mode (lite / pro / ultra); None keeps the- pre-setting default (ultra when `ONE_MEMORY_GRAPH_STORE` is set, else pro).- `features` are the `memory_features` set on its config; none keeps every- SDK default.- Waits while `hold_stores_offline` holds this home's stores.+ `space` names the collections (`build_sdk_config`). `mode` is the SDK+ pipeline mode (lite / pro / ultra) and never changes a name; None keeps+ the pre-setting default (ultra when `ONE_MEMORY_GRAPH_STORE` is set, else+ pro). `features` are the `memory_features` set on its config; none keeps+ every SDK default. Waits while `hold_stores_offline` holds this home's stores."""key = data_dir.resolve()with _STORE_GATE:@@ -419,6 +503,7 @@ def acquire_client(_STORE_GATE.wait()_OPENING[key] = _OPENING.get(key, 0) + 1try:+ named: dict[str, Any] = {"space": space} if space is not None else {}return _acquire_client(profile,api_key=api_key,@@ -426,6 +511,7 @@ def acquire_client(http_transport_factory=http_transport_factory,mode=mode or effective_memory_mode(),features=features,+ **named,)finally:with _STORE_GATE:@@ -460,6 +546,7 @@ def release_stores(data_dir: Path) -> None:def _acquire_client(profile: ModelProfileSnapshot,+ space: EmbeddingSpace | None = None,*,api_key: str | None,data_dir: Path,@@ -467,7 +554,14 @@ def _acquire_client(mode: str = "pro",features: FeatureOverrides = (),) -> ClientLease:- config = build_sdk_config(profile, api_key=api_key, data_dir=data_dir, features=features)+ config = build_sdk_config(+ profile,+ space,+ cast(MemoryMode, mode),+ api_key=api_key,+ data_dir=data_dir,+ features=features,+ )config.http_transport_factory = http_transport_factorymismatch = inspect_graph_width_mismatch(config)if mismatch is not None:@@ -523,6 +617,33 @@ def _generation_access(return endpoint, api_key+def embedding_endpoint(profile: ModelProfileSnapshot) -> str | None:+ """The OpenAI-compatible base URL the SDK embeds through; None when local."""+ provider = profile.embedding_provider_kind or profile.provider_kind+ if provider is ProviderKind.LOCAL_ONNX:+ return None+ return _openai_endpoint(provider, profile.embedding_base_url)+++def legacy_collection_base(profile: ModelProfileSnapshot) -> str:+ """The four-attribute name a profile's space had before the registry.++ Existing homes are registered under exactly this name, so it must never+ change: provider, embedding endpoint, model and declared width.+ """+ provider = profile.embedding_provider_kind or profile.provider_kind+ local = provider is ProviderKind.LOCAL_ONNX+ model = profile.embedding_model or (BUILTIN_EMBEDDING_MODEL if local else None)+ if not model:+ raise HySdkRuntimeError("hy_sdk_embedding_model_required")+ if local:+ return _collection_base(+ provider, None, model, profile.embedding_dimensions or BUILTIN_EMBEDDING_DIMENSIONS+ )+ endpoint = _openai_endpoint(provider, profile.embedding_base_url)+ return _collection_base(provider, endpoint, model, profile.embedding_dimensions)++def _collection_base(provider: ProviderKind,endpoint: str | None,diff --git a/memhub/apps/core/src/one_memory/memory_server/durable_queue.py b/memhub/apps/core/src/one_memory/memory_server/durable_queue.pyindex 878650a..f22529c 100644--- a/memhub/apps/core/src/one_memory/memory_server/durable_queue.py+++ b/memhub/apps/core/src/one_memory/memory_server/durable_queue.py@@ -253,6 +253,9 @@ MODEL_NOT_READY_CODES = frozenset("model_secret_unavailable","secure_storage_unavailable","hy_memory_client_unavailable",+ # The active profile's embedding is not the live space's: activation+ # must go through an embedding switch, so the write waits for it.+ "embedding_space_mismatch",})@@ -2565,6 +2568,9 @@ async def execute_job("model_sedimentation_disabled",# Evolve holds this user; the job runs once it is done."memory_evolve_in_progress",+ # An embedding switch paused writes: the job stays queued and+ # sediments into the new space once the switch commits.+ "embedding_switch_in_progress",}and not hy_invoked):diff --git a/memhub/apps/core/src/one_memory/memory_server/migrations.py b/memhub/apps/core/src/one_memory/memory_server/migrations.pyindex ff129ae..7291aab 100644--- a/memhub/apps/core/src/one_memory/memory_server/migrations.py+++ b/memhub/apps/core/src/one_memory/memory_server/migrations.py@@ -1383,6 +1383,83 @@ async def _050_model_probe_operations_reserved_at(cursor: Any) -> None:)+def embedding_spaces_ddl() -> str:+ """The embedding space registry (`embedding_spaces.py`); the main Core SQLite only.++ Unversioned on purpose, like the visibility tables: a migration raises+ the build's schema version, and a library this build opened would then+ refuse an older package. The table is additive and created idempotently;+ an older build ignores it and opens the space its active profile names,+ which is the registered space on every home that never switched. SQLite+ only (partial unique indexes): it lives in the main Core database.+ """+ return """+CREATE TABLE IF NOT EXISTS embedding_spaces (+ space_id TEXT PRIMARY KEY NOT NULL,+ state TEXT NOT NULL CHECK(state IN ('live','building','stray','retired','dropped')),+ model TEXT,+ dims INTEGER,+ name_dims INTEGER,+ collection_base TEXT NOT NULL,+ naming TEXT NOT NULL CHECK(naming IN ('legacy','v2','discovered')),+ graph_dir TEXT,+ provider_kind TEXT,+ profile_id TEXT,+ profile_revision INTEGER,+ vectors INTEGER,+ created_at TEXT NOT NULL,+ live_since TEXT,+ retired_at TEXT,+ keep_until TEXT,+ dropped_at TEXT+);+CREATE UNIQUE INDEX IF NOT EXISTS embedding_spaces_one_live+ ON embedding_spaces(state) WHERE state = 'live';+CREATE UNIQUE INDEX IF NOT EXISTS embedding_spaces_one_physical+ ON embedding_spaces(collection_base, COALESCE(name_dims, 0))+ WHERE state != 'dropped';+"""+++def embedding_switch_jobs_ddl() -> str:+ """Embedding switch and merge jobs (`embedding_switch.py`); unversioned, as above.++ At most one job is open at a time (the partial unique index), and it+ lives beside the profiles and the registry so the commit is one+ transaction over all three.+ """+ return """+CREATE TABLE IF NOT EXISTS embedding_switch_jobs (+ job_id TEXT PRIMARY KEY NOT NULL,+ kind TEXT NOT NULL CHECK(kind IN ('switch','merge')),+ state TEXT NOT NULL CHECK(state IN (+ 'preparing','reembedding','verifying','committing','done','failed','rolled_back'+ )),+ source_space_id TEXT NOT NULL,+ target_space_id TEXT NOT NULL,+ stray_space_ids TEXT NOT NULL DEFAULT '[]',+ target_profile_id TEXT,+ target_revision INTEGER,+ prior_profile_id TEXT,+ requested_by TEXT NOT NULL,+ plan_json TEXT NOT NULL,+ progress_json TEXT NOT NULL DEFAULT '{}',+ verification_json TEXT,+ error_code TEXT,+ error_detail TEXT,+ cancel_requested INTEGER NOT NULL DEFAULT 0,+ owner_pid INTEGER,+ heartbeat_at TEXT,+ attempt INTEGER NOT NULL DEFAULT 1,+ created_at TEXT NOT NULL,+ updated_at TEXT NOT NULL,+ finished_at TEXT+);+CREATE UNIQUE INDEX IF NOT EXISTS embedding_switch_one_open+ ON embedding_switch_jobs((1)) WHERE state NOT IN ('done','rolled_back');+"""++def model_profile_seeds_ddl(dialect: str = "mysql") -> str:"""Which presets have been seeded, so seeding happens once."""if dialect == "sqlite":diff --git a/memhub/apps/core/src/one_memory/model_probe.py b/memhub/apps/core/src/one_memory/model_probe.pyindex 3b86b1e..659cfc8 100644--- a/memhub/apps/core/src/one_memory/model_probe.py+++ b/memhub/apps/core/src/one_memory/model_probe.py@@ -423,7 +423,7 @@ class ModelProber:ModelProbeOperations(self.store).assert_no_pending(profile.profile_id)# Measuring embedding width may create a new profile version of its own.input_revision = profile.revision- profile = self._record_embedding_width(profile, stages)+ profile, _switch_required = self._record_embedding_width(profile, stages)self.store.record_capabilities(profile.profile_id,expected_revision=profile.revision,@@ -442,32 +442,55 @@ class ModelProber:self,profile: ModelProfile,stages: tuple[ProbeStage, ...],- ) -> ModelProfile:- """Store the measured vector width on the profile.+ ) -> tuple[ModelProfile, bool]:+ """Store the measured vector width on the profile, unless it moves the space.The graph store fixes its embedding column width when it is firstcreated, so guessing this leaves every relation write failing later.+ On the profile that fills the live embedding space a different width+ is not recorded: it would name other collections (B2). True when the+ width was refused that way: using it takes an embedding switch, which+ the switch plan reports (the probe result keeps its shape)."""- width = next(- (- stage.embedding_dimensions- for stage in stages- if stage.stage == "embedding" and stage.embedding_dimensions- ),- None,- )+ width = measured_width(stages)if width is None or width == profile.embedding_dimensions:- return profile- return self.store.update(- profile.profile_id,- ModelProfilePatch(- expected_revision=profile.revision,- embedding_dimensions=width,+ return profile, False+ from one_memory.embedding_spaces import EmbeddingSpaceStore, probe_width_allowed++ spaces = EmbeddingSpaceStore(self.store.database_path)+ with spaces.transaction() as connection:+ allowed = probe_width_allowed(+ connection,+ profile.profile_id,+ width,+ data_dir=self.store.database_path.parent,+ )+ if not allowed:+ return profile, True+ return (+ self.store.update(+ profile.profile_id,+ ModelProfilePatch(+ expected_revision=profile.revision,+ embedding_dimensions=width,+ ),+ self.secrets,),- self.secrets,+ False,)+def measured_width(stages: tuple[ProbeStage, ...]) -> int | None:+ return next(+ (+ stage.embedding_dimensions+ for stage in stages+ if stage.stage == "embedding" and stage.embedding_dimensions+ ),+ None,+ )++def _models_request(profile: ModelProfile,secret: str | None,diff --git a/memhub/apps/core/src/one_memory/model_probe_operations.py b/memhub/apps/core/src/one_memory/model_probe_operations.pyindex 3b6f627..67597df 100644--- a/memhub/apps/core/src/one_memory/model_probe_operations.py+++ b/memhub/apps/core/src/one_memory/model_probe_operations.py@@ -13,6 +13,7 @@ from pydantic import BaseModel, ConfigDict, Field, field_validatorfrom one_memory.database import take_the_write_lock_firstfrom one_memory.database_access import main_database+from one_memory.embedding_spaces import probe_width_allowedfrom one_memory.memory_server.migrations import model_probe_operations_ddlfrom one_memory.model_probe import ModelProbeResult, ProbeStagefrom one_memory.model_profiles import ModelCapabilities, ModelProfileStore@@ -349,7 +350,19 @@ class ModelProbeOperations:)revision = profile["revision"]now = datetime.now(UTC).isoformat()- if width is not None and width != profile["embedding_dimensions"]:+ # The profile that fills the live embedding space records only the+ # space's own width: another one would move writes to new, empty+ # collections (B2). Using it takes an embedding switch.+ if (+ width is not None+ and width != profile["embedding_dimensions"]+ and probe_width_allowed(+ db,+ profile["profile_id"],+ width,+ data_dir=self.store.database_path.parent,+ )+ ):revision += 1db.execute("UPDATE model_profiles SET embedding_dimensions=?,revision=? "diff --git a/memhub/apps/core/src/one_memory/model_profiles.py b/memhub/apps/core/src/one_memory/model_profiles.pyindex 17cc75e..635eebd 100644--- a/memhub/apps/core/src/one_memory/model_profiles.py+++ b/memhub/apps/core/src/one_memory/model_profiles.py@@ -703,10 +703,16 @@ class ModelProfileStore:})# User changes to service/model/credentials need a new explicit activation.- # Probe-discovered embedding width alone retains its existing behavior.+ # Probe-discovered embedding width alone retains its existing behavior;+ # replacing one declared width with another is a new embedding+ # identity, and activating it goes through an embedding switch.deactivate = (patch.api_key is not Noneor patch.clear_api_key+ or (+ row["embedding_dimensions"] is not None+ and next_values["embedding_dimensions"] != row["embedding_dimensions"]+ )or any(row[key] != next_values[key]for key in (diff --git a/memhub/apps/core/src/one_memory/sdk_memory_runtime.py b/memhub/apps/core/src/one_memory/sdk_memory_runtime.pyindex 5c010c2..1f4daa4 100644--- a/memhub/apps/core/src/one_memory/sdk_memory_runtime.py+++ b/memhub/apps/core/src/one_memory/sdk_memory_runtime.py@@ -47,10 +47,13 @@ class SdkMemoryRuntime:extraction_settings: ExtractionSettingsStore,data_dir: Path,memory_mode: Callable[[], str] = lambda: "pro",+ writes_open: Callable[[], bool] = lambda: True,) -> None:self.coordinator = coordinator#: The SDK mode, for the graph store's path (`hy_graph_admin`).self.memory_mode = memory_mode+ #: False while an embedding switch pauses model writes.+ self.writes_open = writes_openself.read_handle = read_handleself.write_queue = write_queueself.extraction_settings = extraction_settings@@ -111,6 +114,8 @@ class SdkMemoryRuntime:)async def digest(self) -> dict[str, object]:+ if not self.writes_open():+ raise HySdkError("embedding_switch_in_progress")async with self.coordinator.use_client() as client:try:raw = await asyncio.to_thread(@@ -151,12 +156,14 @@ class SdkMemoryRuntime:if str(error) == "model_profile_not_active":return Noneraise+ space = await self.coordinator.live_space()return await asyncio.to_thread(inspect_profile_graph_width,profile,api_key=secret,data_dir=self.data_dir,mode=self.memory_mode(),+ graph_dir=space.graph_dir if space is not None and space.graph_dir else "graph",)async def decide_graph_width(@@ -167,6 +174,7 @@ class SdkMemoryRuntime:profile, secret = await self.coordinator.active_profile_credentials()except RuntimeError as error:raise HySdkError(str(error)) from error+ space = await self.coordinator.live_space()return await asyncio.to_thread(decide_profile_graph_width,profile,@@ -174,6 +182,7 @@ class SdkMemoryRuntime:data_dir=self.data_dir,decision=decision,mode=self.memory_mode(),+ graph_dir=space.graph_dir if space is not None and space.graph_dir else "graph",)@asynccontextmanager@@ -183,6 +192,8 @@ class SdkMemoryRuntime:Callers record these against the edit or deletion instead of failingthe request that already committed it."""+ if not self.writes_open():+ raise HySdkError("embedding_switch_in_progress")async with AsyncExitStack() as stack:try:client = await stack.enter_async_context(self.coordinator.use_client())diff --git a/memhub/apps/core/src/one_memory/sdk_migration_verify.py b/memhub/apps/core/src/one_memory/sdk_migration_verify.pyindex a452b35..d394590 100644--- a/memhub/apps/core/src/one_memory/sdk_migration_verify.py+++ b/memhub/apps/core/src/one_memory/sdk_migration_verify.py@@ -222,13 +222,34 @@ def runtime_sdk_client(raise DataPlaneMigrationError("sdk_migration_secure_storage_unavailable") from Noneif secret is None:raise DataPlaneMigrationError("sdk_migration_model_secret_unavailable")- lease = acquire_client(profile, api_key=secret, data_dir=data_dir)+ # The registry's live space when this home has one and the profile fills+ # it; otherwise the space the profile named before the registry existed.+ # A switch in progress never changes it: the profile and the live space+ # change together, at the switch's commit.+ space = live_space_for(database_path, profile)+ lease = (+ acquire_client(profile, space, api_key=secret, data_dir=data_dir)+ if space is not None+ else acquire_client(profile, api_key=secret, data_dir=data_dir)+ )try:yield lease.clientfinally:lease.close()+def live_space_for(database_path: Path, profile: ModelProfileSnapshot) -> Any:+ """The live embedding space `profile` reads, or None to derive it from the profile."""+ from one_memory.embedding_spaces import embedding_identity, read_live_space++ space = read_live_space(database_path)+ if space is None or space.identity is None:+ return None+ if not embedding_identity(profile).matches(space.identity):+ return None+ return space++def verify_readback(client: Any, legacy: LegacyMemoryIds, *, chat_missing_before_migration: int = 0) -> ReadbackReport:diff --git a/memhub/apps/core/src/one_memory/sdk_read_handle.py b/memhub/apps/core/src/one_memory/sdk_read_handle.pyindex 016504c..8b8cace 100644--- a/memhub/apps/core/src/one_memory/sdk_read_handle.py+++ b/memhub/apps/core/src/one_memory/sdk_read_handle.py@@ -1,20 +1,25 @@-"""The read client, kept in the embedding space the active profile writes to.+"""The read client, kept in the live embedding space.Every read used to open the built-in 512-dim collection while writes followed-the active profile, so a custom embedding read an empty space (#242). This-handle opens the active profile's `retrieval_view` instead, and the built-in-space only when no profile is active.+the active profile, so a custom embedding read an empty space (#242). Reads+now open the space the registry pins as live (`embedding_spaces`), which is+the space writes fill. The embedding that reaches it is the active profile's+when its model and width are the space's -- a new endpoint for the same model+keeps the space -- and otherwise the profile version that filled the space+(the built-in model for the built-in space). A switch that is still running+never changes this: reads keep serving the old space until its commit.-A profile change builds a new client and retires the old one; a retired client-is closed once no task still uses it, as `SdkWriteCoordinator` does for writes-(#218). A use is the task that asked for the client: callers keep their-`client = await handle.client()` shape, and the use ends with that task (one-HTTP request, one retention pass).+A change of space or profile builds a new client and retires the old one; a+retired client is closed once no task still uses it, as `SdkWriteCoordinator`+does for writes (#218). A use is the task that asked for the client: callers+keep their `client = await handle.client()` shape, and the use ends with that+task (one HTTP request, one retention pass).The memory mode (lite / pro / ultra) is fixed per SDK client, so a mode changerebuilds and retires the same way, and so do the SDK features-(`memory_features`): handles are keyed by (profile, mode, features). Neither-mode nor features names a collection; both are separate client parameters.+(`memory_features`): handles are keyed by (space, profile, mode, features).+Neither mode nor features names a collection; both are separate client+parameters."""from __future__ import annotations@@ -24,23 +29,33 @@ from collections.abc import Callablefrom pathlib import Pathfrom typing import Any+from one_memory.embedding_health import EmbeddingGuardedClient, EmbeddingHealth+from one_memory.embedding_spaces import (+ EmbeddingSpace,+ EmbeddingSpaceStore,+ embedding_identity,+ registry_for,+)from one_memory.hy_graph_admin import effective_memory_modefrom one_memory.hy_sdk_runtime import (BUILTIN_RETRIEVAL_PROFILE_ID,SdkClientHandle,builtin_retrieval_snapshot,+ embedding_endpoint,retrieval_view,)from one_memory.hy_sdk_types import HySdkRuntimeErrorfrom one_memory.memory_features import FeatureOverrides-from one_memory.model_profiles import ModelProfileStore, ProviderKind+from one_memory.model_profiles import ModelProfileSnapshot, ModelProfileStore, ProviderKindfrom one_memory.secrets import SecretStore, SecretStoreUnavailableError_BUILTIN = (BUILTIN_RETRIEVAL_PROFILE_ID, 0)+#: (space id, profile id, revision, memory mode, features)+_HandleKey = tuple[str, str, int, str, FeatureOverrides]class ActiveProfileReadHandle(SdkClientHandle):- """An `SdkClientHandle` whose profile follows the active one."""+ """An `SdkClientHandle` that follows the live space and its embedding."""def __init__(self,@@ -50,6 +65,8 @@ class ActiveProfileReadHandle(SdkClientHandle):data_dir: Path,memory_mode: Callable[[], str] = effective_memory_mode,features: Callable[[], FeatureOverrides] = lambda: (),+ spaces: EmbeddingSpaceStore | None = None,+ health: EmbeddingHealth | None = None,) -> None:super().__init__(builtin_retrieval_snapshot(), api_key=None, data_dir=data_dir)self.profiles = profiles@@ -57,7 +74,12 @@ class ActiveProfileReadHandle(SdkClientHandle):self.data_dir = data_dirself.memory_mode = memory_modeself.current_features = features- self._handles: dict[tuple[str, int, str, FeatureOverrides], SdkClientHandle] = {}+ #: None only for a profile store without a database (test doubles).+ self.spaces = spaces if spaces is not None else registry_for(profiles)+ self.health = health or EmbeddingHealth()+ self._handles: dict[_HandleKey, SdkClientHandle] = {}+ #: Whether an active profile version reads a space, per (profile, space).+ self._matches: dict[tuple[str, int, str], bool] = {}#: Tasks in flight per handle; a retired handle closes at zero.self._uses: dict[SdkClientHandle, int] = {}self._retired: set[SdkClientHandle] = set()@@ -65,22 +87,45 @@ class ActiveProfileReadHandle(SdkClientHandle):self._handle_lock = asyncio.Lock()async def client(self) -> Any:- profile = await asyncio.to_thread(self.profiles.active_identity) or _BUILTIN- identity = (*profile, self.memory_mode(), self.current_features())+ handle = await self.current_handle()+ return self._guarded(handle, await handle.client())++ def _guarded(self, handle: SdkClientHandle, client: Any) -> Any:+ """A remote embedding's searches report `embedding_unavailable` (no fallback)."""+ profile = getattr(handle, "profile", None)+ if not isinstance(profile, ModelProfileSnapshot):+ return client+ endpoint = embedding_endpoint(profile)+ if endpoint is None:+ return client+ space = handle.space+ name_dims = space.name_dims if space is not None else profile.embedding_dimensions+ return EmbeddingGuardedClient(+ client,+ lambda: self.health.available(+ profile, endpoint=endpoint, name_dims=name_dims, api_key=handle.api_key+ ),+ )++ async def current_handle(self) -> SdkClientHandle:+ """The handle of the live space, held for the asking task."""+ space, identity = await asyncio.to_thread(self._resolve)+ mode, features = self.memory_mode(), self.current_features()+ key = (space.space_id if space is not None else "", *identity, mode, features)async with self._handle_lock:- handle = self._handles.get(identity)+ handle = self._handles.get(key)if handle is None:- # Only on a change of profile: resolving a key can reach the- # system keychain, so it is not done on every read.- handle = await asyncio.to_thread(self._build, identity)- self._handles[identity] = handle- self._retired.update(value for key, value in self._handles.items() if key != identity)- self._handles = {identity: handle}+ # Only on a change of space or profile: resolving a key can+ # reach the system keychain, so it is not done on every read.+ handle = await asyncio.to_thread(self._build, space, identity, mode, features)+ self._handles[key] = handle+ self._retired.update(value for name, value in self._handles.items() if name != key)+ self._handles = {key: handle}unused = {value for value in self._retired if not self._uses.get(value)}self._retired -= unusedself._hold(handle)await asyncio.gather(*(value.close() for value in unused))- return await handle.client()+ return handleasync def close(self) -> None:async with self._handle_lock:@@ -88,6 +133,44 @@ class ActiveProfileReadHandle(SdkClientHandle):self._handles, self._retired, self._uses = {}, set(), {}await asyncio.gather(*(handle.close() for handle in handles), *self._closing)+ async def close_idle(self) -> None:+ """Retire every client; the unused close now, the rest when their task ends."""+ async with self._handle_lock:+ self._retired.update(self._handles.values())+ self._handles = {}+ unused = {value for value in self._retired if not self._uses.get(value)}+ self._retired -= unused+ await asyncio.gather(*(value.close() for value in unused))++ def _resolve(self) -> tuple[EmbeddingSpace | None, tuple[str, int]]:+ active = self.profiles.active_identity()+ if self.spaces is None:+ return None, active or _BUILTIN+ space = self.spaces.live()+ if space is None:+ # A home this process has not bootstrapped yet: register what it+ # already uses, under the name it already has.+ space = self.spaces.bootstrap(+ self.profiles.snapshot(*active) if active is not None else None+ )+ 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)+ return space, _BUILTIN++ def _reads(self, identity: tuple[str, int], space: EmbeddingSpace) -> bool:+ key = (*identity, space.space_id)+ known = self._matches.get(key)+ if known is None:+ if space.identity is None:+ known = False+ else:+ profile = self.profiles.snapshot(*identity)+ known = embedding_identity(profile).matches(space.identity)+ self._matches[key] = known+ return known+def _hold(self, handle: SdkClientHandle) -> None:"""Count a use of `handle` until the asking task finishes."""task = asyncio.current_task()@@ -108,9 +191,16 @@ class ActiveProfileReadHandle(SdkClientHandle):self._closing.add(closing)closing.add_done_callback(self._closing.discard)- def _build(self, key: tuple[str, int, str, FeatureOverrides]) -> SdkClientHandle:- profile_id, revision, mode, features = key- identity = (profile_id, revision)+ def _build(+ self,+ space: EmbeddingSpace | None,+ identity: tuple[str, int],+ mode: str,+ features: FeatureOverrides = (),+ ) -> SdkClientHandle:+ # Without a registry (a profile store with no database) the handle+ # opens the space its profile names, exactly as before.+ named: dict[str, Any] = {"space": space} if space is not None else {}if identity == _BUILTIN:return SdkClientHandle(builtin_retrieval_snapshot(),@@ -118,8 +208,9 @@ class ActiveProfileReadHandle(SdkClientHandle):data_dir=self.data_dir,mode=mode,features=features,+ **named,)- profile = self.profiles.snapshot(*identity)+ profile: ModelProfileSnapshot = self.profiles.snapshot(*identity)view = retrieval_view(profile)secret: str | None = None# Only a remote OpenAI-compatible embedding sends the shared key.@@ -131,5 +222,5 @@ class ActiveProfileReadHandle(SdkClientHandle):if secret is None:raise HySdkRuntimeError("model_secret_unavailable")return SdkClientHandle(- view, api_key=secret, data_dir=self.data_dir, mode=mode, features=features+ view, api_key=secret, data_dir=self.data_dir, mode=mode, features=features, **named)diff --git a/memhub/apps/core/src/one_memory/sdk_vector_reattach.py b/memhub/apps/core/src/one_memory/sdk_vector_reattach.pyindex 11c03bd..d3c3ef9 100644--- a/memhub/apps/core/src/one_memory/sdk_vector_reattach.py+++ b/memhub/apps/core/src/one_memory/sdk_vector_reattach.py@@ -73,6 +73,30 @@ def _stored_names(data_dir: Path, *, filled: bool = False) -> tuple[str, ...]:return tuple(sorted(str(row[0]) for row in rows))+def filled_collection_names(data_dir: Path) -> tuple[str, ...]:+ """Every vector collection holding at least one record. Read-only.++ Safe beside a serving Core: it reads Chroma's own SQLite file, never the+ client system the SDK shares.+ """+ return _stored_names(data_dir, filled=True)+++def stored_collection_width(data_dir: Path, name: str) -> int | None:+ """The vector width Chroma fixed for `name` on its first add; None if unset."""+ database = _vector_directory(data_dir) / "chroma.sqlite3"+ if not database.is_file():+ return None+ with closing(sqlite3.connect(f"file:{database}?mode=ro", uri=True)) as connection:+ try:+ row = connection.execute(+ "SELECT dimension FROM collections WHERE name=?", (name,)+ ).fetchone()+ except sqlite3.Error:+ return None+ return int(row[0]) if row is not None and row[0] is not None else None++def legacy_vector_collections(data_dir: Path, profile: ModelProfileSnapshot) -> tuple[tuple[str, str], ...]:diff --git a/memhub/apps/core/src/one_memory/sdk_write_processor.py b/memhub/apps/core/src/one_memory/sdk_write_processor.pyindex b345be1..90b355f 100644--- a/memhub/apps/core/src/one_memory/sdk_write_processor.py+++ b/memhub/apps/core/src/one_memory/sdk_write_processor.py@@ -9,6 +9,12 @@ from dataclasses import dataclassfrom datetime import datetimefrom typing import Any+from one_memory.embedding_spaces import (+ EmbeddingSpace,+ EmbeddingSpaceStore,+ embedding_identity,+ registry_for,+)from one_memory.hy_graph_admin import effective_memory_modefrom one_memory.hy_sdk_runtime import SdkClientHandle, builtin_retrieval_snapshotfrom one_memory.imports.models import EvidenceContentKind, EvidenceOrigin, EvidenceRecord@@ -156,6 +162,12 @@ class SdkWriteCoordinator:apart: it waits for the user's write in flight, and while it runs thatuser's jobs are refused before the SDK is called(`memory_evolve_in_progress`), so the drain puts them back.++ Writes go to the live embedding space only. An active profile whose+ embedding (model and width) is not the live space's is refused with+ `embedding_space_mismatch`: it used to open a new, empty collection.+ While an embedding switch runs, `writes_open` is false and no write+ starts (`embedding_switch_in_progress`); the job waits in the queue."""def __init__(@@ -168,6 +180,8 @@ class SdkWriteCoordinator:sedimentation_enabled: Callable[[], bool],memory_mode: Callable[[], str] = effective_memory_mode,memory_features: Callable[[], FeatureOverrides] = lambda: (),+ spaces: EmbeddingSpaceStore | None = None,+ writes_open: Callable[[], bool] = lambda: True,) -> None:self.profiles = profilesself.secrets = secrets@@ -176,7 +190,8 @@ class SdkWriteCoordinator:self.sedimentation_enabled = sedimentation_enabledself.memory_mode = memory_modeself.memory_features = memory_features- self._handles: dict[tuple[str, int, str, FeatureOverrides], SdkClientHandle] = {}+ #: Keyed by (profile id, revision, space id, memory mode, features).+ self._handles: dict[tuple[str, int, str, str, FeatureOverrides], SdkClientHandle] = {}#: Users evolve (or the graph backfill) is running for, the writes in#: flight per user, and one exclusive run per user at a time. Writes#: of one user still run side by side; only evolve waits for them.@@ -184,6 +199,10 @@ class SdkWriteCoordinator:self._writing: dict[str, int] = {}self._writes_idle = asyncio.Condition()self._exclusive: dict[str, asyncio.Lock] = {}+ #: None only for a profile store without a database (test doubles):+ #: then every client opens the space its profile names, as before.+ self.spaces = spaces if spaces is not None else registry_for(profiles)+ self.writes_open = writes_open#: Uses in flight per handle; a retired handle closes at zero.self._uses: dict[SdkClientHandle, int] = {}self._retired: set[SdkClientHandle] = set()@@ -198,6 +217,9 @@ class SdkWriteCoordinator:) -> SdkWriteReceipt:if not self.sedimentation_enabled():raise RuntimeError("model_sedimentation_disabled")+ if not self.writes_open():+ # An embedding switch paused writes: the drain puts the job back.+ raise RuntimeError("embedding_switch_in_progress")user_id = records[0].user_id if records else "local"if user_id in self._evolving:# Before any SDK call: the drain returns the job to pending.@@ -230,7 +252,7 @@ class SdkWriteCoordinator:"""build = (self.memory_mode(), self.memory_features())async with self._lock:- stale = {key: handle for key, handle in self._handles.items() if key[2:] != build}+ stale = {key: handle for key, handle in self._handles.items() if key[3:] != build}for key in stale:del self._handles[key]self._retired.update(stale.values())@@ -250,8 +272,11 @@ class SdkWriteCoordinator:"""Hold one user's writes off while evolve runs for them.New writes of the user are refused from here on; the ones already in- flight are waited for before the body runs.+ flight are waited for before the body runs. Evolve and the graph+ backfill write too, so an embedding switch refuses them as well."""+ if not self.writes_open():+ raise RuntimeError("embedding_switch_in_progress")async with self._exclusive.setdefault(user_id, asyncio.Lock()):self._evolving.add(user_id)try:@@ -271,6 +296,19 @@ class SdkWriteCoordinator:self._handles, self._retired, self._uses = {}, set(), {}await asyncio.gather(*(handle.close() for handle in handles))+ def in_use(self) -> int:+ """Writes and reads holding a client right now."""+ return sum(self._uses.values())++ async def close_idle(self) -> None:+ """Retire every handle; the unused close now, the rest when released."""+ async with self._lock:+ self._retired.update(self._handles.values())+ self._handles = {}+ unused = {value for value in self._retired if not self._uses.get(value)}+ self._retired -= unused+ await asyncio.gather(*(value.close() for value in unused))+@asynccontextmanagerasync def use_client(self) -> AsyncIterator[Any]:"""The public SDK client of the active write profile, kept open while used."""@@ -281,20 +319,25 @@ class SdkWriteCoordinator:self,) -> tuple[ModelProfileSnapshot, str | None]:"""Resolve one stable profile snapshot for graph administration."""- _identity, profile, secret = await asyncio.to_thread(self._read_active_credentials)+ _identity, profile, secret, _space = await asyncio.to_thread(self._read_active_credentials)return profile, secret+ async def live_space(self) -> EmbeddingSpace | None:+ if self.spaces is None:+ return None+ return await asyncio.to_thread(self._live_space)+@asynccontextmanagerasync def _active_handle(self) -> AsyncIterator[SdkClientHandle]:"""Use the active profile's handle; retire the others, closing the unused."""mode = self.memory_mode()features = self.memory_features()- profile_identity, profile, secret = await asyncio.to_thread(+ profile_identity, profile, secret, space = await asyncio.to_thread(self._read_active_credentials, mode)- identity = (*profile_identity, mode, features)+ key = (*profile_identity, space.space_id if space is not None else "", mode, features)async with self._lock:- handle = self._handles.get(identity)+ handle = self._handles.get(key)if handle is None:handle = SdkClientHandle(profile,@@ -303,10 +346,11 @@ class SdkWriteCoordinator:http_transport_factory=self.transport_factory(profile),mode=mode,features=features,+ space=space,)- self._handles[identity] = handle- self._retired.update(value for key, value in self._handles.items() if key != identity)- self._handles = {identity: handle}+ self._handles[key] = handle+ self._retired.update(value for name, value in self._handles.items() if name != key)+ self._handles = {key: handle}self._uses[handle] = self._uses.get(handle, 0) + 1unused = {value for value in self._retired if not self._uses.get(value)}self._retired -= unused@@ -325,18 +369,51 @@ class SdkWriteCoordinator:self._retired.discard(handle)await handle.close()+ def _live_space(self) -> EmbeddingSpace:+ assert self.spaces is not None+ space = self.spaces.live()+ if space is None:+ active = self.profiles.active_identity()+ space = self.spaces.bootstrap(+ self.profiles.snapshot(*active) if active is not None else None+ )+ return space++ def _lite_credentials(+ self,+ ) -> tuple[tuple[str, int], ModelProfileSnapshot, str | None, EmbeddingSpace | None]:+ space = self._live_space() if self.spaces is not None else None+ if space is None or space.profile_id is None or space.profile_revision is None:+ builtin = builtin_retrieval_snapshot()+ return (builtin.profile_id, builtin.revision), builtin, None, space+ identity = (space.profile_id, space.profile_revision)+ profile = self.profiles.snapshot(*identity)+ try:+ secret = self.profiles.resolve_snapshot_secret(*identity, self.secrets)+ except SecretStoreUnavailableError:+ raise RuntimeError("secure_storage_unavailable") from None+ if profile.has_api_key and secret is None:+ raise RuntimeError("model_secret_unavailable")+ return identity, profile, secret, space+def _read_active_credentials(self,mode: str = "pro",- ) -> tuple[tuple[str, int], ModelProfileSnapshot, str | None]:+ ) -> tuple[tuple[str, int], ModelProfileSnapshot, str | None, EmbeddingSpace | None]:identity = self.profiles.active_identity()if identity is None:if mode == "lite":- # lite stores raw turns with one embedding and calls no model.- builtin = builtin_retrieval_snapshot()- return (builtin.profile_id, builtin.revision), builtin, None+ # lite stores raw turns with one embedding and calls no model:+ # the live space's own, so they land where reads look.+ return self._lite_credentials()raise RuntimeError("model_profile_not_active")profile = self.profiles.snapshot(*identity)+ space = self._live_space() if self.spaces is not None else None+ if space is not None and (+ space.identity is None or not embedding_identity(profile).matches(space.identity)+ ):+ # Never a new, empty collection: the switch moves the space.+ raise RuntimeError("embedding_space_mismatch")try:secret = self.profiles.resolve_snapshot_secret(*identity,@@ -348,7 +425,7 @@ class SdkWriteCoordinator:raise RuntimeError("model_profile_changed")if profile.has_api_key and secret is None:raise RuntimeError("model_secret_unavailable")- return identity, profile, secret+ return identity, profile, secret, space@dataclass(frozen=True)diff --git a/memhub/apps/core/src/one_memory/semantic_deadline.py b/memhub/apps/core/src/one_memory/semantic_deadline.pyindex a3c14fe..d56d262 100644--- a/memhub/apps/core/src/one_memory/semantic_deadline.py+++ b/memhub/apps/core/src/one_memory/semantic_deadline.py@@ -145,6 +145,10 @@ async def search_within(return (), "failed"error = pending.exception()if error is not None:+ if getattr(error, "code", None) == "embedding_unavailable":+ # Not "HY found nothing": the query could not be embedded, and+ # the caller must say so instead of answering empty.+ raise errorreturn (), "failed"found = pending.result()normalized = normalize_semantic_hits(found)diff --git a/memhub/apps/core/tests/TEST_INDEX.md b/memhub/apps/core/tests/TEST_INDEX.mdindex 719e2ed..e769624 100644--- a/memhub/apps/core/tests/TEST_INDEX.md+++ b/memhub/apps/core/tests/TEST_INDEX.md@@ -88,6 +88,9 @@| `test_diagnostic_trace_api.py` | `integration` | 覆盖 trace lookup is disabled until detailed logging is enabled、trace lookup returns only safe structured steps、log level route applies current process level 等 4 个场景。 || `test_disable_thinking.py` | `contract` | 运行期生成请求须按档案可选关闭思考;默认不向厂商下发未知字段。 || `test_dual_engine_helper.py` | `contract` | Tests for the dual-engine harness itself. |+| `test_embedding_switch.py` | `contract` | Switching the embedding model, and merging stray spaces, without losing a memory. |+| `test_embedding_switch_api.py` | `integration` | The embedding switch through Core's HTTP surface and lifespan. |+| `test_embedding_switch_sdk_adapter.py` | `contract` | The re-embed adapter against the SDK's real re-embed module and Chroma. || `test_event_loop_blocking.py` | `contract` | Proof, as a test, that blocking work on the loop freezes it — and the fix works. || `test_evidence_store.py` | `contract` | 覆盖 same source message merges origins without duplication、identical text from different sources is not deduplicated、rescanning an unchanged file does not write the message again 等 26 个场景。 || `test_export_probe.py` | `contract` | What a probe may say about a stranger's chat history, and what it may not. |@@ -314,4 +317,4 @@| `test_workspace_recall.py` | `contract` | Workspace memories were unreachable from every host; these pin the way in. || `test_write_queue_lease_renewal.py` | `contract` | Rule 8: a lease must outlive the work it covers, and be renewed while it runs. |-共 309 个测试文件。+共 312 个测试文件。diff --git a/memhub/apps/core/tests/core_test_classification.py b/memhub/apps/core/tests/core_test_classification.pyindex 13c1228..16107d3 100644--- a/memhub/apps/core/tests/core_test_classification.py+++ b/memhub/apps/core/tests/core_test_classification.py@@ -14,8 +14,8 @@ from pathlib import Pathimport pytestPRIMARY_MARKERS = ("unit", "contract", "integration", "performance", "live")-EXPECTED_TEST_FILE_COUNT = 309-EXPECTED_TEST_FILES_SHA256 = "a7d6ed33175f618d2d40f401d447a5553e1347ffd51dd878370c0fc84d13396d"+EXPECTED_TEST_FILE_COUNT = 312+EXPECTED_TEST_FILES_SHA256 = "7d0dc6efd88d71d5275bea8016a0ff087ff7568abcb8fd01e5f82c77a08a484f"# Pure transformations, validation models, parity checks and state machines.# This list is intentionally small: uncertain files default to contract.@@ -54,6 +54,7 @@ INTEGRATION_FILES = frozenset("test_backup_endpoint.py","test_recall_raw_fallback.py","test_core_ready_before_recovery.py",+ "test_embedding_switch_api.py","test_backup_restore_api.py","test_c1_import_via_api_path.py","test_capture_deadline.py",diff --git a/memhub/apps/core/tests/embedding_fakes.py b/memhub/apps/core/tests/embedding_fakes.pynew file mode 100644index 0000000..5fd1a77--- /dev/null+++ b/memhub/apps/core/tests/embedding_fakes.py@@ -0,0 +1,301 @@+"""An in-memory `ReembedBackend` for embedding switch tests.++It keeps collections as plain dicts named exactly as the SDK names them, so a+test can lay out a home -- a live space, a stray 512 space left by an older+build, a retired space -- and check what a switch or merge did to each. The+vectors themselves are not computed: a record remembers the model and width+it was "embedded" with, which is what the assertions need.+"""++from __future__ import annotations++import asyncio+import re+import shutil+from collections.abc import Callable+from dataclasses import dataclass, field+from pathlib import Path++from one_memory.embedding_backend import (+ EmbeddingTarget,+ EmbeddingWidthError,+ GraphCheck,+ PhysicalSpace,+ ReembedCancelledError,+ ReembedStep,+ ScannedSpace,+ VectorCheck,+)+from one_memory.embedding_spaces import VECTOR_ROLES, space_collection_names++_ROLE_SUFFIX = re.compile(+ r"^(?P<base>.+?)_(?P<role>coding_keys_cv|coding_keys|working_facts_cv|working_facts)"+ r"(?:_(?P<dims>\d+))?$"+)+_DIMS_SUFFIX = re.compile(r"^(?P<base>.+)_(?P<dims>\d+)$")+++class Crash(BaseException):+ """Stands in for the process dying: nothing in the worker catches it."""+++@dataclass+class Record:+ document: str+ metadata: dict[str, object]+ width: int+ model: str+++@dataclass+class FakeVectorStore:+ collections: dict[str, dict[str, Record]] = field(default_factory=dict)++ def put(+ self,+ base: str,+ name_dims: int | None,+ records: dict[str, tuple[str, str]],+ *,+ role: str = "memory",+ width: int | None = None,+ model: str = "old-model",+ ) -> None:+ """`records` maps id -> (document, user_id)."""+ name = space_collection_names(base, name_dims)[role]+ target = self.collections.setdefault(name, {})+ for record_id, (document, user) in records.items():+ target[record_id] = Record(+ document=document,+ metadata={"user_id": user, "content": document},+ width=width or name_dims or 0,+ model=model,+ )++ def space(self, base: str, name_dims: int | None) -> dict[str, dict[str, Record]]:+ return {+ role: dict(self.collections.get(name, {}))+ for role, name in space_collection_names(base, name_dims).items()+ if name in self.collections+ }++ def ids(self, base: str, name_dims: int | None, role: str = "memory") -> set[str]:+ return set(self.collections.get(space_collection_names(base, name_dims)[role], {}))+++def parse(name: str) -> tuple[str, int | None, str] | None:+ if name.endswith("_tag_index"):+ return None+ match = _ROLE_SUFFIX.match(name)+ if match:+ dims = match.group("dims")+ return match.group("base"), int(dims) if dims else None, match.group("role")+ role = "memory"+ if name.endswith("_entities"):+ name, role = name[: -len("_entities")], "entities"+ match = _DIMS_SUFFIX.match(name)+ if match:+ return match.group("base"), int(match.group("dims")), role+ return name, None, role+++class FakeReembedBackend:+ """The backend contract, over `FakeVectorStore`."""++ def __init__(self, store: FakeVectorStore | None = None) -> None:+ self.store = store or FakeVectorStore()+ self.unavailable: str | None = None+ #: Called before every batch; a test raises `Crash` or flips a cancel here.+ self.before_batch: Callable[[str, int], None] = lambda _role, _done: None+ #: Width the "embedding service" returns; None returns the target's.+ self.returned_width: int | None = None+ #: Ids the re-embed silently loses, to prove verification catches it.+ self.lose_ids: set[str] = set()+ self.batch_size = 2+ self.reembed_calls: list[tuple[str, str]] = []+ self.dropped: list[str] = []+ self.graphs_built: list[Path] = []+ #: When set, every batch waits for it: a switch a test holds mid-way.+ self.pause: asyncio.Event | None = None++ def unavailable_reason(self) -> str | None:+ return self.unavailable++ async def scan(self, *, per_user: bool = False) -> tuple[ScannedSpace, ...]:+ grouped: dict[tuple[str, int | None], dict[str, str]] = {}+ for name in self.store.collections:+ parsed = parse(name)+ if parsed is None:+ continue+ base, dims, role = parsed+ grouped.setdefault((base, dims), {})[role] = name+ out = []+ for (base, dims), roles in sorted(+ grouped.items(), key=lambda kv: (kv[0][0], kv[0][1] or 0)+ ):+ counts = {role: len(self.store.collections[name]) for role, name in roles.items()}+ widths = {+ record.width+ for name in roles.values()+ for record in self.store.collections[name].values()+ }+ users: dict[str, int] = {}+ if per_user:+ for name in roles.values():+ for record in self.store.collections[name].values():+ user = str(record.metadata.get("user_id") or "")+ users[user] = users.get(user, 0) + 1+ out.append(+ ScannedSpace(+ collection_base=base,+ name_dims=dims,+ width=widths.pop() if len(widths) == 1 else None,+ counts=counts,+ collections=roles,+ per_user=users,+ )+ )+ return tuple(out)++ async def diff(self, source: PhysicalSpace, target: PhysicalSpace) -> dict[str, int]:+ target_names = target.names()+ out = {}+ for role, name in source.names().items():+ have = set(self.store.collections.get(target_names.get(role, ""), {}))+ out[role] = len(set(self.store.collections.get(name, {})) - have)+ return out++ async def reembed(+ self,+ source: PhysicalSpace,+ target: PhysicalSpace,+ *,+ embedding: EmbeddingTarget,+ cancel: Callable[[], bool],+ on_step: Callable[[ReembedStep], None],+ batch_size: int = 64,+ ) -> None:+ del batch_size+ if target.dims is None:+ raise ValueError("the target space needs an explicit width")+ self.reembed_calls.append((source.collection_base, target.collection_base))+ target_names = target.names()+ model = embedding.space.model or "?"+ for role in VECTOR_ROLES:+ name = source.names().get(role)+ if name is None or name not in self.store.collections:+ continue+ records = sorted(self.store.collections[name].items())+ destination = self.store.collections.setdefault(target_names[role], {})+ done = embedded = kept = 0+ for start in range(0, len(records), self.batch_size):+ if cancel():+ raise ReembedCancelledError("embedding_switch_cancelled")+ self.before_batch(role, done)+ if self.pause is not None:+ await self.pause.wait()+ batch = records[start : start + self.batch_size]+ width = self.returned_width or target.dims+ if width != target.dims:+ raise EmbeddingWidthError("embedding_dimensions_mismatch")+ for record_id, record in batch:+ if record_id in destination:+ kept += 1+ continue+ if record_id in self.lose_ids:+ continue+ destination[record_id] = Record(+ document=record.document,+ metadata=dict(record.metadata),+ width=width,+ model=model,+ )+ embedded += 1+ done += len(batch)+ on_step(+ ReembedStep(+ phase="vectors",+ role=role,+ done=done,+ total=len(records),+ embedded=embedded,+ kept=kept,+ )+ )++ async def verify(+ self, source: PhysicalSpace, target: PhysicalSpace, *, embedding: EmbeddingTarget+ ) -> VectorCheck:+ del embedding+ problems: list[str] = []+ per_role: dict[str, dict[str, int]] = {}+ users_source: dict[str, int] = {}+ users_target: dict[str, int] = {}+ target_names = target.names()+ for role, name in source.names().items():+ src = self.store.collections.get(name, {})+ tgt = self.store.collections.get(target_names.get(role, ""), {})+ missing = set(src) - set(tgt)+ extra = set(tgt) - set(src)+ mismatched = {+ key for key in set(src) & set(tgt) if src[key].document != tgt[key].document+ }+ bad = sum(1 for record in tgt.values() if record.width != target.dims)+ per_role[role] = {+ "source": len(src),+ "target": len(tgt),+ "missing": len(missing),+ "extra": len(extra),+ "mismatched": len(mismatched),+ "bad_dims": bad,+ }+ for label, value in (+ ("missing", missing),+ ("extra", extra),+ ("mismatched", mismatched),+ ):+ if value:+ problems.append(f"{role}: {len(value)} {label}")+ if bad:+ problems.append(f"{role}: {bad} bad dims")+ for record in src.values():+ user = str(record.metadata.get("user_id") or "")+ users_source[user] = users_source.get(user, 0) + 1+ for record in tgt.values():+ user = str(record.metadata.get("user_id") or "")+ users_target[user] = users_target.get(user, 0) + 1+ for user in sorted(set(users_source) | set(users_target)):+ if users_source.get(user, 0) != users_target.get(user, 0):+ problems.append(f"user {user!r}: counts differ")+ return VectorCheck(per_role=per_role, per_user=users_target, problems=tuple(problems))++ async def graph_vectors(self, path: Path) -> int | None:+ return 3 if path.exists() else None++ async def reembed_graph(+ self,+ source: Path,+ target: Path,+ *,+ embedding: EmbeddingTarget,+ target_dims: int,+ cancel: Callable[[], bool],+ on_step: Callable[[ReembedStep], None],+ ) -> None:+ del embedding, cancel+ target.mkdir(parents=True, exist_ok=True)+ (target / "width").write_text(str(target_dims))+ self.graphs_built.append(target)+ on_step(ReembedStep(phase="graph", role="Memory", done=3, total=3, embedded=3))++ async def verify_graph(self, source: Path, target: Path, *, target_dims: int) -> GraphCheck:+ ok = (target / "width").is_file() and (target / "width").read_text() == str(target_dims)+ return GraphCheck(ok=ok, problems=() if ok else ("graph width",))++ async def drop(self, space: PhysicalSpace) -> None:+ for name in space.names().values():+ if self.store.collections.pop(name, None) is not None:+ self.dropped.append(name)++ async def drop_graph(self, path: Path) -> None:+ shutil.rmtree(path, ignore_errors=True)diff --git a/memhub/apps/core/tests/test_core_ready_before_recovery.py b/memhub/apps/core/tests/test_core_ready_before_recovery.pyindex b0c3991..89db2f3 100644--- a/memhub/apps/core/tests/test_core_ready_before_recovery.py+++ b/memhub/apps/core/tests/test_core_ready_before_recovery.py@@ -164,7 +164,16 @@ def test_metadata_repair_never_overlaps_an_sdk_client(tmp_path, monkeypatch):events.append("repair_finished")return MetadataRepairResult(None, 0, 0, 0)- def open_client(profile, *, api_key, data_dir, http_transport_factory, mode="pro", features=()):+ def open_client(+ profile,+ space=None,+ *,+ api_key,+ data_dir,+ http_transport_factory,+ mode="pro",+ features=(),+ ):events.append("client_opened")return ClientLease(object(), data_dir.resolve())diff --git a/memhub/apps/core/tests/test_embedding_switch.py b/memhub/apps/core/tests/test_embedding_switch.pynew file mode 100644index 0000000..437e9de--- /dev/null+++ b/memhub/apps/core/tests/test_embedding_switch.py@@ -0,0 +1,1057 @@+"""Switching the embedding model, and merging stray spaces, without losing a memory.++The switch worker, the startup merge and the registry, driven against an+in-memory re-embed backend (`tests/embedding_fakes.py`). The SDK's own+re-embed functions are exercised in `test_embedding_switch_sdk_adapter.py`.+"""++from __future__ import annotations++import asyncio+import hashlib+import io+import json+from datetime import UTC, datetime, timedelta+from pathlib import Path++import pytest+from pydantic import SecretStr++from one_memory.embedding_spaces import (+ EmbeddingSpaceStore,+ derived_space,+ probe_width_allowed,+)+from one_memory.embedding_switch import (+ EmbeddingSwitchError,+ EmbeddingSwitchService,+)+from one_memory.hy_sdk_runtime import (+ build_sdk_config,+ builtin_retrieval_snapshot,+)+from one_memory.hy_sdk_types import HySdkRuntimeError+from one_memory.model_profiles import (+ ModelCapabilities,+ ModelProfileInput,+ ModelProfileStore,+ ProviderKind,+)+from one_memory.secrets import InMemorySecretStore+from tests.embedding_fakes import Crash, FakeReembedBackend++pytestmark = pytest.mark.anyio++ENDPOINT = "https://models.example/v1"+++class Home:+ """One MemHub home: profiles, registry, an in-memory vector store, a switch service."""++ def __init__(self, root: Path) -> None:+ self.root = root+ self.database = root / "one-memory.sqlite3"+ self.secrets = InMemorySecretStore()+ self.profiles = ModelProfileStore(self.database)+ self.spaces = EmbeddingSpaceStore(self.database)+ self.backend = FakeReembedBackend()+ self.commits: list[str] = []++ def service(self, *, hold: bool = False, **options: object) -> EmbeddingSwitchService:+ """`hold`: keep the startup gate closed until `recover()`, as Core does."""++ async def on_commit(job: object) -> None:+ self.commits.append(job.job_id) # type: ignore[attr-defined]++ service = EmbeddingSwitchService(+ database_path=self.database,+ data_dir=self.root,+ profiles=self.profiles,+ spaces=self.spaces,+ secrets=self.secrets,+ backend=self.backend,+ on_commit=on_commit,+ **options, # type: ignore[arg-type]+ )+ if not hold:+ service.release_scan_hold()+ return service++ def profile(+ self,+ *,+ model: str | None = "bge-m3",+ dims: int | None = 1024,+ endpoint: str = ENDPOINT,+ name: str = "custom",+ activate: bool = False,+ probed: bool = True,+ ):+ remote = model is not None+ created = self.profiles.create(+ ModelProfileInput(+ name=name,+ provider_kind=ProviderKind.OPENAI_COMPATIBLE,+ base_url=endpoint,+ model="chat",+ embedding_provider_kind=ProviderKind.OPENAI_COMPATIBLE if remote else None,+ embedding_base_url=endpoint if remote else None,+ embedding_model=model,+ embedding_dimensions=dims if remote else None,+ api_key=SecretStr("sk-test"),+ ),+ self.secrets,+ )+ if probed:+ self.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=self.secrets,+ )+ if activate:+ self.profiles.activate(created.profile_id, self.secrets)+ return self.profiles.snapshot(created.profile_id, created.revision)++ def bootstrap(self):+ active = self.profiles.active_identity()+ return self.spaces.bootstrap(+ self.profiles.snapshot(*active) if active is not None else None+ )+++def legacy_name(provider: str, endpoint: str | None, model: str, dims: object) -> str:+ """The four-attribute hash every build before the registry used, spelled out."""+ identity = "\0".join((provider, endpoint or "local", model, str(dims or "auto")))+ return "memhub_" + hashlib.sha256(identity.encode()).hexdigest()[:16]+++async def run(service: EmbeddingSwitchService, job_id: str) -> None:+ await service.run(job_id)+++# ----------------------------------------------------------------------+# Registry bootstrap: existing homes keep their collections byte-for-byte+# ----------------------------------------------------------------------+++def test_a_builtin_home_registers_its_existing_collection(tmp_path: Path) -> None:+ home = Home(tmp_path)+ space = home.bootstrap()++ assert space.collection_base == legacy_name("local_onnx", None, "bge-small-zh-v1.5", 512)+ assert space.name_dims == 512+ assert space.naming == "legacy"+ assert space.graph_dir == "graph"+ config = build_sdk_config(builtin_retrieval_snapshot(), space, api_key=None, data_dir=tmp_path)+ # Exactly what the pre-registry build opened.+ assert config.vector_store.collection_name == space.collection_base+ assert config.vector_store.embedding_dims == 512+ assert config.graph_store.db_path.endswith("governed-v2/graph")+ assert (+ build_sdk_config(+ builtin_retrieval_snapshot(), api_key=None, data_dir=tmp_path+ ).vector_store.collection_name+ == space.collection_base+ )+++def test_a_custom_home_registers_its_four_attribute_name(tmp_path: Path) -> None:+ home = Home(tmp_path)+ profile = home.profile(activate=True)+ space = home.bootstrap()++ assert space.collection_base == legacy_name("openai_compatible", ENDPOINT, "bge-m3", 1024)+ assert (space.model, space.dims, space.name_dims) == ("bge-m3", 1024, 1024)+ assert space.profile_id == profile.profile_id+ config = build_sdk_config(profile, space, api_key="sk-test", data_dir=tmp_path)+ assert config.vector_store.collection_name == space.collection_base+ assert config.embedder.embedding_dims == 1024+ # Bootstrap is once: a second start finds the same row.+ assert home.bootstrap() == space+++def test_an_auto_width_home_keeps_its_unsuffixed_name_and_records_the_width(+ tmp_path: Path,+) -> None:+ home = Home(tmp_path)+ profile = home.profile(dims=None, activate=True)+ space = home.bootstrap()++ assert space.collection_base == legacy_name("openai_compatible", ENDPOINT, "bge-m3", None)+ assert space.name_dims is None and space.dims is None+ config = build_sdk_config(profile, space, api_key="sk-test", data_dir=tmp_path)+ assert config.vector_store.embedding_dims is None # no `_<dims>` suffix+ assert config.embedder.embedding_dims is None # no `dimensions` request field++ # The probe measured 1024 and nothing was stored yet: a relabel.+ with home.spaces.transaction() as connection:+ assert probe_width_allowed(connection, profile.profile_id, 1024, data_dir=tmp_path)+ relabelled = home.spaces.require_live()+ assert relabelled.dims == 1024+ assert relabelled.collection_base == space.collection_base+ assert relabelled.name_dims is None+ measured = profile.model_copy(update={"embedding_dimensions": 1024})+ config = build_sdk_config(measured, relabelled, api_key="sk-test", data_dir=tmp_path)+ assert config.vector_store.collection_name == space.collection_base+ assert config.vector_store.embedding_dims is None+++def test_a_profile_whose_embedding_is_not_the_space_s_never_opens_a_new_collection(+ tmp_path: Path,+) -> None:+ home = Home(tmp_path)+ home.profile(activate=True)+ space = home.bootstrap()+ other = home.profile(model="text-embedding-v3", dims=768, name="other")++ with pytest.raises(HySdkRuntimeError, match="embedding_space_mismatch"):+ build_sdk_config(other, space, api_key="sk-test", data_dir=tmp_path)+++def test_the_memory_mode_never_changes_a_collection_name(tmp_path: Path) -> None:+ home = Home(tmp_path)+ profile = home.profile(activate=True)+ space = home.bootstrap()+ names = {+ build_sdk_config(+ profile, space, mode, api_key="sk-test", data_dir=tmp_path+ ).vector_store.collection_name+ for mode in (None, "lite", "pro", "ultra")+ }+ assert names == {space.collection_base}+++# ----------------------------------------------------------------------+# B2: a probe on the live space's profile never moves the space+# ----------------------------------------------------------------------+++def test_a_probe_measuring_another_width_on_the_active_profile_is_not_recorded(+ tmp_path: Path,+) -> None:+ home = Home(tmp_path)+ profile = home.profile(activate=True)+ home.bootstrap()++ with home.spaces.transaction() as connection:+ assert not probe_width_allowed(connection, profile.profile_id, 768, data_dir=tmp_path)+ assert probe_width_allowed(connection, profile.profile_id, 1024, data_dir=tmp_path)+ assert home.spaces.require_live().dims == 1024+++def test_a_probe_on_another_profile_records_what_it_measured(tmp_path: Path) -> None:+ home = Home(tmp_path)+ home.profile(activate=True)+ home.bootstrap()+ other = home.profile(model="text-embedding-v3", dims=None, name="other")++ with home.spaces.transaction() as connection:+ assert probe_width_allowed(connection, other.profile_id, 768, data_dir=tmp_path)+++# ----------------------------------------------------------------------+# Planning+# ----------------------------------------------------------------------+++async def test_an_endpoint_only_change_needs_no_re_embed(tmp_path: Path) -> None:+ home = Home(tmp_path)+ active = home.profile(activate=True)+ live = home.bootstrap()+ home.backend.store.put(live.collection_base, 1024, {"m1": ("a", "local")})+ moved = home.profile(endpoint="https://proxy.example/v1", name="proxy")++ plan = await home.service().plan(moved.profile_id)++ assert plan.needed is False+ assert plan.reason == "same_embedding"+ # Same collections, reached through the new endpoint.+ config = build_sdk_config(moved, live, api_key="sk-test", data_dir=tmp_path)+ assert config.vector_store.collection_name == live.collection_base+ assert config.embedder.base_url == "https://proxy.example/v1"+ assert active.embedding_base_url != moved.embedding_base_url+++async def test_a_generation_only_change_needs_no_re_embed(tmp_path: Path) -> None:+ home = Home(tmp_path)+ home.profile(model=None, activate=True)+ home.bootstrap()+ builtin_again = home.profile(model=None, name="other chat model")++ plan = await home.service().plan(builtin_again.profile_id)+ assert (plan.needed, plan.reason) == (False, "same_embedding")+++async def test_an_empty_home_switches_without_a_job(tmp_path: Path) -> None:+ home = Home(tmp_path)+ old = home.bootstrap()+ target = home.profile()+ service = home.service()++ plan = await service.plan(target.profile_id)+ assert (plan.needed, plan.reason) == (False, "empty_home")++ space = await asyncio.to_thread(service.activate_empty_home, target.profile_id)+ assert space.state == "live"+ # The name every earlier build gives this profile: a downgrade still reads it.+ assert space.collection_base == legacy_name("openai_compatible", ENDPOINT, "bge-m3", 1024)+ assert home.profiles.active_identity() == (target.profile_id, target.revision)+ assert home.spaces.get(old.space_id).state == "dropped"+ assert service.jobs.open_job() is None+++async def test_a_new_embedding_plans_every_vector_of_every_space(tmp_path: Path) -> None:+ home = Home(tmp_path)+ live = home.bootstrap()+ home.backend.store.put(live.collection_base, 512, {"a": ("one", "local"), "b": ("two", "bob")})+ home.backend.store.put(live.collection_base, 512, {"k": ("key", "local")}, role="coding_keys")+ stray_base = legacy_name("openai_compatible", ENDPOINT, "old-model", 768)+ home.backend.store.put(stray_base, 768, {"c": ("three", "carol")})+ target = home.profile()++ plan = await home.service().plan(target.profile_id)++ assert plan.needed and plan.reason == "embedding_identity_changed"+ assert plan.total_vectors == 4+ assert plan.users == 3+ assert [item.collection_base for item in plan.sources] == [live.collection_base, stray_base]+ assert plan.blockers == []+ assert plan.target.model == "bge-m3" and plan.target.dims == 1024+++async def test_an_unprobed_target_blocks_the_plan(tmp_path: Path) -> None:+ home = Home(tmp_path)+ live = home.bootstrap()+ home.backend.store.put(live.collection_base, 512, {"a": ("one", "local")})+ target = home.profile(probed=False)++ plan = await home.service().plan(target.profile_id)++ assert plan.needed and "embedding_probe_required" in plan.blockers+++async def test_an_sdk_without_re_embed_blocks_the_plan(tmp_path: Path, monkeypatch) -> None:+ home = Home(tmp_path)+ live = home.bootstrap()+ target = home.profile()+ home.backend.unavailable = "sdk_reembed_unavailable"+ # Without the SDK's scan, Chroma's own file says whether vectors exist.+ monkeypatch.setattr(+ "one_memory.sdk_vector_reattach.filled_collection_names",+ lambda _data_dir: (f"{live.collection_base}_512",),+ )++ plan = await home.service().plan(target.profile_id)++ assert plan.needed and "sdk_reembed_unavailable" in plan.blockers+++# ----------------------------------------------------------------------+# The switch+# ----------------------------------------------------------------------+++async def start(home: Home, service: EmbeddingSwitchService, target) -> str:+ plan = await service.plan(target.profile_id)+ with_worker = service.worker_enabled+ service.worker_enabled = False+ try:+ job = await service.start_switch(+ target.profile_id,+ expected_revision=target.revision,+ plan_token=plan.plan_token,+ requested_by="cli",+ )+ finally:+ service.worker_enabled = with_worker+ return job.job_id+++def seed_builtin(home: Home) -> object:+ live = home.bootstrap()+ home.backend.store.put(+ live.collection_base,+ 512,+ {"a": ("one", "local"), "b": ("two", "local"), "c": ("three", "hermes-1")},+ model="bge-small-zh-v1.5",+ )+ return live+++async def test_a_switch_re_embeds_commits_and_activates_in_one_step(tmp_path: Path) -> None:+ home = Home(tmp_path)+ live = seed_builtin(home)+ target = home.profile()+ service = home.service()++ job_id = await start(home, service, target)+ assert not service.writes_open()+ await run(service, job_id)++ job = service.get_job(job_id)+ assert job.state == "done"+ assert job.progress.percent == 100.0+ new = home.spaces.require_live()+ assert new.space_id == job.target.space_id+ assert new.naming == "v2" and new.collection_base.startswith("memhub_e_")+ assert new.graph_dir == f"graph-{new.space_id[:8]}"+ records = home.backend.store.space(new.collection_base, 1024)["memory"]+ assert set(records) == {"a", "b", "c"}+ assert {record.model for record in records.values()} == {"bge-m3"}+ assert {record.width for record in records.values()} == {1024}+ old = home.spaces.get(live.space_id)+ assert old.state == "retired"+ keep = datetime.fromisoformat(old.keep_until) - datetime.fromisoformat(old.retired_at)+ assert keep == timedelta(days=14)+ # The source was never written.+ assert set(home.backend.store.space(live.collection_base, 512)["memory"]) == {"a", "b", "c"}+ assert home.profiles.active_identity() == (target.profile_id, target.revision)+ assert service.writes_open()+ assert home.commits == [job_id]+++async def test_a_switch_folds_in_every_other_non_empty_space(tmp_path: Path) -> None:+ home = Home(tmp_path)+ live = seed_builtin(home)+ stray = legacy_name("openai_compatible", ENDPOINT, "old-model", 768)+ home.backend.store.put(stray, 768, {"a": ("stale copy", "local"), "z": ("only here", "bob")})+ target = home.profile()+ service = home.service()++ job_id = await start(home, service, target)+ await run(service, job_id)++ assert service.get_job(job_id).state == "done"+ new = home.spaces.require_live()+ records = home.backend.store.space(new.collection_base, 1024)["memory"]+ assert set(records) == {"a", "b", "c", "z"}+ # The live space's record wins over the stray's.+ assert records["a"].document == "one"+ states = {space.collection_base: space.state for space in home.spaces.list_spaces()}+ assert states[stray] == "retired"+ assert states[live.collection_base] == "retired"+++async def test_retired_spaces_are_never_folded_back_in(tmp_path: Path) -> None:+ home = Home(tmp_path)+ seed_builtin(home)+ service = home.service()+ first = home.profile()+ await run(service, await start(home, service, first))+ # A memory deleted after the first switch must stay deleted.+ new = home.spaces.require_live()+ home.backend.store.collections[f"{new.collection_base}_1024"].pop("b")++ second = home.profile(model="text-embedding-v3", dims=768, name="second")+ job_id = await start(home, service, second)+ await run(service, job_id)++ latest = home.spaces.require_live()+ assert set(home.backend.store.space(latest.collection_base, 768)["memory"]) == {"a", "c"}+++async def test_a_switch_back_gets_a_fresh_base_beside_the_kept_one(tmp_path: Path) -> None:+ home = Home(tmp_path)+ seed_builtin(home)+ service = home.service()+ first = home.profile()+ await run(service, await start(home, service, first))+ kept = home.spaces.require_live()+ second = home.profile(model="text-embedding-v3", dims=768, name="second")+ await run(service, await start(home, service, second))+ again = home.profile(name="first again")++ job_id = await start(home, service, again)+ await run(service, job_id)++ latest = home.spaces.require_live()+ assert latest.collection_base == f"{kept.collection_base}_g1"+ assert home.spaces.get(kept.space_id).state == "retired"+++async def test_a_second_switch_while_one_runs_is_refused(tmp_path: Path) -> None:+ home = Home(tmp_path)+ seed_builtin(home)+ service = home.service()+ await start(home, service, home.profile())+ other = home.profile(model="text-embedding-v3", dims=768, name="other")+ plan = await service.plan(other.profile_id)++ assert "embedding_switch_running" in plan.blockers+ with pytest.raises(EmbeddingSwitchError, match="embedding_switch_running"):+ await service.start_switch(+ other.profile_id,+ expected_revision=other.revision,+ plan_token=plan.plan_token,+ requested_by="app",+ )+++async def test_a_stale_plan_token_is_refused(tmp_path: Path) -> None:+ home = Home(tmp_path)+ live = seed_builtin(home)+ target = home.profile()+ service = home.service()+ plan = await service.plan(target.profile_id)+ home.backend.store.put(live.collection_base, 512, {"new": ("arrived", "local")})++ with pytest.raises(EmbeddingSwitchError, match="embedding_switch_plan_stale"):+ await service.start_switch(+ target.profile_id,+ expected_revision=target.revision,+ plan_token=plan.plan_token,+ requested_by="app",+ )+++async def test_cancel_rolls_back_and_drops_the_partial_target(tmp_path: Path) -> None:+ home = Home(tmp_path)+ live = seed_builtin(home)+ target = home.profile()+ service = home.service()+ job_id = await start(home, service, target)++ def cancel_midway(_role: str, done: int) -> None:+ if done >= 2:+ service.cancel(job_id)++ home.backend.before_batch = cancel_midway+ await run(service, job_id)++ job = service.get_job(job_id)+ assert (job.state, job.error_code) == ("rolled_back", "embedding_switch_cancelled")+ assert home.spaces.require_live().space_id == live.space_id+ assert home.spaces.get(job.target.space_id).state == "dropped"+ assert not any(name.startswith("memhub_e_") for name in home.backend.store.collections)+ assert home.profiles.active_identity() is None+ assert service.writes_open()+++async def test_a_width_mismatch_fails_before_writing_and_rolls_back(tmp_path: Path) -> None:+ home = Home(tmp_path)+ seed_builtin(home)+ home.backend.returned_width = 768+ service = home.service()+ job_id = await start(home, service, home.profile())++ await run(service, job_id)++ job = service.get_job(job_id)+ assert (job.state, job.error_code) == ("rolled_back", "embedding_dimensions_mismatch")+++async def test_a_lost_record_fails_verification(tmp_path: Path) -> None:+ home = Home(tmp_path)+ seed_builtin(home)+ home.backend.lose_ids = {"c"}+ service = home.service()+ job_id = await start(home, service, home.profile())++ await run(service, job_id)++ job = service.get_job(job_id)+ assert (job.state, job.error_code) == ("rolled_back", "embedding_verification_failed")+ report = json.loads(service.jobs.get(job_id)["verification_json"])+ assert any("missing" in problem for problem in report["problems"])+++async def test_a_target_edited_mid_switch_is_not_activated(tmp_path: Path) -> None:+ from one_memory.model_profiles import ModelProfilePatch++ home = Home(tmp_path)+ live = seed_builtin(home)+ target = home.profile()+ service = home.service()+ job_id = await start(home, service, target)++ def edit(_role: str, done: int) -> None:+ if done == 0:+ home.profiles.update(+ target.profile_id,+ ModelProfilePatch(expected_revision=target.revision, name="renamed"),+ home.secrets,+ )++ home.backend.before_batch = edit+ await run(service, job_id)++ job = service.get_job(job_id)+ assert (job.state, job.error_code) == ("rolled_back", "target_profile_changed")+ assert home.spaces.require_live().space_id == live.space_id+++async def test_writes_that_never_drain_roll_the_switch_back(tmp_path: Path) -> None:+ home = Home(tmp_path)+ seed_builtin(home)++ async def busy() -> bool:+ return False++ service = home.service(drain_idle=busy, drain_timeout_s=0.2)+ job_id = await start(home, service, home.profile())++ await run(service, job_id)++ assert service.get_job(job_id).error_code == "writes_did_not_drain"+++async def test_the_commit_is_one_transaction(tmp_path: Path, monkeypatch) -> None:+ home = Home(tmp_path)+ live = seed_builtin(home)+ target = home.profile()+ service = home.service()+ job_id = await start(home, service, target)+ home.backend.before_batch = lambda *_: None+ # Run up to the commit, then fail inside its transaction.+ real_commit = service._commit_transaction++ def failing_activation(*_args, **_kwargs):+ raise RuntimeError("injected")++ monkeypatch.setattr(+ "one_memory.embedding_switch.ModelProfileStore.activate_in_connection",+ staticmethod(failing_activation),+ )++ def commit_once(job: str) -> None:+ try:+ real_commit(job)+ finally:+ # Nothing of the transaction is visible.+ assert home.spaces.require_live().space_id == live.space_id+ assert home.spaces.get(service.jobs.get(job)["target_space_id"]).state == "building"+ assert service.jobs.get(job)["state"] == "committing"+ assert home.profiles.active_identity() is None++ service._commit_transaction = commit_once # type: ignore[method-assign]+ await run(service, job_id)++ job = service.get_job(job_id)+ assert job.state == "rolled_back"+ assert home.spaces.require_live().space_id == live.space_id+++# ----------------------------------------------------------------------+# Crash and resume, in every state+# ----------------------------------------------------------------------++[email protected]("crash_at", ["preparing", "reembedding", "verifying", "committing"])+async def test_a_switch_resumes_after_a_crash_in_any_state(+ tmp_path: Path, crash_at: str, monkeypatch+) -> None:+ home = Home(tmp_path)+ live = seed_builtin(home)+ target = home.profile()+ first = home.service()+ job_id = await start(home, first, target)++ if crash_at == "preparing":++ async def crash_idle() -> bool:+ raise Crash++ first.drain_idle = crash_idle+ elif crash_at == "reembedding":++ def crash_midway(_role: str, done: int) -> None:+ if done >= 2:+ raise Crash++ home.backend.before_batch = crash_midway+ elif crash_at == "verifying":++ async def crash_verify(*_args, **_kwargs):+ raise Crash++ monkeypatch.setattr(home.backend, "verify", crash_verify)+ else:++ def crash_commit(_job: str) -> None:+ raise Crash++ first._commit_transaction = crash_commit # type: ignore[method-assign]++ with pytest.raises(Crash):+ await run(first, job_id)+ assert first.jobs.get(job_id)["state"] == crash_at+ monkeypatch.undo()+ home.backend.before_batch = lambda *_: None++ # The next process: the gate is closed before anything is decided.+ second = home.service(hold=True)+ assert not second.writes_open()+ await second.recover()+ await second.wait()++ job = second.get_job(job_id)+ assert job.state == "done"+ new = home.spaces.require_live()+ assert set(home.backend.store.space(new.collection_base, 1024)["memory"]) == {"a", "b", "c"}+ assert home.spaces.get(live.space_id).state == "retired"+ assert home.profiles.active_identity() == (target.profile_id, target.revision)+ assert second.writes_open()+++async def test_a_crash_during_rollback_finishes_the_rollback(tmp_path: Path) -> None:+ home = Home(tmp_path)+ live = seed_builtin(home)+ first = home.service()+ job_id = await start(home, first, home.profile())+ first.jobs.update(job_id, state="failed", error_code="embedding_service_failed")++ second = home.service()+ await second.recover()+ await second.wait()++ assert second.get_job(job_id).state == "rolled_back"+ assert home.spaces.require_live().space_id == live.space_id+++async def test_an_app_update_mid_switch_resumes_on_the_new_build(+ tmp_path: Path, monkeypatch+) -> None:+ """The App may install while a switch runs; the next Core finishes it."""+ from one_memory import cli++ home = Home(tmp_path)+ seed_builtin(home)+ target = home.profile()+ old_build = home.service()+ job_id = await start(home, old_build, target)++ def crash_midway(_role: str, done: int) -> None:+ if done >= 2:+ raise Crash++ home.backend.before_batch = crash_midway+ with pytest.raises(Crash):+ await run(old_build, job_id)+ home.backend.before_batch = lambda *_: None++ # The upgrade asks whether the home needs migrating: the switch is+ # reported, never makes a migration required, and is left untouched.+ monkeypatch.setenv("ONE_MEMORY_DATA_DIR", str(tmp_path))+ from one_memory.sdk_data_plane_migration import SdkDataPlaneMigrationStore++ SdkDataPlaneMigrationStore(home.database)+ output = io.StringIO()+ assert cli.run(["sdk-migration-status", "--json"], output=output) == 0+ status = json.loads(output.getvalue().strip().splitlines()[-1])+ assert status["embedding_switch"] == {+ "job_id": job_id,+ "kind": "switch",+ "state": "reembedding",+ }+ assert home.spaces.require_live().state == "live"++ new_build = home.service()+ await new_build.recover()+ await new_build.wait()++ assert new_build.get_job(job_id).state == "done"+ assert home.profiles.active_identity() == (target.profile_id, target.revision)+++# ----------------------------------------------------------------------+# Multi-user+# ----------------------------------------------------------------------+++async def test_every_user_is_re_embedded_and_counted(tmp_path: Path) -> None:+ home = Home(tmp_path)+ live = home.bootstrap()+ users = {+ "local": 3,+ "hermes-alice": 2,+ "hermes-bob": 1,+ # Revoked: no grant any more, but the data is still in the space.+ "hermes-revoked": 2,+ }+ records = {+ f"{user}-{index}": (f"memory {index} of {user}", user)+ for user, count in users.items()+ for index in range(count)+ }+ home.backend.store.put(live.collection_base, 512, records)+ home.backend.store.put(+ live.collection_base, 512, {"fact-1": ("fact", "hermes-alice")}, role="working_facts"+ )+ service = home.service()+ plan = await service.plan(home.profile().profile_id)+ assert plan.users == 4++ job_id = await start(home, service, home.profiles.snapshot(plan.target_profile_id, 1))+ await run(service, job_id)++ assert service.get_job(job_id).state == "done"+ report = json.loads(service.jobs.get(job_id)["verification_json"])+ assert report["per_user"] == {+ "local": 3,+ "hermes-alice": 3,+ "hermes-bob": 1,+ "hermes-revoked": 2,+ }+ new = home.spaces.require_live()+ assert set(home.backend.store.space(new.collection_base, 1024)["working_facts"]) == {"fact-1"}+++# ----------------------------------------------------------------------+# Startup scan and merge+# ----------------------------------------------------------------------+++async def test_startup_merges_a_stray_512_space_into_a_1024_live_space(tmp_path: Path) -> None:+ home = Home(tmp_path)+ profile = home.profile(activate=True)+ live = home.bootstrap()+ home.backend.store.put(+ live.collection_base,+ 1024,+ {"shared": ("live version", "local"), "l1": ("only live", "local")},+ model="bge-m3",+ )+ stray = legacy_name("local_onnx", None, "bge-small-zh-v1.5", 512)+ home.backend.store.put(+ stray,+ 512,+ {"shared": ("stale builtin copy", "local"), "s1": ("only stray", "hermes-1")},+ model="bge-small-zh-v1.5",+ )+ service = home.service(hold=True)++ assert not service.writes_open() # held until the scan decides+ await service.recover()+ job = service.current()["job"]+ assert job is not None and job["kind"] == "merge"+ assert not service.writes_open()+ await service.wait()++ finished = service.get_job(job["job_id"])+ assert finished.state == "done"+ merged = home.backend.store.space(live.collection_base, 1024)["memory"]+ assert set(merged) == {"shared", "l1", "s1"}+ assert merged["shared"].document == "live version" # live wins+ assert merged["s1"].model == "bge-m3" and merged["s1"].width == 1024+ stray_space = next(+ space for space in home.spaces.list_spaces() if space.collection_base == stray+ )+ assert stray_space.state == "retired" and stray_space.keep_until+ # A merge never changes the live space or the active profile.+ assert home.spaces.require_live().space_id == live.space_id+ assert home.profiles.active_identity() == (profile.profile_id, profile.revision)+ assert service.writes_open()++ # The next start finds nothing to merge.+ again = home.service()+ await again.recover()+ assert again.current()["job"] is None+ assert again.writes_open()+++async def test_a_stray_holding_nothing_unmerged_is_retired_without_a_job(tmp_path: Path) -> None:+ home = Home(tmp_path)+ live = seed_builtin(home)+ stray = legacy_name("openai_compatible", ENDPOINT, "old-model", 768)+ home.backend.store.put(stray, 768, {"a": ("copy", "local")})+ service = home.service()++ await service.recover()++ assert service.current()["job"] is None+ states = {space.collection_base: space.state for space in home.spaces.list_spaces()}+ assert states == {live.collection_base: "live", stray: "retired"}+ assert service.writes_open()+++async def test_a_merge_resumes_after_a_crash(tmp_path: Path) -> None:+ home = Home(tmp_path)+ live = seed_builtin(home)+ stray = legacy_name("openai_compatible", ENDPOINT, "old-model", 768)+ home.backend.store.put(stray, 768, {f"s{i}": (f"stray {i}", "local") for i in range(5)})+ first = home.service()++ def crash_midway(_role: str, done: int) -> None:+ if done >= 2:+ raise Crash++ home.backend.before_batch = crash_midway+ await first.recover()+ with pytest.raises(Crash):+ await first._task+ home.backend.before_batch = lambda *_: None++ second = home.service()+ await second.recover()+ await second.wait()++ assert set(home.backend.store.space(live.collection_base, 512)["memory"]) == {+ "a",+ "b",+ "c",+ *(f"s{i}" for i in range(5)),+ }+++async def test_an_old_sdk_skips_the_scan_and_opens_the_gate(tmp_path: Path) -> None:+ home = Home(tmp_path)+ seed_builtin(home)+ home.backend.unavailable = "sdk_reembed_unavailable"+ service = home.service()++ await service.recover()++ assert service.scan_state == "unavailable"+ assert service.writes_open()+++# ----------------------------------------------------------------------+# Retention+# ----------------------------------------------------------------------+++async def test_retired_spaces_are_dropped_after_14_days_and_never_the_live_one(+ tmp_path: Path,+) -> None:+ home = Home(tmp_path)+ old = seed_builtin(home)+ service = home.service()+ await run(service, await start(home, service, home.profile()))+ live = home.spaces.require_live()++ assert await service.sweep_retired(now=datetime.now(UTC) + timedelta(days=13)) == []+ dropped = await service.sweep_retired(now=datetime.now(UTC) + timedelta(days=15))++ assert dropped == [old.space_id]+ assert home.spaces.get(old.space_id).state == "dropped"+ assert not home.backend.store.space(old.collection_base, 512)+ assert home.spaces.require_live().space_id == live.space_id+++async def test_cleanup_drops_only_a_retired_space(tmp_path: Path) -> None:+ home = Home(tmp_path)+ old = seed_builtin(home)+ service = home.service()+ with pytest.raises(EmbeddingSwitchError, match="embedding_space_not_retired"):+ await service.drop_space(old.space_id)+ await run(service, await start(home, service, home.profile()))++ dropped = await service.drop_space(old.space_id)++ assert dropped.state == "dropped"+++def test_derived_space_is_the_profile_s_pre_registry_space() -> None:+ builtin = derived_space(builtin_retrieval_snapshot())+ assert builtin.profile_id is None+ assert builtin.collection_base == legacy_name("local_onnx", None, "bge-small-zh-v1.5", 512)+++def test_the_probe_never_records_a_width_that_would_move_the_live_space(tmp_path: Path) -> None:+ from one_memory.model_probe import ModelProber, ProbeCode, ProbeStage++ home = Home(tmp_path)+ profile = home.profile(activate=True)+ live = home.bootstrap()+ prober = ModelProber(store=home.profiles, secrets=home.secrets)+ current = home.profiles.require(profile.profile_id, home.secrets)++ def measured(width: int) -> tuple[ProbeStage, ...]:+ return (+ ProbeStage(+ stage="embedding",+ ok=True,+ code=ProbeCode.OK,+ latency_ms=1,+ embedding_dimensions=width,+ ),+ )++ after, switch_required = prober._record_embedding_width(current, measured(768))++ assert switch_required+ assert (after.embedding_dimensions, after.revision) == (1024, current.revision)+ assert home.spaces.require_live() == live+ assert home.profiles.active_identity() == (profile.profile_id, profile.revision)+++def test_an_auto_width_profile_records_its_measured_width_without_renaming(+ tmp_path: Path,+) -> None:+ from one_memory.model_probe import ModelProber, ProbeCode, ProbeStage++ home = Home(tmp_path)+ profile = home.profile(dims=None, activate=True)+ live = home.bootstrap()+ prober = ModelProber(store=home.profiles, secrets=home.secrets)+ current = home.profiles.require(profile.profile_id, home.secrets)+ stage = ProbeStage(+ stage="embedding", ok=True, code=ProbeCode.OK, latency_ms=1, embedding_dimensions=1024+ )++ after, switch_required = prober._record_embedding_width(current, (stage,))++ assert not switch_required and after.embedding_dimensions == 1024+ relabelled = home.spaces.require_live()+ assert (relabelled.space_id, relabelled.collection_base, relabelled.name_dims) == (+ live.space_id,+ live.collection_base,+ None,+ )+ assert relabelled.dims == 1024+ snapshot = home.profiles.snapshot(*home.profiles.active_identity())+ config = build_sdk_config(snapshot, relabelled, api_key="sk-test", data_dir=tmp_path)+ assert config.vector_store.collection_name == live.collection_base+ assert config.vector_store.embedding_dims is None+++async def test_ultra_mode_builds_a_new_graph_at_the_target_width(tmp_path: Path) -> None:+ home = Home(tmp_path)+ seed_builtin(home)+ graph = tmp_path / "hy-memory" / "governed-v2" / "graph"+ graph.mkdir(parents=True)+ quiesced: list[str] = []++ async def quiesce():+ quiesced.append("closed")+ return lambda: quiesced.append("released")++ service = home.service(graph_enabled=lambda: True, quiesce_clients=quiesce)+ target = home.profile()+ plan = await service.plan(target.profile_id)+ assert plan.graph_vectors == 3++ job_id = await start(home, service, target)+ await run(service, job_id)++ assert service.get_job(job_id).state == "done"+ new = home.spaces.require_live()+ built = tmp_path / "hy-memory" / "governed-v2" / new.graph_dir+ 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"]+++async def test_a_job_another_live_core_still_beats_for_is_not_taken_over(tmp_path: Path) -> None:+ import os++ home = Home(tmp_path)+ seed_builtin(home)+ first = home.service()+ job_id = await start(home, first, home.profile())+ # The parent process is alive and "beat" just now.+ first.jobs.update(job_id, owner_pid=os.getppid(), heartbeat_at=datetime.now(UTC).isoformat())++ second = home.service(hold=True)+ await second.recover()++ assert second._task is None+ assert not second.writes_open()+ assert second.jobs.get(job_id)["state"] == "preparing"diff --git a/memhub/apps/core/tests/test_embedding_switch_api.py b/memhub/apps/core/tests/test_embedding_switch_api.pynew file mode 100644index 0000000..3bb3b13--- /dev/null+++ b/memhub/apps/core/tests/test_embedding_switch_api.py@@ -0,0 +1,383 @@+"""The embedding switch through Core's HTTP surface and lifespan.++Activation refusals and the empty-home path, a whole switch driven over the+API with writes paused and intake still queueing, the startup merge of a+stray space before the drain starts, and `embedding_unavailable` on recall+and context search when the remote embedding does not answer.+"""++from __future__ import annotations++import asyncio+import hashlib+import time+from types import SimpleNamespace+from uuid import uuid4++import httpx+import pytest+from httpx import ASGITransport, AsyncClient+from pydantic import SecretStr++from one_memory import embedding_health+from one_memory.api import create_app+from one_memory.config import Settings+from one_memory.model_profiles import ModelCapabilities, ModelProfileInput, ProviderKind+from one_memory.secrets import InMemorySecretStore+from tests.embedding_fakes import FakeReembedBackend++pytestmark = pytest.mark.fresh_sdk++ENDPOINT = "https://models.example/v1"+++def builtin_base() -> str:+ identity = "\0".join(("local_onnx", "local", "bge-small-zh-v1.5", "512"))+ return "memhub_" + hashlib.sha256(identity.encode()).hexdigest()[:16]+++def backend(monkeypatch) -> FakeReembedBackend:+ fake = FakeReembedBackend()+ monkeypatch.setattr(+ "one_memory.embedding_switch.default_reembed_backend", lambda _data_dir: fake+ )+ return fake+++def application(tmp_path):+ return create_app(+ Settings(+ data_dir=tmp_path / "data",+ source_home=tmp_path,+ api_token=SecretStr("switch-test"),+ imports_enabled=False,+ automatic_memory_processing=False,+ live_sync_enabled=False,+ ),+ secret_store=InMemorySecretStore(),+ )+++def client_for(app):+ return AsyncClient(+ transport=ASGITransport(app=app),+ base_url="http://test",+ headers={"Authorization": "Bearer switch-test"},+ )+++async def recovered(client) -> dict:+ deadline = time.monotonic() + 10+ while time.monotonic() < deadline:+ body = (await client.get("/api/v1/health")).json()+ if body["recovery"] in {"done", "failed"}:+ return body+ await asyncio.sleep(0.01)+ raise AssertionError("recovery did not finish")+++async def until(client, predicate, *, seconds: float = 10.0) -> dict:+ deadline = time.monotonic() + seconds+ while time.monotonic() < deadline:+ body = (await client.get("/api/v1/embedding-switches/current")).json()+ if predicate(body):+ return body+ await asyncio.sleep(0.01)+ raise AssertionError(f"switch never reached the expected state: {body}")+++def remote_profile(app, *, model="bge-m3", dims=1024, name="custom", endpoint=ENDPOINT):+ store, secrets = app.state.model_profile_store, app.state.secret_store+ created = store.create(+ ModelProfileInput(+ name=name,+ provider_kind=ProviderKind.OPENAI_COMPATIBLE,+ base_url=endpoint,+ model="chat",+ embedding_provider_kind=ProviderKind.OPENAI_COMPATIBLE,+ embedding_base_url=endpoint,+ embedding_model=model,+ embedding_dimensions=dims,+ api_key=SecretStr("sk-test"),+ ),+ secrets,+ )+ store.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 created+++def test_activating_another_embedding_answers_with_the_plan(tmp_path, backend):+ backend.store.put(builtin_base(), 512, {"a": ("one", "local"), "b": ("two", "bob")})++ async def scenario():+ app = application(tmp_path)+ async with app.router.lifespan_context(app), client_for(app) as client:+ await recovered(client)+ profile = remote_profile(app)++ response = await client.post(f"/api/v1/model-profiles/{profile.profile_id}/activate")++ assert response.status_code == 409+ body = response.json()+ assert body["detail"] == "embedding_switch_required"+ plan = body["plan"]+ assert plan["needed"] is True and plan["total_vectors"] == 2 and plan["users"] == 2+ assert plan["source"]["model"] == "bge-small-zh-v1.5"+ assert (plan["target"]["model"], plan["target"]["dims"]) == ("bge-m3", 1024)+ assert app.state.model_profile_store.active_identity() is None++ asyncio.run(scenario())+++def test_an_empty_home_activates_another_embedding_directly(tmp_path, backend):+ async def scenario():+ app = application(tmp_path)+ async with app.router.lifespan_context(app), client_for(app) as client:+ await recovered(client)+ builtin = app.state.embedding_spaces.require_live()+ profile = remote_profile(app)++ response = await client.post(f"/api/v1/model-profiles/{profile.profile_id}/activate")++ assert response.status_code == 200, response.text+ assert response.json()["is_active"] is True+ live = app.state.embedding_spaces.require_live()+ assert (live.model, live.dims) == ("bge-m3", 1024)+ assert app.state.embedding_spaces.get(builtin.space_id).state == "dropped"+ # The same embedding again: a plain activation, no plan.+ again = remote_profile(app, name="same model, other chat model")+ assert (+ await client.post(f"/api/v1/model-profiles/{again.profile_id}/activate")+ ).status_code == 200+ assert app.state.embedding_spaces.require_live().space_id == live.space_id++ asyncio.run(scenario())+++def test_a_switch_over_the_api_pauses_writes_and_keeps_intake(tmp_path, backend):+ backend.store.put(+ builtin_base(),+ 512,+ {f"m{i}": (f"memory {i}", "local") for i in range(6)},+ model="bge-small-zh-v1.5",+ )++ async def scenario():+ app = application(tmp_path)+ async with app.router.lifespan_context(app), client_for(app) as client:+ await recovered(client)+ old = app.state.embedding_spaces.require_live()+ profile = remote_profile(app)+ planned = await client.post(+ "/api/v1/embedding-switches/plan", json={"profile_id": profile.profile_id}+ )+ assert planned.status_code == 200+ plan = planned.json()+ stale = await client.post(+ "/api/v1/embedding-switches",+ json={+ "profile_id": profile.profile_id,+ "expected_revision": profile.revision,+ "plan_token": "stale",+ },+ )+ assert stale.status_code == 409+ assert stale.json()["detail"] == "embedding_switch_plan_stale"++ backend.pause = asyncio.Event()+ started = await client.post(+ "/api/v1/embedding-switches",+ json={+ "profile_id": profile.profile_id,+ "expected_revision": profile.revision,+ "plan_token": plan["plan_token"],+ "requested_by": "cli",+ },+ )+ assert started.status_code == 202, started.text+ job_id = started.json()["job_id"]+ running = await until(+ client, lambda body: (body["job"] or {}).get("state") == "reembedding"+ )+ assert running["writes_paused"] is True and running["phase"] == "running"++ # Direct writers wait; intake keeps queueing; status shows the switch.+ edit = await client.put(+ f"/api/v2/memories/{uuid4()}", json={"content": "changed", "user_id": "local"}+ )+ assert edit.status_code == 409+ assert edit.json()["detail"] == "embedding_switch_in_progress"+ delete = await client.delete(f"/api/v2/memories/{uuid4()}")+ assert delete.status_code == 409+ added = await client.post(+ "/api/v2/memories",+ json={"request_id": str(uuid4()), "text": "请记住这件事", "scope": "all-apps"},+ )+ assert added.status_code == 201+ processing = (await client.get("/api/v1/memory-processing")).json()+ assert processing["embedding_switch"]["job_id"] == job_id+ assert (await client.get("/api/v1/health")).json()["embedding_switch"]["kind"] == (+ "switch"+ )+ other = remote_profile(app, model="text-embedding-v3", dims=768, name="other")+ refused = await client.post(f"/api/v1/model-profiles/{other.profile_id}/activate")+ assert refused.json()["detail"] == "embedding_switch_running"++ backend.pause.set()+ done = await until(+ client, lambda body: (body["last_finished"] or {}).get("job_id") == job_id+ )+ assert done["last_finished"]["state"] == "done"+ assert done["writes_paused"] is False+ assert app.state.model_profile_store.active_identity()[0] == profile.profile_id++ spaces = (await client.get("/api/v1/embedding-spaces")).json()+ states = {space["space_id"]: space["state"] for space in spaces["spaces"]}+ assert states[old.space_id] == "retired"+ assert spaces["live_space_id"] == done["last_finished"]["target"]["space_id"]+ cleaned = await client.delete(f"/api/v1/embedding-spaces/{old.space_id}")+ assert cleaned.status_code == 200+ assert cleaned.json()["space"]["state"] == "dropped"+ live_cleanup = await client.delete(+ f"/api/v1/embedding-spaces/{spaces['live_space_id']}"+ )+ assert live_cleanup.json()["detail"] == "embedding_space_not_retired"++ # Same model and width behind another endpoint: no re-embed.+ proxied = remote_profile(app, name="proxy", endpoint="https://proxy.example/v1")+ moved = await client.post(f"/api/v1/model-profiles/{proxied.profile_id}/activate")+ assert moved.status_code == 200, moved.text+ assert app.state.embedding_spaces.require_live().space_id == spaces["live_space_id"]++ asyncio.run(scenario())+++def test_cancel_over_the_api(tmp_path, backend):+ backend.store.put(builtin_base(), 512, {f"m{i}": (f"m {i}", "local") for i in range(4)})++ async def scenario():+ app = application(tmp_path)+ async with app.router.lifespan_context(app), client_for(app) as client:+ await recovered(client)+ profile = remote_profile(app)+ plan = (+ await client.post(+ "/api/v1/embedding-switches/plan", json={"profile_id": profile.profile_id}+ )+ ).json()+ backend.pause = asyncio.Event()+ job_id = (+ await client.post(+ "/api/v1/embedding-switches",+ json={+ "profile_id": profile.profile_id,+ "expected_revision": profile.revision,+ "plan_token": plan["plan_token"],+ },+ )+ ).json()["job_id"]+ await until(client, lambda body: (body["job"] or {}).get("state") == "reembedding")++ cancelled = await client.post(f"/api/v1/embedding-switches/{job_id}/cancel")+ assert cancelled.status_code == 200 and cancelled.json()["cancel_requested"]+ backend.pause.set()+ done = await until(client, lambda body: body["last_finished"] is not None)++ assert done["last_finished"]["state"] == "rolled_back"+ assert done["last_finished"]["error_code"] == "embedding_switch_cancelled"+ missing = await client.post(f"/api/v1/embedding-switches/{uuid4()}/cancel")+ assert missing.status_code == 404++ asyncio.run(scenario())+++def test_startup_merges_a_stray_space_before_writes_resume(tmp_path, backend):+ backend.store.put(builtin_base(), 512, {"live-1": ("live", "local")})+ stray = "memhub_" + "a" * 16+ backend.store.put(stray, 1024, {"stray-1": ("left by an older build", "hermes-1")})++ async def scenario():+ app = application(tmp_path)+ async with app.router.lifespan_context(app), client_for(app) as client:+ # Core answers at once; the merge runs behind the loading screen.+ assert (await client.get("/api/v1/health")).status_code == 200+ await recovered(client)+ done = await until(client, lambda body: body["last_finished"] is not None)++ assert done["last_finished"]["kind"] == "merge"+ assert done["last_finished"]["state"] == "done"+ assert backend.store.ids(builtin_base(), 512) == {"live-1", "stray-1"}+ spaces = (await client.get("/api/v1/embedding-spaces")).json()+ stray_row = next(row for row in spaces["spaces"] if row["collection_base"] == stray)+ assert stray_row["state"] == "retired" and stray_row["keep_until"]+ assert app.state.embedding_switch.writes_open()++ asyncio.run(scenario())+++class _EmptySearchClient:+ def search(self, *_args, **_kwargs):+ return {"request_id": "r", "memories": {"schema": [], "proactive": [], "normal": []}}++ def get(self, *_args, **_kwargs):+ return None+++def test_a_dead_remote_embedding_answers_embedding_unavailable(tmp_path, backend, monkeypatch):+ status = {"code": 503}++ def transport():+ return httpx.MockTransport(+ lambda request: httpx.Response(+ status["code"], json={"data": [{"embedding": [0.1] * 4}]}+ )+ )++ monkeypatch.setattr(embedding_health, "transport_factory", transport)+ monkeypatch.setattr(+ "one_memory.hy_sdk_runtime.acquire_client",+ lambda *args, **kwargs: SimpleNamespace(client=_EmptySearchClient(), close=lambda: None),+ )++ async def ready(_app):+ return True++ monkeypatch.setattr("one_memory.api._recall_model_ready", ready)++ async def scenario():+ app = application(tmp_path)+ async with app.router.lifespan_context(app), client_for(app) as client:+ await recovered(client)+ profile = remote_profile(app)+ assert (+ await client.post(f"/api/v1/model-profiles/{profile.profile_id}/activate")+ ).status_code == 200++ recall = await client.post("/api/v1/recall", json={"query": "数据库"})+ assert recall.status_code == 503+ assert recall.json()["detail"] == "embedding_unavailable"+ context = await client.post(+ "/api/v2/context/search",+ json={"query": "数据库", "user_id": "local", "kinds": ["memory"]},+ )+ assert context.status_code == 503+ assert context.json()["detail"] == "embedding_unavailable"++ # The service answers again: an empty result is just empty.+ status["code"] = 200+ app.state.sdk_client_handle.health.forget()+ recall = await client.post("/api/v1/recall", json={"query": "数据库"})+ assert recall.status_code == 200++ asyncio.run(scenario())diff --git a/memhub/apps/core/tests/test_embedding_switch_sdk_adapter.py b/memhub/apps/core/tests/test_embedding_switch_sdk_adapter.pynew file mode 100644index 0000000..a1f98b1--- /dev/null+++ b/memhub/apps/core/tests/test_embedding_switch_sdk_adapter.py@@ -0,0 +1,271 @@+"""The re-embed adapter against the SDK's real re-embed module and Chroma.++Skipped on an SDK without `hy_memory.reembed` (before 2.0.10): there the+switch is unavailable and the plan says `sdk_reembed_unavailable`, which+`test_embedding_switch.py` covers.+"""++from __future__ import annotations++import asyncio+from pathlib import Path++import pytest++from one_memory.embedding_backend import EmbeddingTarget, PhysicalSpace+from one_memory.embedding_spaces import EmbeddingSpace, space_collection_names+from one_memory.hy_sdk_migration import SdkReembedBackend+from one_memory.hy_sdk_runtime import builtin_retrieval_snapshot++pytestmark = pytest.mark.skipif(+ SdkReembedBackend(Path("/nonexistent")).unavailable_reason() is not None,+ reason="the installed SDK has no re-embed module (hy-memory < 2.0.10)",+)++SOURCE = "memhub_" + "1" * 16+TARGET = "memhub_e_" + "2" * 16+++class _Embedder:+ """A deterministic 8-wide stand-in for the target model."""++ def __init__(self, width: int = 8) -> None:+ self.width = width+ self.texts: list[str] = []++ async def embed_batch(self, texts: list[str], use_cache: bool = True) -> list[list[float]]:+ self.texts.extend(texts)+ return [[float(len(text) % 7 + 1)] + [0.5] * (self.width - 1) for text in texts]++ async def embed(self, text: str, use_cache: bool = True) -> list[float]:+ return (await self.embed_batch([text]))[0]++ def get_embedding_dims(self) -> int:+ return self.width+++def _seed(data_dir: Path) -> None:+ import chromadb++ vector = data_dir / "hy-memory" / "governed-v2" / "vector"+ vector.mkdir(parents=True)+ client = chromadb.PersistentClient(path=str(vector))+ names = space_collection_names(SOURCE, 4)+ memory = client.get_or_create_collection(names["memory"], metadata={"hnsw:space": "cosine"})+ memory.add(+ ids=["m1", "m2", "m3"],+ embeddings=[[0.1, 0.2, 0.3, 0.4]] * 3,+ documents=["one", "two", "three"],+ metadatas=[{"user_id": "local"}, {"user_id": "hermes-a"}, {"user_id": "hermes-b"}],+ )+ keys = client.get_or_create_collection(names["coding_keys"], metadata={"hnsw:space": "cosine"})+ keys.add(+ ids=["e1:0"],+ embeddings=[[0.4, 0.3, 0.2, 0.1]],+ documents=["task"],+ metadatas=[{"user_id": "local"}],+ )+++def _target() -> EmbeddingTarget:+ space = EmbeddingSpace(+ space_id="target",+ state="building",+ model="stand-in",+ dims=8,+ name_dims=8,+ collection_base=TARGET,+ naming="v2",+ created_at="2026-11-01T00:00:00+00:00",+ )+ return EmbeddingTarget(profile=builtin_retrieval_snapshot(), space=space, api_key=None)+++def test_core_names_a_space_exactly_as_the_sdk_does() -> None:+ import hy_memory++ for dims in (None, 512, 1024):+ sdk = hy_memory.vector_space_names(hy_memory.VectorSpace(base_name=SOURCE, dims=dims))+ assert sdk == space_collection_names(SOURCE, dims)+++def test_scan_reembed_verify_and_drop_through_the_sdk(tmp_path: Path, monkeypatch) -> None:+ _seed(tmp_path)+ backend = SdkReembedBackend(tmp_path)+ embedder = _Embedder()+ monkeypatch.setattr(backend, "_embedding_service", lambda _target: embedder)+ source = PhysicalSpace(collection_base=SOURCE, name_dims=4, dims=4)+ target = PhysicalSpace(collection_base=TARGET, name_dims=8, dims=8, model="stand-in")+ steps = []++ async def scenario() -> None:+ scanned = await backend.scan(per_user=True)+ found = {item.collection_base: item for item in scanned}+ assert found[SOURCE].vectors == 4+ assert found[SOURCE].per_user == {"local": 2, "hermes-a": 1, "hermes-b": 1}++ await backend.reembed(+ source, target, embedding=_target(), cancel=lambda: False, on_step=steps.append+ )+ assert not any((await backend.diff(source, target)).values())+ check = await backend.verify(source, target, embedding=_target())+ assert check.problems == ()+ assert check.per_user == {"local": 2, "hermes-a": 1, "hermes-b": 1}++ # Resumable: a second run embeds nothing more.+ before = len(embedder.texts)+ await backend.reembed(+ source, target, embedding=_target(), cancel=lambda: False, on_step=steps.append+ )+ assert len(embedder.texts) == before++ await backend.drop(target)+ remaining = {item.collection_base for item in await backend.scan()}+ assert TARGET not in remaining and SOURCE in remaining++ asyncio.run(scenario())+ assert {step.role for step in steps} >= {"memory", "coding_keys"}+++def test_a_wrong_width_fails_before_anything_is_written(tmp_path: Path, monkeypatch) -> None:+ from one_memory.embedding_backend import EmbeddingWidthError++ _seed(tmp_path)+ backend = SdkReembedBackend(tmp_path)+ monkeypatch.setattr(backend, "_embedding_service", lambda _target: _Embedder(width=6))+ source = PhysicalSpace(collection_base=SOURCE, name_dims=4, dims=4)+ target = PhysicalSpace(collection_base=TARGET, name_dims=8, dims=8)++ async def scenario() -> None:+ with pytest.raises(EmbeddingWidthError):+ await backend.reembed(+ source, target, embedding=_target(), cancel=lambda: False, on_step=lambda _: None+ )+ found = {item.collection_base: item for item in await backend.scan()}+ assert TARGET not in found or found[TARGET].vectors == 0++ asyncio.run(scenario())+++def test_cancel_stops_at_a_batch_boundary(tmp_path: Path, monkeypatch) -> None:+ from one_memory.embedding_backend import ReembedCancelledError++ _seed(tmp_path)+ backend = SdkReembedBackend(tmp_path)+ monkeypatch.setattr(backend, "_embedding_service", lambda _target: _Embedder())+ source = PhysicalSpace(collection_base=SOURCE, name_dims=4, dims=4)+ target = PhysicalSpace(collection_base=TARGET, name_dims=8, dims=8)++ async def scenario() -> None:+ with pytest.raises(ReembedCancelledError):+ await backend.reembed(+ source, target, embedding=_target(), cancel=lambda: True, on_step=lambda _: None+ )++ asyncio.run(scenario())+++def test_a_whole_switch_through_the_real_sdk(tmp_path: Path, monkeypatch) -> None:+ """Registry, worker and commit over real Chroma collections and the SDK."""+ import chromadb+ from pydantic import SecretStr++ from one_memory.embedding_spaces import EmbeddingSpaceStore+ from one_memory.embedding_switch import EmbeddingSwitchService+ 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)+ live = spaces.bootstrap(None)+ vector = tmp_path / "hy-memory" / "governed-v2" / "vector"+ vector.mkdir(parents=True)+ client = chromadb.PersistentClient(path=str(vector))+ memory = client.get_or_create_collection(+ live.collection_names()["memory"], metadata={"hnsw:space": "cosine"}+ )+ memory.add(+ ids=["a", "b", "c"],+ embeddings=[[0.1] * 512, [0.2] * 512, [0.3] * 512],+ documents=["one", "two", "three"],+ metadatas=[{"user_id": "local"}, {"user_id": "hermes-a"}, {"user_id": "local"}],+ )+ stray_base = "memhub_" + "9" * 16+ stray = client.get_or_create_collection(+ space_collection_names(stray_base, 768)["memory"], metadata={"hnsw:space": "cosine"}+ )+ stray.add(+ ids=["a", "z"],+ embeddings=[[0.5] * 768, [0.6] * 768],+ documents=["stale", "only in the stray"],+ metadatas=[{"user_id": "local"}, {"user_id": "hermes-b"}],+ )+ created = profiles.create(+ ModelProfileInput(+ name="remote",+ provider_kind=ProviderKind.OPENAI_COMPATIBLE,+ base_url="https://models.example/v1",+ model="chat",+ embedding_provider_kind=ProviderKind.OPENAI_COMPATIBLE,+ embedding_base_url="https://models.example/v1",+ embedding_model="stand-in",+ embedding_dimensions=8,+ api_key=SecretStr("sk-test"),+ ),+ 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,+ )+ backend = SdkReembedBackend(tmp_path)+ monkeypatch.setattr(backend, "_embedding_service", lambda _target: _Embedder())+ service = EmbeddingSwitchService(+ database_path=database,+ data_dir=tmp_path,+ profiles=profiles,+ spaces=spaces,+ secrets=secrets,+ backend=backend,+ worker_enabled=False,+ )+ service.release_scan_hold()++ async def scenario() -> None:+ plan = await service.plan(created.profile_id)+ assert plan.needed and plan.total_vectors == 5 and plan.users == 3+ 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", service.jobs.get(job.job_id)["verification_json"]++ asyncio.run(scenario())+ new = spaces.require_live()+ target = client.get_collection(new.collection_names()["memory"])+ got = target.get(include=["documents", "embeddings"])+ documents = dict(zip(got["ids"], got["documents"], strict=True))+ assert documents == {"a": "one", "b": "two", "c": "three", "z": "only in the stray"}+ assert {len(vector) for vector in got["embeddings"]} == {8}+ assert profiles.active_identity() == (created.profile_id, created.revision)+ states = {space.collection_base: space.state for space in spaces.list_spaces()}+ assert states[live.collection_base] == "retired"+ assert states[stray_base] == "retired"diff --git a/memhub/apps/core/tests/test_health.py b/memhub/apps/core/tests/test_health.pyindex dd17295..08fa85a 100644--- a/memhub/apps/core/tests/test_health.py+++ b/memhub/apps/core/tests/test_health.py@@ -48,6 +48,7 @@ def test_health_reports_the_single_core() -> None:# No lifespan ran, so recovery has not begun."recovery": "pending","recovery_failed_steps": [],+ "embedding_switch": None,}diff --git a/memhub/apps/core/tests/test_main_database_entry.py b/memhub/apps/core/tests/test_main_database_entry.pyindex 4db15e9..cd1e437 100644--- a/memhub/apps/core/tests/test_main_database_entry.py+++ b/memhub/apps/core/tests/test_main_database_entry.py@@ -111,6 +111,11 @@ ALLOWED = {"the offline migration opens Chroma",opened_with="?mode=ro",),+ ("sdk_vector_reattach.py", "stored_collection_width"): Allowed(+ "Chroma's own chroma.sqlite3, read-only, for the width it fixed on a "+ "collection: a probe on the live space's profile may only record that one",+ opened_with="?mode=ro",+ ),("imports/sqlite_access.py", "open_sqlite_readonly"): Allowed("a host app's own SQLite (Cursor state.vscdb / store.db): one direct ""read-only open when there is no WAL, and one read-only open of the "diff --git a/memhub/apps/core/tests/test_memory_library_all_scenes.py b/memhub/apps/core/tests/test_memory_library_all_scenes.pyindex d53dd41..0b37872 100644--- a/memhub/apps/core/tests/test_memory_library_all_scenes.py+++ b/memhub/apps/core/tests/test_memory_library_all_scenes.py@@ -318,6 +318,12 @@ def run_with_sdk(tmp_path, monkeypatch, scenario):async with app.router.lifespan_context(app):app.state.sdk_client_handle = Handle()monkeypatch.setattr(app.state.sdk_write_coordinator, "use_client", write_client)+ # Edits and deletes wait for the startup scan of embedding spaces,+ # as they would behind the App's loading screen.+ for _ in range(500):+ if app.state.embedding_switch.writes_open():+ break+ await asyncio.sleep(0.01)async with client_for(app) as client:await scenario(app, sdk, client)diff --git a/memhub/apps/core/tests/test_memory_mode_and_evolve.py b/memhub/apps/core/tests/test_memory_mode_and_evolve.pyindex 30a2ecd..4cecaa9 100644--- a/memhub/apps/core/tests/test_memory_mode_and_evolve.py+++ b/memhub/apps/core/tests/test_memory_mode_and_evolve.py@@ -684,6 +684,12 @@ def run_app(tmp_path, monkeypatch, scenario) -> None:async with app.router.lifespan_context(app):monkeypatch.setattr(app.state.sdk_write_coordinator, "use_client", write_client)+ # Model writes wait for the startup scan of embedding spaces, as+ # they would behind the App's loading screen.+ for _ in range(500):+ if app.state.embedding_switch.writes_open():+ break+ await asyncio.sleep(0.01)async with client_for(app) as client:await scenario(app, sdk, client)diff --git a/memhub/apps/core/tests/test_memory_server_durable_queue.py b/memhub/apps/core/tests/test_memory_server_durable_queue.pyindex 062accc..9204c90 100644--- a/memhub/apps/core/tests/test_memory_server_durable_queue.py+++ b/memhub/apps/core/tests/test_memory_server_durable_queue.py@@ -12,10 +12,12 @@ import timefrom concurrent.futures import ThreadPoolExecutorfrom datetime import UTC, datetime, timedeltafrom hashlib import sha256+from types import SimpleNamespaceimport pytestfrom one_memory.database_access import main_database+from one_memory.embedding_spaces import EmbeddingIdentityfrom one_memory.memory_server.contracts import BatchIdentity, WriteRequestfrom one_memory.memory_server.durable_queue import (CANCELLED,@@ -1226,6 +1228,10 @@ def _coordinator(monkeypatch, opened: list[_TrackedHandle]):return valuemonkeypatch.setattr(sdk_write_processor, "SdkClientHandle", handle)+ # One live embedding space the stand-in profiles all fill.+ identity = EmbeddingIdentity(model="stand-in")+ monkeypatch.setattr(sdk_write_processor, "embedding_identity", lambda _profile: identity)+ space = SimpleNamespace(space_id="space", identity=identity)profiles = _SwitchableProfiles()coordinator = sdk_write_processor.SdkWriteCoordinator(profiles=profiles, # type: ignore[arg-type]@@ -1233,6 +1239,7 @@ def _coordinator(monkeypatch, opened: list[_TrackedHandle]):data_dir=None,transport_factory=lambda _profile: None,sedimentation_enabled=lambda: True,+ spaces=SimpleNamespace(live=lambda: space), # type: ignore[arg-type])return coordinator, profilesdiff --git a/memhub/apps/core/tests/test_search_without_profile.py b/memhub/apps/core/tests/test_search_without_profile.pyindex c713e59..f0749bd 100644--- a/memhub/apps/core/tests/test_search_without_profile.py+++ b/memhub/apps/core/tests/test_search_without_profile.py@@ -141,11 +141,19 @@ class _Recorder:self.closed: list[str] = []def __call__(- self, profile, *, api_key, data_dir, http_transport_factory=None, mode="pro", features=()+ self,+ profile,+ space=None,+ *,+ api_key,+ data_dir,+ http_transport_factory=None,+ mode=None,+ features=(),):from one_memory.hy_sdk_runtime import build_sdk_config- config = build_sdk_config(profile, api_key=api_key, data_dir=data_dir)+ config = build_sdk_config(profile, space, mode, api_key=api_key, data_dir=data_dir)name = config.vector_store.collection_nameself.opened.append((name, config.vector_store.embedding_dims, api_key))return SimpleNamespace(@@ -155,10 +163,11 @@ class _Recorder:@pytest.mark.anyio-async def test_reads_open_the_collection_the_active_profile_writes(+async def test_reads_open_the_live_space_the_active_profile_writes(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:"""#242: a 2560-dim profile wrote `memhub_<sha>_2560`, reads opened `_512`."""+ from one_memory.embedding_spaces import EmbeddingSpaceStorefrom one_memory.hy_sdk_runtime import build_sdk_configfrom one_memory.model_profiles import ModelProfileStorefrom one_memory.sdk_read_handle import ActiveProfileReadHandle@@ -168,13 +177,14 @@ async def test_reads_open_the_collection_the_active_profile_writes(monkeypatch.setattr("one_memory.hy_sdk_runtime.acquire_client", recorder)profiles = ModelProfileStore(tmp_path / "one-memory.sqlite3")secrets = InMemorySecretStore()- handle = ActiveProfileReadHandle(profiles=profiles, secrets=secrets, data_dir=tmp_path)-- builtin = build_sdk_config(builtin_retrieval_snapshot(), api_key=None, data_dir=tmp_path)- assert (await handle.client()).collection == builtin.vector_store.collection_name-+ # A home whose custom profile was active when this build first started:+ # the registry pins the collection that profile has been writing.written = _activate(profiles, secrets, dimensions=2560)+ spaces = EmbeddingSpaceStore(profiles.database_path)+ spaces.bootstrap(written)+ handle = ActiveProfileReadHandle(profiles=profiles, secrets=secrets, data_dir=tmp_path)writes = build_sdk_config(written, api_key="sk-test", data_dir=tmp_path)+ builtin = build_sdk_config(builtin_retrieval_snapshot(), api_key=None, data_dir=tmp_path)async def read() -> str:return str((await handle.client()).collection)@@ -186,9 +196,11 @@ async def test_reads_open_the_collection_the_active_profile_writes(@pytest.mark.anyio-async def test_a_profile_change_rebuilds_reads_without_closing_one_in_flight(+async def test_an_activation_that_skips_the_switch_never_moves_reads(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ """Only a switch's commit moves the space; reads stay where the data is."""+ from one_memory.embedding_spaces import EmbeddingSpaceStorefrom one_memory.model_profiles import ModelProfileStorefrom one_memory.sdk_read_handle import ActiveProfileReadHandlefrom one_memory.secrets import InMemorySecretStore@@ -197,8 +209,40 @@ async def test_a_profile_change_rebuilds_reads_without_closing_one_in_flight(monkeypatch.setattr("one_memory.hy_sdk_runtime.acquire_client", recorder)profiles = ModelProfileStore(tmp_path / "one-memory.sqlite3")secrets = InMemorySecretStore()+ first = _activate(profiles, secrets, dimensions=1024)+ live = EmbeddingSpaceStore(profiles.database_path).bootstrap(first)handle = ActiveProfileReadHandle(profiles=profiles, secrets=secrets, data_dir=tmp_path)- _activate(profiles, secrets, dimensions=1024)+ _activate(profiles, secrets, dimensions=2560, model="chat-2")++ collection = (await asyncio.create_task(handle.client())).collection++ assert collection == live.collection_base+ await handle.close()+++async def test_a_committed_switch_rebuilds_reads_without_closing_one_in_flight(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ from one_memory.embedding_spaces import (+ EmbeddingSpaceStore,+ derived_space,+ insert_space_in,+ set_state_in,+ )+ from one_memory.model_profiles import ModelProfileStore+ from one_memory.sdk_read_handle import ActiveProfileReadHandle+ from one_memory.secrets import InMemorySecretStore++ recorder = _Recorder(tmp_path)+ monkeypatch.setattr("one_memory.hy_sdk_runtime.acquire_client", recorder)+ profiles = ModelProfileStore(tmp_path / "one-memory.sqlite3")+ secrets = InMemorySecretStore()+ spaces = EmbeddingSpaceStore(profiles.database_path)+ old_space = spaces.bootstrap(_activate(profiles, secrets, dimensions=1024))+ handle = ActiveProfileReadHandle(+ profiles=profiles, secrets=secrets, data_dir=tmp_path, spaces=spaces+ )holding = asyncio.Event()finish = asyncio.Event()@@ -213,7 +257,15 @@ async def test_a_profile_change_rebuilds_reads_without_closing_one_in_flight(await holding.wait()[(old, _, _)] = recorder.opened- _activate(profiles, secrets, dimensions=2560, model="chat-2")+ # What a switch's commit does: a new live space, the old one retired, and+ # the target profile active -- one transaction.+ target = _activate(profiles, secrets, dimensions=2560, model="chat-2")+ with spaces.transaction() as connection:+ set_state_in(connection, old_space.space_id, state="retired", expected=("live",))+ insert_space_in(+ connection,+ derived_space(target).model_copy(update={"space_id": "new-space"}),+ )async def read() -> str:return str((await handle.client()).collection)diff --git a/memhub/docs/contracts/sdk-data-plane-migration-v1.md b/memhub/docs/contracts/sdk-data-plane-migration-v1.mdindex 451d9b2..da0da17 100644--- a/memhub/docs/contracts/sdk-data-plane-migration-v1.md+++ b/memhub/docs/contracts/sdk-data-plane-migration-v1.md@@ -66,6 +66,13 @@ one-memory sdk-migration-status --json # read-only: is there work?one-memory sdk-migrate --runtime-build <build> --yes --json```+An unfinished embedding switch or merge (`embedding-switch-v1.md`) never makes+a migration required and never blocks one: `sdk-migration-status` reports it as+an extra `embedding_switch: {job_id, kind, state}` field, `sdk-migrate` leaves+the `embedding_spaces` and `embedding_switch_jobs` tables alone, its readback+opens the registry's live space (which a switch changes only at its commit),+and the next serving Core resumes the job.+`sdk-migrate` requires a stopped Runtime. It takes the host capture fence(hooks return silently instead of writing Evidence while its PID is alive),then: