Python
fix(memhub): name the migration failure instead of one opaque code
kristinhe82044d61725e
diff --git a/memhub/apps/core/src/one_memory/cli.py b/memhub/apps/core/src/one_memory/cli.pyindex ed9b6d6..67cae2d 100644--- a/memhub/apps/core/src/one_memory/cli.py+++ b/memhub/apps/core/src/one_memory/cli.py@@ -31,13 +31,60 @@ def _end_by(seconds: str | None) -> None:if __name__ == "__main__" and sys.argv[1:2] == ["capture"]:_end_by(os.environ.get("ONE_MEMORY_CAPTURE_DEADLINE_S"))+import errno # noqa: E402import json # noqa: E402-from collections.abc import Sequence # noqa: E402+import re # noqa: E402+from collections.abc import Iterator, Sequence # noqa: E402from typing import TextIO # noqa: E402from one_memory.config import load_settings # noqa: E402from one_memory.runtime_client import RuntimeStatus, inspect_runtime # noqa: E402+# A single `sdk_migration_backfill_failed` told the person nothing: running out+# of disk, a model that was never configured, and a Coding/Working-Fact gap are+# three different next steps, and the startup dialog can only act on the name it+# is given. These are the names that reach it.+_SAFE_MIGRATION_CODE = re.compile(r"^[a-z][a-z0-9_]{0,95}$")+_OUT_OF_SPACE = frozenset({errno.ENOSPC, getattr(errno, "EDQUOT", errno.ENOSPC)})+++def _exception_chain(error: BaseException) -> Iterator[BaseException]:+ seen: set[int] = set()+ current: BaseException | None = error+ while current is not None and id(current) not in seen:+ seen.add(id(current))+ yield current+ current = current.__cause__ or current.__context__+++def migration_failure_code(+ error: BaseException, *, fallback: str = "sdk_migration_backfill_failed"+) -> str:+ """Name a migration failure; never guess a code from free text.++ Errs toward the caller's generic code: an exception this does not recognize+ keeps its message out of the document Desktop reads.+ """+ chain = list(_exception_chain(error))+ for item in chain:+ if isinstance(item, OSError) and item.errno in _OUT_OF_SPACE:+ return "sdk_migration_disk_space_insufficient"+ for item in chain:+ code = getattr(item, "code", "")+ if not isinstance(code, str) or not _SAFE_MIGRATION_CODE.match(code):+ continue+ if code.startswith(("sdk_data_plane_", "sdk_migration_")):+ return code+ if code.startswith("hy_sdk_productivity_"):+ # The Coding inventory could not be read or classified; that is a+ # data-shape problem the person cannot fix by retrying.+ return "sdk_migration_coding_inventory_failed"+ if code == "hy_sdk_memory_import_failed" and any(+ "working_fact" in str(part) for part in chain+ ):+ return "sdk_migration_working_fact_conflict"+ return fallback+def main() -> None:if sys.argv[1:] == ["--keychain-read"]:@@ -345,9 +392,16 @@ def migration_bundle(options: Sequence[str], stream: TextIO) -> int:document = {"schema_version": 1,"state": "failed",- "code": error.code,+ "code": migration_failure_code(error, fallback=error.code),}- _write_restore(stream, as_json, document, f"迁移备份失败:{error.code}")+ _write_restore(stream, as_json, document, f"迁移备份失败:{document['code']}")+ return 1+ except OSError as error:+ # A full disk while copying is the most common first-launch failure and+ # the only one the person fixes by deleting something.+ code = migration_failure_code(error, fallback="sdk_migration_bundle_copy_failed")+ document = {"schema_version": 1, "state": "failed", "code": code}+ _write_restore(stream, as_json, document, f"迁移备份失败:{code}")return 1document = {"schema_version": 1,@@ -461,14 +515,15 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:except SecretStoreUnavailableError:code = "secure_storage_unavailable"except Exception as error:+ message = str(error)code = (- str(error)- if str(error)+ message+ if messagein {"model_profile_not_active","model_secret_unavailable",}- else "sdk_migration_preflight_failed"+ else migration_failure_code(error, fallback="sdk_migration_preflight_failed"))else:namespace_fingerprint = hashlib.sha256(HY_MEMORY_NAMESPACE.encode()).hexdigest()@@ -497,8 +552,8 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:paths=staging,database_path=database,)- except Exception:- code = "sdk_migration_staging_failed"+ except Exception as error:+ code = migration_failure_code(error, fallback="sdk_migration_staging_failed")staging_data_dir = Noneasync def run_backfill() -> BackfillResult:@@ -525,13 +580,9 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:await asyncio.to_thread(lease.close)try:- result = (- asyncio.run(run_backfill())- if staging_data_dir is not None- else None- )- except Exception:- code = "sdk_migration_backfill_failed"+ result = asyncio.run(run_backfill()) if staging_data_dir is not None else None+ except Exception as error:+ code = migration_failure_code(error)else:if result is None:document = {"schema_version": 1, "state": "failed", "code": code}@@ -708,18 +759,11 @@ def sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:migration_id=marker.migration_id,namespace=HY_MEMORY_NAMESPACE,)- staging_cleanup = (- staging.protective_root.exists()- or staging.staging_home.exists()- )+ staging_cleanup = staging.protective_root.exists() or staging.staging_home.exists()document = {"schema_version": 1,"authority": "sdk",- "state": (- "cleanup_required"- if legacy_tables or staging_cleanup- else "complete"- ),+ "state": ("cleanup_required" if legacy_tables or staging_cleanup else "complete"),"migration_id": marker.migration_id if marker else None,"generation": generation,"legacy_tables": list(legacy_tables),@@ -759,9 +803,7 @@ def sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:"authority": "legacy","state": "required" if any(counts.values()) else "empty","migration_id": (- str(active_migration["migration_id"])- if active_migration is not None- else None+ str(active_migration["migration_id"]) if active_migration is not None else None),"bundle_id": (str(active_migration["backup_bundle_id"])diff --git a/memhub/apps/core/tests/core_test_classification.py b/memhub/apps/core/tests/core_test_classification.pyindex abfb775..c24f9a4 100644--- a/memhub/apps/core/tests/core_test_classification.py+++ b/memhub/apps/core/tests/core_test_classification.py@@ -14,13 +14,14 @@ from pathlib import Pathimport pytestPRIMARY_MARKERS = ("unit", "contract", "integration", "performance", "live")-EXPECTED_TEST_FILE_COUNT = 322-EXPECTED_TEST_FILES_SHA256 = "d242783adb4015ebdbb5c099f3b5aa88a99c828ca6fddc8ca8d6c74c56e48945"+EXPECTED_TEST_FILE_COUNT = 323+EXPECTED_TEST_FILES_SHA256 = "10a2327bd047a281511980f5b558c1ea64d857f0fff550e4bd96cb53800205ba"# Pure transformations, validation models, parity checks and state machines.# This list is intentionally small: uncertain files default to contract.UNIT_FILES = frozenset({+ "test_cli_migration_error_codes.py","test_context_v2_contract_parity.py","test_daemon_contract.py","test_diagnostic_payload_keys.py",diff --git a/memhub/apps/core/tests/test_cli_migration_error_codes.py b/memhub/apps/core/tests/test_cli_migration_error_codes.pynew file mode 100644index 0000000..f7a6874--- /dev/null+++ b/memhub/apps/core/tests/test_cli_migration_error_codes.py@@ -0,0 +1,115 @@+"""The startup dialog can only act on the code it is handed.++`sdk_migration_backfill_failed` covered a full disk, a missing model profile and+a Coding classification gap alike, so every one of them reached the person as+the same unactionable sentence. These tests pin the names that replace it.+"""++from __future__ import annotations++import errno+from pathlib import Path++import pytest++from one_memory.cli import migration_failure_code+++class _Coded(RuntimeError):+ def __init__(self, code: str) -> None:+ super().__init__(code)+ self.code = code+++def test_running_out_of_disk_is_named_however_deep_it_is_wrapped() -> None:+ error = OSError(errno.ENOSPC, "No space left on device")+ wrapped: BaseException = error+ for _ in range(3):+ try:+ raise RuntimeError("wrapper") from wrapped+ except RuntimeError as caught:+ wrapped = caught++ assert migration_failure_code(wrapped) == "sdk_migration_disk_space_insufficient"+ # The explicit context chain counts too: `raise ... from None` discards the+ # cause but Python still keeps the original as __context__.+ try:+ try:+ raise OSError(errno.ENOSPC, "No space left on device")+ except OSError:+ raise RuntimeError("sdk_snapshot_failed") from None+ except RuntimeError as caught:+ assert migration_failure_code(caught) == "sdk_migration_disk_space_insufficient"+++def test_quota_exhaustion_counts_as_no_space(tmp_path: Path) -> None:+ quota = getattr(errno, "EDQUOT", errno.ENOSPC)+ assert (+ migration_failure_code(OSError(quota, "Disk quota exceeded"))+ == "sdk_migration_disk_space_insufficient"+ )+++def test_a_coding_inventory_gap_is_not_reported_as_a_generic_failure() -> None:+ assert (+ migration_failure_code(_Coded("hy_sdk_productivity_variant_invalid"))+ == "sdk_migration_coding_inventory_failed"+ )+++def test_the_legacy_working_fact_failure_keeps_its_own_name() -> None:+ error = _Coded("hy_sdk_memory_import_failed")+ error.__cause__ = ValueError("Invalid memory layer: working_fact")++ assert migration_failure_code(error) == "sdk_migration_working_fact_conflict"+++def test_migration_state_codes_pass_through_because_they_are_already_actionable() -> None:+ assert (+ migration_failure_code(_Coded("sdk_data_plane_migration_item_conflict"))+ == "sdk_data_plane_migration_item_conflict"+ )+ assert (+ migration_failure_code(_Coded("sdk_migration_staging_invalid"))+ == "sdk_migration_staging_invalid"+ )+++def test_unknown_failures_keep_their_message_out_of_the_code() -> None:+ error = RuntimeError("/Users/someone/private/path blew up")+ assert migration_failure_code(error) == "sdk_migration_backfill_failed"+ assert (+ migration_failure_code(error, fallback="sdk_migration_preflight_failed")+ == "sdk_migration_preflight_failed"+ )+++def test_a_non_code_attribute_never_becomes_a_code() -> None:+ class Odd(RuntimeError):+ code = 17++ assert migration_failure_code(Odd("x")) == "sdk_migration_backfill_failed"+++def test_the_chain_survives_a_cycle() -> None:+ first = RuntimeError("first")+ second = RuntimeError("second")+ first.__cause__ = second+ second.__cause__ = first++ assert migration_failure_code(first) == "sdk_migration_backfill_failed"+++ "code",+ [+ "sdk_migration_disk_space_insufficient",+ "sdk_migration_working_fact_conflict",+ "sdk_migration_coding_inventory_failed",+ ],+)+def test_the_codes_the_desktop_translates_stay_in_sync(code: str) -> None:+ """Desktop maps these exact names to sentences; renaming one blinds it."""+ desktop = Path(__file__).resolve().parents[2] / "desktop" / "src" / "stable-runtime.ts"+ assert desktop.is_file(), desktop+ assert f'"{code}"' in desktop.read_text(encoding="utf-8")