Python
fix(memhub): reattach stranded vectors and read memories back before cutover
alvinfeid8837b4fb22e
diff --git a/memhub/apps/cli/src/cli.ts b/memhub/apps/cli/src/cli.tsindex b451ad7..4cdb1d6 100644--- a/memhub/apps/cli/src/cli.ts+++ b/memhub/apps/cli/src/cli.ts@@ -4131,6 +4131,15 @@ function notReadyAfterMigration(command: "install" | "upgrade") {};}+const SDK_MIGRATION_FAILURES: Record<string, string> = {+ sdk_migration_disk_space_insufficient:+ "磁盘空间不足,记忆数据迁移没有完成,已回滚到上一版本。请腾出与记忆数据同等大小的空间后重试;原有记忆数据不会丢失。",+ sdk_migration_memory_unreadable:+ "核对发现新版本还读不到你的全部记忆,没有切换数据源,已回滚到上一版本。请把这个错误码反馈给我们;原有记忆数据不会丢失。",+ sdk_migration_model_profile_required:+ "迁移需要先有可用的模型配置,用来核对新版本能否读回记忆。已回滚到上一版本;请先用 memhub models setup 完成配置后再升级。",+};+function sdkMigrationFailure(command: "install" | "upgrade", code: string) {return {schema_version: 1,@@ -4139,9 +4148,8 @@ function sdkMigrationFailure(command: "install" | "upgrade", code: string) {status: "error",code,message:- code === "sdk_migration_disk_space_insufficient"- ? "磁盘空间不足,记忆数据迁移没有完成,已回滚到上一版本。请腾出与记忆数据同等大小的空间后重试;原有记忆数据不会丢失。"- : "记忆数据迁移没有完成,已回滚到上一版本。请重试;如果仍然失败,请把这个错误码反馈给我们。原有记忆数据不会丢失。",+ SDK_MIGRATION_FAILURES[code] ??+ "记忆数据迁移没有完成,已回滚到上一版本。请重试;如果仍然失败,请把这个错误码反馈给我们。原有记忆数据不会丢失。",};}diff --git a/memhub/apps/core/src/one_memory/api.py b/memhub/apps/core/src/one_memory/api.pyindex b42e0a1..19d462d 100644--- a/memhub/apps/core/src/one_memory/api.py+++ b/memhub/apps/core/src/one_memory/api.py@@ -3130,11 +3130,8 @@ def create_app(store = getattr(app.state, "sdk_data_plane_migrations", None)if store is None:store = SdkDataPlaneMigrationStore(_evidence_store(app).database_path)- marker = store.cutover()- return MemoryAuthorityResponse(- authority="sdk" if marker is not None else "legacy",- migration_id=marker.migration_id if marker is not None else None,- )+ authority, migration_id = store.authority_state()+ return MemoryAuthorityResponse(authority=authority.value, migration_id=migration_id)@app.get("/api/v2/memory-library",diff --git a/memhub/apps/core/src/one_memory/cli.py b/memhub/apps/core/src/one_memory/cli.pyindex c5676de..ee81e05 100644--- a/memhub/apps/core/src/one_memory/cli.py+++ b/memhub/apps/core/src/one_memory/cli.py@@ -335,6 +335,8 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:"bundle": "正在备份记忆数据……","prepare": "正在整理待处理的写入任务……","cutover": "正在切换数据源……",+ "vectors": "正在接回旧版本的向量数据……",+ "verify": "正在用新版本核对记忆能否读回……","cleanup": "正在删除旧表……",}@@ -356,13 +358,17 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:progress=progress,)except Exception as error:+ from one_memory.sdk_migration_verify import MemoryReadbackFailed+code = migration_failure_code(error)- document = {"schema_version": 1, "state": "failed", "code": code}- _write_restore(stream, as_json, document, f"迁移未完成:{code}")+ failed: dict[str, object] = {"schema_version": 1, "state": "failed", "code": code}+ if isinstance(error, MemoryReadbackFailed):+ failed["readback"] = error.report.as_document()+ _write_restore(stream, as_json, failed, f"迁移未完成:{code}")return 1messages = {"not_required": "不需要迁移。",- "complete": "迁移已完成,旧表已清理。",+ "complete": "迁移已完成;遗留的旧表或向量已处理。","cutover": "迁移完成:记忆数据已以 SDK 为准。",}_write_restore(stream, as_json, result.as_document(), messages[result.state])@@ -390,16 +396,23 @@ def sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:SdkDataPlaneMigrationStore,)from one_memory.sdk_migration_runner import abandoned_staging_present+ from one_memory.sdk_migration_verify import read_active_profile+ from one_memory.sdk_vector_reattach import legacy_vector_collectionsfrom one_memory.target_schema import legacy_tables_presentauthority = SdkDataPlaneMigrationStore(database_path).authority()if authority is MemoryAuthority.SDK:+ profile = read_active_profile(database_path)leftovers = bool(legacy_tables_present(database_path)or abandoned_staging_present(data_dir=settings.data_dir,namespace=HY_MEMORY_NAMESPACE,)+ or (+ profile is not None+ and legacy_vector_collections(settings.data_dir, profile)+ ))state = "required" if leftovers else "not_required"else:diff --git a/memhub/apps/core/src/one_memory/hy_sdk_runtime.py b/memhub/apps/core/src/one_memory/hy_sdk_runtime.pyindex 5c461b6..a510dcc 100644--- a/memhub/apps/core/src/one_memory/hy_sdk_runtime.py+++ b/memhub/apps/core/src/one_memory/hy_sdk_runtime.py@@ -237,15 +237,9 @@ def build_sdk_config(root = data_dir.resolve() / "hy-memory" / "governed-v2"root.mkdir(parents=True, exist_ok=True)- collection_identity = "\0".join(- (- embedding_provider.value,- embedding_endpoint or "local",- embedding_model,- str(dimensions or "auto"),- )+ collection = _collection_base(+ embedding_provider, embedding_endpoint, embedding_model, dimensions)- collection = "memhub_" + hashlib.sha256(collection_identity.encode()).hexdigest()[:16]return MemoryConfig.from_dict({@@ -348,6 +342,49 @@ def _generation_access(return endpoint, api_key+def _collection_base(+ provider: ProviderKind,+ endpoint: str | None,+ model: str,+ dimensions: int | None,+) -> str:+ identity = "\0".join((provider.value, endpoint or "local", model, str(dimensions or "auto")))+ return "memhub_" + hashlib.sha256(identity.encode()).hexdigest()[:16]+++def vector_collection_bases(profile: ModelProfileSnapshot) -> tuple[str, tuple[str, ...]]:+ """The SDK vector collection base for this embedding space, and the older ones.++ The SDK derives every vector collection (chat, Coding keys, Working facts,+ each variant) by suffixing this base. Builds before #145 named the same+ embedding space `one_memory_<12 hex>`, with or without a declared width;+ the offline migration renames those so their vectors stay readable.+ """+ 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")+ endpoint: str | None+ dimensions: int | None+ if local:+ endpoint, dimensions = None, profile.embedding_dimensions or BUILTIN_EMBEDDING_DIMENSIONS+ legacy_endpoint = "local-onnx"+ else:+ endpoint = _openai_endpoint(provider, profile.embedding_base_url or profile.base_url)+ dimensions = profile.embedding_dimensions+ legacy_endpoint = endpoint+ legacy_model = profile.embedding_model or "bge-small-zh-v1.5"+ legacy = tuple(+ "one_memory_"+ + hashlib.sha256(+ ":".join((provider.value, legacy_endpoint, legacy_model, *declared)).encode()+ ).hexdigest()[:12]+ for declared in ((), ("auto",), (str(profile.embedding_dimensions or "auto"),))+ )+ return _collection_base(provider, endpoint, model, dimensions), tuple(dict.fromkeys(legacy))++def _openai_endpoint(provider: ProviderKind, endpoint: str | None) -> str:value = (endpoint or "").rstrip("/")if not value:diff --git a/memhub/apps/core/src/one_memory/sdk_data_plane_migration.py b/memhub/apps/core/src/one_memory/sdk_data_plane_migration.pyindex ced4278..502f37b 100644--- a/memhub/apps/core/src/one_memory/sdk_data_plane_migration.py+++ b/memhub/apps/core/src/one_memory/sdk_data_plane_migration.py@@ -50,18 +50,29 @@ class SdkDataPlaneMigrationStore:return datetime.now(UTC).isoformat()def authority(self) -> MemoryAuthority:+ return self.authority_state()[0]++ def authority_state(self) -> tuple[MemoryAuthority, str | None]:+ """The surviving singleton: authority and the migration that set it.++ This is the only source of authority. The detailed cutover receipt is+ dropped after cleanup and never exists on a fresh home.+ """try:with main_database(self.database_path).read() as connection:row = connection.execute(- "SELECT authority FROM memory_authority_state WHERE singleton=1"+ "SELECT authority,migration_id FROM memory_authority_state WHERE singleton=1").fetchone()except sqlite3.OperationalError as error:if "no such table" not in str(error).lower():raiseelse:if row is not None:- return MemoryAuthority(str(row[0]))- return MemoryAuthority.SDK if self.cutover() is not None else MemoryAuthority.LEGACY+ return MemoryAuthority(str(row[0])), (str(row[1]) if row[1] else None)+ marker = self.cutover()+ if marker is not None:+ return MemoryAuthority.SDK, marker.migration_id+ return MemoryAuthority.LEGACY, Nonedef cutover(self) -> CutoverMarker | None:try:diff --git a/memhub/apps/core/src/one_memory/sdk_migration_runner.py b/memhub/apps/core/src/one_memory/sdk_migration_runner.pyindex 670bb72..cc991c3 100644--- a/memhub/apps/core/src/one_memory/sdk_migration_runner.py+++ b/memhub/apps/core/src/one_memory/sdk_migration_runner.py@@ -15,9 +15,10 @@ import osimport shutilimport sqlite3from collections.abc import Callable, Iterator-from contextlib import contextmanager+from contextlib import AbstractContextManager, contextmanagerfrom dataclasses import dataclassfrom pathlib import Path+from typing import Anyfrom one_memory.database_access import main_databasefrom one_memory.imports.models import EvidenceRecord@@ -35,6 +36,7 @@ from one_memory.memory_server.durable_queue import (DurableWriteQueue,)from one_memory.memory_server.unified_entry import UnifiedWriteIntake+from one_memory.model_profiles import ModelProfileSnapshotfrom one_memory.sdk_data_plane_migration import (CutoverMarker,DataPlaneMigrationError,@@ -42,6 +44,20 @@ from one_memory.sdk_data_plane_migration import (SdkDataPlaneMigrationStore,)from one_memory.sdk_migration_bundle import inspect_sdk_migration_bundle+from one_memory.sdk_migration_verify import (+ MemoryReadbackFailed,+ ReadbackReport,+ legacy_memory_ids_from,+ legacy_memory_ids_from_bundle,+ read_active_profile,+ runtime_sdk_client,+ verify_readback,+)+from one_memory.sdk_vector_reattach import (+ ReattachedCollection,+ legacy_vector_collections,+ reattach_legacy_vectors,+)from one_memory.target_schema import drop_legacy_tables, legacy_tables_presentPREPARED_PHASE = "prepared"@@ -341,6 +357,8 @@ class StartupMigrationResult:bundle_id: str | None = Nonepreparation: CutoverPreparation | None = Nonedropped_tables: tuple[str, ...] = ()+ reattached: tuple[ReattachedCollection, ...] = ()+ readback: ReadbackReport | None = Nonedef as_document(self) -> dict[str, object]:document: dict[str, object] = {"schema_version": 1, "state": self.state}@@ -349,6 +367,18 @@ class StartupMigrationResult:document["bundle_id"] = self.bundle_idif self.preparation is not None:document.update(self.preparation.as_document())+ if self.reattached:+ document["reattached_vectors"] = [+ {+ "collection": item.current,+ "legacy_count": item.legacy_count,+ "merged_count": item.merged_count,+ "final_count": item.final_count,+ }+ for item in self.reattached+ ]+ if self.readback is not None:+ document["readback"] = self.readback.as_document()if self.dropped_tables:document["dropped_tables"] = list(self.dropped_tables)return document@@ -415,6 +445,15 @@ def _ensure_bundle(*, data_dir: Path, bundle_id: str, runtime_build: str) -> dicreturn inspect_sdk_migration_bundle(data_dir=data_dir, bundle_id=bundle_id)+def _vacuum(database_path: Path) -> None:+ """Return the dropped tables' pages to the disk; a full disk only skips it."""+ try:+ with main_database(database_path).write(autocommit=True) as database:+ database.execute("VACUUM")+ except sqlite3.OperationalError:+ return++def run_startup_migration(*,data_dir: Path,@@ -422,24 +461,59 @@ def run_startup_migration(sdk_version: str,namespace: str,progress: Callable[[str], None] = lambda _step: None,+ open_client: Callable[[ModelProfileSnapshot], AbstractContextManager[Any]] | None = None,) -> StartupMigrationResult:"""Bring one stopped home to SDK authority. Safe to repeat after any failure.The caller must stop Runtime and keep its service from restarting.+ `open_client` yields a public SDK client configured as the Runtime will be;+ tests replace it."""database_path = data_dir / "one-memory.sqlite3"if not database_path.is_file():return StartupMigrationResult(state="not_required")++ def client_for(profile: ModelProfileSnapshot) -> AbstractContextManager[Any]:+ if open_client is not None:+ return open_client(profile)+ return runtime_sdk_client(database_path, data_dir, profile)+store = SdkDataPlaneMigrationStore(database_path)- if store.authority() is MemoryAuthority.SDK:- if not legacy_tables_present(database_path) and not abandoned_staging_present(+ authority, authority_migration = store.authority_state()+ profile = read_active_profile(database_path)+ if authority is MemoryAuthority.SDK:+ vectors_waiting = profile is not None and bool(legacy_vector_collections(data_dir, profile))+ leftovers = bool(legacy_tables_present(database_path)) or abandoned_staging_present(data_dir=data_dir, namespace=namespace- ):+ )+ if not vectors_waiting and not leftovers:return StartupMigrationResult(state="not_required")- progress("cleanup")+ reattached: tuple[ReattachedCollection, ...] = ()+ readback: ReadbackReport | None = None+ if vectors_waiting:+ assert profile is not None+ progress("vectors")+ reattached = reattach_legacy_vectors(data_dir, profile)+ legacy = legacy_memory_ids_from_bundle(data_dir, authority_migration)+ if legacy is not None and not legacy.empty:+ # Authority already moved, so nothing is left to protect by+ # refusing; record what the repaired home reads back.+ progress("verify")+ with client_for(profile) as client:+ readback = verify_readback(client, legacy)+ dropped: tuple[str, ...] = ()+ if leftovers:+ progress("cleanup")+ dropped = resume_legacy_cleanup(data_dir=data_dir, database_path=database_path)+ if dropped:+ _vacuum(database_path)return StartupMigrationResult(state="complete",- dropped_tables=resume_legacy_cleanup(data_dir=data_dir, database_path=database_path),+ migration_id=authority_migration,+ bundle_id=f"{authority_migration}-pre-cutover" if authority_migration else None,+ dropped_tables=dropped,+ reattached=reattached,+ readback=readback,)from one_memory.database_access import close_main_databases@@ -447,6 +521,11 @@ def run_startup_migration(from one_memory.memory_server.migrations import MIGRATIONSmigration_id, bundle_id = _resumable_identity(database_path)+ legacy = legacy_memory_ids_from(database_path)+ if profile is None and not legacy.empty:+ # Without the embedding profile the Runtime's collections cannot be+ # named, so neither reattached nor read back. Legacy stays intact.+ raise DataPlaneMigrationError("sdk_migration_model_profile_required")with capture_fence(data_dir):progress("bundle")manifest = _ensure_bundle(@@ -472,6 +551,19 @@ def run_startup_migration(backup_bundle_id=bundle_id,)preparation = prepare_legacy_work_for_cutover(database_path)+ reattached = ()+ readback = None+ if profile is not None:+ progress("vectors")+ reattached = reattach_legacy_vectors(data_dir, profile)+ if not legacy.empty:+ assert profile is not None+ progress("verify")+ with client_for(profile) as client:+ readback = verify_readback(client, legacy)+ if not readback.passed:+ store.set_phase(migration_id, phase="readback_failed", state="blocked")+ raise MemoryReadbackFailed(readback)store.set_phase(migration_id, phase=PREPARED_PHASE, state="ready")progress("cutover")commit_sdk_cutover(@@ -483,10 +575,14 @@ def run_startup_migration()progress("cleanup")dropped = resume_legacy_cleanup(data_dir=data_dir, database_path=database_path)+ if dropped:+ _vacuum(database_path)return StartupMigrationResult(state="cutover",migration_id=migration_id,bundle_id=bundle_id,preparation=preparation,dropped_tables=dropped,+ reattached=reattached,+ readback=readback,)diff --git a/memhub/apps/core/src/one_memory/sdk_migration_verify.py b/memhub/apps/core/src/one_memory/sdk_migration_verify.pynew file mode 100644index 0000000..529e5e8--- /dev/null+++ b/memhub/apps/core/src/one_memory/sdk_migration_verify.py@@ -0,0 +1,232 @@+"""Read legacy memory IDs back through the SDK before (and after) the cutover.++The cutover is only safe if the SDK, configured exactly as the new Runtime+will configure it, returns the memories the legacy mirror lists. Checking that+the backup bundle is complete says nothing about it: build 20 dropped the+legacy tables while its Runtime read an empty vector collection.++Reads go through the public `HyMemoryClient` (`list_memories`, `get`).+"""++from __future__ import annotations++import json+import sqlite3+from collections.abc import Iterator+from contextlib import closing, contextmanager+from dataclasses import dataclass+from pathlib import Path+from typing import Any++from one_memory.database_access import main_database+from one_memory.model_profiles import ModelProfileSnapshot+from one_memory.sdk_data_plane_migration import DataPlaneMigrationError++_PRODUCTIVITY_KINDS = frozenset({"coding", "working"})+_PRODUCTIVITY_LAYERS = frozenset(+ {"coding_experience", "working_experience", "coding_fact", "working_fact"}+)+_SDK_STATUSES = ("active", "superseded", "shadow", "negated", "conflicted", "archived")+_PAGE = 500+++@dataclass(frozen=True)+class LegacyMemoryIds:+ chat: tuple[str, ...]+ productivity: tuple[str, ...]+ users: tuple[str, ...]++ @property+ def empty(self) -> bool:+ return not self.chat and not self.productivity+++@dataclass(frozen=True)+class ReadbackReport:+ chat_expected: int+ chat_readable: int+ productivity_expected: int+ productivity_readable: int++ @property+ def passed(self) -> bool:+ # Every chat memory is an SDK node by construction, so all must read+ # back. The SDK's Coding reconciler deletes experiences it retires, so+ # a partial productivity count is normal; none at all is not.+ return self.chat_readable == self.chat_expected and (+ self.productivity_expected == 0 or self.productivity_readable > 0+ )++ def as_document(self) -> dict[str, object]:+ return {+ "chat_expected": self.chat_expected,+ "chat_readable": self.chat_readable,+ "productivity_expected": self.productivity_expected,+ "productivity_readable": self.productivity_readable,+ "passed": self.passed,+ }+++class MemoryReadbackFailed(DataPlaneMigrationError):+ def __init__(self, report: ReadbackReport) -> None:+ super().__init__("sdk_migration_memory_unreadable")+ self.report = report+++def _tables(connection: sqlite3.Connection) -> set[str]:+ return {+ str(row[0])+ for row in connection.execute("SELECT name FROM sqlite_master WHERE type='table'")+ }+++def read_legacy_memory_ids(connection: sqlite3.Connection) -> LegacyMemoryIds:+ """Confirmed legacy memories, by the SDK id the old bridge recorded."""+ tables = _tables(connection)+ if "governed_memories" not in tables:+ return LegacyMemoryIds(chat=(), productivity=(), users=())+ mapped: dict[str, tuple[str, str | None]] = {}+ if "memory_task_outputs" in tables:+ for (body,) in connection.execute("SELECT body FROM memory_task_outputs"):+ try:+ document = json.loads(body)+ except (TypeError, ValueError):+ continue+ legacy_id, sdk_id = document.get("memory_id"), document.get("hy_memory_id")+ if isinstance(legacy_id, str) and isinstance(sdk_id, str):+ layer = document.get("layer")+ mapped[legacy_id] = (sdk_id, layer if isinstance(layer, str) else None)+ chat: set[str] = set()+ productivity: set[str] = set()+ users: set[str] = set()+ for memory_id, user_id, kind in connection.execute(+ "SELECT memory_id,user_id,kind FROM governed_memories WHERE status='confirmed'"+ ):+ sdk_id, layer = mapped.get(str(memory_id), (str(memory_id), None))+ users.add(str(user_id))+ if str(kind) in _PRODUCTIVITY_KINDS or layer in _PRODUCTIVITY_LAYERS:+ productivity.add(sdk_id)+ else:+ chat.add(sdk_id)+ return LegacyMemoryIds(+ chat=tuple(sorted(chat)),+ productivity=tuple(sorted(productivity)),+ users=tuple(sorted(users)),+ )+++def legacy_memory_ids_from(database_path: Path) -> LegacyMemoryIds:+ with main_database(database_path).read() as connection:+ return read_legacy_memory_ids(connection)+++def legacy_memory_ids_from_bundle(+ data_dir: Path, migration_id: str | None+) -> LegacyMemoryIds | None:+ """The same list from the pre-cutover bundle, for a home already migrated."""+ if not migration_id:+ return None+ database = (+ data_dir+ / "backups"+ / f"{migration_id}-pre-cutover.sdk-bundle"+ / "management"+ / "one-memory.sqlite3"+ )+ if not database.is_file():+ return None+ with closing(sqlite3.connect(f"file:{database}?mode=ro", uri=True)) as connection:+ return read_legacy_memory_ids(connection)+++def read_active_profile(database_path: Path) -> ModelProfileSnapshot | None:+ """The active model profile, read only; the status probe runs beside Core."""+ with main_database(database_path).read(row_factory=sqlite3.Row) as connection:+ if not {"model_profiles", "model_profile_versions"} <= _tables(connection):+ return None+ row = connection.execute(+ "SELECT version.* FROM model_profiles profile "+ "JOIN model_profile_versions version "+ "ON version.profile_id=profile.profile_id AND version.revision=profile.revision "+ "WHERE profile.is_active=1"+ ).fetchone()+ if row is None:+ return None+ return ModelProfileSnapshot(+ profile_id=row["profile_id"],+ revision=row["revision"],+ provider_kind=row["provider_kind"],+ base_url=row["base_url"],+ model=row["model"],+ embedding_model=row["embedding_model"],+ embedding_provider_kind=row["embedding_provider_kind"],+ embedding_base_url=row["embedding_base_url"],+ embedding_dimensions=row["embedding_dimensions"],+ timeout_seconds=row["timeout_seconds"],+ max_concurrency=row["max_concurrency"],+ context_window=row["context_window"],+ has_api_key=row["secret_ref"] is not None,+ disable_thinking=bool(row["disable_thinking"]),+ )+++@contextmanager+def runtime_sdk_client(+ database_path: Path, data_dir: Path, profile: ModelProfileSnapshot+) -> Iterator[Any]:+ """A public SDK client configured exactly as the Runtime configures it."""+ from one_memory.hy_sdk_runtime import acquire_client+ from one_memory.model_profiles import ModelProfileStore+ from one_memory.secrets import KeyringSecretStore, SecretStoreUnavailableError++ try:+ secret = ModelProfileStore(database_path).resolve_snapshot_secret(+ profile.profile_id, profile.revision, KeyringSecretStore()+ )+ except SecretStoreUnavailableError:+ raise DataPlaneMigrationError("sdk_migration_secure_storage_unavailable") from None+ if profile.has_api_key and secret is None:+ raise DataPlaneMigrationError("sdk_migration_model_secret_unavailable")+ lease = acquire_client(profile, api_key=secret, data_dir=data_dir)+ try:+ yield lease.client+ finally:+ lease.close()+++def verify_readback(client: Any, legacy: LegacyMemoryIds) -> ReadbackReport:+ listed: set[str] = set()+ for user_id in legacy.users or ("local",):+ offset = 0+ while True:+ raw = client.list_memories(+ user_id=user_id,+ statuses=list(_SDK_STATUSES),+ limit=_PAGE,+ offset=offset,+ order="asc",+ )+ bucket = raw.get("vdb") if isinstance(raw, dict) else None+ rows = bucket.get("memories") if isinstance(bucket, dict) else None+ total = bucket.get("total") if isinstance(bucket, dict) else None+ if not isinstance(rows, list) or not isinstance(total, int):+ raise DataPlaneMigrationError("sdk_migration_memory_list_shape_unknown")+ listed.update(+ str(row["memory_id"])+ for row in rows+ if isinstance(row, dict) and row.get("memory_id")+ )+ offset += len(rows)+ if not rows or offset >= total:+ break++ def readable(memory_id: str) -> bool:+ return memory_id in listed or client.get(memory_id) is not None++ return ReadbackReport(+ chat_expected=len(legacy.chat),+ chat_readable=sum(1 for memory_id in legacy.chat if readable(memory_id)),+ productivity_expected=len(legacy.productivity),+ productivity_readable=sum(1 for memory_id in legacy.productivity if readable(memory_id)),+ )+diff --git a/memhub/apps/core/src/one_memory/sdk_vector_reattach.py b/memhub/apps/core/src/one_memory/sdk_vector_reattach.pynew file mode 100644index 0000000..4136cb4--- /dev/null+++ b/memhub/apps/core/src/one_memory/sdk_vector_reattach.py@@ -0,0 +1,149 @@+"""Offline reattachment of SDK vector collections named by builds before #145.++Those builds named a profile's embedding space `one_memory_<12 hex>`; #145+renamed it `memhub_<16 hex>` and dropped the step that carried the old+collections over, so every later Runtime opened an empty space beside the old+one. Runtime code only reaches vectors through the SDK. This module runs from+`sdk-migrate` while the Runtime is stopped, through Chroma's public client.+"""++from __future__ import annotations++import sqlite3+from collections.abc import Iterator+from contextlib import closing+from dataclasses import dataclass+from pathlib import Path+from typing import Any++from one_memory.hy_sdk_runtime import vector_collection_bases+from one_memory.model_profiles import ModelProfileSnapshot+from one_memory.sdk_data_plane_migration import DataPlaneMigrationError++_BATCH = 500+++@dataclass(frozen=True)+class ReattachedCollection:+ legacy: str+ current: str+ legacy_count: int+ merged_count: int+ final_count: int+++def _vector_directory(data_dir: Path) -> Path:+ return data_dir / "hy-memory" / "governed-v2" / "vector"+++def _stored_names(data_dir: Path) -> tuple[str, ...]:+ database = _vector_directory(data_dir) / "chroma.sqlite3"+ if not database.is_file():+ return ()+ with closing(sqlite3.connect(f"file:{database}?mode=ro", uri=True)) as connection:+ try:+ rows = connection.execute("SELECT name FROM collections").fetchall()+ except sqlite3.Error:+ return ()+ return tuple(sorted(str(row[0]) for row in rows))+++def legacy_vector_collections(+ data_dir: Path, profile: ModelProfileSnapshot+) -> tuple[tuple[str, str], ...]:+ """(legacy name, current name) pairs still waiting to be reattached.++ Read-only, so `sdk-migration-status` can ask it.+ """+ current, legacy_bases = vector_collection_bases(profile)+ pairs: list[tuple[str, str]] = []+ for name in _stored_names(data_dir):+ for base in legacy_bases:+ if name == base or name.startswith(f"{base}_"):+ pairs.append((name, current + name[len(base) :]))+ break+ return tuple(pairs)+++def _records(collection: Any) -> Iterator[dict[str, Any]]:+ offset = 0+ while True:+ page = collection.get(+ include=["embeddings", "documents", "metadatas"],+ limit=_BATCH,+ offset=offset,+ )+ ids = list(page["ids"])+ if not ids:+ return+ yield {+ "ids": ids,+ "embeddings": page["embeddings"],+ "documents": page["documents"],+ "metadatas": page["metadatas"],+ }+ offset += len(ids)+++def reattach_legacy_vectors(+ data_dir: Path, profile: ModelProfileSnapshot+) -> tuple[ReattachedCollection, ...]:+ """Rename legacy collections to the current names, keeping newer writes.++ A current collection that already exists (written after the rename broke)+ is merged into the legacy one first; on an id present in both, the newer+ current record wins. Callers must have stopped every SDK writer.+ """+ pairs = legacy_vector_collections(data_dir, profile)+ if not pairs:+ return ()+ import chromadb+ from chromadb.config import Settings++ client = chromadb.PersistentClient(+ path=str(_vector_directory(data_dir)),+ settings=Settings(anonymized_telemetry=False),+ )+ existing = set(_stored_names(data_dir))+ done: list[ReattachedCollection] = []+ for legacy_name, current_name in pairs:+ legacy = client.get_collection(legacy_name)+ legacy_count = legacy.count()+ merged = 0+ if current_name in existing:+ current = client.get_collection(current_name)+ legacy_ids = set(_ids(legacy))+ current_ids: set[str] = set()+ for batch in _records(current):+ legacy.upsert(**batch)+ current_ids.update(batch["ids"])+ merged = len(current_ids)+ if legacy.count() != len(legacy_ids | current_ids):+ raise DataPlaneMigrationError("sdk_migration_vector_merge_incomplete")+ client.delete_collection(current_name)+ legacy.modify(name=current_name)+ final = client.get_collection(current_name).count()+ if final < legacy_count:+ raise DataPlaneMigrationError("sdk_migration_vector_reattach_incomplete")+ existing.discard(legacy_name)+ existing.add(current_name)+ done.append(+ ReattachedCollection(+ legacy=legacy_name,+ current=current_name,+ legacy_count=legacy_count,+ merged_count=merged,+ final_count=final,+ )+ )+ return tuple(done)+++def _ids(collection: Any) -> Iterator[str]:+ offset = 0+ while True:+ ids = list(collection.get(include=[], limit=_BATCH, offset=offset)["ids"])+ if not ids:+ return+ yield from ids+ offset += len(ids)diff --git a/memhub/apps/core/tests/test_main_database_entry.py b/memhub/apps/core/tests/test_main_database_entry.pyindex 1b778b8..49b2b5d 100644--- a/memhub/apps/core/tests/test_main_database_entry.py+++ b/memhub/apps/core/tests/test_main_database_entry.py@@ -91,6 +91,16 @@ ALLOWED = {"Chroma's own chroma.sqlite3, read-only, checked before Chroma opens it",opened_with='"?mode=ro"',),+ ("sdk_migration_verify.py", "legacy_memory_ids_from_bundle"): Allowed(+ "the pre-cutover bundle's copy of the legacy database, read-only, to list "+ "the memory ids a migrated home must still read back",+ opened_with="?mode=ro",+ ),+ ("sdk_vector_reattach.py", "_stored_names"): Allowed(+ "Chroma's own chroma.sqlite3, read-only, to list collection names before "+ "the offline migration opens Chroma",+ 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_sdk_data_plane_migration.py b/memhub/apps/core/tests/test_sdk_data_plane_migration.pyindex 31e0196..e0c7cad 100644--- a/memhub/apps/core/tests/test_sdk_data_plane_migration.py+++ b/memhub/apps/core/tests/test_sdk_data_plane_migration.py@@ -8,11 +8,15 @@ from datetime import UTC, datetime, timedeltafrom pathlib import Pathimport pytest+from httpx import ASGITransport, AsyncClient+from pydantic import SecretStrfrom one_memory import cli+from one_memory.api import create_appfrom one_memory.config import Settingsfrom one_memory.database_access import close_main_databases, main_databasefrom one_memory.hy_sdk_types import HySdkRawPage+from one_memory.imports.storage import EvidenceStorefrom one_memory.memory_server.contracts import BatchIdentity, WriteRequestfrom one_memory.memory_server.durable_queue import DurableWriteQueuefrom one_memory.memory_server.migration_runner import SqliteMigrationStore, migrate@@ -35,6 +39,7 @@ from one_memory.sdk_migration_runner import (resume_legacy_cleanup,run_startup_migration,)+from one_memory.secrets import InMemorySecretStorefrom one_memory.target_schema import legacy_tables_present@@ -283,6 +288,235 @@ def test_finished_jobs_without_input_do_not_stop_the_migration(store):prepare_legacy_write_queue_for_cutover(store.database_path)+def _chroma(home: Path):+ import chromadb+ from chromadb.config import Settings as ChromaSettings++ return chromadb.PersistentClient(+ path=str(home / "hy-memory" / "governed-v2" / "vector"),+ settings=ChromaSettings(anonymized_telemetry=False),+ )+++def _fill(client, name: str, ids: list[str], *, text: str = "old") -> None:+ collection = client.get_or_create_collection(name, metadata={"hnsw:space": "cosine"})+ collection.upsert(+ ids=ids,+ embeddings=[[float(index + 1)] * 4 for index, _ in enumerate(ids)],+ documents=[f"{text} {identifier}" for identifier in ids],+ metadatas=[{"layer": "l2_fact"} for _ in ids],+ )+++def test_legacy_vectors_are_renamed_and_newer_writes_are_kept(tmp_path) -> None:+ """Build 20: 3317 memories in `one_memory_*`, the Runtime reading an empty `memhub_*`."""+ from one_memory.hy_sdk_runtime import builtin_retrieval_snapshot, vector_collection_bases+ from one_memory.sdk_vector_reattach import (+ legacy_vector_collections,+ reattach_legacy_vectors,+ )++ profile = builtin_retrieval_snapshot()+ current, legacy = vector_collection_bases(profile)+ client = _chroma(tmp_path)+ _fill(client, f"{legacy[0]}_4", ["a", "b", "both"])+ _fill(client, f"{legacy[0]}_coding_keys_cv_4", ["k1"])+ _fill(client, f"{current}_4", ["new", "both"], text="newer")+ del client++ assert len(legacy_vector_collections(tmp_path, profile)) == 2+ done = reattach_legacy_vectors(tmp_path, profile)++ assert {(item.current, item.final_count) for item in done} == {+ (f"{current}_4", 4),+ (f"{current}_coding_keys_cv_4", 1),+ }+ assert legacy_vector_collections(tmp_path, profile) == ()+ client = _chroma(tmp_path)+ assert sorted(collection.name for collection in client.list_collections()) == [+ f"{current}_4",+ f"{current}_coding_keys_cv_4",+ ]+ chat = client.get_collection(f"{current}_4").get(ids=["both"], include=["documents"])+ assert chat["documents"] == ["newer both"]+ assert reattach_legacy_vectors(tmp_path, profile) == ()+++def _confirmed(store, *memory_ids: str, kind: str = "chat") -> None:+ with main_database(store.database_path).write() as database, database:+ for memory_id in memory_ids:+ database.execute(+ "INSERT INTO governed_memories (memory_id,user_id,kind,status,content,"+ "scopes_json,revision,created_at,updated_at) "+ "VALUES (?,'local',?,'confirmed','x','[]',1,'now','now')",+ (memory_id, kind),+ )+++class _ReadingClient:+ """Public-API shaped SDK client that holds only `readable` ids."""++ def __init__(self, readable: set[str]) -> None:+ self.readable = readable++ def list_memories(self, *, user_id, statuses, limit, offset, order):+ del user_id, statuses, order+ ids = sorted(self.readable)+ rows = [{"memory_id": memory_id} for memory_id in ids[offset : offset + limit]]+ return {"vdb": {"memories": rows, "total": len(ids)}}++ def get(self, memory_id):+ return {"memory_id": memory_id} if memory_id in self.readable else None+++def _reading(readable: set[str]):+ from contextlib import contextmanager++ @contextmanager+ def open_client(_profile):+ yield _ReadingClient(readable)++ return open_client+++def active_profile(monkeypatch):+ from one_memory.hy_sdk_runtime import builtin_retrieval_snapshot++ profile = builtin_retrieval_snapshot()+ monkeypatch.setattr("one_memory.sdk_migration_runner.read_active_profile", lambda _db: profile)+ monkeypatch.setattr("one_memory.sdk_migration_verify.read_active_profile", lambda _db: profile)+ return profile+++def test_cutover_waits_until_the_new_runtime_reads_every_chat_memory(store, active_profile):+ """Build 20 reported success on 37 of 3317. Now the legacy tables stay."""+ from one_memory.sdk_migration_verify import MemoryReadbackFailed++ _confirmed(store, "m1", "m2", "m3")+ home = store.database_path.parent++ with pytest.raises(MemoryReadbackFailed) as caught:+ run_startup_migration(+ data_dir=home,+ runtime_build="21",+ sdk_version="2.0.5",+ namespace="governed-v2",+ open_client=_reading({"m1"}),+ )++ assert caught.value.code == "sdk_migration_memory_unreadable"+ assert caught.value.report.as_document() == {+ "chat_expected": 3,+ "chat_readable": 1,+ "productivity_expected": 0,+ "productivity_readable": 0,+ "passed": False,+ }+ assert store.authority() is MemoryAuthority.LEGACY+ assert "governed_memories" in legacy_tables_present(store.database_path)++ result = run_startup_migration(+ data_dir=home,+ runtime_build="21",+ sdk_version="2.0.5",+ namespace="governed-v2",+ open_client=_reading({"m1", "m2", "m3"}),+ )++ assert result.state == "cutover"+ assert result.readback is not None and result.readback.passed+ assert store.authority() is MemoryAuthority.SDK+++def test_retired_coding_experiences_do_not_block_but_an_empty_store_does(store, active_profile):+ _confirmed(store, "chat-1")+ _confirmed(store, "exp-kept", "exp-retired", kind="coding")+ home = store.database_path.parent+ from one_memory.sdk_migration_verify import MemoryReadbackFailed++ with pytest.raises(MemoryReadbackFailed):+ run_startup_migration(+ data_dir=home,+ runtime_build="21",+ sdk_version="2.0.5",+ namespace="governed-v2",+ open_client=_reading({"chat-1"}),+ )+ result = run_startup_migration(+ data_dir=home,+ runtime_build="21",+ sdk_version="2.0.5",+ namespace="governed-v2",+ open_client=_reading({"chat-1", "exp-kept"}),+ )+ assert result.readback is not None+ assert (result.readback.productivity_expected, result.readback.productivity_readable) == (2, 1)+++def test_memories_without_a_model_profile_keep_legacy_authority(store, monkeypatch):+ monkeypatch.setattr("one_memory.sdk_migration_runner.read_active_profile", lambda _db: None)+ _confirmed(store, "m1")++ with pytest.raises(DataPlaneMigrationError, match="sdk_migration_model_profile_required"):+ run_startup_migration(+ data_dir=store.database_path.parent,+ runtime_build="21",+ sdk_version="2.0.5",+ namespace="governed-v2",+ )+ assert store.authority() is MemoryAuthority.LEGACY+++def test_a_build_20_home_gets_its_vectors_back_and_is_checked_against_its_backup(+ store, active_profile, monkeypatch+):+ from one_memory.hy_sdk_runtime import vector_collection_bases++ home = store.database_path.parent+ current, legacy_bases = vector_collection_bases(active_profile)+ client = _chroma(home)+ _fill(client, f"{legacy_bases[0]}_512", ["m1", "m2"])+ _fill(client, f"{current}_512", ["after-upgrade"], text="newer")+ del client+ _confirmed(store, "m1", "m2")+ first = run_startup_migration(+ data_dir=home,+ runtime_build="20",+ sdk_version="2.0.5",+ namespace="governed-v2",+ open_client=_reading({"m1", "m2"}),+ )+ assert first.state == "cutover"+ # Reproduce build 20: cut over while the legacy collection stayed stranded.+ client = _chroma(home)+ client.get_collection(f"{current}_512").modify(name=f"{legacy_bases[0]}_512")+ _fill(client, f"{current}_512", ["after-upgrade"], text="newer")+ del client+ monkeypatch.setattr(cli, "load_settings", lambda: Settings(_env_file=None, data_dir=home))+ status = io.StringIO()+ assert cli.run(["sdk-migration-status", "--json"], output=status) == 0+ assert json.loads(status.getvalue())["state"] == "required"++ repaired = run_startup_migration(+ data_dir=home,+ runtime_build="21",+ sdk_version="2.0.5",+ namespace="governed-v2",+ open_client=_reading({"m1", "m2", "after-upgrade"}),+ )++ assert repaired.state == "complete"+ assert [(item.current, item.final_count) for item in repaired.reattached] == [+ (f"{current}_512", 3)+ ]+ assert repaired.readback is not None and repaired.readback.passed+ assert repaired.readback.chat_expected == 2+ status = io.StringIO()+ assert cli.run(["sdk-migration-status", "--json"], output=status) == 0+ assert json.loads(status.getvalue())["state"] == "not_required"++def test_pending_dispatch_becomes_one_write_job_per_conversation(store):_insert_evidence(store, "a1", conversation="a", seq=1)_insert_evidence(store, "a2", conversation="a", role="assistant", seq=2)@@ -560,3 +794,75 @@ def test_sdk_raw_retention_keeps_only_the_latest_three_days():)assert asyncio.run(runtime.prune_expired_raw(now=now)) == 1assert [row["memory_id"] for row in client.rows] == ["recent"]+++# The UI asks which memory data plane is authoritative and must get the+# answer the API gates use.+++def _app_settings(tmp_path) -> Settings:+ return Settings(+ _env_file=None,+ data_dir=tmp_path / "data",+ source_home=tmp_path,+ api_token=SecretStr("authority-test"),+ imports_enabled=False,+ automatic_memory_processing=False,+ live_sync_enabled=False,+ )+++async def _authority(tmp_path) -> tuple[dict[str, object], str]:+ app = create_app(_app_settings(tmp_path), secret_store=InMemorySecretStore())+ async with (+ app.router.lifespan_context(app),+ AsyncClient(+ transport=ASGITransport(app=app),+ base_url="http://test",+ headers={"Authorization": "Bearer authority-test"},+ ) as client,+ ):+ response = await client.get("/api/v2/memory-authority")+ assert response.status_code == 200+ return response.json(), app.state.memory_authority.value+++def test_a_fresh_home_reports_sdk_authority(tmp_path) -> None:+ document, gate = asyncio.run(_authority(tmp_path))++ assert document == {"authority": "sdk", "migration_id": None}+ assert gate == "sdk"+++def test_a_migrated_home_still_reports_sdk_after_its_receipt_is_dropped(+ tmp_path, monkeypatch+) -> None:+ """Build 20: the cleanup dropped the cutover receipt, the UI fell back to legacy."""+ data_dir = tmp_path / "data"+ EvidenceStore(data_dir / "one-memory.sqlite3")+ monkeypatch.setattr(cli, "load_settings", lambda: _app_settings(tmp_path))+ monkeypatch.setattr(+ cli,+ "inspect_runtime",+ lambda _data_dir: RuntimeStatus("stopped", "runtime_receipt_missing"),+ )+ output = io.StringIO()+ assert cli.run(["sdk-migrate", "--runtime-build", "21", "--yes", "--json"], output=output) == 0+ migration_id = json.loads(output.getvalue().splitlines()[-1])["migration_id"]+ assert legacy_tables_present(data_dir / "one-memory.sqlite3") == ()++ document, gate = asyncio.run(_authority(tmp_path))++ assert document == {"authority": "sdk", "migration_id": migration_id}+ assert gate == "sdk"+++def test_a_legacy_home_reports_legacy_authority(tmp_path) -> None:+ document, gate = asyncio.run(_authority(tmp_path))++ assert document == {"authority": "legacy", "migration_id": None}+ assert gate == "legacy"diff --git a/memhub/apps/desktop/src/stable-runtime.test.ts b/memhub/apps/desktop/src/stable-runtime.test.tsindex 79f8dd0..ad6fbc6 100644--- a/memhub/apps/desktop/src/stable-runtime.test.ts+++ b/memhub/apps/desktop/src/stable-runtime.test.ts@@ -285,6 +285,12 @@ describe("startup install errors", () => {expect(noSpace).toContain("重新启动");expect(noSpace).toContain("不会丢失");expect(noSpace).not.toContain("sdk_migration_disk_space_insufficient");++ const unreadable = stableRuntimeUserMessage(+ new Error("sdk_migration_memory_unreadable"),+ );+ expect(unreadable).toContain("没有切换数据源");+ expect(unreadable).toContain("不会丢失");});});diff --git a/memhub/apps/desktop/src/stable-runtime.ts b/memhub/apps/desktop/src/stable-runtime.tsindex af919f7..7794f97 100644--- a/memhub/apps/desktop/src/stable-runtime.ts+++ b/memhub/apps/desktop/src/stable-runtime.ts@@ -130,6 +130,10 @@ const SAFE_STABLE_RUNTIME_ERROR_CODES = new Set([// a first launch can be given. They stay codes here and become sentences in// STABLE_RUNTIME_USER_MESSAGES: a person reading the dialog never sees them."sdk_migration_preflight_failed",+ "sdk_migration_memory_unreadable",+ "sdk_migration_model_profile_required",+ "sdk_migration_model_secret_unavailable",+ "sdk_migration_secure_storage_unavailable","sdk_migration_disk_space_insufficient","sdk_migration_cutover_failed","sdk_migration_bundle_copy_failed",@@ -201,6 +205,14 @@ export const STABLE_RUNTIME_USER_MESSAGES: Record<string, string> = {"已安装的运行环境比这个安装包更新,无法用旧安装包启动。请安装最新版本的 MemHub;你的记忆数据不会受到影响。",install_current_unmanaged:"运行环境的安装目录被改动过,无法安全接管。请重新安装 MemHub,你的记忆数据不会受到影响。",+ sdk_migration_memory_unreadable:+ "升级前核对发现,新版本还读不到你的全部记忆,所以没有切换数据源,旧数据保持原样可用。请把这个提示反馈给我们;原有记忆数据不会丢失。",+ sdk_migration_model_profile_required:+ "升级记忆数据格式需要先有可用的模型配置,用来核对新版本能否读回你的记忆。请在旧版本中完成模型配置后重启;你的记忆数据不会受到影响。",+ sdk_migration_model_secret_unavailable:+ "模型密钥读不到(可能被系统钥匙串拒绝),无法核对新版本能否读回你的记忆。请允许 MemHub 访问钥匙串后重新启动;你的记忆数据不会受到影响。",+ sdk_migration_secure_storage_unavailable:+ "系统钥匙串暂时不可用,无法核对新版本能否读回你的记忆。请解锁钥匙串后重新启动;你的记忆数据不会受到影响。",sdk_migration_disk_space_insufficient:"磁盘空间不足,升级记忆数据格式时中断了。请至少腾出与记忆数据同等大小的可用空间(可在「关于本机 → 储存空间」查看),然后重新启动 MemHub;升级会自动继续,原有记忆数据不会丢失。",sdk_migration_bundle_copy_failed:diff --git a/memhub/docs/ARCHITECTURE.md b/memhub/docs/ARCHITECTURE.mdindex a8d03e8..9b6637a 100644--- a/memhub/docs/ARCHITECTURE.md+++ b/memhub/docs/ARCHITECTURE.md@@ -135,7 +135,7 @@ This exception does not extend to VDB, Coding, prompt, reconcile, or lifecycle.- Context wire:cutover marker 提交前只使用 legacy Context v1;提交后 Host Bridge 只使用 SDK-native Context v2。两种 schema 原样校验、原样返回,不把 SDK item 补造成 v1 的 `revision`、`evidence_ids`、`paths` 或 `adoption`,已选择的 v2 路径失败时也不回退 legacy 权威。- Ask wire:marker 前保留 Governance Ask v1;marker 后 Web / Host Bridge 只调用 SDK Ask v2。v2 的引用只含 SDK 原生 `memory_id/content/layer/status/source/gmt_created`,生成过程中重复 `get` 校验同一 SDK 快照,不补造 revision、Evidence 或 scopes,SDK 失败不回退 v1。- Matter:未形成已发布产品合同,不迁移占位数据;所有 `matter*` 表在升级清理时物理删除,fresh install 不创建,Runtime 不注册 Matter API。-- 旧用户迁移:由 App 在可见的启动 loading 阶段统一执行;此时 Core 尚未对外提供产品读写。所有已发布版本都先经 SDK 写入,Governance/Evidence 只是镜像,所以迁移**不复制、不比对任何 memory 或 raw**:只创建并校验完整 bundle、让写入队列脱离旧表、提交 marker、删除旧表。由一个 Core 命令 `sdk-migrate` 完成;Desktop 启动与 CLI `memhub install`/`upgrade`(macOS、Linux)在启动新 Runtime 前调用它,普通用户不需要另跑命令。App 不得在 migration `deferred` 状态继续启动 Runtime。+- 旧用户迁移:由 App 在可见的启动 loading 阶段统一执行;此时 Core 尚未对外提供产品读写。所有已发布版本都先经 SDK 写入,Governance/Evidence 只是镜像,所以迁移**不复制任何 memory 或 raw**:创建并校验完整 bundle、让写入队列脱离旧表、把旧版命名的 SDK 向量集合接回当前名字、用 Runtime 同样配置的公开 SDK client 按 ID 回读核对,通过后才提交 marker、删除旧表。由一个 Core 命令 `sdk-migrate` 完成;Desktop 启动与 CLI `memhub install`/`upgrade`(macOS、Linux)在启动新 Runtime 前调用它,普通用户不需要另跑命令。App 不得在 migration `deferred` 状态继续启动 Runtime。- 迁移期间宿主 capture hook 由 Desktop 活跃 PID marker 静默挡住,不再追加Evidence;cutover 后先从宿主 History checkpoint 补齐遗漏 turn,再恢复 live sync。- Matter 若未来重新开发,需以新的 SDK-native 合同重新设计,不继承当前占位 schema。diff --git a/memhub/docs/contracts/sdk-data-plane-migration-v1.md b/memhub/docs/contracts/sdk-data-plane-migration-v1.mdindex 445345f..03e7ac9 100644--- a/memhub/docs/contracts/sdk-data-plane-migration-v1.md+++ b/memhub/docs/contracts/sdk-data-plane-migration-v1.md@@ -1,6 +1,6 @@# SDK Data Plane Migration v1-Updated: 2026-10-24.+Updated: 2026-10-24 (vector reattach, readback).This contract moves released MemHub installations from the historicalEvidence/Governance authority to the Hy Memory SDK data plane defined by@@ -29,6 +29,14 @@ and no raw turn, and does not compare the mirror with the SDK:- SDK L1 raw is retained for three days by the Runtime's own`prune_expired_raw`, not by the migration.+"Already complete" holds only if the new Runtime opens the same stores. Builds+before #145 named a profile's vector collections `one_memory_<12 hex>…`; #145+renamed them `memhub_<16 hex>…` without carrying the old ones over, so later+Runtimes read an empty collection (build 20 cut over showing 37 of 3317+memories). The migration therefore reattaches those collections (§3, step 3)+and proves the new Runtime reads the memories back before it cuts over+(step 4).+## 2. Authority before and after cutoverBefore the cutover marker is committed, legacy tables remain the product read@@ -68,9 +76,32 @@ then:restore; an existing verified bundle of the same run is reused;2. **prepare**: applies the management schema migrations, discards SDK stagingleft by builds through 19 (§5) and makes legacy queue work self-contained- (§4); it needs no model profile and no SDK client;-3. **cutover**: re-verifies the bundle, repeats §4, commits SDK authority;-4. **cleanup**: drops the legacy tables (including the `evidence_search` index).+ (§4);+3. **vectors**: for the active embedding profile, renames every+ `one_memory_<old hash>…` collection to the current `memhub_<hash>…` name+ through Chroma's public client. A current collection that already holds+ writes is merged in first (newer record wins on a shared id); counts are+ checked after each step;+4. **verify**: opens the public SDK client exactly as the Runtime will and reads+ the legacy confirmed memory ids back (`list_memories`, then `get`). Every+ chat memory must read back. Coding/Working may be fewer, because the SDK's+ Coding reconciler deletes experiences it retires, but not zero when the+ legacy mirror has some. Otherwise the run stops with+ `sdk_migration_memory_unreadable` and the counts, before anything+ irreversible; legacy authority and tables stay intact;+5. **cutover**: re-verifies the bundle, repeats §4, commits SDK authority;+6. **cleanup**: drops the legacy tables (including the `evidence_search`+ index) and runs `VACUUM` (skipped if the disk is too full).++A home with legacy memories but no active model profile is not migrated+(`sdk_migration_model_profile_required`): its collections can be neither named+nor read back.++A home already on SDK authority still reports `required` while legacy-named+vector collections exist for its profile (build 20 homes). `sdk-migrate` then+reattaches them and reads back against the memory ids in the pre-cutover+bundle; that report is recorded but does not block, as nothing irreversible is+left. Runtime code never renames or reads Chroma directly.With `--json` each step prints `{"state":"running","step":…}` and the last lineis the result: `cutover`, `complete` (only cleanup was left), `not_required`, or@@ -148,6 +179,12 @@ The release gate covers:- CLI upgrade migrating before restart, rolling back on a failed migration,and keeping the new version when a migrated home is slow to come up;- host capture fenced for the whole command;+- legacy-named vector collections reattached (with merge) before verifying,+ and on a home that already cut over;+- readback refusing a cutover the new Runtime cannot read, and tolerating+ retired Coding experiences;+- `/api/v2/memory-authority` agreeing with the API gates on fresh, migrated+ and legacy homes;- pending job freezing, legacy task and pending dispatch conversion;- invoked/unknown legacy tasks and pending deletions not blocking cutover;- interrupted directory swap recovery before and after authority;