@ngocsangairvds/vsaf 4.0.6 → 4.0.7

package/skills/vds-skill/vds-scripts/platform_core/tests/test_protocols.py

@@ -0,0 +1,132 @@
+"""Tests for vds_platform_core.protocols — TSK-7.1.
+
+Duck-type verification for all three runtime_checkable Protocols.
+Note: Python's @runtime_checkable isinstance() checks presence of method/attribute
+*names* only — not signatures. A class with the right names but wrong signatures
+still passes isinstance() at runtime; this is expected Protocol behavior.
+"""
+
+from __future__ import annotations
+
+from vds_platform_core.protocols import CredentialResolver, HTTPClient, RetryPolicy
+
+# ---------------------------------------------------------------------------
+# HTTPClient — 3 tests
+# ---------------------------------------------------------------------------
+
+
+class _GoodHTTPClient:
+    """Minimal valid HTTPClient implementation."""
+
+    async def get(self, url: str, **kw: object) -> object:
+        return None
+
+    async def post(self, url: str, **kw: object) -> object:
+        return None
+
+    async def aclose(self) -> None:
+        pass
+
+
+class _MissingAcloseHTTPClient:
+    async def get(self, url: str, **kw: object) -> object:
+        return None
+
+    async def post(self, url: str, **kw: object) -> object:
+        return None
+
+
+class _MissingPostHTTPClient:
+    async def get(self, url: str, **kw: object) -> object:
+        return None
+
+    async def aclose(self) -> None:
+        pass
+
+
+def test_http_client_positive() -> None:
+    """Object with all required methods passes isinstance check."""
+    assert isinstance(_GoodHTTPClient(), HTTPClient)
+
+
+def test_http_client_missing_aclose() -> None:
+    """Object missing aclose() fails isinstance check."""
+    assert not isinstance(_MissingAcloseHTTPClient(), HTTPClient)
+
+
+def test_http_client_missing_post() -> None:
+    """Object missing post() fails isinstance check."""
+    assert not isinstance(_MissingPostHTTPClient(), HTTPClient)
+
+
+# ---------------------------------------------------------------------------
+# CredentialResolver — 3 tests
+# ---------------------------------------------------------------------------
+
+
+class _GoodCredentialResolver:
+    def resolve(self) -> str | None:
+        return "secret"
+
+
+class _MissingResolveCredentialResolver:
+    def something_else(self) -> str:
+        return ""
+
+
+class _WrongNameCredentialResolver:
+    def resolver(self) -> str | None:  # typo: resolver vs resolve
+        return None
+
+
+def test_credential_resolver_positive() -> None:
+    """Object with resolve() passes isinstance check."""
+    assert isinstance(_GoodCredentialResolver(), CredentialResolver)
+
+
+def test_credential_resolver_missing_resolve() -> None:
+    """Object missing resolve() fails isinstance check."""
+    assert not isinstance(_MissingResolveCredentialResolver(), CredentialResolver)
+
+
+def test_credential_resolver_wrong_method_name() -> None:
+    """Object with misspelled method name fails isinstance check."""
+    assert not isinstance(_WrongNameCredentialResolver(), CredentialResolver)
+
+
+# ---------------------------------------------------------------------------
+# RetryPolicy — 3 tests
+# ---------------------------------------------------------------------------
+
+
+class _GoodRetryPolicy:
+    def can_retry(self, attempt: int, exc: BaseException) -> bool:
+        return attempt < 3
+
+    def wait_seconds(self, attempt: int) -> float:
+        return 2.0**attempt
+
+
+class _MissingWaitSecondsRetryPolicy:
+    def can_retry(self, attempt: int, exc: BaseException) -> bool:
+        return False
+
+
+class _MissingCanRetryPolicy:
+    def wait_seconds(self, attempt: int) -> float:
+        return 1.0
+
+
+def test_retry_policy_positive() -> None:
+    """Object with both required methods passes isinstance check."""
+    assert isinstance(_GoodRetryPolicy(), RetryPolicy)
+
+
+def test_retry_policy_missing_wait_seconds() -> None:
+    """Object missing wait_seconds() fails isinstance check."""
+    assert not isinstance(_MissingWaitSecondsRetryPolicy(), RetryPolicy)
+
+
+def test_retry_policy_missing_can_retry() -> None:
+    """Object missing can_retry() fails isinstance check."""
+    assert not isinstance(_MissingCanRetryPolicy(), RetryPolicy)

