msdev 0.9.0__py3-none-any.whl

msdev/core/services/model.py

@@ -0,0 +1,1085 @@
+"""Typed model inventory application service for the msdev CLI."""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from ..inventory import SCHEMA_VERSION
+from ..resources import Node
+from ..limits import (
+    MAX_INVENTORY_ALIASES_PER_ARTIFACT,
+    MAX_INVENTORY_ARTIFACTS,
+    MAX_INVENTORY_CONTENT_BYTES,
+    MAX_INVENTORY_LINE_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,
+)
+from ..transport import RpcError, RpcTransport
+from .context import ServiceContext
+
+
+_MODEL_STATES = frozenset({"ready", "dirty", "missing", "broken"})
+_MODEL_SCOPES = frozenset({"user", "team", "system"})
+_MODEL_MANAGEMENT = frozenset({"external"})
+_VERIFICATION_LEVELS = frozenset(
+    {"metadata_verified", "checksum_verified"}
+)
+_NAMESPACE_PATTERN = re.compile(r"[A-Za-z0-9._-]+")
+
+_INVENTORY_KEYS = frozenset(
+    {"schema_version", "exported_at", "source_node", "artifacts"}
+)
+_JSONL_META_KEYS = frozenset(
+    {"type", "schema_version", "exported_at", "source_node"}
+)
+_JSONL_ARTIFACT_RECORD_KEYS = frozenset({"type", "value"})
+_ARTIFACT_KEYS = frozenset(
+    {
+        "ref",
+        "revision",
+        "variant",
+        "format",
+        "manifest_digest",
+        "metadata",
+        "created_at",
+        "updated_at",
+        "description",
+        "deleted_at",
+        "aliases",
+        "tags",
+        "replicas",
+    }
+)
+_REPLICA_KEYS = frozenset(
+    {
+        "node_id",
+        "path",
+        "scope",
+        "management",
+        "state",
+        "verification_level",
+        "size_bytes",
+        "file_count",
+        "last_seen",
+    }
+)
+
+
+def _required_string(value: Any, name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{name} must be a non-empty string")
+    return value
+
+
+def _optional_string(value: Any, name: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ValueError(f"{name} must be a string")
+    return value
+
+
+def _boolean(value: Any, name: str) -> bool:
+    if type(value) is not bool:
+        raise ValueError(f"{name} must be a boolean")
+    return value
+
+
+def _bounded_integer(
+    value: Any,
+    name: str,
+    *,
+    minimum: int,
+    maximum: int,
+) -> int:
+    if type(value) is not int:
+        raise ValueError(f"{name} must be an integer")
+    if not minimum <= value <= maximum:
+        raise ValueError(f"{name} must be between {minimum} and {maximum}")
+    return value
+
+
+def _string_array(value: Any, name: str) -> tuple[str, ...]:
+    if not isinstance(value, (list, tuple)) or isinstance(value, (str, bytes)):
+        raise ValueError(f"{name} must be a string array")
+    return tuple(_required_string(item, f"{name} item") for item in value)
+
+
+def _nullable_string(value: Any, name: str) -> str | None:
+    if value is not None and not isinstance(value, str):
+        raise ValueError(f"{name} must be a string or null")
+    return value
+
+
+def _nonnegative_integer(value: Any, name: str) -> int:
+    if type(value) is not int:
+        raise ValueError(f"{name} must be an integer")
+    if value < 0:
+        raise ValueError(f"{name} must be non-negative")
+    return value
+
+
+def _validate_json_value(
+    value: Any,
+    name: str,
+    active_containers: set[int] | None = None,
+) -> None:
+    active = active_containers if active_containers is not None else set()
+    if value is None or isinstance(value, (str, bool, int)):
+        return
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError(f"{name} must contain only finite numbers")
+        return
+    if isinstance(value, list):
+        identity = id(value)
+        if identity in active:
+            raise ValueError(f"{name} contains a recursive JSON value")
+        active.add(identity)
+        try:
+            for index, item in enumerate(value):
+                _validate_json_value(item, f"{name}[{index}]", active)
+        finally:
+            active.remove(identity)
+        return
+    if isinstance(value, dict):
+        identity = id(value)
+        if identity in active:
+            raise ValueError(f"{name} contains a recursive JSON value")
+        active.add(identity)
+        try:
+            for key, item in value.items():
+                if not isinstance(key, str):
+                    raise ValueError(f"{name} object keys must be strings")
+                _validate_json_value(item, f"{name}.{key}", active)
+        finally:
+            active.remove(identity)
+        return
+    raise ValueError(
+        f"{name} contains unsupported JSON value type: "
+        f"{type(value).__name__}"
+    )
+
+
+def _ensure_json_value(value: Any, name: str) -> None:
+    try:
+        _validate_json_value(value, name)
+    except RecursionError as exc:
+        raise ValueError(f"{name} is too deeply nested") from exc
+
+
+def _reject_unknown_keys(
+    value: dict[str, Any],
+    allowed: frozenset[str],
+    name: str,
+) -> None:
+    unknown = set(value) - allowed
+    if unknown:
+        rendered = ", ".join(sorted(repr(item) for item in unknown))
+        raise ValueError(f"{name} has unknown field(s): {rendered}")
+
+
+def _json_text(value: Any, name: str) -> str:
+    try:
+        return json.dumps(
+            value,
+            ensure_ascii=False,
+            sort_keys=True,
+            allow_nan=False,
+        )
+    except (TypeError, ValueError, OverflowError, RecursionError) as exc:
+        raise ValueError(f"{name} is not valid JSON data: {exc}") from exc
+
+
+def _reject_json_constant(value: str) -> None:
+    raise ValueError(f"non-finite JSON number is not allowed: {value}")
+
+
+def _load_json(value: str, name: str) -> Any:
+    try:
+        return json.loads(
+            value,
+            parse_constant=_reject_json_constant,
+        )
+    except (json.JSONDecodeError, ValueError, RecursionError) as exc:
+        raise ValueError(f"invalid {name} JSON: {exc}") from exc
+
+
+def _utf8_size(value: str, name: str) -> int:
+    try:
+        return len(value.encode("utf-8"))
+    except UnicodeEncodeError as exc:
+        raise ValueError(f"{name} is not valid UTF-8: {exc}") from exc
+
+
+def _check_size(value: str, name: str, maximum: int) -> None:
+    if _utf8_size(value, name) > maximum:
+        raise ValueError(f"{name} exceeds {maximum} UTF-8 bytes")
+
+
+def _root_maps(value: Any) -> tuple[tuple[str, str], ...]:
+    if not isinstance(value, (list, tuple)) or isinstance(value, (str, bytes)):
+        raise ValueError("root_maps must be an array of [old, new] pairs")
+    if len(value) > MAX_ROOT_MAPS:
+        raise ValueError(f"root_maps must contain at most {MAX_ROOT_MAPS} pairs")
+    result: list[tuple[str, str]] = []
+    for item in value:
+        if (
+            not isinstance(item, (list, tuple))
+            or isinstance(item, (str, bytes))
+            or len(item) != 2
+        ):
+            raise ValueError("each root mapping must contain exactly [old, new]")
+        old = _required_string(item[0], "root mapping old")
+        new = _required_string(item[1], "root mapping new")
+        for path, name in ((old, "old"), (new, "new")):
+            if _utf8_size(path, f"root mapping {name}") > MAX_ROOT_MAP_PATH_BYTES:
+                raise ValueError(
+                    f"root mapping {name} exceeds "
+                    f"{MAX_ROOT_MAP_PATH_BYTES} UTF-8 bytes"
+                )
+        result.append((old, new))
+    return tuple(result)
+
+
+def _validate_artifact(artifact: Any) -> dict[str, Any]:
+    if not isinstance(artifact, dict):
+        raise ValueError("each inventory artifact must be an object")
+    _reject_unknown_keys(
+        artifact,
+        _ARTIFACT_KEYS,
+        "inventory artifact",
+    )
+    _required_string(artifact.get("ref"), "inventory artifact ref")
+
+    for name in (
+        "manifest_digest",
+        "format",
+        "revision",
+        "variant",
+        "description",
+        "deleted_at",
+        "created_at",
+        "updated_at",
+    ):
+        if name in artifact:
+            _nullable_string(artifact[name], f"inventory artifact {name}")
+
+    if "metadata" in artifact and not isinstance(artifact["metadata"], dict):
+        raise ValueError("inventory artifact metadata must be an object")
+
+    aliases = artifact.get("aliases", [])
+    if not isinstance(aliases, list):
+        raise ValueError("inventory artifact aliases must be an array")
+    if len(aliases) > MAX_INVENTORY_ALIASES_PER_ARTIFACT:
+        raise ValueError("inventory artifact has too many aliases")
+    _string_array(aliases, "inventory artifact aliases")
+
+    tags = artifact.get("tags", [])
+    if not isinstance(tags, list):
+        raise ValueError("inventory artifact tags must be an array")
+    if len(tags) > MAX_INVENTORY_TAGS_PER_ARTIFACT:
+        raise ValueError("inventory artifact has too many tags")
+    _string_array(tags, "inventory artifact tags")
+
+    replicas = artifact.get("replicas", [])
+    if not isinstance(replicas, list):
+        raise ValueError("inventory artifact replicas must be an array")
+    if len(replicas) > MAX_INVENTORY_REPLICAS_PER_ARTIFACT:
+        raise ValueError("inventory artifact has too many replicas")
+    for replica in replicas:
+        if not isinstance(replica, dict):
+            raise ValueError("each inventory replica must be an object")
+        _reject_unknown_keys(
+            replica,
+            _REPLICA_KEYS,
+            "inventory replica",
+        )
+        _required_string(replica.get("path"), "inventory replica path")
+        if "node_id" in replica:
+            _required_string(replica["node_id"], "inventory replica node_id")
+        if "scope" in replica:
+            scope = _required_string(replica["scope"], "inventory replica scope")
+            if scope not in _MODEL_SCOPES:
+                raise ValueError(f"unsupported inventory replica scope: {scope}")
+        if "management" in replica:
+            management = _required_string(
+                replica["management"],
+                "inventory replica management",
+            )
+            if management not in _MODEL_MANAGEMENT:
+                raise ValueError(
+                    f"unsupported inventory replica management: {management}"
+                )
+        if "state" in replica:
+            state = _required_string(replica["state"], "inventory replica state")
+            if state not in _MODEL_STATES:
+                raise ValueError(f"unsupported inventory replica state: {state}")
+        if "verification_level" in replica:
+            level = _required_string(
+                replica["verification_level"],
+                "inventory replica verification_level",
+            )
+            if level not in _VERIFICATION_LEVELS:
+                raise ValueError(
+                    f"unsupported inventory replica verification_level: {level}"
+                )
+        for name in ("size_bytes", "file_count"):
+            if name in replica:
+                _nonnegative_integer(
+                    replica[name],
+                    f"inventory replica {name}",
+                )
+        if "last_seen" in replica:
+            _required_string(
+                replica["last_seen"],
+                "inventory replica last_seen",
+            )
+    return artifact
+
+
+def _add_artifact_fanout(
+    artifact: dict[str, Any],
+    totals: tuple[int, int, int],
+) -> tuple[int, int, int]:
+    total_aliases = totals[0] + len(artifact.get("aliases", []))
+    total_tags = totals[1] + len(artifact.get("tags", []))
+    total_replicas = totals[2] + len(artifact.get("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")
+    return total_aliases, total_tags, total_replicas
+
+
+def _validate_inventory_payload(
+    payload: Any,
+    *,
+    jsonl_lines: list[str] | None = None,
+) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        raise ValueError("inventory payload must be an object")
+    _ensure_json_value(payload, "inventory payload")
+    _reject_unknown_keys(
+        payload,
+        _INVENTORY_KEYS,
+        "inventory payload",
+    )
+    schema_version = payload.get("schema_version")
+    if type(schema_version) is not int:
+        raise ValueError("inventory schema_version must be an integer")
+    if schema_version != SCHEMA_VERSION:
+        raise ValueError(f"unsupported inventory schema: {schema_version}")
+    for name in ("exported_at", "source_node"):
+        if name in payload:
+            _nullable_string(payload[name], f"inventory {name}")
+    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")
+
+    header = _json_text(
+        {
+            "type": "meta",
+            "schema_version": schema_version,
+            "exported_at": payload.get("exported_at"),
+            "source_node": payload.get("source_node"),
+        },
+        "inventory metadata",
+    )
+    _check_size(header, "inventory metadata line", MAX_INVENTORY_LINE_BYTES)
+    if jsonl_lines is not None:
+        jsonl_lines.append(header)
+    serialized_bytes = _utf8_size(header, "inventory metadata line") + 1
+    if serialized_bytes > MAX_INVENTORY_CONTENT_BYTES:
+        raise ValueError(
+            "inventory JSONL content exceeds "
+            f"{MAX_INVENTORY_CONTENT_BYTES} UTF-8 bytes"
+        )
+
+    fanout = (0, 0, 0)
+    for artifact in artifacts:
+        _validate_artifact(artifact)
+        fanout = _add_artifact_fanout(artifact, fanout)
+        artifact_line = _json_text(
+            {"type": "artifact", "value": artifact},
+            "inventory artifact",
+        )
+        _check_size(
+            artifact_line,
+            "inventory artifact line",
+            MAX_INVENTORY_LINE_BYTES,
+        )
+        if jsonl_lines is not None:
+            jsonl_lines.append(artifact_line)
+        serialized_bytes += _utf8_size(
+            artifact_line,
+            "inventory artifact line",
+        ) + 1
+        if serialized_bytes > MAX_INVENTORY_CONTENT_BYTES:
+            raise ValueError(
+                "inventory JSONL content exceeds "
+                f"{MAX_INVENTORY_CONTENT_BYTES} UTF-8 bytes"
+            )
+    return payload
+
+
+def _model_list_rows(value: Any) -> tuple[dict[str, Any], ...]:
+    if not isinstance(value, list):
+        raise ValueError("model.list response must be an array")
+    if not all(isinstance(item, dict) for item in value):
+        raise ValueError("every model.list response item must be an object")
+    return tuple(value)
+
+
+def inventory_to_jsonl(payload: Any) -> str:
+    """Serialize structured inventory records using the CLI-compatible JSONL format."""
+    lines: list[str] = []
+    _validate_inventory_payload(payload, jsonl_lines=lines)
+    return "\n".join(lines) + "\n"
+
+
+def inventory_from_jsonl(content: Any) -> dict[str, Any]:
+    """Parse CLI-compatible JSONL into structured inventory records."""
+    if not isinstance(content, str):
+        raise ValueError("inventory jsonl must be a string")
+    _check_size(
+        content,
+        "inventory JSONL content",
+        MAX_INVENTORY_CONTENT_BYTES,
+    )
+    lines = content.splitlines()
+    if not lines:
+        raise ValueError("empty inventory export")
+    for line in lines:
+        _check_size(
+            line,
+            "inventory JSONL line",
+            MAX_INVENTORY_LINE_BYTES,
+        )
+    meta = _load_json(lines[0], "inventory metadata")
+    if not isinstance(meta, dict) or meta.get("type") != "meta":
+        raise ValueError("inventory export is missing metadata header")
+    _ensure_json_value(meta, "inventory metadata")
+    _reject_unknown_keys(
+        meta,
+        _JSONL_META_KEYS,
+        "inventory metadata",
+    )
+    artifacts: list[dict[str, Any]] = []
+    fanout = (0, 0, 0)
+    for line in lines[1:]:
+        if not line.strip():
+            continue
+        record = _load_json(line, "inventory record")
+        if not isinstance(record, dict):
+            raise ValueError("inventory record must be an object")
+        _ensure_json_value(record, "inventory record")
+        _reject_unknown_keys(
+            record,
+            _JSONL_ARTIFACT_RECORD_KEYS,
+            "inventory artifact record",
+        )
+        record_type = record.get("type")
+        if record_type != "artifact":
+            raise ValueError(
+                f"unsupported inventory JSONL record type: {record_type!r}"
+            )
+        if len(artifacts) >= MAX_INVENTORY_ARTIFACTS:
+            raise ValueError("inventory contains too many artifacts")
+        artifact = _validate_artifact(record.get("value"))
+        fanout = _add_artifact_fanout(artifact, fanout)
+        artifacts.append(artifact)
+    payload = {
+        "schema_version": meta.get("schema_version"),
+        "exported_at": meta.get("exported_at"),
+        "source_node": meta.get("source_node"),
+        "artifacts": artifacts,
+    }
+    return _validate_inventory_payload(payload)
+
+
+@dataclass(frozen=True)
+class ModelRefRequest:
+    node: Any
+    ref: Any
+
+
+@dataclass(frozen=True)
+class ModelRegisterRequest:
+    node: Any
+    ref: Any
+    path: Any
+    scope: Any = "user"
+    format_name: Any = None
+    full_checksum: Any = False
+
+
+@dataclass(frozen=True)
+class ModelDiscoverRequest:
+    node: Any
+    root: Any
+    max_depth: Any = 5
+    register: Any = False
+    namespace: Any = "discovered"
+
+
+@dataclass(frozen=True)
+class ModelListRequest:
+    node: Any = None
+    all_nodes: Any = False
+    format_name: Any = None
+    model_type: Any = None
+    state: Any = None
+    tag: Any = None
+    name: Any = None
+    include_deleted: Any = False
+
+
+@dataclass(frozen=True)
+class ModelUpdateRequest:
+    node: Any
+    ref: Any
+    add_aliases: Any = ()
+    remove_aliases: Any = ()
+    add_tags: Any = ()
+    remove_tags: Any = ()
+    description: Any = None
+    clear_description: Any = False
+
+
+@dataclass(frozen=True)
+class ModelRefreshRequest:
+    node: Any
+    ref: Any
+    path: Any = None
+    full_checksum: Any = False
+
+
+@dataclass(frozen=True)
+class ModelValidateRequest:
+    node: Any
+    ref: Any
+    path: Any = None
+
+
+@dataclass(frozen=True)
+class ModelAuditRequest:
+    node: Any
+    ref: Any = None
+    limit: Any = 100
+
+
+@dataclass(frozen=True)
+class ModelReplicaAddRequest:
+    node: Any
+    ref: Any
+    path: Any
+    full_checksum: Any = False
+
+
+@dataclass(frozen=True)
+class ModelReplicaRemoveRequest:
+    node: Any
+    ref: Any
+    path: Any
+
+
+@dataclass(frozen=True)
+class ModelVerifyRequest:
+    node: Any
+    ref: Any
+    full_checksum: Any = False
+
+
+@dataclass(frozen=True)
+class ModelUnregisterRequest:
+    node: Any
+    ref: Any
+    path: Any = None
+
+
+@dataclass(frozen=True)
+class ModelImportRequest:
+    node: Any
+    payload: Any = None
+    jsonl: Any = None
+    root_maps: Any = ()
+
+
+@dataclass(frozen=True)
+class ModelRebindRequest:
+    node: Any
+    ref: Any
+    path: Any
+    scope: Any = "user"
+    full_checksum: Any = False
+
+
+@dataclass(frozen=True)
+class ModelOperationResult:
+    node: str
+    value: Any
+    exit_code: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "node": self.node,
+            "value": self.value,
+            "exit_code": self.exit_code,
+        }
+
+
+@dataclass(frozen=True)
+class ModelNodeResult:
+    node: str
+    ssh_host: str | None
+    models: tuple[dict[str, Any], ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "node": self.node,
+            "ssh_host": self.ssh_host,
+            "models": list(self.models),
+        }
+
+
+@dataclass(frozen=True)
+class ModelNodeError:
+    node: str
+    ssh_host: str
+    error: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "node": self.node,
+            "ssh_host": self.ssh_host,
+            "error": self.error,
+        }
+
+
+@dataclass(frozen=True)
+class ModelListResult:
+    nodes: tuple[ModelNodeResult, ...]
+    errors: tuple[ModelNodeError, ...] = ()
+    exit_code: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "nodes": [item.to_dict() for item in self.nodes],
+            "errors": [item.to_dict() for item in self.errors],
+            "exit_code": self.exit_code,
+        }
+
+
+@dataclass(frozen=True)
+class ModelExportResult:
+    node: str
+    payload: dict[str, Any]
+    jsonl: str
+    exit_code: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "node": self.node,
+            "payload": self.payload,
+            "jsonl": self.jsonl,
+            "exit_code": self.exit_code,
+        }
+
+
+class ModelService:
+    """Own validation, node routing, and model inventory orchestration."""
+
+    def __init__(self, context: ServiceContext):
+        self.context = context
+
+    def _transport(self, node_name: Any) -> tuple[str, Node | None, RpcTransport]:
+        name = _required_string(node_name, "node")
+        node = None if name == "local" else self.context.node_store.get(name)
+        return name, node, self.context.create_transport(node)
+
+    @staticmethod
+    def _ref(request: ModelRefRequest) -> str:
+        return _required_string(request.ref, "model ref")
+
+    def _call(
+        self,
+        node: Any,
+        method: str,
+        params: dict[str, Any],
+        *,
+        exit_code: int = 0,
+    ) -> ModelOperationResult:
+        name, _node, transport = self._transport(node)
+        value = transport.call(method, params)
+        return ModelOperationResult(name, value, exit_code)
+
+    def register(self, request: ModelRegisterRequest) -> ModelOperationResult:
+        ref = _required_string(request.ref, "model ref")
+        path = _required_string(request.path, "model path")
+        scope = _required_string(request.scope, "scope")
+        if scope not in _MODEL_SCOPES:
+            raise ValueError(f"unsupported scope: {scope}")
+        format_name = _optional_string(request.format_name, "format")
+        full_checksum = _boolean(request.full_checksum, "full_checksum")
+        return self._call(
+            request.node,
+            "model.register",
+            {
+                "ref": ref,
+                "path": path,
+                "scope": scope,
+                "format": format_name,
+                "full_checksum": full_checksum,
+            },
+        )
+
+    def discover(self, request: ModelDiscoverRequest) -> ModelOperationResult:
+        root = _required_string(request.root, "discovery root")
+        max_depth = _bounded_integer(
+            request.max_depth,
+            "max_depth",
+            minimum=0,
+            maximum=20,
+        )
+        register = _boolean(request.register, "register")
+        namespace = _required_string(request.namespace, "namespace")
+        if _NAMESPACE_PATTERN.fullmatch(namespace) is None:
+            raise ValueError(
+                "namespace may only contain letters, numbers, dot, underscore, and dash"
+            )
+        return self._call(
+            request.node,
+            "model.discover",
+            {
+                "root": root,
+                "max_depth": max_depth,
+                "register": register,
+                "namespace": namespace,
+            },
+        )
+
+    @staticmethod
+    def _list_params(request: ModelListRequest) -> dict[str, Any]:
+        state = _optional_string(request.state, "state")
+        if state is not None and state not in _MODEL_STATES:
+            raise ValueError(f"unsupported model state: {state}")
+        return {
+            "format": _optional_string(request.format_name, "format"),
+            "model_type": _optional_string(request.model_type, "model_type"),
+            "state": state,
+            "tag": _optional_string(request.tag, "tag"),
+            "name": _optional_string(request.name, "name"),
+            "include_deleted": _boolean(
+                request.include_deleted,
+                "include_deleted",
+            ),
+        }
+
+    def list(self, request: ModelListRequest) -> ModelListResult:
+        all_nodes = _boolean(request.all_nodes, "all_nodes")
+        if all_nodes:
+            if request.node is not None:
+                raise ValueError("node and all_nodes cannot be used together")
+        elif request.node is None:
+            raise ValueError("node or all_nodes is required")
+        params = self._list_params(request)
+
+        if not all_nodes:
+            name, node, transport = self._transport(request.node)
+            models = _model_list_rows(transport.call("model.list", params))
+            return ModelListResult(
+                nodes=(
+                    ModelNodeResult(
+                        node=name,
+                        ssh_host=node.ssh_host if node is not None else None,
+                        models=models,
+                    ),
+                )
+            )
+
+        configured_nodes = self.context.node_store.list()
+        if not configured_nodes:
+            raise ValueError("no SSH nodes registered")
+        nodes: list[ModelNodeResult] = []
+        errors: list[ModelNodeError] = []
+        for node in configured_nodes:
+            try:
+                transport = self.context.create_transport(node)
+                models = _model_list_rows(
+                    transport.call("model.list", params)
+                )
+                nodes.append(
+                    ModelNodeResult(
+                        node=node.name,
+                        ssh_host=node.ssh_host,
+                        models=models,
+                    )
+                )
+            except (
+                RpcError,
+                OSError,
+                ValueError,
+                TypeError,
+                RuntimeError,
+            ) as exc:
+                errors.append(
+                    ModelNodeError(
+                        node=node.name,
+                        ssh_host=node.ssh_host,
+                        error=str(exc),
+                    )
+                )
+        return ModelListResult(
+            nodes=tuple(nodes),
+            errors=tuple(errors),
+            exit_code=1 if errors else 0,
+        )
+
+    def inspect(self, request: ModelRefRequest) -> ModelOperationResult:
+        return self._call(
+            request.node,
+            "model.inspect",
+            {"ref": self._ref(request)},
+        )
+
+    def update(self, request: ModelUpdateRequest) -> ModelOperationResult:
+        description = _optional_string(request.description, "description")
+        clear_description = _boolean(
+            request.clear_description,
+            "clear_description",
+        )
+        if description is not None and clear_description:
+            raise ValueError("description and clear_description cannot be used together")
+        return self._call(
+            request.node,
+            "model.update",
+            {
+                "ref": _required_string(request.ref, "model ref"),
+                "add_aliases": list(
+                    _string_array(request.add_aliases, "add_aliases")
+                ),
+                "remove_aliases": list(
+                    _string_array(request.remove_aliases, "remove_aliases")
+                ),
+                "add_tags": list(_string_array(request.add_tags, "add_tags")),
+                "remove_tags": list(
+                    _string_array(request.remove_tags, "remove_tags")
+                ),
+                "description": description,
+                "clear_description": clear_description,
+            },
+        )
+
+    def delete(self, request: ModelRefRequest) -> ModelOperationResult:
+        return self._call(
+            request.node,
+            "model.delete",
+            {"ref": self._ref(request)},
+        )
+
+    def restore(self, request: ModelRefRequest) -> ModelOperationResult:
+        return self._call(
+            request.node,
+            "model.restore",
+            {"ref": self._ref(request)},
+        )
+
+    def refresh(self, request: ModelRefreshRequest) -> ModelOperationResult:
+        return self._call(
+            request.node,
+            "model.refresh",
+            {
+                "ref": _required_string(request.ref, "model ref"),
+                "path": _optional_string(request.path, "model path"),
+                "full_checksum": _boolean(
+                    request.full_checksum,
+                    "full_checksum",
+                ),
+            },
+        )
+
+    def validate(
+        self,
+        request: ModelValidateRequest,
+    ) -> ModelOperationResult:
+        result = self._call(
+            request.node,
+            "model.validate",
+            {
+                "ref": _required_string(request.ref, "model ref"),
+                "path": _optional_string(request.path, "model path"),
+            },
+        )
+        if not isinstance(result.value, dict) or type(result.value.get("valid")) is not bool:
+            raise ValueError("model.validate response must contain boolean valid")
+        return ModelOperationResult(
+            node=result.node,
+            value=result.value,
+            exit_code=0 if result.value["valid"] else 1,
+        )
+
+    def audit(self, request: ModelAuditRequest) -> ModelOperationResult:
+        ref = _optional_string(request.ref, "model ref")
+        limit = _bounded_integer(
+            request.limit,
+            "audit limit",
+            minimum=1,
+            maximum=1000,
+        )
+        return self._call(
+            request.node,
+            "model.audit",
+            {"ref": ref, "limit": limit},
+        )
+
+    def replica_list(self, request: ModelRefRequest) -> ModelOperationResult:
+        return self._call(
+            request.node,
+            "replica.list",
+            {"ref": self._ref(request)},
+        )
+
+    def replica_add(
+        self,
+        request: ModelReplicaAddRequest,
+    ) -> ModelOperationResult:
+        return self._call(
+            request.node,
+            "replica.add",
+            {
+                "ref": _required_string(request.ref, "model ref"),
+                "path": _required_string(request.path, "replica path"),
+                "full_checksum": _boolean(
+                    request.full_checksum,
+                    "full_checksum",
+                ),
+            },
+        )
+
+    def replica_remove(
+        self,
+        request: ModelReplicaRemoveRequest,
+    ) -> ModelOperationResult:
+        return self._call(
+            request.node,
+            "replica.remove",
+            {
+                "ref": _required_string(request.ref, "model ref"),
+                "path": _required_string(request.path, "replica path"),
+            },
+        )
+
+    def verify(self, request: ModelVerifyRequest) -> ModelOperationResult:
+        result = self._call(
+            request.node,
+            "model.verify",
+            {
+                "ref": _required_string(request.ref, "model ref"),
+                "full_checksum": _boolean(
+                    request.full_checksum,
+                    "full_checksum",
+                ),
+            },
+        )
+        if not isinstance(result.value, dict) or not isinstance(
+            result.value.get("results"),
+            list,
+        ):
+            raise ValueError("model.verify response must contain a results array")
+        entries = result.value["results"]
+        if not entries:
+            raise ValueError("model.verify results must not be empty")
+        states: list[str] = []
+        for index, item in enumerate(entries):
+            if not isinstance(item, dict):
+                raise ValueError(
+                    f"model.verify result {index} must be an object"
+                )
+            state = item.get("state")
+            if state not in _MODEL_STATES:
+                raise ValueError(
+                    f"model.verify result {index} has invalid state: {state!r}"
+                )
+            states.append(state)
+        return ModelOperationResult(
+            node=result.node,
+            value=result.value,
+            exit_code=0 if all(state == "ready" for state in states) else 1,
+        )
+
+    def unregister(
+        self,
+        request: ModelUnregisterRequest,
+    ) -> ModelOperationResult:
+        return self._call(
+            request.node,
+            "model.unregister",
+            {
+                "ref": _required_string(request.ref, "model ref"),
+                "path": _optional_string(request.path, "replica path"),
+            },
+        )
+
+    def export(self, node: Any) -> ModelExportResult:
+        name, _node, transport = self._transport(node)
+        payload = _validate_inventory_payload(transport.call("model.export"))
+        return ModelExportResult(
+            node=name,
+            payload=payload,
+            jsonl=inventory_to_jsonl(payload),
+        )
+
+    def import_records(
+        self,
+        request: ModelImportRequest,
+    ) -> ModelOperationResult:
+        if request.payload is None and request.jsonl is None:
+            raise ValueError("exactly one of payload or jsonl is required")
+        if request.payload is not None and request.jsonl is not None:
+            raise ValueError("payload and jsonl cannot be used together")
+        payload = (
+            _validate_inventory_payload(request.payload)
+            if request.payload is not None
+            else inventory_from_jsonl(request.jsonl)
+        )
+        maps = _root_maps(request.root_maps)
+        return self._call(
+            request.node,
+            "model.import",
+            {
+                "payload": payload,
+                "root_maps": [list(item) for item in maps],
+            },
+        )
+
+    def rebind(self, request: ModelRebindRequest) -> ModelOperationResult:
+        scope = _required_string(request.scope, "scope")
+        if scope not in _MODEL_SCOPES:
+            raise ValueError(f"unsupported scope: {scope}")
+        return self._call(
+            request.node,
+            "model.rebind",
+            {
+                "ref": _required_string(request.ref, "model ref"),
+                "path": _required_string(request.path, "model path"),
+                "scope": scope,
+                "full_checksum": _boolean(
+                    request.full_checksum,
+                    "full_checksum",
+                ),
+            },
+        )