refactor(domain): operator-visible deprecation for instance_type/instance_profile

The instance_type->machine_type and instance_profile->machine_role
aliases only warned on the Python-kwarg path; the model_validate /
YAML deserialization path that operators actually use accepted the old
key silently (AliasChoices), and the repo's warnings filter suppresses
DeprecationWarning even in tests.

Move the deprecation signal to a model_validator(mode="before") that
emits logger.warning on every deserialization path, and mark the new
fields with Field(deprecated=...) for OpenAPI/schema visibility. The
application-layer command handler emits a single operator-visible
warning at the boundary where instance_type is mapped to machine_types.

This establishes the house pattern for operator-facing Pydantic field
deprecations: AliasChoices for back-compat + model_validator(mode=before)
logger.warning for the runtime signal + Field(deprecated=) for schema.

Author: fgogolli

src/orb/application/commands/template_handlers.py

@@ -1,6 +1,10 @@
 """Template command handlers for CQRS pattern."""
 
+import logging
+
 from orb.application.base.handlers import BaseCommandHandler
+
+_logger = logging.getLogger(__name__)
 from orb.application.decorators import command_handler
 from orb.application.template.commands import (
     CreateTemplateCommand,
@@ -98,6 +102,9 @@ async def execute_command(self, command: CreateTemplateCommand) -> None:
         }
         # instance_type → machine_types (backward compat)
         if command.instance_type is not None and "machine_types" not in dto_fields:
+            _logger.warning(
+                "CreateTemplateCommand.instance_type is deprecated; use machine_type instead."
+            )
             dto_fields["machine_types"] = {command.instance_type: 1}
         # Remove None values so TemplateDTO defaults apply
         dto_fields = {k: v for k, v in dto_fields.items() if v is not None}
@@ -171,6 +178,9 @@ async def execute_command(self, command: UpdateTemplateCommand) -> None:
 
         # instance_type → machine_types (backward compat)
         if command.instance_type is not None and "machine_types" not in update_fields:
+            _logger.warning(
+                "UpdateTemplateCommand.instance_type is deprecated; use machine_type instead."
+            )
             update_fields["machine_types"] = {command.instance_type: 1}
 
         if update_fields:

src/orb/domain/template/template_aggregate.py

@@ -1,11 +1,14 @@
 """Template configuration value object - core template domain logic."""
 
+import logging
 import warnings
 from datetime import datetime
 from typing import Any, Optional
 
 from pydantic import AliasChoices, BaseModel, ConfigDict, Field, model_validator
 
+logger = logging.getLogger(__name__)
+
 
 class Template(BaseModel):
     """Template configuration value object with both snake_case and camelCase support via aliases."""
@@ -25,6 +28,7 @@ class Template(BaseModel):
     machine_type: Optional[str] = Field(
         default=None,
         validation_alias=AliasChoices("machine_type", "instance_type"),
+        deprecated="use 'machine_type' instead of 'instance_type'",
     )
     image_id: Optional[str] = None
     max_instances: int = 1
@@ -61,6 +65,7 @@ class Template(BaseModel):
     machine_role: Optional[str] = Field(
         default=None,
         validation_alias=AliasChoices("machine_role", "instance_profile"),
+        deprecated="use 'machine_role' instead of 'instance_profile'",
     )  # IAM role, service principal, or service account
 
     # Advanced configuration (extensible)
@@ -82,6 +87,42 @@ class Template(BaseModel):
     # Active status flag
     is_active: bool = True
 
