refactor(BA-6041): split MountOption into SessionMountOption and ModelServingMountOption

jopemachine · claude · jopemachine · commit 9c3636c1209e · 2026-05-14T17:27:10.000+09:00
The unified ``MountOption`` introduced in #11608 conflated two distinct wire schemas. ``mount_destination`` was honored only by inference service creation (where ``extra_mounts`` is a single ``dict[UUID, MountOption]`` without a separate destination map). Session creation has always carried destinations via ``mount_map`` / ``mount_id_map`` and never read ``mount_destination`` from ``mount_options[uuid]``. Replace the unified type with two structurally independent classes (no inheritance) so callers cannot mix them up: - ``ai.backend.common.dto.manager.session.types.SessionMountOption`` — used by ``CreationConfigV*.mount_options``; carries ``type``, ``permission``, ``subpath`` only. - ``ai.backend.common.dto.manager.model_serving.request.ModelServingMountOption`` — used by ``ServiceConfigModel.extra_mounts``; adds ``mount_destination`` on top of the same three fields. All SDK / manager / test callers are updated accordingly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/changes/11610.enhance.md b/changes/11610.enhance.md
@@ -0,0 +1 @@
+Split the unified `MountOption` into two distinct types — `SessionMountOption` (in `common/dto/manager/session/types`) and `ModelServingMountOption` (in `common/dto/manager/model_serving/request`) — so the wire schemas cannot accidentally cross paths. Session creation does not accept inline `mount_destination` (destinations come from `mount_map` / `mount_id_map`); inference service creation embeds `mount_destination` per-vfolder. The two types are kept structurally independent rather than inheriting, so callers must explicitly pick the right one.
diff --git a/src/ai/backend/client/cli/service.py b/src/ai/backend/client/cli/service.py
@@ -19,7 +19,7 @@
 from ai.backend.client.session import AsyncSession, Session
 from ai.backend.common.arch import DEFAULT_IMAGE_ARCH
 from ai.backend.common.bgtask.types import BgtaskStatus
-from ai.backend.common.dto.manager.session.types import MountOption
+from ai.backend.common.dto.manager.model_serving.request import ModelServingMountOption
 from ai.backend.common.types import ClusterMode, RuntimeVariant
 
 from .extensions import pass_ctx_obj