package/skills/vds-skill/vds-scripts/platform_core/tests/test_retry.py

@@ -0,0 +1,151 @@
+"""Tests for vds_platform_core.http.retry — TSK-7.3."""
+
+from __future__ import annotations
+
+import pytest
+from vds_platform_core.http.retry import exponential_backoff, with_retry
+from vds_platform_core.protocols import HTTPClient
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+class _FakeClient:
+    """Minimal HTTPClient stub."""
+
+    def __init__(self, responses: list) -> None:
+        """*responses* is consumed left-to-right; exceptions are raised."""
+        self._responses = list(responses)
+        self.get_calls = 0
+        self.post_calls = 0
+        self.aclose_calls = 0
+
+    async def get(self, url: str, **kwargs: object) -> object:
+        self.get_calls += 1
+        r = self._responses.pop(0)
+        if isinstance(r, BaseException):
+            raise r
+        return r
+
+    async def post(self, url: str, **kwargs: object) -> object:
+        self.post_calls += 1
+        r = self._responses.pop(0)
+        if isinstance(r, BaseException):
+            raise r
+        return r
+
+    async def aclose(self) -> None:
+        self.aclose_calls += 1
+
+
+_INSTANT = exponential_backoff(initial_wait=0.0, max_wait=0.0, jitter=0.0)
+
+
+# ---------------------------------------------------------------------------
+# Protocol conformance
+# ---------------------------------------------------------------------------
+
+
+def test_wrapper_isinstance_http_client() -> None:
+    """with_retry() returns an object satisfying the HTTPClient protocol."""
+    wrapper = with_retry(_FakeClient(["ok"]), _INSTANT)
+    assert isinstance(wrapper, HTTPClient)
+
+
+# ---------------------------------------------------------------------------
+# Retry behaviour
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_get_retries_on_retryable_error() -> None:
+    """get() retries once on a retryable exception then returns success."""
+    client = _FakeClient([OSError("timeout"), "result"])
+    wrapper = with_retry(client, _INSTANT)
+    result = await wrapper.get("http://x")
+    assert result == "result"
+    assert client.get_calls == 2
+
+
+@pytest.mark.asyncio
+async def test_post_retries_on_retryable_error() -> None:
+    """post() retries once on a retryable exception then returns success."""
+    client = _FakeClient([OSError("timeout"), "posted"])
+    wrapper = with_retry(client, _INSTANT)
+    result = await wrapper.post("http://x", json={})
+    assert result == "posted"
+    assert client.post_calls == 2
+
+
+@pytest.mark.asyncio
+async def test_non_retryable_propagates_immediately() -> None:
+    """Exceptions outside the retryable tuple propagate without retry."""
+    policy = exponential_backoff(retryable=(OSError,), initial_wait=0.0, jitter=0.0)
+    client = _FakeClient([ValueError("not retryable")])
+    wrapper = with_retry(client, policy)
+    with pytest.raises(ValueError, match="not retryable"):
+        await wrapper.get("http://x")
+    assert client.get_calls == 1
+
+
+@pytest.mark.asyncio
+async def test_max_attempts_respected() -> None:
+    """Raises after exhausting max_attempts retries."""
+    policy = exponential_backoff(max_attempts=2, initial_wait=0.0, jitter=0.0)
+    client = _FakeClient([OSError("a"), OSError("b"), "unreachable"])
+    wrapper = with_retry(client, policy)
+    with pytest.raises(OSError):
+        await wrapper.get("http://x")
+    assert client.get_calls == 2
+
+
+@pytest.mark.asyncio
+async def test_exception_type_preserved_after_exhaustion() -> None:
+    """The original exception type is preserved after retries are exhausted."""
+    policy = exponential_backoff(max_attempts=2, initial_wait=0.0, jitter=0.0)
+    client = _FakeClient([ConnectionError("down"), ConnectionError("still down")])
+    wrapper = with_retry(client, policy)
+    with pytest.raises(ConnectionError):
+        await wrapper.get("http://x")
+
+
+# ---------------------------------------------------------------------------
+# aclose delegation
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_aclose_delegates_to_underlying_client() -> None:
+    """aclose() is forwarded to the wrapped client."""
+    client = _FakeClient([])
+    wrapper = with_retry(client, _INSTANT)
+    await wrapper.aclose()
+    assert client.aclose_calls == 1
+
+
+# ---------------------------------------------------------------------------
+# exponential_backoff policy unit tests
+# ---------------------------------------------------------------------------
+
+
+def test_wait_seconds_exponential_formula() -> None:
+    """wait_seconds follows min(initial * multiplier**attempt, max_wait)."""
+    policy = exponential_backoff(initial_wait=1.0, multiplier=2.0, max_wait=10.0, jitter=0.0)
+    assert policy.wait_seconds(0) == 1.0
+    assert policy.wait_seconds(1) == 2.0
+    assert policy.wait_seconds(2) == 4.0
+    assert policy.wait_seconds(10) == 10.0  # capped at max_wait
+
+
+def test_can_retry_true_for_retryable_exception() -> None:
+    """can_retry returns True for exceptions within the retryable tuple."""
+    policy = exponential_backoff(retryable=(OSError, ValueError))
+    assert policy.can_retry(0, OSError("x"))
+    assert policy.can_retry(1, ValueError("y"))
+
+
+def test_can_retry_false_for_non_retryable_exception() -> None:
+    """can_retry returns False for exceptions outside the retryable tuple."""
+    policy = exponential_backoff(retryable=(OSError,))
+    assert not policy.can_retry(0, TypeError("x"))