+    @model_validator(mode="before")
+    @classmethod
+    def _warn_deprecated_field_names(cls, data: Any) -> Any:
+        """House pattern for operator-facing Pydantic field deprecation.
+
+        This is the canonical way to emit operator-visible deprecation warnings
+        for renamed fields in this codebase.  It runs on the raw input dict
+        before Pydantic applies AliasChoices, so it fires on EVERY entry point:
+        ``model_validate()``, YAML/JSON deserialization, and ``__init__`` kwargs.
+
+        Pattern:
+          1. Keep ``AliasChoices("new_name", "old_name")`` on the new field so
+             old data still deserializes without a hard error.
+          2. Add this ``model_validator(mode="before")`` to emit
+             ``logger.warning(...)`` for each deprecated key present in the raw
+             input.  The logger message appears in server logs where operators
+             can see it, unlike ``warnings.warn`` which is filtered in tests and
+             production by default.
+          3. Mark the new field with ``Field(..., deprecated="...")`` for
+             OpenAPI/JSON-schema visibility (requires Pydantic >= 2.7).
+          4. Keep ``warnings.warn(DeprecationWarning)`` in ``__init__`` as a
+             developer/test signal (visible via ``python -W`` or
+             ``pytest.warns``).
+        """
+        if not isinstance(data, dict):
+            return data
+        if "instance_type" in data and "machine_type" not in data:
+            logger.warning(
+                "Template field 'instance_type' is deprecated; use 'machine_type' instead."
+            )
+        if "instance_profile" in data and "machine_role" not in data:
+            logger.warning(
+                "Template field 'instance_profile' is deprecated; use 'machine_role' instead."
+            )
+        return data
+
     def __init__(self, **data: Any) -> None:
         """Initialize template with default values and validation.
 
@@ -91,30 +132,35 @@ def __init__(self, **data: Any) -> None:
         Note:
             Sets default name from template_id if not provided.
             Sets default timestamps if not provided.
-            The deprecated ``instance_type`` keyword argument is accepted and
-            silently promoted to ``machine_type``; a DeprecationWarning is
-            emitted to encourage callers to update.
+            The deprecated ``instance_type`` kwarg is accepted and mapped to
+            ``machine_type`` by Pydantic's AliasChoices; a DeprecationWarning
+            is emitted here as a developer-visible signal (pytest.warns / -W),
+            while the operator-visible logger.warning is emitted by the
+            ``_warn_deprecated_field_names`` model_validator above.
+
+            IMPORTANT: do NOT pop the deprecated key here — popping before
+            calling ``super().__init__`` would hide the key from the
+            model_validator(mode="before"), preventing the logger.warning.
+            AliasChoices handles the field mapping after model_validator fires.
         """
-        # Promote deprecated instance_type kwarg → machine_type.
-        # validation_alias handles model_validate() paths; __init__ kwargs need
-        # explicit handling here because Pydantic v2 validation_alias is not
-        # applied to __init__ keyword arguments.
+        # Emit developer-facing DeprecationWarning for deprecated kwarg names.
+        # Do NOT pop the keys — leave them in data so that model_validator
+        # (mode="before") can see them and emit the operator-visible logger.warning.
+        # AliasChoices will map instance_type → machine_type and
+        # instance_profile → machine_role during Pydantic's validation pass.
         if "instance_type" in data and "machine_type" not in data:
             warnings.warn(
                 "Template field 'instance_type' is deprecated; use 'machine_type' instead.",
                 DeprecationWarning,
                 stacklevel=2,
             )
-            data["machine_type"] = data.pop("instance_type")
 
-        # Promote deprecated instance_profile kwarg → machine_role.
         if "instance_profile" in data and "machine_role" not in data:
             warnings.warn(
                 "Template field 'instance_profile' is deprecated; use 'machine_role' instead.",
                 DeprecationWarning,
                 stacklevel=2,
             )
-            data["machine_role"] = data.pop("instance_profile")
 
         # Set default name if not provided
         if "name" not in data and "template_id" in data:

tests/unit/application/commands/test_template_command_handlers.py

@@ -1,5 +1,6 @@
 """Unit tests for template command handlers — TDD for store-unification fix."""
 
+import logging
 from unittest.mock import AsyncMock, Mock
 
 import pytest
