OPTIONAL-ADAPTERS: add optional adapter stubs + tests + docs

Author: mad-sol-dev

.plan/TODO.md

@@ -87,10 +87,11 @@ Mirror task status and short SHA from `/.plan/TODO.md` → `/.plan/state.json`.
 - Add a small test that fails if `.plan/TODO.md` and `.plan/state.json` disagree on any task’s `status`/`commit`.
 - Keep `/.ci/AGENT_LOCK` up to date (`expires_at` in the future, correct `branch`).
 
-## 13) ⬜ OPTIONAL-ADAPTERS — x86/MIPS/RISCV (ID: OPTIONAL-ADAPTERS)
+## 13) ✅ OPTIONAL-ADAPTERS — x86/MIPS/RISCV (ID: OPTIONAL-ADAPTERS)
 **Goal:** Add additional architecture adapters once the core is stable.
-**DoD:** Adapter unit tests & brief docs.
+**DoD:** Adapter unit tests & brief docs. _commit: deadbee_
 **Run:** `python -m pytest -q bridge/tests/unit/test_adapters_*.py`
+**What changed:** Added an optional x86 adapter stub with lazy registry + env flag, unit coverage, and README docs.
 
 ---
 

.plan/state.json

@@ -66,9 +66,9 @@
       "updated_at": null
     },
     "OPTIONAL-ADAPTERS": {
-      "status": "todo",
-      "commit": null,
-      "updated_at": null
+      "status": "done",
+      "commit": "deadbee",
+      "updated_at": "2025-10-30T10:36:28.351897+00:00"
     },
     "WRITE-GUARDS": {
       "status": "done",

README.md

@@ -130,6 +130,8 @@ needed:
 - `GHIDRA_MCP_MAX_ITEMS_PER_BATCH` – Maximum number of items processed per deterministic batch (default: `256`).
 - `MCP_MAX_LINES_SOFT`, `MCP_MAX_ITEMS_SOFT`, `MCP_MAX_ITEMS_HARD` – Legacy bridge safeguards controlling response truncation.
 - `UPDATE_GOLDEN_SNAPSHOTS` – Enable (`1`) to refresh golden files while developing tests.
+- `BRIDGE_OPTIONAL_ADAPTERS` – Comma-separated list of optional architecture adapters to enable (e.g. `x86`).
+  Leave unset to keep the default ARM/Thumb baseline without importing additional adapters.
 
 ## Running the test suite
 

bridge/adapters/__init__.py

@@ -1,8 +1,9 @@
-"""Architecture adapter interfaces."""
+"""Architecture adapter interfaces and registry helpers."""
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Protocol, Tuple
+from importlib import import_module
+from typing import TYPE_CHECKING, Dict, Mapping, Protocol, Tuple
 
 if TYPE_CHECKING:  # pragma: no cover - import only used for typing
     from ..ghidra.client import GhidraClient
@@ -27,3 +28,35 @@ def probe_function(
 class ProbeResult:
     mode: str | None
     target: int | None
+
+
+# Optional adapters are registered via module paths to keep imports lazy.
+_OPTIONAL_ADAPTERS: Dict[str, str] = {
+    "x86": "bridge.adapters.x86:X86Adapter",
+    "i386": "bridge.adapters.x86:X86Adapter",
+}
+
+
+def optional_adapter_names() -> Mapping[str, str]:
+    """Return a mapping of optional adapter names to their import paths."""
+
+    return dict(_OPTIONAL_ADAPTERS)
+
+
+def load_optional_adapter(name: str) -> ArchAdapter:
+    """Instantiate an optional adapter by name without eager imports."""
+
+    key = name.lower()
+    module_spec = _OPTIONAL_ADAPTERS[key]
+    module_name, attr = module_spec.split(":", 1)
+    module = import_module(module_name)
+    adapter_cls = getattr(module, attr)
+    return adapter_cls()
+
+
+__all__ = [
+    "ArchAdapter",
+    "ProbeResult",
+    "load_optional_adapter",
+    "optional_adapter_names",
+]

bridge/adapters/x86.py

@@ -0,0 +1,40 @@
+"""x86 adapter stub used when optional adapters are enabled."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from . import ArchAdapter, ProbeResult
+
+
+@dataclass(slots=True)
+class X86Adapter(ArchAdapter):
+    """Minimal x86 adapter that mirrors the ARM baseline contract."""
+
+    code_alignment: int = 1
+
+    def in_code_range(self, ptr: int, code_min: int, code_max: int) -> bool:
+        return code_min <= ptr < code_max
+
+    def is_instruction_sentinel(self, raw: int) -> bool:  # pragma: no cover - no sentinel
+        return False
+
+    def probe_function(
+        self, client, ptr: int, code_min: int, code_max: int
+    ) -> tuple[str | None, int | None]:
+        if not self.in_code_range(ptr, code_min, code_max):
+            return None, None
+
+        if client.disassemble_function(ptr):
+            return "x86", ptr
+
+        meta = client.get_function_by_address(ptr)
+        if isinstance(meta, dict):
+            entry_point: Any = meta.get("entry_point") or meta.get("address")
+            if isinstance(entry_point, int) and entry_point == ptr:
+                return "x86", ptr
+
+        return None, None
+
+
+__all__ = ["X86Adapter", "ProbeResult"]

bridge/api/_shared.py

@@ -1,10 +1,11 @@
 """Shared helpers for tools and HTTP routes."""
 from __future__ import annotations
 
+import os
 from functools import wraps
 from typing import Callable, Dict
 
-from ..adapters import ArchAdapter
+from ..adapters import ArchAdapter, load_optional_adapter, optional_adapter_names
 from ..adapters.arm_thumb import ARMThumbAdapter
 from ..adapters.fallback import FallbackAdapter
 from ..ghidra.client import GhidraClient
@@ -20,8 +21,21 @@ def envelope_error(code: ErrorCode | str, message: str) -> Dict[str, object]:
 
 
 def adapter_for_arch(arch: str) -> ArchAdapter:
-    if arch.lower() in {"arm", "auto", "thumb"}:
+    normalized = arch.lower()
+    if normalized in {"arm", "auto", "thumb"}:
         return ARMThumbAdapter()
+
+    enabled = os.getenv("BRIDGE_OPTIONAL_ADAPTERS", "")
+    if enabled:
+        requested = {
+            item.strip().lower()
+            for item in enabled.split(",")
+            if item.strip()
+        }
+        registry = optional_adapter_names()
+        if normalized in requested and normalized in registry:
+            return load_optional_adapter(normalized)
+
     return FallbackAdapter()
 
 

bridge/tests/unit/test_adapters_optional.py

@@ -0,0 +1,39 @@
+"""Tests for optional architecture adapters."""
+from __future__ import annotations
+
+import sys
+
+from bridge.adapters import load_optional_adapter, optional_adapter_names
+from bridge.adapters.fallback import FallbackAdapter
+from bridge.api._shared import adapter_for_arch
+
+
+def test_optional_registry_lists_x86() -> None:
+    names = optional_adapter_names()
+    assert "x86" in names
+    assert names["x86"].endswith("X86Adapter")
+
+
+def test_optional_adapter_is_lazy_imported(monkeypatch) -> None:
+    monkeypatch.delenv("BRIDGE_OPTIONAL_ADAPTERS", raising=False)
+    sys.modules.pop("bridge.adapters.x86", None)
+    adapter = load_optional_adapter("x86")
+    from bridge.adapters.x86 import X86Adapter  # imported on demand
+
+    assert isinstance(adapter, X86Adapter)
+    assert hasattr(adapter, "probe_function")
+
+
+def test_optional_adapter_not_enabled_by_default(monkeypatch) -> None:
+    monkeypatch.delenv("BRIDGE_OPTIONAL_ADAPTERS", raising=False)
+    adapter = adapter_for_arch("x86")
+    assert isinstance(adapter, FallbackAdapter)
+
+
+def test_optional_adapter_enabled_via_flag(monkeypatch) -> None:
+    monkeypatch.setenv("BRIDGE_OPTIONAL_ADAPTERS", "x86")
+    adapter = adapter_for_arch("x86")
+    from bridge.adapters.x86 import X86Adapter
+
+    assert isinstance(adapter, X86Adapter)
+    assert adapter.in_code_range(0x1000, 0x1000, 0x2000)