@@ -326,7 +326,7 @@ def create(
     parsed_resources = prepare_resource_arg(resources)
     parsed_resource_opts = prepare_resource_arg(resource_opts)
     extra_mount_options = {
-        key: MountOption.model_validate(opts) for key, opts in mount_options.items()
+        key: ModelServingMountOption.model_validate(opts) for key, opts in mount_options.items()
     }
     body = {
         "service_name": name,
diff --git a/src/ai/backend/client/cli/session/execute.py b/src/ai/backend/client/cli/session/execute.py
@@ -41,7 +41,7 @@
 if TYPE_CHECKING:
     from ai.backend.client.func.session import ComputeSession
 from ai.backend.common.arch import DEFAULT_IMAGE_ARCH
-from ai.backend.common.dto.manager.session.types import MountOption
+from ai.backend.common.dto.manager.session.types import SessionMountOption
 from ai.backend.common.types import ClusterMode, MountExpression
 
 from .args import click_start_option
@@ -477,7 +477,7 @@ def run(
     resource_opts = prepare_resource_arg(resource_opts)
     mount, mount_map, raw_mount_options = prepare_mount_arg(mount, escape=True)
     mount_options = {
-        key: MountOption.model_validate(opts) for key, opts in raw_mount_options.items()
+        key: SessionMountOption.model_validate(opts) for key, opts in raw_mount_options.items()
     }
 
     env_ranges: dict[str, Any] = {v: r for v, r in env_range}  # type: ignore[has-type]
diff --git a/src/ai/backend/client/cli/session/lifecycle.py b/src/ai/backend/client/cli/session/lifecycle.py
@@ -43,7 +43,7 @@
 from ai.backend.client.session import AsyncSession, Session
 from ai.backend.common.arch import DEFAULT_IMAGE_ARCH
 from ai.backend.common.bgtask.types import BgtaskStatus
-from ai.backend.common.dto.manager.session.types import MountOption
+from ai.backend.common.dto.manager.session.types import SessionMountOption
 from ai.backend.common.types import ClusterMode
 
 from .args import click_start_option
@@ -199,7 +199,7 @@ def create(
         parsed_resource_opts = prepare_resource_arg(resource_opts)
         mount, mount_map, raw_mount_options = prepare_mount_arg(mount, escape=True)
         mount_options = {
-            key: MountOption.model_validate(opts) for key, opts in raw_mount_options.items()
+            key: SessionMountOption.model_validate(opts) for key, opts in raw_mount_options.items()
         }
 
         preopen_ports = preopen
diff --git a/src/ai/backend/client/func/service.py b/src/ai/backend/client/func/service.py
@@ -13,7 +13,7 @@
 from ai.backend.client.session import api_session
 from ai.backend.client.utils import dedent as _d
 from ai.backend.common.arch import DEFAULT_IMAGE_ARCH
-from ai.backend.common.dto.manager.session.types import MountOption
+from ai.backend.common.dto.manager.model_serving.request import ModelServingMountOption
 from ai.backend.common.typed_validators import SESSION_NAME_MAX_LENGTH
 from ai.backend.common.types import RuntimeVariant
 
@@ -104,7 +104,7 @@ async def create(
         scaling_group: str,
         extra_mounts: Sequence[str] | None = None,
         extra_mount_map: Mapping[str, str] | None = None,
-        extra_mount_options: Mapping[str, MountOption] | None = None,
+        extra_mount_options: Mapping[str, ModelServingMountOption] | None = None,
         service_name: str | None = None,
         model_version: str | None = None,
         _dependencies: Sequence[str] | None = None,
@@ -183,7 +183,7 @@ async def create(
                     if mount not in vfolder_name_to_id:
                         raise BackendClientError(f"VFolder (name: {mount}) not found") from e
                     vfolder_id = vfolder_name_to_id[mount]
-                options = extra_mount_options.get(mount) or MountOption()
+                options = extra_mount_options.get(mount) or ModelServingMountOption()
                 body = options.model_dump(exclude_none=True)
                 if (dest := extra_mount_map.get(mount)) is not None:
                     body["mount_destination"] = dest
diff --git a/src/ai/backend/client/func/session.py b/src/ai/backend/client/func/session.py
@@ -44,7 +44,7 @@
 from ai.backend.client.utils import dedent as _d
 from ai.backend.client.versioning import get_id_or_name, get_naming
 from ai.backend.common.arch import DEFAULT_IMAGE_ARCH
-from ai.backend.common.dto.manager.session.types import MountOption
+from ai.backend.common.dto.manager.session.types import SessionMountOption
 from ai.backend.common.types import ClusterMode, SessionTypes
 
 from .base import BaseFunction, api_function
@@ -211,7 +211,7 @@ async def get_or_create(
         mount_map: Mapping[str, str] | None = None,
         mount_ids: list[UUID] | None = None,
         mount_id_map: Mapping[UUID, str] | None = None,
-        mount_options: Mapping[str, MountOption] | None = None,
+        mount_options: Mapping[str, SessionMountOption] | None = None,
         envs: Mapping[str, str] | None = None,
         startup_command: str | None = None,
         batch_timeout: str | int | None = None,
@@ -1424,7 +1424,7 @@ async def get_or_create(
         callback_url: str | None = None,
         mounts: list[str] | None = None,
         mount_map: Mapping[str, str] | None = None,
-        mount_options: Mapping[str, MountOption] | None = None,
+        mount_options: Mapping[str, SessionMountOption] | None = None,
         mount_ids: list[UUID] | None = None,
         mount_id_map: Mapping[UUID, str] | None = None,
         envs: Mapping[str, str] | None = None,
diff --git a/src/ai/backend/common/dto/manager/model_serving/request.py b/src/ai/backend/common/dto/manager/model_serving/request.py
@@ -19,10 +19,9 @@
 )
 
 from ai.backend.common import typed_validators as tv
-from ai.backend.common.api_handlers import BaseRequestModel
+from ai.backend.common.api_handlers import BaseFieldModel, BaseRequestModel
 from ai.backend.common.dto.manager.query import StringFilter
-from ai.backend.common.dto.manager.session.types import MountOption
-from ai.backend.common.types import RuntimeVariant
+from ai.backend.common.types import MountPermission, MountTypes, RuntimeVariant
 
 __all__ = (
     # Path param models
@@ -32,6 +31,7 @@
     "ListServeRequestModel",
     "ServiceFilterModel",
     "SearchServicesRequestModel",
+    "ModelServingMountOption",
     "ServiceConfigModel",
     "NewServiceRequestModel",
     "ScaleRequestModel",
@@ -40,6 +40,40 @@
 )
 
 
+class ModelServingMountOption(BaseFieldModel):
+    """Per-mount option used inside ``ServiceConfigModel.extra_mounts``.
+
+    Inference service creation embeds the per-vfolder mount destination inline
+    because the wire schema has no separate destination map for ``extra_mounts``.
+    Session creation uses
+    :class:`ai.backend.common.dto.manager.session.types.SessionMountOption`
+    instead and supplies destinations via ``mount_map`` / ``mount_id_map``;
+    the two types are kept structurally distinct so callers cannot accidentally
+    use one where the other is expected.
+    """
+
+    mount_destination: str | None = Field(
+        default=None,
+        description=(
+            "Mount destination inside the container. Defaults to ``/home/work/{folder_name}``."
+        ),
+    )
+    type: MountTypes = MountTypes.BIND
+    permission: MountPermission | None = Field(
+        default=None,
+        validation_alias=AliasChoices("permission", "perm"),
+    )
+    subpath: str | None = Field(
+        default=None,
+        min_length=1,
+        description=(
+            "Subpath within the vfolder to mount. ``null`` (default) mounts the vfolder root."
+            " Empty string is rejected; omit the field to mount the root."
+        ),
+    )
+    model_config = ConfigDict(extra="allow")
+
+
 class ServiceIdPathParam(BaseRequestModel):
     service_id: uuid.UUID
 
@@ -95,7 +129,7 @@ class ServiceConfigModel(BaseRequestModel):
         alias="vfolderSubpath",
     )
 
-    extra_mounts: dict[uuid.UUID, MountOption] = Field(
+    extra_mounts: dict[uuid.UUID, ModelServingMountOption] = Field(
         description=(
             "Specifications about extra VFolders mounted to model service session. "
             "MODEL type VFolders are not allowed to be attached to model service session"
diff --git a/src/ai/backend/common/dto/manager/session/__init__.py b/src/ai/backend/common/dto/manager/session/__init__.py
@@ -56,14 +56,14 @@
     CreationConfigV6,
     CreationConfigV6Template,
     CreationConfigV7,
-    MountOption,
     ResourceOpts,
+    SessionMountOption,
 )
 
 __all__ = (
     # Types
     "ResourceOpts",
-    "MountOption",
+    "SessionMountOption",
     "CreationConfigV1",
     "CreationConfigV2",
     "CreationConfigV3",
diff --git a/src/ai/backend/common/dto/manager/session/types.py b/src/ai/backend/common/dto/manager/session/types.py
@@ -22,7 +22,7 @@
     "TimeoutSeconds",
     # Shared field models
     "ResourceOpts",
-    "MountOption",
+    "SessionMountOption",
     # Creation configs
     "CreationConfigV1",
     "CreationConfigV2",
@@ -144,18 +144,15 @@ class ResourceOpts(BaseFieldModel):
     model_config = ConfigDict(extra="allow")
 
 
-class MountOption(BaseFieldModel):
-    """Per-mount option used inside ``mount_options`` mapping.
+class SessionMountOption(BaseFieldModel):
+    """Per-mount option used inside ``CreationConfigV*.mount_options``.
 
-    Single source of truth for per-vfolder mount overrides — used by both
-    session creation (``CreationConfigV*.mount_options``) and inference
-    service creation (``ServiceConfigModel.extra_mounts``).
+    Session creation does NOT accept inline ``mount_destination`` — destinations
+    are supplied separately via ``mount_map`` / ``mount_id_map``. For inference
+    service creation (which embeds the destination per-vfolder), see
+    :class:`ai.backend.common.dto.manager.model_serving.request.ModelServingMountOption`.
     """
 
-    mount_destination: str | None = Field(
-        default=None,
-        description="Mount destination inside the container. Defaults to ``/home/work/{folder_name}``.",
-    )
     type: MountTypes = MountTypes.BIND
     permission: MountPermission | None = Field(
         default=None,
@@ -331,7 +328,7 @@ class CreationConfigV5(BaseFieldModel):
         default=None,
         validation_alias=AliasChoices("mount_map", "mountMap"),
     )
-    mount_options: dict[str, MountOption] | None = Field(
+    mount_options: dict[str, SessionMountOption] | None = Field(
         default=None,
         validation_alias=AliasChoices("mount_options", "mountOptions"),
     )
@@ -383,7 +380,7 @@ class CreationConfigV6(BaseFieldModel):
         default=None,
         validation_alias=AliasChoices("mount_map", "mountMap"),
     )
-    mount_options: dict[str, MountOption] | None = Field(
+    mount_options: dict[str, SessionMountOption] | None = Field(
         default=None,
         validation_alias=AliasChoices("mount_options", "mountOptions"),
     )
@@ -448,7 +445,7 @@ class CreationConfigV7(BaseFieldModel):
         default=None,
         validation_alias=AliasChoices("mount_id_map", "mountIdMap"),
     )
-    mount_options: dict[str, MountOption] | None = Field(
+    mount_options: dict[str, SessionMountOption] | None = Field(
         default=None,
         validation_alias=AliasChoices("mount_options", "mountOptions"),
     )
diff --git a/src/ai/backend/manager/data/model_serving/types.py b/src/ai/backend/manager/data/model_serving/types.py
@@ -13,7 +13,9 @@
 from ai.backend.common.config import ModelDefinition
 from ai.backend.common.data.endpoint.types import EndpointLifecycle, ScalingState
 from ai.backend.common.data.user.types import UserRole
-from ai.backend.common.dto.manager.session.types import MountOption as MountOptionDTO
+from ai.backend.common.dto.manager.model_serving.request import (
+    ModelServingMountOption as MountOptionDTO,
+)
 from ai.backend.common.identifier.deployment import DeploymentID
 from ai.backend.common.identifier.runtime_variant import RuntimeVariantID
 from ai.backend.common.identifier.vfolder import VFolderUUID
diff --git a/tests/unit/common/dto/manager/session/test_types.py b/tests/unit/common/dto/manager/session/test_types.py
@@ -17,8 +17,8 @@
     CreationConfigV6,
     CreationConfigV6Template,
     CreationConfigV7,
-    MountOption,
     ResourceOpts,
+    SessionMountOption,
     TimeoutSeconds,
 )
 from ai.backend.common.exception import BackendAISchemaValidationFailed
@@ -41,18 +41,18 @@ def test_extra_fields_allowed(self) -> None:
         assert opts.model_extra["custom_key"] == "custom_val"
 
 
-class TestMountOption:
+class TestSessionMountOption:
     def test_defaults(self) -> None:
-        opt = MountOption()
+        opt = SessionMountOption()
         assert opt.type == MountTypes.BIND
         assert opt.permission is None
 
     def test_with_permission_alias(self) -> None:
-        opt = MountOption.model_validate({"perm": "ro"})
+        opt = SessionMountOption.model_validate({"perm": "ro"})
         assert opt.permission == MountPermission.READ_ONLY
 
     def test_extra_fields_allowed(self) -> None:
-        opt = MountOption.model_validate({"type": "bind", "extra": True})
+        opt = SessionMountOption.model_validate({"type": "bind", "extra": True})
         assert opt.model_extra is not None
         assert opt.model_extra["extra"] is True
 
diff --git a/tests/unit/manager/test_registry.py b/tests/unit/manager/test_registry.py
@@ -18,6 +18,7 @@
     ModelHealthCheck,
     ModelServiceConfig,
 )
+from ai.backend.common.dto.manager.model_serving.request import ModelServingMountOption
 from ai.backend.common.events.event_types.session.broadcast import SchedulingBroadcastEvent
 from ai.backend.common.events.types import AbstractEvent
 from ai.backend.common.plugin.hook import HookPluginContext
@@ -28,6 +29,7 @@
     SlotName,
 )
 from ai.backend.manager.config.provider import ManagerConfigProvider
+from ai.backend.manager.data.model_serving.types import MountOption
 from ai.backend.manager.data.session.types import SessionStatus
 from ai.backend.manager.errors.kernel import SessionNotFound
 from ai.backend.manager.plugin.network import NetworkPluginContext
@@ -392,3 +394,43 @@ async def _hang(cache_id: str) -> AsyncIterator[AbstractEvent]:
                 await mock_registry_obj._wait_for_session_running(
                     session_id, mock_propagator, max_wait=0
                 )
+
+
+class TestMountDestinationAsymmetry:
+    """``mount_destination`` is part of ``ModelServingMountOption`` but not of
+    ``SessionMountOption``: session creation reads destinations from
+    ``mount_map`` / ``mount_id_map`` and never from ``mount_options[uuid]``,
+    while inference service creation embeds it inline in ``extra_mounts``.
+    """
+
+    def test_session_creation_drops_mount_destination_from_mount_options(self) -> None:
+        vfid = uuid.uuid4()
+        # Even if a caller smuggles in a ``mount_destination`` (allowed by the
+        # ``extra="allow"`` config on SessionMountOption), the session-side
+        # mount entry builder ignores it.
+        creation_config = {
+            "mount_ids": [vfid],
+            "mount_id_map": {},  # caller did not provide a destination here
+            "mount_options": {
+                vfid: {"mount_destination": "/should/be/ignored", "permission": "ro"},
+            },
+        }
+
+        entries = AgentRegistry._mount_entries_from_creation_config(creation_config)
+
+        assert len(entries) == 1
+        # ``mount_destination`` from mount_options is silently dropped — only
+        # mount_id_map can supply destinations for session creation.
+        assert entries[0].mount_destination is None
+
+    def test_inference_service_preserves_mount_destination_via_from_dto(self) -> None:
+        dto = ModelServingMountOption.model_validate({
+            "mount_destination": "/models/extra",
+            "perm": "ro",
+        })
+
+        data = MountOption.from_dto(dto)
+
+        # Service-creation flow carries mount_destination through to the data
+        # layer (and ultimately to VFolderMount.kernel_path).
+        assert data.mount_destination == "/models/extra"

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Split the unified `MountOption` into two distinct types — `SessionMountOption` (in `common/dto/manager/session/types`) and `ModelServingMountOption` (in `common/dto/manager/model_serving/request`) — so the wire schemas cannot accidentally cross paths. Session creation does not accept inline `mount_destination` (destinations come from `mount_map` / `mount_id_map`); inference service creation embeds `mount_destination` per-vfolder. The two types are kept structurally independent rather than inheriting, so callers must explicitly pick the right one.