@@ -238,3 +239,86 @@ async def test_update_validation_errors_sets_updated_false() -> None:
     assert command.updated is False
     assert command.validation_errors == ["invalid field"]
     manager.save_template.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# Deprecation warning tests — application-layer handler boundary
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_create_handler_warns_on_instance_type(caplog) -> None:
+    """CreateTemplateHandler emits logger.warning when instance_type is used."""
+    manager = _make_manager(existing=None)
+    port = _make_template_port(manager)
+    handler = _make_create_handler(port)
+
+    command = CreateTemplateCommand(
+        template_id="tpl-dep-1",
+        provider_api="EC2Fleet",
+        image_id="ami-000",
+        instance_type="m5.xlarge",
+    )
+
+    with caplog.at_level(logging.WARNING, logger="orb.application.commands.template_handlers"):
+        await handler.handle(command)
+
+    assert command.created is True
+    assert any(
+        "instance_type" in r.message and "deprecated" in r.message for r in caplog.records
+    ), f"Expected deprecation log for instance_type; got: {[r.message for r in caplog.records]}"
+
+    # Value is mapped into machine_types on the saved DTO
+    saved = manager.save_template.call_args[0][0]
+    assert saved.machine_types == {"m5.xlarge": 1}
+
+
+@pytest.mark.asyncio
+async def test_update_handler_warns_on_instance_type(caplog) -> None:
+    """UpdateTemplateHandler emits logger.warning when instance_type is used."""
+    existing = _make_dto()
+    manager = _make_manager(existing=existing)
+    port = _make_template_port(manager)
+    handler = _make_update_handler(port)
+
+    command = UpdateTemplateCommand(
+        template_id="tpl-dep-2",
+        instance_type="c5.2xlarge",
+    )
+
+    with caplog.at_level(logging.WARNING, logger="orb.application.commands.template_handlers"):
+        await handler.handle(command)
+
+    assert command.updated is True
+    assert any(
+        "instance_type" in r.message and "deprecated" in r.message for r in caplog.records
+    ), f"Expected deprecation log for instance_type; got: {[r.message for r in caplog.records]}"
+
+    # Value is mapped into machine_types on the saved DTO
+    saved = manager.save_template.call_args[0][0]
+    assert saved.machine_types == {"c5.2xlarge": 1}
+
+
+@pytest.mark.asyncio
+async def test_create_handler_no_warn_without_instance_type(caplog) -> None:
+    """CreateTemplateHandler does NOT emit a deprecation log when machine_type is used."""
+    manager = _make_manager(existing=None)
+    port = _make_template_port(manager)
+    handler = _make_create_handler(port)
+
+    command = CreateTemplateCommand(
+        template_id="tpl-nodep-1",
+        provider_api="EC2Fleet",
+        image_id="ami-000",
+        machine_type="t3.medium",
+    )
+
+    with caplog.at_level(logging.WARNING, logger="orb.application.commands.template_handlers"):
+        await handler.handle(command)
+
+    deprecation_records = [
+        r for r in caplog.records if "instance_type" in r.message and "deprecated" in r.message
+    ]
+    assert not deprecation_records, (
+        f"Unexpected deprecation log when using machine_type: {[r.message for r in deprecation_records]}"
+    )

tests/unit/domain/test_template_aggregate.py

@@ -549,6 +549,107 @@ def test_old_name_instance_profile_not_readable_as_attribute(self):
         )
 
 
