Skip to content
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.py
index 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: E402
import json # noqa: E402
-from collections.abc import Sequence # noqa: E402
+import re # noqa: E402
+from collections.abc import Iterator, Sequence # noqa: E402
from typing import TextIO # noqa: E402
from one_memory.config import load_settings # noqa: E402
from 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 1
document = {
"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 message
in {
"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 = None
async 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.py
index 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 Path
import pytest
PRIMARY_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.py
new file mode 100644
index 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")