package/skills/vds-skill/vds-scripts/platform_core/tests/test_serialization.py

@@ -0,0 +1,92 @@
+"""Tests for safe_dump and SafeDumpMixin (FR-6.2)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field, SecretStr
+from vds_platform_core.serialization import SafeDumpMixin, safe_dump
+
+
+class _SecretsModel(BaseModel):
+    """Model with mixed secret and non-secret fields for testing."""
+
+    api_key: SecretStr = Field(default_factory=lambda: SecretStr("sk-real"))
+    host: str = "localhost"
+    # Dict field where values are also SecretStr — explicitly typed so model_dump
+    # preserves the SecretStr wrapper.
+    auth_headers: dict[str, SecretStr] = Field(
+        default_factory=lambda: {"x-token": SecretStr("bearer-secret")},
+    )
+
+
+class _SafeModel(SafeDumpMixin, BaseModel):
+    """Model using the mixin."""
+
+    api_key: SecretStr = Field(default_factory=lambda: SecretStr("sk-mixin"))
+    value: int = 42
+
+
+class _NestedContainer(BaseModel):
+    """Model with SecretStr inside a nested model inside a list."""
+
+    inner_key: SecretStr = Field(default_factory=lambda: SecretStr("deep-secret"))
+
+
+class _ListContainer(BaseModel):
+    items: list[_NestedContainer] = []
+
+
+class TestSafeDump:
+    """safe_dump() redacts SecretStr at all nesting levels."""
+
+    def test_secret_str_redacted_at_root(self) -> None:
+        model = _SecretsModel()
+        dumped = safe_dump(model)
+        assert dumped["api_key"] == "***"
+        assert dumped["host"] == "localhost"
+
+    def test_secret_str_redacted_in_nested_dict(self) -> None:
+        """Dict[str, SecretStr] — model_dump preserves SecretStr wrapper."""
+        model = _SecretsModel()
+        dumped = safe_dump(model)
+        assert dumped["auth_headers"]["x-token"] == "***"
+
+    def test_secret_str_redacted_in_list_of_nested_models(self) -> None:
+        """SecretStr inside a nested model inside a list."""
+        model = _ListContainer(
+            items=[_NestedContainer(), _NestedContainer()],
+        )
+        dumped = safe_dump(model)
+        assert dumped["items"][0]["inner_key"] == "***"
+        assert dumped["items"][1]["inner_key"] == "***"
+
+    def test_non_secret_fields_unchanged(self) -> None:
+        model = _SecretsModel(host="prod.example.com")
+        dumped = safe_dump(model)
+        assert dumped["host"] == "prod.example.com"
+
+    def test_empty_secret_value(self) -> None:
+        model = _SecretsModel(api_key=SecretStr(""))
+        dumped = safe_dump(model)
+        assert dumped["api_key"] == "***"
+
+    def test_plain_dict_str_values_not_mistaken_for_secrets(self) -> None:
+        """Plain str values in dict fields are not SecretStr — kept as-is."""
+        model = _SecretsModel(host="plain-host.example.com")
+        dumped = safe_dump(model)
+        assert dumped["host"] == "plain-host.example.com"
+
+
+class TestSafeDumpMixin:
+    """SafeDumpMixin provides a .safe_dump() convenience method."""
+
+    def test_safe_dump_redacts_secret(self) -> None:
+        model = _SafeModel()
+        assert model.safe_dump()["api_key"] == "***"
+
+    def test_safe_dump_preserves_non_secret(self) -> None:
+        model = _SafeModel(value=99)
+        assert model.safe_dump()["value"] == 99
+
+    def test_safe_dump_equals_safe_dump(self) -> None:
+        model = _SafeModel()
+        assert model.safe_dump() == safe_dump(model)

package/skills/vds-skill/vds-scripts/platform_core/tests/test_severity.py

@@ -0,0 +1,178 @@
+"""Tests for vds_platform_core.severity — TDD RED phase."""
+
+import pytest
+from vds_platform_core.severity import (
+    ErrorCodeMeta,
+    ErrorCodeRegistry,
+    ErrorRecoverability,
+    ErrorSeverity,
+)
+
+# ---------------------------------------------------------------------------
+# ErrorSeverity enum
+# ---------------------------------------------------------------------------
+
+
+class TestErrorSeverity:
+    def test_values_are_strings(self) -> None:
+        assert isinstance(ErrorSeverity.CRITICAL, str)
+        assert isinstance(ErrorSeverity.HIGH, str)
+        assert isinstance(ErrorSeverity.MEDIUM, str)
+        assert isinstance(ErrorSeverity.LOW, str)
+
+    def test_str_comparison(self) -> None:
+        """StrEnum members compare equal to their string values."""
+        assert ErrorSeverity.CRITICAL == "critical"
+        assert ErrorSeverity.HIGH == "high"
+        assert ErrorSeverity.MEDIUM == "medium"
+        assert ErrorSeverity.LOW == "low"
+
+    def test_all_members_present(self) -> None:
+        members = {m.value for m in ErrorSeverity}
+        assert members == {"critical", "high", "medium", "low"}
+
+
+# ---------------------------------------------------------------------------
+# ErrorRecoverability enum
+# ---------------------------------------------------------------------------
+
+
+class TestErrorRecoverability:
+    def test_values_are_strings(self) -> None:
+        assert isinstance(ErrorRecoverability.TRANSIENT, str)
+        assert isinstance(ErrorRecoverability.RATE_LIMITED, str)
+        assert isinstance(ErrorRecoverability.DEGRADED, str)
+        assert isinstance(ErrorRecoverability.MANUAL, str)
+        assert isinstance(ErrorRecoverability.PERMANENT, str)
+
+    def test_str_comparison(self) -> None:
+        assert ErrorRecoverability.TRANSIENT == "transient"
+        assert ErrorRecoverability.RATE_LIMITED == "rate_limited"
+        assert ErrorRecoverability.DEGRADED == "degraded"
+        assert ErrorRecoverability.MANUAL == "manual"
+        assert ErrorRecoverability.PERMANENT == "permanent"
+
+    def test_all_members_present(self) -> None:
+        members = {m.value for m in ErrorRecoverability}
+        assert members == {"transient", "rate_limited", "degraded", "manual", "permanent"}
+
+    def test_registry_accepts_all_five_values(self) -> None:
+        """Each of the 5 recoverability values can be stored in a registry entry."""
+        reg = ErrorCodeRegistry()
+        for recov in ErrorRecoverability:
+            meta = ErrorCodeMeta(
+                code=f"TST-{recov.value.upper()[:3]}",
+                description=f"Test for {recov.value}",
+                severity=ErrorSeverity.LOW,
+                recoverability=recov,
+            )
+            reg.register("TST", meta)
+        assert len(list(reg.all_codes(prefix="TST"))) == 5
+
+
+# ---------------------------------------------------------------------------
+# ErrorCodeMeta dataclass
+# ---------------------------------------------------------------------------
+
+
+class TestErrorCodeMeta:
+    def test_frozen_dataclass(self) -> None:
+        meta = ErrorCodeMeta(
+            code="CLI-001",
+            description="Config missing",
+            severity=ErrorSeverity.HIGH,
+            recoverability=ErrorRecoverability.PERMANENT,
+        )
+        with pytest.raises((AttributeError, TypeError)):
+            meta.code = "CLI-999"  # type: ignore[misc]
+
+    def test_fields_accessible(self) -> None:
+        meta = ErrorCodeMeta(
+            code="CLI-001",
+            description="Config missing",
+            severity=ErrorSeverity.HIGH,
+            recoverability=ErrorRecoverability.PERMANENT,
+        )
+        assert meta.code == "CLI-001"
+        assert meta.description == "Config missing"
+        assert meta.severity == ErrorSeverity.HIGH
+        assert meta.recoverability == ErrorRecoverability.PERMANENT
+
+
+# ---------------------------------------------------------------------------
+# ErrorCodeRegistry
+# ---------------------------------------------------------------------------
+
+
+class TestErrorCodeRegistry:
+    def _make_registry(self) -> ErrorCodeRegistry:
+        return ErrorCodeRegistry()
+
+    def test_register_and_lookup(self) -> None:
+        reg = self._make_registry()
+        meta = ErrorCodeMeta(
+            code="CLI-001",
+            description="Config missing",
+            severity=ErrorSeverity.HIGH,
+            recoverability=ErrorRecoverability.PERMANENT,
+        )
+        reg.register("CLI", meta)
+        result = reg.lookup("CLI-001")
+        assert result is meta
+
+    def test_lookup_missing_returns_none(self) -> None:
+        reg = self._make_registry()
+        assert reg.lookup("NONEXISTENT-999") is None
+
+    def test_all_codes_empty(self) -> None:
+        reg = self._make_registry()
+        assert list(reg.all_codes()) == []
+
+    def test_all_codes_returns_registered(self) -> None:
+        reg = self._make_registry()
+        meta1 = ErrorCodeMeta("CLI-001", "desc1", ErrorSeverity.LOW, ErrorRecoverability.TRANSIENT)
+        meta2 = ErrorCodeMeta("CLI-002", "desc2", ErrorSeverity.MEDIUM, ErrorRecoverability.PERMANENT)
+        reg.register("CLI", meta1)
+        reg.register("CLI", meta2)
+        codes = list(reg.all_codes())
+        assert len(codes) == 2
+        assert meta1 in codes
+        assert meta2 in codes
+
+    def test_prefix_scoped_all_codes(self) -> None:
+        reg = self._make_registry()
+        cli_meta = ErrorCodeMeta("CLI-001", "d1", ErrorSeverity.LOW, ErrorRecoverability.TRANSIENT)
+        sonar_meta = ErrorCodeMeta("SONAR-001", "d2", ErrorSeverity.HIGH, ErrorRecoverability.PERMANENT)
+        reg.register("CLI", cli_meta)
+        reg.register("SONAR", sonar_meta)
+
+        cli_codes = list(reg.all_codes(prefix="CLI"))
+        sonar_codes = list(reg.all_codes(prefix="SONAR"))
+
+        assert cli_meta in cli_codes
+        assert sonar_meta not in cli_codes
+        assert sonar_meta in sonar_codes
+        assert cli_meta not in sonar_codes
+
+    def test_prefix_collision_raises(self) -> None:
+        """Registering two metas with the same code under the same prefix raises ValueError."""
+        reg = self._make_registry()
+        meta1 = ErrorCodeMeta("CLI-001", "first", ErrorSeverity.LOW, ErrorRecoverability.TRANSIENT)
+        meta2 = ErrorCodeMeta("CLI-001", "duplicate", ErrorSeverity.HIGH, ErrorRecoverability.PERMANENT)
+        reg.register("CLI", meta1)
+        with pytest.raises(ValueError, match="CLI-001"):
+            reg.register("CLI", meta2)
+
+    def test_enumerate_is_iterable(self) -> None:
+        reg = self._make_registry()
+        meta = ErrorCodeMeta("CLI-001", "d", ErrorSeverity.CRITICAL, ErrorRecoverability.PERMANENT)
+        reg.register("CLI", meta)
+        found = list(reg.all_codes())
+        assert meta in found
+
+    def test_generic_parameterisation(self) -> None:
+        """ErrorCodeRegistry[ErrorSeverity, ErrorRecoverability] is valid at runtime."""
+        # The generic alias should be constructable without error
+        RegType = ErrorCodeRegistry[ErrorSeverity, ErrorRecoverability]  # type: ignore[type-arg]
+        reg = RegType()
+        assert isinstance(reg, ErrorCodeRegistry)

package/skills/vds-skill/vds-scripts/platform_core/tests/test_stack.py

@@ -0,0 +1,130 @@
+"""Tests for platform_core.http.stack — TSK-7.18."""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import httpx
+from vds_platform_core.config import HTTPClientSettings
+from vds_platform_core.http.stack import build_client, vds_default_stack
+from vds_platform_core.protocols import HTTPClient
+
+
+def _settings(**kw: Any) -> HTTPClientSettings:
+    return HTTPClientSettings(**kw)
+
+
+def _stub_httpx_client() -> MagicMock:
+    """Plain MagicMock with get/post/aclose — satisfies HTTPClient Protocol.
+
+    Intentionally no spec= so this works both inside and outside @patch contexts
+    (patching httpx.AsyncClient replaces the class globally, making spec= fail).
+    """
+    stub = MagicMock()
+    stub.get = MagicMock(return_value=None)
+    stub.post = MagicMock(return_value=None)
+    stub.aclose = MagicMock(return_value=None)
+    return stub
+
+
+class TestBuildClientProtocol:
+    @patch("vds_platform_core.http.stack.httpx.AsyncClient")
+    def test_returns_http_client_protocol(self, mock_cls: MagicMock) -> None:
+        mock_cls.return_value = _stub_httpx_client()
+        result = build_client(settings=_settings(), service="svc", base_url="http://api", token_field="TOKEN")
+        assert isinstance(result, HTTPClient)
+
+    @patch("vds_platform_core.http.stack.httpx.AsyncClient")
+    def test_service_param_accepted_without_error(self, mock_cls: MagicMock) -> None:
+        mock_cls.return_value = _stub_httpx_client()
+        # service is reserved for future error-map registry — must not raise
+        build_client(settings=_settings(), service="my-service", base_url="http://x", token_field="TOK")
+
+
+class TestBuildClientTimeouts:
+    def test_timeouts_flow_to_httpx(self) -> None:
+        captured: dict[str, Any] = {}
+        original_init = httpx.AsyncClient.__init__
+
+        def tracking_init(self: Any, **kwargs: Any) -> None:
+            captured.update(kwargs)
+            original_init(self, **kwargs)
+
+        s = _settings(connect_timeout=1.0, read_timeout=2.0, write_timeout=3.0, pool_timeout=4.0)
+        with patch.object(httpx.AsyncClient, "__init__", tracking_init):
+            build_client(settings=s, service="svc", base_url="http://api", token_field="TOK")
+
+        t: httpx.Timeout = captured["timeout"]
+        assert t.connect == 1.0
+        assert t.read == 2.0
+        assert t.write == 3.0
+        assert t.pool == 4.0
+
+
+class TestBuildClientHeaderName:
+    @patch("vds_platform_core.http.stack.httpx.AsyncClient")
+    def test_default_header_name_is_authorization(self, mock_cls: MagicMock) -> None:
+        mock_cls.return_value = _stub_httpx_client()
+        client = build_client(settings=_settings(), service="svc", base_url="http://api", token_field="TOKEN")
+        # unwrap auth wrapper → _header_name attribute set by with_auth
+        assert client._header_name == "Authorization"  # type: ignore[attr-defined]
+
+    @patch("vds_platform_core.http.stack.httpx.AsyncClient")
+    def test_custom_header_name_propagates(self, mock_cls: MagicMock) -> None:
+        mock_cls.return_value = _stub_httpx_client()
+        client = build_client(
+            settings=_settings(),
+            service="svc",
+            base_url="http://api",
+            token_field="TOKEN",
+            header_name="X-Api-Key",
+        )
+        assert client._header_name == "X-Api-Key"  # type: ignore[attr-defined]
+
+
+class TestExtraMiddleware:
+    @patch("vds_platform_core.http.stack.httpx.AsyncClient")
+    def test_extra_middleware_fifo_order(self, mock_cls: MagicMock) -> None:
+        mock_cls.return_value = _stub_httpx_client()
+        applied: list[int] = []
+
+        def mw1(c: HTTPClient) -> HTTPClient:
+            applied.append(1)
+            return c
+
+        def mw2(c: HTTPClient) -> HTTPClient:
+            applied.append(2)
+            return c
+
+        build_client(
+            settings=_settings(),
+            service="svc",
+            base_url="http://api",
+            token_field="TOKEN",
+            extra_middleware=(mw1, mw2),
+        )
+        assert applied == [1, 2]
+
+    @patch("vds_platform_core.http.stack.httpx.AsyncClient")
+    def test_no_extra_middleware_works(self, mock_cls: MagicMock) -> None:
+        mock_cls.return_value = _stub_httpx_client()
+        result = build_client(settings=_settings(), service="svc", base_url="http://api", token_field="TOKEN")
+        assert isinstance(result, HTTPClient)
+
+
+class TestVdsDefaultStack:
+    def test_wraps_client_satisfying_protocol(self) -> None:
+        from vds_platform_core.credentials import HeaderAuthResolver
+        from vds_platform_core.http.retry import exponential_backoff
+
+        stub = _stub_httpx_client()
+        resolver = HeaderAuthResolver(token_field="TOK", header_name="Authorization")
+        policy = exponential_backoff()
+        result = vds_default_stack(
+            stub,  # type: ignore[arg-type]
+            resolver=resolver,
+            retry_policy=policy,
+            service="test",
+        )
+        assert isinstance(result, HTTPClient)