+@pytest.mark.unit
+class TestTemplateDeprecatedAliasesLoggerWarning:
+    """Tests that deprecated field names emit logger.warning on ALL deserialization paths.
+
+    AliasChoices silently accepts old keys via model_validate — these tests
+    assert that operators see a warning in server logs even when using the
+    YAML/JSON deserialization path (not just the Python-kwarg path).
+    """
+
+    def test_model_validate_instance_type_emits_logger_warning(self, caplog):
+        """model_validate with deprecated 'instance_type' emits a logger.warning."""
+        import logging
+
+        with caplog.at_level(logging.WARNING, logger="orb.domain.template.template_aggregate"):
+            t = Template.model_validate({"template_id": "lw-1", "instance_type": "m5.large"})
+        assert t.machine_type == "m5.large"
+        assert any(
+            "instance_type" in r.message and "deprecated" in r.message for r in caplog.records
+        ), f"Expected deprecation log for instance_type; got: {[r.message for r in caplog.records]}"
+
+    def test_model_validate_instance_profile_emits_logger_warning(self, caplog):
+        """model_validate with deprecated 'instance_profile' emits a logger.warning."""
+        import logging
+
+        with caplog.at_level(logging.WARNING, logger="orb.domain.template.template_aggregate"):
+            t = Template.model_validate(
+                {
+                    "template_id": "lw-2",
+                    "instance_profile": "arn:aws:iam::123456789012:instance-profile/legacy",
+                }
+            )
+        assert t.machine_role == "arn:aws:iam::123456789012:instance-profile/legacy"
+        assert any(
+            "instance_profile" in r.message and "deprecated" in r.message for r in caplog.records
+        ), (
+            f"Expected deprecation log for instance_profile; got: {[r.message for r in caplog.records]}"
+        )
+
+    def test_kwarg_instance_type_emits_logger_warning(self, caplog):
+        """Template(instance_type=...) kwarg path also emits logger.warning (via model_validator)."""
+        import logging
+
+        with caplog.at_level(logging.WARNING, logger="orb.domain.template.template_aggregate"):
+            with pytest.warns(DeprecationWarning):
+                t = Template(template_id="lw-3", instance_type="c5.xlarge")
+        assert t.machine_type == "c5.xlarge"
+        assert any(
+            "instance_type" in r.message and "deprecated" in r.message for r in caplog.records
+        ), (
+            f"Expected deprecation log for instance_type kwarg; got: {[r.message for r in caplog.records]}"
+        )
+
+    def test_kwarg_instance_profile_emits_logger_warning(self, caplog):
+        """Template(instance_profile=...) kwarg path also emits logger.warning (via model_validator)."""
+        import logging
+
+        with caplog.at_level(logging.WARNING, logger="orb.domain.template.template_aggregate"):
+            with pytest.warns(DeprecationWarning):
+                t = Template(
+                    template_id="lw-4",
+                    instance_profile="arn:aws:iam::123456789012:instance-profile/worker",
+                )
+        assert t.machine_role == "arn:aws:iam::123456789012:instance-profile/worker"
+        assert any(
+            "instance_profile" in r.message and "deprecated" in r.message for r in caplog.records
+        ), (
+            f"Expected deprecation log for instance_profile kwarg; got: {[r.message for r in caplog.records]}"
+        )
+
+    def test_new_field_names_emit_no_logger_warning(self, caplog):
+        """Using machine_type / machine_role directly produces no deprecation log."""
+        import logging
+
+        with caplog.at_level(logging.WARNING, logger="orb.domain.template.template_aggregate"):
+            t = Template.model_validate(
+                {
+                    "template_id": "lw-5",
+                    "machine_type": "t3.medium",
+                    "machine_role": "arn:aws:iam::123456789012:instance-profile/new",
+                }
+            )
+        assert t.machine_type == "t3.medium"
+        assert t.machine_role == "arn:aws:iam::123456789012:instance-profile/new"
+        assert not caplog.records, (
+            f"Expected no deprecation log with new field names; got: {[r.message for r in caplog.records]}"
+        )
+
+    def test_model_validate_instance_type_warns_once(self, caplog):
+        """Exactly one warning is emitted per deprecated key per model_validate call."""
+        import logging
+
+        with caplog.at_level(logging.WARNING, logger="orb.domain.template.template_aggregate"):
+            Template.model_validate({"template_id": "lw-6", "instance_type": "r5.large"})
+        instance_type_warnings = [
+            r for r in caplog.records if "instance_type" in r.message and "deprecated" in r.message
+        ]
+        assert len(instance_type_warnings) == 1, (
+            f"Expected exactly 1 warning; got {len(instance_type_warnings)}"
+        )
+
+
 @pytest.mark.unit
 class TestTemplateExceptions:
     """Test cases for Template-specific exceptions."""