clm-kernel 0.0.0__py3-none-any.whl

clm/layer0/utils.py

@@ -0,0 +1,886 @@
+"""Shared utility functions and helpers for the CLM Python implementation.
+
+This module consolidates common routines for path resolution, hashing,
+environment checks, and system capabilities to avoid code duplication
+and improve maintainability.
+
+Hash function upgradeability (INV-02):
+    All content hashing routes through ``clm_hash_string`` / ``clm_hash_file``.
+    SHA-256 is the current default, but the system is designed to be
+    algorithm-agnostic. Stored hash values carry an algorithm prefix
+    (e.g. ``sha256:<hex>``) so multiple algorithms can coexist.
+    To switch algorithms, change ``HASH_PREFIX`` and the implementation
+    of ``clm_hash_string`` — all call sites will pick up the change.
+"""
+
+import contextlib
+import enum
+import hashlib
+import os
+import platform
+import sys
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+from clm.cross_cutting.clm_logger import get_logger
+
+_logger = get_logger("clm.utils")
+
+
+def normalize_line_endings_bytes(content: bytes) -> bytes:
+    """Normalize CRLF or CR line endings to LF in bytes."""
+    return content.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+
+def normalize_line_endings_str(content: str) -> str:
+    """Normalize CRLF or CR line endings to LF in string."""
+    return content.replace("\r\n", "\n").replace("\r", "\n")
+
+# ── Hash function infrastructure (INV-02: upgradable hash function) ────────
+
+BLAKE3_HASH_PREFIX: str = "blake3:"
+SHA256_HASH_PREFIX: str = "sha256:"
+
+#: Default algorithm prefix for stored hash values.
+DEFAULT_HASH_PREFIX: str = BLAKE3_HASH_PREFIX
+HASH_PREFIX: str = DEFAULT_HASH_PREFIX
+
+#: Default collision threshold before triggering an algorithm upgrade.
+DEFAULT_COLLISION_THRESHOLD: int = 2
+
+
+# ── HashProvider protocol (Step 2: provider registry) ──────────────────────
+
+
+@runtime_checkable
+class HashProvider(Protocol):
+    """Protocol for pluggable content-hash algorithms."""
+
+    def hash(self, content: bytes) -> str:
+        """Compute the raw hex digest of content."""
+        ...
+
+    def prefix(self) -> str:
+        """Algorithm prefix (e.g. 'sha256:')."""
+        ...
+
+
+# ── Zero-dependency pure Python BLAKE3 engine (INV-02 fallback) ─────────
+_B3_IV = (
+    0x6A09E667, 0xBB67AE85, 0x3C6EF372, 0xA54FF53A,
+    0x510E527F, 0x9B05688C, 0x1F83D9AB, 0x5BE0CD19,
+)
+_B3_MSG_PERM = (2, 6, 3, 10, 7, 0, 4, 13, 1, 11, 12, 5, 9, 14, 15, 8)
+_B3_CHUNK_START, _B3_CHUNK_END, _B3_PARENT, _B3_ROOT = 1, 2, 4, 8
+
+def _b3_rotr(w: int, r: int) -> int:
+    return ((w >> r) | (w << (32 - r))) & 0xFFFFFFFF
+
+def _b3_g(s: list, a: int, b: int, c: int, d: int, mx: int, my: int) -> None:
+    s[a] = (s[a] + s[b] + mx) & 0xFFFFFFFF
+    s[d] = _b3_rotr(s[d] ^ s[a], 16)
+    s[c] = (s[c] + s[d]) & 0xFFFFFFFF
+    s[b] = _b3_rotr(s[b] ^ s[c], 12)
+    s[a] = (s[a] + s[b] + my) & 0xFFFFFFFF
+    s[d] = _b3_rotr(s[d] ^ s[a], 8)
+    s[c] = (s[c] + s[d]) & 0xFFFFFFFF
+    s[b] = _b3_rotr(s[b] ^ s[c], 7)
+
+def _b3_round(s: list, m: list) -> None:
+    _b3_g(s, 0, 4, 8, 12, m[0], m[1])
+    _b3_g(s, 1, 5, 9, 13, m[2], m[3])
+    _b3_g(s, 2, 6, 10, 14, m[4], m[5])
+    _b3_g(s, 3, 7, 11, 15, m[6], m[7])
+    _b3_g(s, 0, 5, 10, 15, m[8], m[9])
+    _b3_g(s, 1, 6, 11, 12, m[10], m[11])
+    _b3_g(s, 2, 7, 8, 13, m[12], m[13])
+    _b3_g(s, 3, 4, 9, 14, m[14], m[15])
+
+def _b3_compress(cv: list, block_words: list, block_len: int, counter: int, flags: int) -> list:
+    s = list(cv) + list(_B3_IV[:4]) + [counter & 0xFFFFFFFF, (counter >> 32) & 0xFFFFFFFF, block_len, flags]
+    m = list(block_words)
+    for r in range(7):
+        _b3_round(s, m)
+        if r < 6:
+            m = [m[_B3_MSG_PERM[i]] for i in range(16)]
+    out = [0] * 16
+    for i in range(8):
+        out[i] = (s[i] ^ s[i + 8]) & 0xFFFFFFFF
+        out[i + 8] = (s[i + 8] ^ cv[i]) & 0xFFFFFFFF
+    return out
+
+def _b3_words_from_bytes(b: bytearray) -> list:
+    words = [0] * 16
+    for i in range(min(16, (len(b) + 3) // 4)):
+        chunk = b[i*4 : (i+1)*4]
+        words[i] = int.from_bytes(chunk, "little")
+    return words
+
+def _b3_words_to_hex(words: list) -> str:
+    import struct
+    return "".join(struct.pack("<I", w).hex() for w in words)
+
+class _B3ChunkState:
+    def __init__(self, counter: int, flags: int = 0):
+        self.cv = list(_B3_IV)
+        self.counter = counter
+        self.flags = flags
+        self.block = bytearray()
+        self.blocks_compressed = 0
+
+    def start_flag(self) -> int:
+        return _B3_CHUNK_START if self.blocks_compressed == 0 else 0
+
+    def update(self, data: bytes) -> None:
+        offset = 0
+        while offset < len(data):
+            if len(self.block) == 64:
+                words = _b3_words_from_bytes(self.block)
+                out = _b3_compress(self.cv, words, 64, self.counter, self.flags | self.start_flag())
+                self.cv = out[:8]
+                self.blocks_compressed += 1
+                self.block = bytearray()
+            take = min(64 - len(self.block), len(data) - offset)
+            self.block.extend(data[offset : offset + take])
+            offset += take
+
+    def output(self, is_root: bool = False) -> list:
+        words = _b3_words_from_bytes(self.block)
+        flags = self.flags | self.start_flag() | _B3_CHUNK_END
+        if is_root:
+            flags |= _B3_ROOT
+        return _b3_compress(self.cv, words, len(self.block), self.counter, flags)
+
+def _b3_parent_output(left_cv: list, right_cv: list, is_root: bool = False) -> list:
+    block_words = left_cv[:8] + right_cv[:8]
+    flags = _B3_PARENT
+    if is_root:
+        flags |= _B3_ROOT
+    return _b3_compress(_B3_IV, block_words, 64, 0, flags)
+
+def pure_python_blake3(data: bytes) -> str:
+    """Zero-dependency pure Python BLAKE3 hash computation."""
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+    if len(data) <= 1024:
+        c = _B3ChunkState(0, 0)
+        c.update(data)
+        return _b3_words_to_hex(c.output(True)[:8])
+
+    stack = []
+    chunk_counter = 0
+    offset = 0
+    while offset + 1024 < len(data):
+        chunk_bytes = data[offset : offset + 1024]
+        c = _B3ChunkState(chunk_counter, 0)
+        c.update(chunk_bytes)
+        chunk_cv = c.output(False)[:8]
+        chunk_counter += 1
+        offset += 1024
+
+        total = chunk_counter
+        while (total & 1) == 0:
+            left_cv = stack.pop()
+            chunk_cv = _b3_parent_output(left_cv, chunk_cv, False)[:8]
+            total >>= 1
+        stack.append(chunk_cv)
+
+    final = _B3ChunkState(chunk_counter, 0)
+    final.update(data[offset:])
+    out = final.output(len(stack) == 0)[:8]
+    if len(stack) == 0:
+        return _b3_words_to_hex(out)
+
+    while stack:
+        left = stack.pop()
+        is_root = (len(stack) == 0)
+        out = _b3_parent_output(left, out, is_root)[:8]
+    return _b3_words_to_hex(out)
+
+
+class Blake3Provider:
+    """BLAKE3 hash provider (default active algorithm under INV-02)."""
+
+    def hash(self, content: bytes) -> str:
+        try:
+            import blake3  # type: ignore
+            return blake3.blake3(content).hexdigest()
+        except ImportError:
+            pass
+
+        # Try native clm_rust_core binary
+        candidates = [
+            os.environ.get("CLM_RUST_CORE_BIN"),
+            os.path.join(os.path.dirname(__file__), "../../../clm_rust_core/target/release/clm_rust_core"),
+            os.path.join(os.path.dirname(__file__), "../../../clm_rust_core/target/debug/clm_rust_core"),
+            os.path.join(os.path.dirname(__file__), "../../../../kernel/clm_rust_core/target/debug/clm_rust_core"),
+            "clm_rust_core",
+            "b3sum",
+        ]
+        if os.environ.get("CLM_ZERO_FS", "").lower() == "true":
+            return pure_python_blake3(content)
+
+        for bin_path in candidates:
+            if not bin_path:
+                continue
+            try:
+                import subprocess
+                cmd = [bin_path, "hash"] if "clm_rust_core" in bin_path else [bin_path, "--no-names"]
+                proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+                stdout, _ = proc.communicate(input=content)
+                if proc.returncode == 0 and stdout:
+                    out = stdout.decode("utf-8").strip()
+                    if out:
+                        return out.split()[0]
+            except Exception:
+                continue
+
+        # Zero-dependency pure Python fallback (works in hermetic sandboxes & temp mock roots)
+        return pure_python_blake3(content)
+
+    def prefix(self) -> str:
+        return BLAKE3_HASH_PREFIX
+
+
+class Sha256Provider:
+    """Default SHA-256 hash provider."""
+
+    def hash(self, content: bytes) -> str:
+        return hashlib.sha256(content).hexdigest()
+
+    def prefix(self) -> str:
+        return SHA256_HASH_PREFIX
+
+
+class Md5Provider:
+    """MD5 hash provider (weakest in the hierarchy, for legacy compatibility)."""
+
+    def hash(self, content: bytes) -> str:
+        return hashlib.md5(content).hexdigest()
+
+    def prefix(self) -> str:
+        return "md5:"
+
+
+class Sha1Provider:
+    """SHA-1 hash provider (legacy, for migration path compatibility)."""
+
+    def hash(self, content: bytes) -> str:
+        return hashlib.sha1(content).hexdigest()
+
+    def prefix(self) -> str:
+        return "sha1:"
+
+
+class Sha512Provider:
+    """SHA-512 hash provider (stronger than SHA-256)."""
+
+    def hash(self, content: bytes) -> str:
+        return hashlib.sha512(content).hexdigest()
+
+    def prefix(self) -> str:
+        return "sha512:"
+
+
+class Shake256Provider:
+    """Keccak SHAKE-256 provider with configurable output bit-length (custom-N).
+
+    Uses the SHAKE-256 extendable-output function (XOF) to produce a digest
+    of N bits. The prefix is ``custom-N:`` (e.g. ``custom-1024:``).
+    This provides future-proofing: if custom-N is exhausted, upgrade to
+    custom-2N by registering a new provider with doubled bit-length.
+    """
+
+    def __init__(self, bits: int) -> None:
+        self.bits = bits
+        self._prefix = f"custom-{bits}:"
+
+    def hash(self, content: bytes) -> str:
+        byte_len = (self.bits + 7) // 8
+        return hashlib.shake_256(content).hexdigest(byte_len)
+
+    def prefix(self) -> str:
+        return self._prefix
+
+
+# Algorithm strength hierarchy (weakest → strongest).
+STRENGTH_HIERARCHY: list[str] = [
+    "md5:",
+    "sha1:",
+    "sha256:",
+    "blake3:",
+    "sha512:",
+    "custom-1024:",
+]
+
+
+def next_stronger_algorithm(current: str) -> str:
+    """Recommend the next stronger algorithm in the hierarchy.
+
+    If the current algorithm is ``custom-N``, returns ``custom-2N``
+    (recursive doubling). If not in the hierarchy, returns ``blake3:``.
+    """
+    if current.startswith("custom-") and current.endswith(":"):
+        num_str = current[len("custom-"):-1]
+        try:
+            doubled = int(num_str) * 2
+            return f"custom-{doubled}:"
+        except ValueError:
+            pass
+    try:
+        pos = STRENGTH_HIERARCHY.index(current)
+        if pos + 1 < len(STRENGTH_HIERARCHY):
+            return STRENGTH_HIERARCHY[pos + 1]
+    except ValueError:
+        pass
+    return DEFAULT_HASH_PREFIX
+
+
+def register_custom_provider(bits: int) -> None:
+    """Register a custom-N (SHAKE-256) provider with the given bit-length."""
+    register_provider(Shake256Provider(bits))
+
+
+# Provider registry — maps algorithm prefix → provider instance
+_PROVIDER_REGISTRY: dict[str, HashProvider] = {}
+
+
+def register_provider(provider: HashProvider) -> None:
+    """Register a new hash provider under its algorithm prefix."""
+    _PROVIDER_REGISTRY[provider.prefix()] = provider
+
+
+def list_algorithms() -> list[str]:
+    """List all registered algorithm prefixes."""
+    return list(_PROVIDER_REGISTRY.keys())
+
+
+# Register the default providers at import time
+register_provider(Blake3Provider())
+register_provider(Sha256Provider())
+register_provider(Md5Provider())
+register_provider(Sha1Provider())
+register_provider(Sha512Provider())
+
+
+# ── Hash configuration policy (Step 4) ─────────────────────────────────────
+
+@dataclass
+class HashConfig:
+    """Configuration policy for hash algorithm selection and collision handling.
+
+    Attributes:
+        active_algorithm: Algorithm prefix for new content (e.g. 'blake3:').
+        collision_threshold: Number of collisions before triggering an upgrade.
+        fallback_order: Ordered list of fallback algorithm prefixes.
+    """
+    active_algorithm: str = BLAKE3_HASH_PREFIX
+    collision_threshold: int = DEFAULT_COLLISION_THRESHOLD
+    fallback_order: list[str] = field(default_factory=lambda: [BLAKE3_HASH_PREFIX, SHA256_HASH_PREFIX])
+
+
+def _load_hash_config() -> HashConfig:
+    """Load hash configuration from environment variables.
+
+    Checks ``CLM_HASH_CONFIG`` (format: ``active|threshold|fallback1,fallback2``).
+    If not present, checks ``CLM_HASH_ALGO`` or ``MCARD_HASH_ALGORITHM``.
+    Defaults to ``blake3:`` with fallback ``["blake3:", "sha256:"]``.
+    """
+    raw = os.environ.get("CLM_HASH_CONFIG", "")
+    if raw:
+        parts = raw.split("|", 2)
+        if len(parts) >= 2:
+            active = parts[0] if parts[0] else BLAKE3_HASH_PREFIX
+            if not active.endswith(":"):
+                active = f"{active}:"
+            try:
+                threshold = int(parts[1])
+            except ValueError:
+                threshold = DEFAULT_COLLISION_THRESHOLD
+            if len(parts) == 3 and parts[2]:
+                fallbacks = [s if s.endswith(":") else f"{s}:" for s in parts[2].split(",") if s]
+            else:
+                fallbacks = [active, SHA256_HASH_PREFIX]
+            return HashConfig(
+                active_algorithm=active,
+                collision_threshold=threshold,
+                fallback_order=fallbacks,
+            )
+
+    single_algo = os.environ.get("CLM_HASH_ALGO") or os.environ.get("MCARD_HASH_ALGORITHM")
+    if single_algo:
+        algo = single_algo.strip().lower()
+        if not algo.endswith(":"):
+            algo = f"{algo}:"
+        return HashConfig(
+            active_algorithm=algo,
+            collision_threshold=DEFAULT_COLLISION_THRESHOLD,
+            fallback_order=[algo, SHA256_HASH_PREFIX] if algo != SHA256_HASH_PREFIX else [SHA256_HASH_PREFIX],
+        )
+
+    return HashConfig()
+
+
+#: Global hash configuration, loaded once from environment.
+_HASH_CONFIG: HashConfig = _load_hash_config()
+
+
+def get_hash_config() -> HashConfig:
+    """Get the current hash configuration."""
+    return _HASH_CONFIG
+
+
+# ── Prefix-based dispatch (Step 3) ─────────────────────────────────────────
+
+def extract_hash_prefix(prefixed: str | bytes) -> str | None:
+    """Extract the algorithm prefix from a stored hash string.
+
+    Returns the prefix (including ':') or None if no prefix is found.
+    """
+    if isinstance(prefixed, bytes):
+        prefixed = prefixed.decode("utf-8", errors="replace")
+    pos = prefixed.find(":")
+    if pos >= 0:
+        return prefixed[: pos + 1]
+    return None
+
+
+def verify_hash(stored_hash: str | bytes, content: str | bytes) -> bool:
+    """Verify a stored hash against content by dispatching to the correct provider.
+
+    Parses the algorithm prefix from ``stored_hash``, looks up the
+    corresponding provider, and checks whether the content matches.
+
+    Returns True if the hash matches, False otherwise.
+    """
+    sh_str = stored_hash.decode("utf-8", errors="replace") if isinstance(stored_hash, bytes) else str(stored_hash)
+    ct_str = content.decode("utf-8", errors="replace") if isinstance(content, bytes) else str(content)
+    if ":" not in sh_str and ":" in ct_str:
+        stored_hash, content = content, stored_hash
+        sh_str, ct_str = ct_str, sh_str
+
+    prefix = extract_hash_prefix(stored_hash) or HASH_PREFIX
+    provider = _PROVIDER_REGISTRY.get(prefix)
+    if provider is None:
+        _logger.warning(f"Unknown hash algorithm prefix: {prefix} (registered: {list_algorithms()})")
+        return False
+    content_bytes = content.encode("utf-8") if isinstance(content, str) else content
+    computed = provider.hash(content_bytes)
+    stored_raw = strip_hash_prefix(stored_hash)
+    return computed == stored_raw
+
+
+# ── Collision detection (Step 5) ───────────────────────────────────────────
+
+
+class CollisionCheckResult(enum.Enum):
+    """Result of a collision check."""
+    NO_COLLISION = "no_collision"
+    COLLISION = "collision"
+    THRESHOLD_EXCEEDED = "threshold_exceeded"
+
+
+def check_collision(
+    hash_value: str,
+    new_content: bytes,
+    existing_content: bytes | None,
+    collision_count: int = 0,
+) -> tuple[CollisionCheckResult, int]:
+    """Check whether a hash collision has occurred.
+
+    Callers should invoke this *before* inserting a new card into the database.
+    If ``existing_content`` is not None and differs from ``new_content``, a
+    collision is recorded. When the collision count reaches the configured
+    threshold, ``THRESHOLD_EXCEEDED`` is returned.
+
+    Returns a tuple of (result, new_collision_count).
+    """
+    if existing_content is None or existing_content == new_content:
+        return CollisionCheckResult.NO_COLLISION, collision_count
+
+    count = collision_count + 1
+    cfg = get_hash_config()
+    if count >= cfg.collision_threshold:
+        return CollisionCheckResult.THRESHOLD_EXCEEDED, count
+    return CollisionCheckResult.COLLISION, count
+
+
+def recommended_fallback_algorithm() -> str:
+    """Get the recommended fallback algorithm when threshold is exceeded."""
+    cfg = get_hash_config()
+    for algo in cfg.fallback_order:
+        if algo != cfg.active_algorithm and algo in _PROVIDER_REGISTRY:
+            return algo
+    return cfg.active_algorithm
+
+
+# ── Convenience functions ──────────────────────────────────────────────────
+
+
+def clm_hash_string(content: str | bytes) -> str:
+    """Compute the content hash of a string or bytes using the active provider.
+
+    Dispatches dynamically to the registered provider matching the active algorithm.
+    All call sites across the codebase route through this function.
+    """
+    content_bytes = content.encode("utf-8") if isinstance(content, str) else content
+    active = get_hash_config().active_algorithm
+    provider = _PROVIDER_REGISTRY.get(active)
+    if provider is not None:
+        return provider.hash(content_bytes)
+    return hashlib.sha256(content_bytes).hexdigest()
+
+
+def prefixed_hash(content: str | bytes) -> str:
+    """Compute the prefixed content hash (e.g. ``blake3:<hex>`` or ``sha256:<hex>``)."""
+    cfg = get_hash_config()
+    provider = _PROVIDER_REGISTRY.get(cfg.active_algorithm)
+    pfx = provider.prefix() if provider is not None else HASH_PREFIX
+    return f"{pfx}{clm_hash_string(content)}"
+
+
+def prefixed_hash_raw(raw_hex: str) -> str:
+    """Prepend the active algorithm prefix to an already-computed raw hex digest."""
+    cfg = get_hash_config()
+    return f"{cfg.active_algorithm}{raw_hex}"
+
+
+def strip_hash_prefix(prefixed: str | bytes) -> str:
+    """Strip the algorithm prefix from a hash string.
+
+    If the hash starts with a known prefix (e.g. ``blake3:`` or ``sha256:``),
+    the unprefixed hex is returned. Otherwise the input is returned as-is.
+    """
+    if isinstance(prefixed, bytes):
+        prefixed = prefixed.decode("utf-8", errors="replace")
+    active = get_hash_config().active_algorithm
+    if prefixed.startswith(active):
+        return prefixed[len(active):]
+    if prefixed.startswith(DEFAULT_HASH_PREFIX):
+        return prefixed[len(DEFAULT_HASH_PREFIX):]
+    if prefixed.startswith(SHA256_HASH_PREFIX):
+        return prefixed[len(SHA256_HASH_PREFIX):]
+    # Generic fallback: strip any ``<algo>:`` prefix
+    if ":" in prefixed:
+        return prefixed.split(":", 1)[1]
+    return prefixed
+
+def clm_hash_file(filepath: str) -> str:
+    """Compute the content hash of a file after normalizing line endings."""
+    if not os.path.exists(filepath):
+        return ""
+    with open(filepath, "rb") as f:
+        raw = f.read()
+    normalized = normalize_line_endings_bytes(raw)
+    return clm_hash_string(normalized)
+
+
+# ── Content-equivalence operator (Gap 2) ──────────────────────────────────
+
+
+def content_equivalent(db_path: str, hash_a: str, hash_b: str) -> bool:
+    """Check whether two hashes point to the same content in the CAS.
+
+    This is the Python equivalent of the shell ``clm_content_equivalent`` operator.
+    Two hashes generated by different algorithms (e.g. ``sha256:abc`` and
+    ``sha512:def``) will never match as strings, but they may point to the same
+    underlying content. This function resolves both hashes to their stored
+    content and compares the raw bytes.
+
+    Returns ``True`` if both hashes exist and point to identical content,
+    ``False`` otherwise.
+    """
+    if hash_a == hash_b:
+        return True
+    import sqlite3
+    conn = sqlite3.connect(db_path)
+    try:
+        cursor = conn.cursor()
+        cursor.execute("SELECT content FROM card WHERE hash = ?", (hash_a,))
+        row_a = cursor.fetchone()
+        cursor.execute("SELECT content FROM card WHERE hash = ?", (hash_b,))
+        row_b = cursor.fetchone()
+        if row_a is None or row_b is None:
+            return False
+        return row_a[0] == row_b[0]
+    finally:
+        conn.close()
+
+
+# ── Handle migration lifecycle (Gap 3) ────────────────────────────────────
+
+
+def migrate_handle_hash(db_path: str, handle: str, target_algo: str) -> str:
+    """Migrate a handle to use a different hash algorithm.
+
+    This is the Python equivalent of the shell ``clm_migrate_handle_hash`` operator.
+    It resolves the handle to its current hash, retrieves the content from the
+    CAS, computes a new hash under the target algorithm, and transactionally
+    inserts the new card, records handle history, and updates the handle pointer.
+
+    Args:
+        db_path: Path to the content_memory SQLite database.
+        handle: The handle name to migrate (e.g. ``test:migration_handle``).
+        target_algo: Target algorithm prefix (e.g. ``sha256:``, ``sha512:``,
+            ``custom-1024:``). Must be a registered provider.
+
+    Returns:
+        The new hash string (with algorithm prefix).
+
+    Raises:
+        ValueError: If the handle is not found, content is missing, or the
+            target algorithm is not registered.
+    """
+    # Validate target algorithm
+    algo = target_algo.rstrip(":")
+    if algo not in _PROVIDER_REGISTRY and f"{algo}:" not in _PROVIDER_REGISTRY:
+        # Try with colon
+        if target_algo in _PROVIDER_REGISTRY:
+            algo = target_algo
+        else:
+            raise ValueError(
+                f"Unsupported target algorithm: '{target_algo}' "
+                f"(registered: {list_algorithms()})"
+            )
+
+    import sqlite3
+    from datetime import datetime, timezone
+
+    conn = sqlite3.connect(db_path)
+    try:
+        cursor = conn.cursor()
+
+        # 1. Resolve handle to get current hash
+        cursor.execute(
+            "SELECT current_hash FROM handle_registry WHERE handle = ?",
+            (handle,),
+        )
+        row = cursor.fetchone()
+        if row is None:
+            raise ValueError(f"Handle '{handle}' not found in handle_registry")
+        current_hash = row[0]
+
+        # 2. Retrieve existing content
+        cursor.execute(
+            "SELECT content FROM card WHERE hash = ?", (current_hash,)
+        )
+        row = cursor.fetchone()
+        if row is None:
+            raise ValueError(
+                f"Content not found in CAS for hash '{current_hash}'"
+            )
+        content = row[0]
+
+        # 3. Compute new hash under target algorithm
+        provider_key = target_algo if target_algo in _PROVIDER_REGISTRY else f"{algo}:"
+        provider = _PROVIDER_REGISTRY.get(provider_key)
+        if provider is None:
+            raise ValueError(f"Provider not found for algorithm '{target_algo}'")
+        new_raw_hash = provider.hash(content if isinstance(content, bytes) else content.encode("utf-8"))
+        new_hash = f"{provider.prefix()}{new_raw_hash}"
+
+        # 4. Transactional update with retry for WAL lock contention
+        now_utc = datetime.now(timezone.utc).isoformat()
+        g_time = f"{algo}|{now_utc}|UTC"
+
+        import time as _time
+        max_attempts = 3
+        last_err: Exception | None = None
+        for attempt in range(max_attempts):
+            try:
+                conn.execute("BEGIN TRANSACTION")
+                conn.execute(
+                    "INSERT OR IGNORE INTO card (hash, content, g_time) VALUES (?, ?, ?)",
+                    (new_hash, content, g_time),
+                )
+                conn.execute(
+                    "INSERT INTO handle_history (handle, previous_hash, changed_at) VALUES (?, ?, ?)",
+                    (handle, current_hash, now_utc),
+                )
+                conn.execute(
+                    "UPDATE handle_registry SET current_hash = ?, updated_at = ? WHERE handle = ?",
+                    (new_hash, now_utc, handle),
+                )
+                conn.execute("COMMIT")
+
+                _logger.info(
+                    f"migrate_handle_hash: migrated '{handle}' from {current_hash} to {new_hash}"
+                )
+                return new_hash
+            except Exception as retry_err:
+                last_err = retry_err
+                with contextlib.suppress(Exception):
+                    conn.execute("ROLLBACK")
+                if attempt + 1 < max_attempts:
+                    _time.sleep(0.2)
+
+        raise RuntimeError(
+            f"Transaction failed after {max_attempts} attempts: {last_err}"
+        )
+    finally:
+        conn.close()
+
+def resolve_clm_path(clm_root: str, ref: str) -> str:
+    """Resolve a relative CLM path referencing files/directories to absolute path."""
+    if not ref:
+        return ref
+    if os.path.isabs(ref):
+        return ref
+    if os.path.exists(ref):
+        return os.path.abspath(ref)
+
+    cand = os.path.join(clm_root, ref)
+    if os.path.exists(cand):
+        return os.path.abspath(cand)
+
+    project_root = os.path.dirname(clm_root)
+    cand = os.path.join(project_root, ref)
+    if os.path.exists(cand):
+        return os.path.abspath(cand)
+
+    if ref.startswith("clm/"):
+        stripped = ref[4:]
+        cand = os.path.join(clm_root, stripped)
+        if os.path.exists(cand):
+            return os.path.abspath(cand)
+
+    return ref
+
+def detect_host_os() -> str:
+    """Detect and return host OS platform in lowercase (linux, darwin, windows, etc.)."""
+    raw_os = platform.system().lower()
+    if "linux" in raw_os:
+        return "linux"
+    elif "darwin" in raw_os:
+        return "darwin"
+    elif "windows" in raw_os:
+        return "windows"
+    return "unknown"
+
+def is_docker_live(port: int) -> bool:
+    """Check if docker daemon is responsive and a service is open at localhost:port."""
+    if os.environ.get("CLM_ZERO_FS", "").lower() == "true":
+        return False
+    try:
+        import socket
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        s.settimeout(0.5)
+        s.connect(("127.0.0.1", port))
+        s.close()
+    except Exception:
+        return False
+    try:
+        import subprocess
+        proc = subprocess.Popen(["docker", "info"], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        try:
+            proc.communicate(timeout=2)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.communicate()
+            return False
+        if proc.returncode != 0:
+            return False
+    except Exception:
+        return False
+
+    if port == 9000:
+        try:
+            proc = subprocess.Popen(["docker", "exec", "minio_server", "mc", "alias", "list", "local"], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+            try:
+                proc.communicate(timeout=2)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                proc.communicate()
+                return False
+            return proc.returncode == 0
+        except Exception:
+            return False
+    elif port == 5001:
+        try:
+            proc = subprocess.Popen(["docker", "exec", "ipfs_host", "ipfs", "id"], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+            try:
+                proc.communicate(timeout=2)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                proc.communicate()
+                return False
+            return proc.returncode == 0
+        except Exception:
+            return False
+
+    return True
+
+def get_bash_command() -> str:
+    """Resolve the bash executable path on the current platform, preferring Git Bash on Windows."""
+    if sys.platform == "win32":
+        bash_env = os.environ.get("BASH")
+        if bash_env and os.path.exists(bash_env):
+            return bash_env
+        git_bash = r"C:\Program Files\Git\bin\bash.exe"
+        if os.path.exists(git_bash):
+            return git_bash
+    return "bash"
+
+
+def verify_file_hash(filepath: str, expected_hash: str) -> bytes:
+    """Read a file, normalize line endings, verify SHA-256, and return normalized content."""
+    if not os.path.exists(filepath):
+        sys.exit(f"FATAL: Manifest missing at {filepath}")
+
+    with open(filepath, "rb") as fh:
+        raw = fh.read()
+
+    normalized = normalize_line_endings_bytes(raw)
+    computed = hashlib.sha256(normalized).hexdigest()
+
+    if computed != expected_hash:
+        _logger.error("  INTEGRITY FAILURE: file content has changed")
+        _logger.error(f"  Expected: {expected_hash}")
+        _logger.error(f"  Actual:   {computed}")
+        sys.exit(1)
+
+    return normalized
+
+
+def extract_python_script_from_yaml(normalized_content: bytes) -> str:
+    """Extract the indented Python bootstrap script from a clmEval.yaml payload."""
+    lines = normalized_content.decode("utf-8").splitlines()
+    in_python_block = False
+    in_script = False
+    script_lines = []
+    indent_len = None
+
+    for line in lines:
+        stripped = line.strip()
+        if not in_python_block:
+            if stripped == "- type: python":
+                in_python_block = True
+        else:
+            if stripped.startswith("- type:"):
+                break
+            if stripped.startswith("balanced_exp:"):
+                break
+            if not in_script:
+                if stripped.startswith("script:"):
+                    in_script = True
+            else:
+                if line:
+                    leading_spaces = len(line) - len(line.lstrip(' '))
+                    if indent_len is None:
+                        indent_len = leading_spaces
+                    if leading_spaces < indent_len:
+                        break
+                if indent_len is not None:
+                    if len(line) >= indent_len:
+                        script_lines.append(line[indent_len:])
+                    else:
+                        script_lines.append("")
+                else:
+                    if len(line) >= 8:
+                        script_lines.append(line[8:])
+                    else:
+                        script_lines.append("")
+
+    if not script_lines:
+        sys.exit("FATAL: Could not extract Python bootstrap script.")
+
+    return "\n".join(script_lines)