msdev 0.9.0__py3-none-any.whl

msdev/core/inventory.py

@@ -0,0 +1,1390 @@
+"""Node-local model artifact and replica inventory."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import socket
+import sqlite3
+import uuid
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterable, Iterator
+
+from .limits import (
+    MAX_INVENTORY_ALIASES_PER_ARTIFACT,
+    MAX_INVENTORY_ARTIFACTS,
+    MAX_INVENTORY_CONTENT_BYTES,
+    MAX_INVENTORY_REPLICAS_PER_ARTIFACT,
+    MAX_INVENTORY_TAGS_PER_ARTIFACT,
+    MAX_INVENTORY_TOTAL_ALIASES,
+    MAX_INVENTORY_TOTAL_REPLICAS,
+    MAX_INVENTORY_TOTAL_TAGS,
+    MAX_ROOT_MAP_PATH_BYTES,
+    MAX_ROOT_MAPS,
+)
+
+
+SCHEMA_VERSION = 1
+_DISCOVERY_SKIP_DIRS = {
+    ".git",
+    "__pycache__",
+    "node_modules",
+    "site-packages",
+    "venv",
+    ".venv",
+}
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class Inventory:
+    """SQLite inventory owned by one user-level daemon."""
+
+    def __init__(self, data_dir: Path):
+        self.data_dir = data_dir.expanduser()
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        self.db_path = self.data_dir / "inventory.db"
+        self.node_id = self._load_node_id()
+        self._initialize()
+
+    def _load_node_id(self) -> str:
+        path = self.data_dir / "node-id"
+        if path.exists():
+            value = path.read_text(encoding="utf-8").strip()
+            if value:
+                return value
+        value = f"{socket.gethostname()}-{uuid.uuid4().hex[:12]}"
+        path.write_text(value + "\n", encoding="utf-8")
+        os.chmod(path, 0o600)
+        return value
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA foreign_keys = ON")
+        conn.execute("PRAGMA journal_mode = WAL")
+        return conn
+
+    @contextmanager
+    def _connection(self) -> Iterator[sqlite3.Connection]:
+        conn = self._connect()
+        try:
+            with conn:
+                yield conn
+        finally:
+            conn.close()
+
+    def _initialize(self) -> None:
+        with self._connection() as conn:
+            conn.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS artifacts (
+                    id INTEGER PRIMARY KEY,
+                    ref TEXT NOT NULL UNIQUE,
+                    revision TEXT,
+                    variant TEXT,
+                    format TEXT,
+                    manifest_digest TEXT,
+                    metadata_json TEXT NOT NULL DEFAULT '{}',
+                    created_at TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                );
+
+                CREATE TABLE IF NOT EXISTS replicas (
+                    id INTEGER PRIMARY KEY,
+                    artifact_id INTEGER NOT NULL REFERENCES artifacts(id) ON DELETE CASCADE,
+                    node_id TEXT NOT NULL,
+                    path TEXT NOT NULL,
+                    scope TEXT NOT NULL,
+                    management TEXT NOT NULL,
+                    state TEXT NOT NULL,
+                    verification_level TEXT NOT NULL,
+                    size_bytes INTEGER NOT NULL DEFAULT 0,
+                    file_count INTEGER NOT NULL DEFAULT 0,
+                    last_seen TEXT NOT NULL,
+                    UNIQUE(node_id, path)
+                );
+                """
+            )
+            artifact_columns = {
+                row["name"]
+                for row in conn.execute("PRAGMA table_info(artifacts)").fetchall()
+            }
+            if "description" not in artifact_columns:
+                conn.execute("ALTER TABLE artifacts ADD COLUMN description TEXT")
+            if "deleted_at" not in artifact_columns:
+                conn.execute("ALTER TABLE artifacts ADD COLUMN deleted_at TEXT")
+            conn.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS artifact_aliases (
+                    artifact_id INTEGER NOT NULL REFERENCES artifacts(id) ON DELETE CASCADE,
+                    alias TEXT NOT NULL UNIQUE,
+                    PRIMARY KEY (artifact_id, alias)
+                );
+
+                CREATE TABLE IF NOT EXISTS artifact_tags (
+                    artifact_id INTEGER NOT NULL REFERENCES artifacts(id) ON DELETE CASCADE,
+                    tag TEXT NOT NULL,
+                    PRIMARY KEY (artifact_id, tag)
+                );
+
+                CREATE TABLE IF NOT EXISTS audit_log (
+                    id INTEGER PRIMARY KEY,
+                    action TEXT NOT NULL,
+                    ref TEXT,
+                    details_json TEXT NOT NULL DEFAULT '{}',
+                    created_at TEXT NOT NULL
+                );
+                """
+            )
+
+    @staticmethod
+    def _audit(
+        conn: sqlite3.Connection,
+        action: str,
+        ref: str | None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        conn.execute(
+            """
+            INSERT INTO audit_log (action, ref, details_json, created_at)
+            VALUES (?, ?, ?, ?)
+            """,
+            (
+                action,
+                ref,
+                json.dumps(details or {}, ensure_ascii=False, sort_keys=True),
+                _utc_now(),
+            ),
+        )
+
+    @staticmethod
+    def _artifact_row(
+        conn: sqlite3.Connection,
+        ref_or_alias: str,
+    ) -> sqlite3.Row:
+        row = conn.execute(
+            "SELECT * FROM artifacts WHERE ref = ?",
+            (ref_or_alias,),
+        ).fetchone()
+        if row is None:
+            row = conn.execute(
+                """
+                SELECT a.*
+                FROM artifacts a
+                JOIN artifact_aliases x ON x.artifact_id = a.id
+                WHERE x.alias = ?
+                """,
+                (ref_or_alias,),
+            ).fetchone()
+        if row is None:
+            raise KeyError(f"unknown model: {ref_or_alias}")
+        return row
+
+    @staticmethod
+    def _file_digest(path: Path, hasher: Any) -> None:
+        with path.open("rb") as handle:
+            while chunk := handle.read(8 * 1024 * 1024):
+                hasher.update(chunk)
+
+    @classmethod
+    def scan_path(cls, path: Path, full_checksum: bool = False) -> dict[str, Any]:
+        resolved = path.expanduser().resolve(strict=True)
+        files: list[tuple[str, Path]] = []
+        if resolved.is_file():
+            files.append((resolved.name, resolved))
+        elif resolved.is_dir():
+            for child in resolved.rglob("*"):
+                if child.is_file():
+                    files.append((child.relative_to(resolved).as_posix(), child))
+        else:
+            raise ValueError(f"model path must be a file or directory: {resolved}")
+
+        files.sort(key=lambda item: item[0])
+        metadata_hasher = hashlib.sha256()
+        content_hasher = hashlib.sha256() if full_checksum else None
+        total_size = 0
+        for relative, file_path in files:
+            stat = file_path.stat()
+            total_size += stat.st_size
+            metadata_hasher.update(relative.encode("utf-8"))
+            metadata_hasher.update(b"\0")
+            metadata_hasher.update(str(stat.st_size).encode("ascii"))
+            metadata_hasher.update(b"\0")
+            metadata_hasher.update(str(stat.st_mtime_ns).encode("ascii"))
+            metadata_hasher.update(b"\n")
+            if content_hasher is not None:
+                content_hasher.update(relative.encode("utf-8"))
+                content_hasher.update(b"\0")
+                cls._file_digest(file_path, content_hasher)
+
+        return {
+            "path": str(resolved),
+            "size_bytes": total_size,
+            "file_count": len(files),
+            "metadata_digest": f"sha256:{metadata_hasher.hexdigest()}",
+            "content_digest": f"sha256:{content_hasher.hexdigest()}" if content_hasher else None,
+        }
+
+    @staticmethod
+    def _model_metadata(path: Path) -> tuple[str, dict[str, Any]] | None:
+        try:
+            files = [item for item in path.iterdir() if item.is_file()]
+        except (OSError, PermissionError):
+            return None
+        names = {item.name for item in files}
+        suffixes = {item.suffix.lower() for item in files}
+        has_config = "config.json" in names
+        has_adapter = "adapter_config.json" in names
+        has_safetensors = ".safetensors" in suffixes
+        has_bin = ".bin" in suffixes
+        has_gguf = ".gguf" in suffixes
+        has_index = bool(
+            {
+                "model.safetensors.index.json",
+                "pytorch_model.bin.index.json",
+            }
+            & names
+        )
+        if not (
+            (has_config and (has_safetensors or has_bin or has_gguf or has_index))
+            or (has_adapter and (has_safetensors or has_bin))
+            or has_gguf
+        ):
+            return None
+
+        if has_adapter:
+            format_name = "adapter-safetensors" if has_safetensors else "adapter-bin"
+        elif has_gguf:
+            format_name = "gguf"
+        elif has_safetensors or "model.safetensors.index.json" in names:
+            format_name = "huggingface-safetensors"
+        else:
+            format_name = "pytorch-bin"
+
+        config_name = "adapter_config.json" if has_adapter else "config.json"
+        config: dict[str, Any] = {}
+        config_path = path / config_name
+        if config_path.is_file() and config_path.stat().st_size <= 4 * 1024 * 1024:
+            try:
+                value = json.loads(config_path.read_text(encoding="utf-8"))
+                if isinstance(value, dict):
+                    config = value
+            except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+                pass
+        return format_name, config
+
+    @staticmethod
+    def _portable_structure(path: Path) -> dict[str, Any]:
+        hasher = hashlib.sha256()
+        total_size = 0
+        file_count = 0
+        for child in sorted(
+            (item for item in path.rglob("*") if item.is_file()),
+            key=lambda item: item.relative_to(path).as_posix(),
+        ):
+            try:
+                stat = child.stat()
+            except (OSError, FileNotFoundError):
+                continue
+            relative = child.relative_to(path).as_posix()
+            total_size += stat.st_size
+            file_count += 1
+            hasher.update(relative.encode("utf-8"))
+            hasher.update(b"\0")
+            hasher.update(str(stat.st_size).encode("ascii"))
+            hasher.update(b"\n")
+        return {
+            "structure_digest": f"sha256:{hasher.hexdigest()}",
+            "size_bytes": total_size,
+            "file_count": file_count,
+        }
+
+    @staticmethod
+    def _discovered_ref(
+        root: Path,
+        path: Path,
+        config: dict[str, Any],
+        structure_digest: str,
+        namespace: str,
+    ) -> str:
+        configured = config.get("_name_or_path")
+        if isinstance(configured, str) and configured and not Path(configured).is_absolute():
+            name = configured.removeprefix("model://")
+        else:
+            try:
+                name = path.relative_to(root).as_posix()
+            except ValueError:
+                name = path.name
+        components = []
+        for component in name.split("/"):
+            normalized = re.sub(r"[^A-Za-z0-9._-]+", "-", component).strip("-")
+            if normalized:
+                components.append(normalized)
+        safe_name = "/".join(components) or "model"
+        digest = structure_digest.removeprefix("sha256:")[:12]
+        return f"model://{namespace}/{safe_name}@{digest}"
+
+    def discover_models(
+        self,
+        *,
+        root: str,
+        max_depth: int = 5,
+        register: bool = False,
+        namespace: str = "discovered",
+    ) -> dict[str, Any]:
+        root_path = Path(root).expanduser().resolve(strict=True)
+        if not root_path.is_dir():
+            raise ValueError(f"discovery root must be a directory: {root_path}")
+        if not 0 <= max_depth <= 20:
+            raise ValueError("max_depth must be between 0 and 20")
+        if not re.fullmatch(r"[A-Za-z0-9._-]+", namespace):
+            raise ValueError("namespace may only contain letters, numbers, dot, underscore, and dash")
+
+        found: list[dict[str, Any]] = []
+        for current, dirs, _files in os.walk(root_path, followlinks=False):
+            current_path = Path(current)
+            depth = len(current_path.relative_to(root_path).parts)
+            dirs[:] = [
+                name
+                for name in dirs
+                if name not in _DISCOVERY_SKIP_DIRS
+                and not (current_path / name).is_symlink()
+            ]
+            if depth > max_depth:
+                dirs[:] = []
+                continue
+
+            detected = self._model_metadata(current_path)
+            if detected is None:
+                if depth == max_depth:
+                    dirs[:] = []
+                continue
+
+            format_name, config = detected
+            structure = self._portable_structure(current_path)
+            ref = self._discovered_ref(
+                root_path,
+                current_path,
+                config,
+                structure["structure_digest"],
+                namespace,
+            )
+            item = {
+                "ref": ref,
+                "path": str(current_path),
+                "format": format_name,
+                "size_bytes": structure["size_bytes"],
+                "file_count": structure["file_count"],
+                "structure_digest": structure["structure_digest"],
+                "model_type": config.get("model_type"),
+                "architectures": config.get("architectures"),
+                "registered": False,
+            }
+            if register:
+                registered = self.register_model(
+                    ref=ref,
+                    path=str(current_path),
+                    format_name=format_name,
+                    extra_metadata={
+                        "model_type": config.get("model_type"),
+                        "architectures": config.get("architectures"),
+                    },
+                )
+                item["registered"] = True
+                item["state"] = registered["replicas"][0]["state"]
+            found.append(item)
+            dirs[:] = []
+
+        return {
+            "root": str(root_path),
+            "max_depth": max_depth,
+            "registered": register,
+            "models": found,
+        }
+
+    def _upsert_artifact(
+        self,
+        conn: sqlite3.Connection,
+        *,
+        ref: str,
+        manifest_digest: str | None,
+        format_name: str | None = None,
+        revision: str | None = None,
+        variant: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> int:
+        now = _utc_now()
+        conn.execute(
+            """
+            INSERT INTO artifacts (
+                ref, revision, variant, format, manifest_digest,
+                metadata_json, created_at, updated_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT(ref) DO UPDATE SET
+                revision = COALESCE(excluded.revision, artifacts.revision),
+                variant = COALESCE(excluded.variant, artifacts.variant),
+                format = COALESCE(excluded.format, artifacts.format),
+                manifest_digest = COALESCE(excluded.manifest_digest, artifacts.manifest_digest),
+                metadata_json = excluded.metadata_json,
+                deleted_at = NULL,
+                updated_at = excluded.updated_at
+            """,
+            (
+                ref,
+                revision,
+                variant,
+                format_name,
+                manifest_digest,
+                json.dumps(metadata or {}, ensure_ascii=False, sort_keys=True),
+                now,
+                now,
+            ),
+        )
+        row = conn.execute("SELECT id FROM artifacts WHERE ref = ?", (ref,)).fetchone()
+        assert row is not None
+        return int(row["id"])
+
+    def register_model(
+        self,
+        *,
+        ref: str,
+        path: str,
+        scope: str = "user",
+        format_name: str | None = None,
+        full_checksum: bool = False,
+        extra_metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        if not ref.strip():
+            raise ValueError("model ref must not be empty")
+        if scope not in {"user", "team", "system"}:
+            raise ValueError(f"unsupported scope: {scope}")
+        with self._connection() as conn:
+            existing = conn.execute(
+                "SELECT manifest_digest, metadata_json FROM artifacts WHERE ref = ?",
+                (ref,),
+            ).fetchone()
+        existing_metadata = json.loads(existing["metadata_json"]) if existing else {}
+        require_content = bool(existing_metadata.get("content_digest"))
+        scanned = self.scan_path(Path(path), full_checksum=full_checksum or require_content)
+        with self._connection() as conn:
+            self._register_scanned(
+                conn,
+                ref=ref,
+                scanned=scanned,
+                scope=scope,
+                format_name=format_name,
+                extra_metadata=extra_metadata,
+            )
+        return self.inspect_model(ref)
+
+    def _register_scanned(
+        self,
+        conn: sqlite3.Connection,
+        *,
+        ref: str,
+        scanned: dict[str, Any],
+        scope: str,
+        format_name: str | None,
+        extra_metadata: dict[str, Any] | None = None,
+    ) -> None:
+        existing = conn.execute(
+            "SELECT manifest_digest, metadata_json FROM artifacts WHERE ref = ?",
+            (ref,),
+        ).fetchone()
+        existing_metadata = json.loads(existing["metadata_json"]) if existing else {}
+        require_content = bool(existing_metadata.get("content_digest"))
+        actual_identity = (
+            scanned["content_digest"]
+            if require_content
+            else scanned["metadata_digest"]
+        )
+        expected_identity = (
+            existing_metadata.get("content_digest")
+            or existing_metadata.get("metadata_digest")
+            or (existing["manifest_digest"] if existing else None)
+        )
+        state = "ready" if expected_identity in {None, actual_identity} else "dirty"
+        manifest = existing["manifest_digest"] if existing else (
+            scanned["content_digest"] or scanned["metadata_digest"]
+        )
+        verification = (
+            "checksum_verified"
+            if scanned["content_digest"] is not None and state == "ready"
+            else "metadata_verified"
+        )
+        now = _utc_now()
+        artifact_metadata = dict(existing_metadata)
+        if existing is None:
+            artifact_metadata.update(
+                {
+                    "metadata_digest": scanned["metadata_digest"],
+                    "content_digest": scanned["content_digest"],
+                }
+            )
+        artifact_metadata.update(extra_metadata or {})
+        artifact_id = self._upsert_artifact(
+            conn,
+            ref=ref,
+            manifest_digest=manifest,
+            format_name=format_name,
+            metadata=artifact_metadata,
+        )
+        conn.execute(
+            """
+            INSERT INTO replicas (
+                artifact_id, node_id, path, scope, management, state,
+                verification_level, size_bytes, file_count, last_seen
+            ) VALUES (?, ?, ?, ?, 'external', ?, ?, ?, ?, ?)
+            ON CONFLICT(node_id, path) DO UPDATE SET
+                artifact_id = excluded.artifact_id,
+                scope = excluded.scope,
+                state = excluded.state,
+                verification_level = excluded.verification_level,
+                size_bytes = excluded.size_bytes,
+                file_count = excluded.file_count,
+                last_seen = excluded.last_seen
+            """,
+            (
+                artifact_id,
+                self.node_id,
+                scanned["path"],
+                scope,
+                state,
+                verification,
+                scanned["size_bytes"],
+                scanned["file_count"],
+                now,
+            ),
+        )
+        self._audit(
+            conn,
+            "model.register",
+            ref,
+            {
+                "path": scanned["path"],
+                "state": state,
+                "verification_level": verification,
+            },
+        )
+
+    def list_models(
+        self,
+        *,
+        format_name: str | None = None,
+        model_type: str | None = None,
+        state: str | None = None,
+        tag: str | None = None,
+        name: str | None = None,
+        include_deleted: bool = False,
+    ) -> list[dict[str, Any]]:
+        with self._connection() as conn:
+            query = "SELECT * FROM artifacts"
+            if not include_deleted:
+                query += " WHERE deleted_at IS NULL"
+            query += " ORDER BY ref"
+            artifacts = conn.execute(query).fetchall()
+            results: list[dict[str, Any]] = []
+            for artifact in artifacts:
+                metadata = json.loads(artifact["metadata_json"])
+                aliases = [
+                    row["alias"]
+                    for row in conn.execute(
+                        "SELECT alias FROM artifact_aliases WHERE artifact_id = ? ORDER BY alias",
+                        (artifact["id"],),
+                    ).fetchall()
+                ]
+                tags = [
+                    row["tag"]
+                    for row in conn.execute(
+                        "SELECT tag FROM artifact_tags WHERE artifact_id = ? ORDER BY tag",
+                        (artifact["id"],),
+                    ).fetchall()
+                ]
+                if format_name and artifact["format"] != format_name:
+                    continue
+                if model_type and metadata.get("model_type") != model_type:
+                    continue
+                if tag and tag not in tags:
+                    continue
+                replicas = conn.execute(
+                    "SELECT * FROM replicas WHERE artifact_id = ? ORDER BY node_id, path",
+                    (artifact["id"],),
+                ).fetchall()
+                replica_values: list[sqlite3.Row | None] = list(replicas) or [None]
+                for replica in replica_values:
+                    if state and (replica is None or replica["state"] != state):
+                        continue
+                    value = {
+                        "ref": artifact["ref"],
+                        "revision": artifact["revision"],
+                        "variant": artifact["variant"],
+                        "format": artifact["format"],
+                        "manifest_digest": artifact["manifest_digest"],
+                        "description": artifact["description"],
+                        "deleted_at": artifact["deleted_at"],
+                        "aliases": aliases,
+                        "tags": tags,
+                        "model_type": metadata.get("model_type"),
+                    }
+                    if replica is not None:
+                        value.update(dict(replica))
+                        value.pop("id", None)
+                        value.pop("artifact_id", None)
+                    else:
+                        value.update(
+                            {
+                                "node_id": None,
+                                "path": None,
+                                "scope": None,
+                                "management": None,
+                                "state": None,
+                                "verification_level": None,
+                                "size_bytes": 0,
+                                "file_count": 0,
+                                "last_seen": None,
+                            }
+                        )
+                    searchable = " ".join(
+                        [
+                            artifact["ref"],
+                            *aliases,
+                            value.get("path") or "",
+                            artifact["description"] or "",
+                        ]
+                    ).lower()
+                    if name and name.lower() not in searchable:
+                        continue
+                    results.append(value)
+        return results
+
+    def inspect_model(self, ref: str) -> dict[str, Any]:
+        with self._connection() as conn:
+            artifact = self._artifact_row(conn, ref)
+            replicas = conn.execute(
+                "SELECT * FROM replicas WHERE artifact_id = ? ORDER BY node_id, path",
+                (artifact["id"],),
+            ).fetchall()
+            aliases = [
+                row["alias"]
+                for row in conn.execute(
+                    "SELECT alias FROM artifact_aliases WHERE artifact_id = ? ORDER BY alias",
+                    (artifact["id"],),
+                ).fetchall()
+            ]
+            tags = [
+                row["tag"]
+                for row in conn.execute(
+                    "SELECT tag FROM artifact_tags WHERE artifact_id = ? ORDER BY tag",
+                    (artifact["id"],),
+                ).fetchall()
+            ]
+        value = dict(artifact)
+        value["metadata"] = json.loads(value.pop("metadata_json"))
+        value["replicas"] = [dict(row) for row in replicas]
+        value["aliases"] = aliases
+        value["tags"] = tags
+        return value
+
+    def update_model(
+        self,
+        ref: str,
+        *,
+        add_aliases: Iterable[str] = (),
+        remove_aliases: Iterable[str] = (),
+        add_tags: Iterable[str] = (),
+        remove_tags: Iterable[str] = (),
+        description: str | None = None,
+        clear_description: bool = False,
+    ) -> dict[str, Any]:
+        additions_alias = sorted({item.strip() for item in add_aliases if item.strip()})
+        removals_alias = sorted({item.strip() for item in remove_aliases if item.strip()})
+        additions_tag = sorted({item.strip() for item in add_tags if item.strip()})
+        removals_tag = sorted({item.strip() for item in remove_tags if item.strip()})
+        with self._connection() as conn:
+            artifact = self._artifact_row(conn, ref)
+            try:
+                for alias in additions_alias:
+                    existing_alias = conn.execute(
+                        "SELECT artifact_id FROM artifact_aliases WHERE alias = ?",
+                        (alias,),
+                    ).fetchone()
+                    if existing_alias is None:
+                        conn.execute(
+                            "INSERT INTO artifact_aliases (artifact_id, alias) VALUES (?, ?)",
+                            (artifact["id"], alias),
+                        )
+                    elif existing_alias["artifact_id"] != artifact["id"]:
+                        raise ValueError(
+                            f"alias already belongs to another model: {alias}"
+                        )
+            except sqlite3.IntegrityError as exc:
+                raise ValueError(f"alias already belongs to another model: {alias}") from exc
+            for alias in removals_alias:
+                conn.execute(
+                    "DELETE FROM artifact_aliases WHERE artifact_id = ? AND alias = ?",
+                    (artifact["id"], alias),
+                )
+            for tag in additions_tag:
+                conn.execute(
+                    "INSERT OR IGNORE INTO artifact_tags (artifact_id, tag) VALUES (?, ?)",
+                    (artifact["id"], tag),
+                )
+            for tag in removals_tag:
+                conn.execute(
+                    "DELETE FROM artifact_tags WHERE artifact_id = ? AND tag = ?",
+                    (artifact["id"], tag),
+                )
+            if description is not None or clear_description:
+                conn.execute(
+                    "UPDATE artifacts SET description = ?, updated_at = ? WHERE id = ?",
+                    (None if clear_description else description, _utc_now(), artifact["id"]),
+                )
+            self._audit(
+                conn,
+                "model.update",
+                artifact["ref"],
+                {
+                    "add_aliases": additions_alias,
+                    "remove_aliases": removals_alias,
+                    "add_tags": additions_tag,
+                    "remove_tags": removals_tag,
+                    "description_changed": description is not None or clear_description,
+                },
+            )
+        return self.inspect_model(artifact["ref"])
+
+    def delete_model(self, ref: str) -> dict[str, Any]:
+        with self._connection() as conn:
+            artifact = self._artifact_row(conn, ref)
+            deleted_at = _utc_now()
+            conn.execute(
+                "UPDATE artifacts SET deleted_at = ?, updated_at = ? WHERE id = ?",
+                (deleted_at, deleted_at, artifact["id"]),
+            )
+            self._audit(conn, "model.delete", artifact["ref"])
+        return {"ref": artifact["ref"], "deleted_at": deleted_at}
+
+    def restore_model(self, ref: str) -> dict[str, Any]:
+        with self._connection() as conn:
+            artifact = self._artifact_row(conn, ref)
+            conn.execute(
+                "UPDATE artifacts SET deleted_at = NULL, updated_at = ? WHERE id = ?",
+                (_utc_now(), artifact["id"]),
+            )
+            self._audit(conn, "model.restore", artifact["ref"])
+        return self.inspect_model(artifact["ref"])
+
+    def list_replicas(self, ref: str) -> dict[str, Any]:
+        model = self.inspect_model(ref)
+        return {
+            "ref": model["ref"],
+            "deleted_at": model["deleted_at"],
+            "replicas": model["replicas"],
+        }
+
+    def remove_replica(self, ref: str, path: str) -> dict[str, Any]:
+        resolved = str(Path(path).expanduser().resolve())
+        with self._connection() as conn:
+            artifact = self._artifact_row(conn, ref)
+            removed = conn.execute(
+                """
+                DELETE FROM replicas
+                WHERE artifact_id = ? AND node_id = ? AND path = ?
+                """,
+                (artifact["id"], self.node_id, resolved),
+            ).rowcount
+            self._audit(
+                conn,
+                "replica.remove",
+                artifact["ref"],
+                {"path": resolved, "removed": int(removed)},
+            )
+        return {"ref": artifact["ref"], "path": resolved, "removed": int(removed)}
+
+    def refresh_model(
+        self,
+        ref: str,
+        *,
+        path: str | None = None,
+        full_checksum: bool = False,
+    ) -> dict[str, Any]:
+        model = self.inspect_model(ref)
+        replicas = [
+            item
+            for item in model["replicas"]
+            if item["node_id"] == self.node_id
+            and (path is None or item["path"] == str(Path(path).expanduser().resolve()))
+        ]
+        if not replicas:
+            raise KeyError(f"model has no matching replica on this node: {ref}")
+        scans: list[tuple[dict[str, Any], dict[str, Any] | None]] = []
+        for replica in replicas:
+            replica_path = Path(replica["path"])
+            scan = (
+                self.scan_path(replica_path, full_checksum=full_checksum)
+                if replica_path.exists()
+                else None
+            )
+            scans.append((replica, scan))
+        baseline = next((scan for _replica, scan in scans if scan is not None), None)
+        if baseline is None:
+            raise FileNotFoundError("no matching replica paths exist")
+        identity_key = "content_digest" if full_checksum else "metadata_digest"
+        metadata = dict(model["metadata"])
+        metadata["metadata_digest"] = baseline["metadata_digest"]
+        metadata["content_digest"] = baseline["content_digest"] if full_checksum else None
+        now = _utc_now()
+        with self._connection() as conn:
+            conn.execute(
+                """
+                UPDATE artifacts
+                SET manifest_digest = ?, metadata_json = ?, deleted_at = NULL, updated_at = ?
+                WHERE id = ?
+                """,
+                (
+                    baseline[identity_key],
+                    json.dumps(metadata, ensure_ascii=False, sort_keys=True),
+                    now,
+                    model["id"],
+                ),
+            )
+            results = []
+            for replica, scan in scans:
+                if scan is None:
+                    state = "missing"
+                    verification = "metadata_verified"
+                else:
+                    state = (
+                        "ready"
+                        if scan[identity_key] == baseline[identity_key]
+                        else "dirty"
+                    )
+                    verification = (
+                        "checksum_verified" if full_checksum and state == "ready"
+                        else "metadata_verified"
+                    )
+                conn.execute(
+                    """
+                    UPDATE replicas
+                    SET state = ?, verification_level = ?,
+                        size_bytes = ?, file_count = ?, last_seen = ?
+                    WHERE id = ?
+                    """,
+                    (
+                        state,
+                        verification,
+                        scan["size_bytes"] if scan else 0,
+                        scan["file_count"] if scan else 0,
+                        now,
+                        replica["id"],
+                    ),
+                )
+                results.append({"path": replica["path"], "state": state, "scan": scan})
+            self._audit(
+                conn,
+                "model.refresh",
+                model["ref"],
+                {"paths": [item["path"] for item, _scan in scans], "full_checksum": full_checksum},
+            )
+        return {"ref": model["ref"], "results": results}
+
+    def validate_model(self, ref: str, path: str | None = None) -> dict[str, Any]:
+        model = self.inspect_model(ref)
+        replicas = [
+            item
+            for item in model["replicas"]
+            if item["node_id"] == self.node_id
+            and (path is None or item["path"] == str(Path(path).expanduser().resolve()))
+        ]
+        if not replicas:
+            raise KeyError(f"model has no matching replica on this node: {ref}")
+        results = []
+        for replica in replicas:
+            root = Path(replica["path"])
+            missing: list[str] = []
+            index_files = [
+                root / "model.safetensors.index.json",
+                root / "pytorch_model.bin.index.json",
+            ]
+            index_path = next((item for item in index_files if item.is_file()), None)
+            referenced: list[str] = []
+            parse_error = None
+            if index_path is not None:
+                try:
+                    index = json.loads(index_path.read_text(encoding="utf-8"))
+                    weight_map = index.get("weight_map") or {}
+                    referenced = sorted(
+                        {str(item) for item in weight_map.values()}
+                    )
+                    missing = [
+                        item for item in referenced if not (root / item).is_file()
+                    ]
+                except (OSError, UnicodeDecodeError, json.JSONDecodeError, AttributeError) as exc:
+                    parse_error = str(exc)
+            weights = sorted(
+                item.name
+                for item in root.iterdir()
+                if item.is_file()
+                and item.suffix.lower() in {".safetensors", ".bin", ".gguf"}
+            ) if root.is_dir() else []
+            has_config = (root / "config.json").is_file() or (
+                root / "adapter_config.json"
+            ).is_file()
+            valid = bool(root.is_dir() and weights and not missing and not parse_error)
+            if not any(item.endswith(".gguf") for item in weights):
+                valid = valid and has_config
+            results.append(
+                {
+                    "path": replica["path"],
+                    "valid": valid,
+                    "index": str(index_path) if index_path else None,
+                    "referenced_shards": len(referenced),
+                    "present_weight_files": len(weights),
+                    "missing_files": missing,
+                    "parse_error": parse_error,
+                }
+            )
+        return {"ref": model["ref"], "valid": all(item["valid"] for item in results), "results": results}
+
+    def audit_records(self, ref: str | None = None, limit: int = 100) -> list[dict[str, Any]]:
+        if not 1 <= limit <= 1000:
+            raise ValueError("audit limit must be between 1 and 1000")
+        with self._connection() as conn:
+            if ref:
+                artifact = self._artifact_row(conn, ref)
+                rows = conn.execute(
+                    "SELECT * FROM audit_log WHERE ref = ? ORDER BY id DESC LIMIT ?",
+                    (artifact["ref"], limit),
+                ).fetchall()
+            else:
+                rows = conn.execute(
+                    "SELECT * FROM audit_log ORDER BY id DESC LIMIT ?",
+                    (limit,),
+                ).fetchall()
+        results = []
+        for row in rows:
+            value = dict(row)
+            value["details"] = json.loads(value.pop("details_json"))
+            results.append(value)
+        return results
+
+    def unregister_model(self, ref: str, path: str | None = None) -> dict[str, Any]:
+        with self._connection() as conn:
+            artifact = self._artifact_row(conn, ref)
+            if path is None:
+                removed = conn.execute(
+                    "DELETE FROM replicas WHERE artifact_id = ? AND node_id = ?",
+                    (artifact["id"], self.node_id),
+                ).rowcount
+            else:
+                resolved = str(Path(path).expanduser().resolve())
+                removed = conn.execute(
+                    "DELETE FROM replicas WHERE artifact_id = ? AND node_id = ? AND path = ?",
+                    (artifact["id"], self.node_id, resolved),
+                ).rowcount
+            remaining = conn.execute(
+                "SELECT COUNT(*) AS count FROM replicas WHERE artifact_id = ?",
+                (artifact["id"],),
+            ).fetchone()["count"]
+            if remaining == 0:
+                conn.execute(
+                    "UPDATE artifacts SET deleted_at = ?, updated_at = ? WHERE id = ?",
+                    (_utc_now(), _utc_now(), artifact["id"]),
+                )
+            self._audit(
+                conn,
+                "model.unregister",
+                artifact["ref"],
+                {
+                    "path": path,
+                    "removed_replicas": int(removed),
+                    "soft_deleted": remaining == 0,
+                },
+            )
+        return {
+            "removed_replicas": int(removed),
+            "soft_deleted": remaining == 0,
+        }
+
+    def verify_model(self, ref: str, full_checksum: bool = False) -> dict[str, Any]:
+        model = self.inspect_model(ref)
+        local = [item for item in model["replicas"] if item["node_id"] == self.node_id]
+        if not local:
+            raise KeyError(f"model has no replica on this node: {ref}")
+        results = []
+        with self._connection() as conn:
+            for replica in local:
+                path = Path(replica["path"])
+                if not path.exists():
+                    state = "missing"
+                    scanned = None
+                else:
+                    require_content = full_checksum or bool(model["metadata"].get("content_digest"))
+                    scanned = self.scan_path(path, full_checksum=require_content)
+                    actual = (
+                        scanned["content_digest"]
+                        if require_content
+                        else scanned["metadata_digest"]
+                    )
+                    comparable_expected = (
+                        model["metadata"].get("content_digest")
+                        if require_content
+                        else model["metadata"].get("metadata_digest")
+                    )
+                    state = "ready" if comparable_expected in {None, actual} else "dirty"
+                verification = (
+                    "checksum_verified"
+                    if scanned and scanned["content_digest"] and state == "ready"
+                    else "metadata_verified"
+                )
+                if (
+                    scanned
+                    and full_checksum
+                    and state == "ready"
+                    and not model["metadata"].get("content_digest")
+                ):
+                    metadata = dict(model["metadata"])
+                    metadata["content_digest"] = scanned["content_digest"]
+                    conn.execute(
+                        """
+                        UPDATE artifacts
+                        SET manifest_digest = ?, metadata_json = ?, updated_at = ?
+                        WHERE id = ?
+                        """,
+                        (
+                            scanned["content_digest"],
+                            json.dumps(metadata, ensure_ascii=False, sort_keys=True),
+                            _utc_now(),
+                            model["id"],
+                        ),
+                    )
+                conn.execute(
+                    """
+                    UPDATE replicas
+                    SET state = ?, verification_level = ?, last_seen = ?
+                    WHERE id = ?
+                    """,
+                    (state, verification, _utc_now(), replica["id"]),
+                )
+                results.append({"path": replica["path"], "state": state, "scan": scanned})
+        return {"ref": ref, "results": results}
+
+    def export_records(self) -> dict[str, Any]:
+        exported_at = _utc_now()
+        header = {
+            "type": "meta",
+            "schema_version": SCHEMA_VERSION,
+            "exported_at": exported_at,
+            "source_node": self.node_id,
+        }
+
+        def json_size(value: Any) -> int:
+            try:
+                text = json.dumps(
+                    value,
+                    ensure_ascii=False,
+                    sort_keys=True,
+                    allow_nan=False,
+                )
+                return len(text.encode("utf-8"))
+            except (TypeError, ValueError, UnicodeEncodeError) as exc:
+                raise ValueError(
+                    f"inventory export contains invalid JSON data: {exc}"
+                ) from exc
+
+        serialized_bytes = json_size(header) + 1
+        if serialized_bytes > MAX_INVENTORY_CONTENT_BYTES:
+            raise ValueError("inventory export content exceeds byte limit")
+        artifacts: list[dict[str, Any]] = []
+        total_aliases = 0
+        total_tags = 0
+        total_replicas = 0
+        with self._connection() as conn:
+            rows = conn.execute("SELECT * FROM artifacts ORDER BY ref")
+            for artifact_index, row in enumerate(rows):
+                if artifact_index >= MAX_INVENTORY_ARTIFACTS:
+                    raise ValueError("inventory contains too many artifacts")
+                artifact = dict(row)
+                artifact["metadata"] = json.loads(artifact.pop("metadata_json"))
+                artifact["aliases"] = []
+                artifact["tags"] = []
+                artifact["replicas"] = []
+                artifact_id = artifact["id"]
+                artifact.pop("id", None)
+
+                artifact_size = json_size(
+                    {"type": "artifact", "value": artifact}
+                )
+                if (
+                    serialized_bytes + artifact_size + 1
+                    > MAX_INVENTORY_CONTENT_BYTES
+                ):
+                    raise ValueError("inventory export content exceeds byte limit")
+
+                def append_item(
+                    field: str,
+                    item: Any,
+                    *,
+                    per_artifact_limit: int,
+                ) -> None:
+                    nonlocal artifact_size
+                    values = artifact[field]
+                    if len(values) >= per_artifact_limit:
+                        raise ValueError(
+                            f"inventory artifact has too many {field}"
+                        )
+                    added_size = json_size(item) + (2 if values else 0)
+                    if (
+                        serialized_bytes + artifact_size + added_size + 1
+                        > MAX_INVENTORY_CONTENT_BYTES
+                    ):
+                        raise ValueError(
+                            "inventory export content exceeds byte limit"
+                        )
+                    values.append(item)
+                    artifact_size += added_size
+
+                for value in conn.execute(
+                    """
+                    SELECT alias FROM artifact_aliases
+                    WHERE artifact_id = ? ORDER BY alias
+                    """,
+                    (artifact_id,),
+                ):
+                    total_aliases += 1
+                    if total_aliases > MAX_INVENTORY_TOTAL_ALIASES:
+                        raise ValueError("inventory has too many total aliases")
+                    append_item(
+                        "aliases",
+                        value["alias"],
+                        per_artifact_limit=MAX_INVENTORY_ALIASES_PER_ARTIFACT,
+                    )
+                for value in conn.execute(
+                    """
+                    SELECT tag FROM artifact_tags
+                    WHERE artifact_id = ? ORDER BY tag
+                    """,
+                    (artifact_id,),
+                ):
+                    total_tags += 1
+                    if total_tags > MAX_INVENTORY_TOTAL_TAGS:
+                        raise ValueError("inventory has too many total tags")
+                    append_item(
+                        "tags",
+                        value["tag"],
+                        per_artifact_limit=MAX_INVENTORY_TAGS_PER_ARTIFACT,
+                    )
+                for value in conn.execute(
+                    """
+                    SELECT * FROM replicas
+                    WHERE artifact_id = ? ORDER BY node_id, path
+                    """,
+                    (artifact_id,),
+                ):
+                    total_replicas += 1
+                    if total_replicas > MAX_INVENTORY_TOTAL_REPLICAS:
+                        raise ValueError("inventory has too many total replicas")
+                    replica = dict(value)
+                    replica.pop("id", None)
+                    replica.pop("artifact_id", None)
+                    append_item(
+                        "replicas",
+                        replica,
+                        per_artifact_limit=MAX_INVENTORY_REPLICAS_PER_ARTIFACT,
+                    )
+
+                exact_size = json_size(
+                    {"type": "artifact", "value": artifact}
+                )
+                if (
+                    serialized_bytes + exact_size + 1
+                    > MAX_INVENTORY_CONTENT_BYTES
+                ):
+                    raise ValueError("inventory export content exceeds byte limit")
+                artifacts.append(artifact)
+                serialized_bytes += exact_size + 1
+        return {
+            "schema_version": SCHEMA_VERSION,
+            "exported_at": exported_at,
+            "source_node": self.node_id,
+            "artifacts": artifacts,
+        }
+
+    @staticmethod
+    def _normalize_root_maps(
+        root_maps: Iterable[tuple[str, str]],
+    ) -> tuple[tuple[Path, Path], ...]:
+        result: list[tuple[Path, Path]] = []
+        for index, item in enumerate(root_maps):
+            if index >= MAX_ROOT_MAPS:
+                raise ValueError(
+                    f"root maps must contain at most {MAX_ROOT_MAPS} pairs"
+                )
+            if (
+                not isinstance(item, (list, tuple))
+                or isinstance(item, (str, bytes))
+                or len(item) != 2
+            ):
+                raise ValueError(
+                    "root maps must contain old/new path pairs"
+                )
+            old, new = item
+            old_text = str(old)
+            new_text = str(new)
+            for value, name in ((old_text, "old"), (new_text, "new")):
+                if not value:
+                    raise ValueError(f"root mapping {name} must not be empty")
+                try:
+                    path_bytes = len(value.encode("utf-8"))
+                except UnicodeEncodeError as exc:
+                    raise ValueError(
+                        f"root mapping {name} is not valid UTF-8"
+                    ) from exc
+                if path_bytes > MAX_ROOT_MAP_PATH_BYTES:
+                    raise ValueError(
+                        f"root mapping {name} exceeds "
+                        f"{MAX_ROOT_MAP_PATH_BYTES} UTF-8 bytes"
+                    )
+            result.append(
+                (Path(old_text).expanduser(), Path(new_text).expanduser())
+            )
+        return tuple(result)
+
+    @staticmethod
+    def _mapped_path(
+        path: str,
+        root_maps: Iterable[tuple[Path, Path]],
+    ) -> str | None:
+        source = Path(path)
+        for old, new in root_maps:
+            try:
+                relative = source.relative_to(old)
+            except ValueError:
+                continue
+            return str(new / relative)
+        return None
+
+    def import_records(
+        self,
+        payload: dict[str, Any],
+        root_maps: Iterable[tuple[str, str]] = (),
+    ) -> dict[str, int]:
+        if payload.get("schema_version") != SCHEMA_VERSION:
+            raise ValueError(f"unsupported inventory schema: {payload.get('schema_version')}")
+        maps = self._normalize_root_maps(root_maps)
+        artifacts = payload.get("artifacts", [])
+        if not isinstance(artifacts, list):
+            raise ValueError("inventory artifacts must be an array")
+        if len(artifacts) > MAX_INVENTORY_ARTIFACTS:
+            raise ValueError("inventory contains too many artifacts")
+        total_aliases = 0
+        total_tags = 0
+        total_replicas = 0
+        for artifact in artifacts:
+            if not isinstance(artifact, dict):
+                raise ValueError("each inventory artifact must be an object")
+            aliases = artifact.get("aliases", [])
+            tags = artifact.get("tags", [])
+            replicas = artifact.get("replicas", [])
+            for name, values in (
+                ("aliases", aliases),
+                ("tags", tags),
+                ("replicas", replicas),
+            ):
+                if not isinstance(values, list):
+                    raise ValueError(
+                        f"inventory artifact {name} must be an array"
+                    )
+            total_aliases += len(aliases)
+            total_tags += len(tags)
+            total_replicas += len(replicas)
+            if total_aliases > MAX_INVENTORY_TOTAL_ALIASES:
+                raise ValueError("inventory has too many total aliases")
+            if total_tags > MAX_INVENTORY_TOTAL_TAGS:
+                raise ValueError("inventory has too many total tags")
+            if total_replicas > MAX_INVENTORY_TOTAL_REPLICAS:
+                raise ValueError("inventory has too many total replicas")
+
+        prepared: list[
+            tuple[dict[str, Any], str, tuple[dict[str, Any], str] | None]
+        ] = []
+        for artifact in artifacts:
+            ref = artifact.get("ref")
+            if not ref:
+                continue
+            registration = None
+            metadata = artifact.get("metadata") or {}
+            require_content = bool(metadata.get("content_digest"))
+            for replica in artifact.get("replicas", []):
+                mapped = self._mapped_path(str(replica.get("path", "")), maps)
+                if mapped and Path(mapped).expanduser().exists():
+                    scope = replica.get("scope", "user")
+                    if scope not in {"user", "team", "system"}:
+                        raise ValueError(f"unsupported scope: {scope}")
+                    registration = (
+                        self.scan_path(
+                            Path(mapped),
+                            full_checksum=require_content,
+                        ),
+                        scope,
+                    )
+                    break
+            prepared.append((artifact, ref, registration))
+
+        rebound_replicas = 0
+        with self._connection() as conn:
+            for artifact, ref, registration in prepared:
+                artifact_id = self._upsert_artifact(
+                    conn,
+                    ref=ref,
+                    manifest_digest=artifact.get("manifest_digest"),
+                    format_name=artifact.get("format"),
+                    revision=artifact.get("revision"),
+                    variant=artifact.get("variant"),
+                    metadata=artifact.get("metadata") or {},
+                )
+                conn.execute(
+                    """
+                    UPDATE artifacts
+                    SET description = ?, deleted_at = ?, updated_at = ?
+                    WHERE id = ?
+                    """,
+                    (
+                        artifact.get("description"),
+                        artifact.get("deleted_at"),
+                        _utc_now(),
+                        artifact_id,
+                    ),
+                )
+                for alias in artifact.get("aliases") or []:
+                    conn.execute(
+                        "INSERT OR IGNORE INTO artifact_aliases (artifact_id, alias) VALUES (?, ?)",
+                        (artifact_id, str(alias)),
+                    )
+                for tag in artifact.get("tags") or []:
+                    conn.execute(
+                        "INSERT OR IGNORE INTO artifact_tags (artifact_id, tag) VALUES (?, ?)",
+                        (artifact_id, str(tag)),
+                    )
+                self._audit(conn, "model.import", ref)
+                if registration is not None:
+                    scanned, scope = registration
+                    self._register_scanned(
+                        conn,
+                        ref=ref,
+                        scanned=scanned,
+                        scope=scope,
+                        format_name=artifact.get("format"),
+                    )
+                    rebound_replicas += 1
+        return {
+            "imported_artifacts": len(prepared),
+            "rebound_replicas": rebound_replicas,
+        }