feat(multi-instance): dcy-009 BAT-013 — RabbitMQ 다중 인스턴스 토폴로지 (REQ-048~051)

dcy-009(다중 인스턴스 RabbitMQ 토폴로지) 전체 SDLC: draft-req → confirm-req →
draft-batch(BAT-013) → run-batch-delivery → confirm-req-implemented.

- REQ-048 (Configuration): DaemonInstanceConfig.from_toml + DaemonConfig.from_config
  (env 병합, portfolio_hub_token 주입) + 데몬 --config 필수 argparse + .gitignore 인스턴스
  TOML + config/instance.example.toml
- REQ-049 (Interface): topology 동적 큐명 빌더 intent/snapshot/control_queue(instance_key)
  — default=리터럴 큐명(하위호환), named=`{base}.{instance_key}` + daemon per-instance 구독
- REQ-050 (Integration): trex.direct(topic)/trex.broadcast(fanout) exchange +
  declare_topology(instance_key) per-instance binding + control dual binding + direct_routing_key
- REQ-051 (Documentation): interface-contract/runtime-flows/project-structure 정합

하위호환: instance_key="default" → 기존 리터럴 큐명·RPC 경로 무회귀(FR-5).
split-brain 방지(NFR-3): 인스턴스 전용 큐. 민감값(NFR-4): TOML + gitignore.

검증: 신규 9 단위 + RabbitMQ 라우팅 2, 단위 271 passed,
인프라 게이트 301 passed(directed 격리 S-2 + broadcast dual S-3 + default 무회귀 S-4),
ruff clean. REQ-048~051 Implemented, BAT-013 release-candidate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

trex_core/adapters/messaging/rabbitmq.py

@@ -28,14 +28,19 @@ import pika
 import pika.exceptions
 
 from trex_core.adapters.messaging.topology import (
-    CONTROL_REQ_QUEUE,
+    BROADCAST_EXCHANGE,
+    DEFAULT_INSTANCE_KEY,
+    DIRECT_EXCHANGE,
     EVENTS_DLQ_EXCHANGE,
     EVENTS_DLQ_QUEUE,
     EVENTS_EXCHANGE,
     INTENT_REQ_QUEUE,
     PAUSE_REQ_QUEUE,
-    SNAPSHOT_REQ_QUEUE,
     STRATEGY_QUEUE_ARGS,
+    control_queue,
+    direct_routing_key,
+    intent_queue,
+    snapshot_queue,
 )
 from trex_core.application.messaging import (
     EventHandler,
@@ -118,37 +123,33 @@ class RabbitMQTransport:
             return self._health
 
     # ------------------------------------------------------------ topology
-    def declare_topology(self) -> None:
+    def declare_topology(self, instance_key: str = DEFAULT_INSTANCE_KEY) -> None:
         self._ensure_connected()
         ch = self._channel
         assert ch is not None
+        dlx = {"x-dead-letter-exchange": EVENTS_DLQ_EXCHANGE}
         # Events topic + DLQ
         ch.exchange_declare(EVENTS_EXCHANGE, exchange_type="topic", durable=True)
         ch.exchange_declare(EVENTS_DLQ_EXCHANGE, exchange_type="fanout", durable=True)
         ch.queue_declare(EVENTS_DLQ_QUEUE, durable=True)
         ch.queue_bind(EVENTS_DLQ_QUEUE, EVENTS_DLQ_EXCHANGE)
-        # RPC queues (durable for intent + snapshot)
-        ch.queue_declare(
-            INTENT_REQ_QUEUE,
-            durable=True,
-            arguments={"x-dead-letter-exchange": EVENTS_DLQ_EXCHANGE},
-        )
-        ch.queue_declare(
-            SNAPSHOT_REQ_QUEUE,
-            durable=True,
-            arguments={"x-dead-letter-exchange": EVENTS_DLQ_EXCHANGE},
-        )
-        ch.queue_declare(
-            PAUSE_REQ_QUEUE,
-            durable=True,
-            arguments={"x-dead-letter-exchange": EVENTS_DLQ_EXCHANGE},
-        )
-        # BAT-012 / REQ-043: operator control channel (action dispatch).
-        ch.queue_declare(
-            CONTROL_REQ_QUEUE,
-            durable=True,
-            arguments={"x-dead-letter-exchange": EVENTS_DLQ_EXCHANGE},
-        )
+        # BAT-013 / REQ-050: multi-instance control exchanges.
+        ch.exchange_declare(DIRECT_EXCHANGE, exchange_type="topic", durable=True)
+        ch.exchange_declare(BROADCAST_EXCHANGE, exchange_type="fanout", durable=True)
+        # Per-instance RPC queues (default → literal names, REQ-049 backward-compat).
+        iq = intent_queue(instance_key)
+        sq = snapshot_queue(instance_key)
+        cq = control_queue(instance_key)
+        for q, channel_type in ((iq, "intent"), (sq, "snapshot"), (cq, "control")):
+            ch.queue_declare(q, durable=True, arguments=dlx)
+            # Directed binding: trex.direct → {instance_key}.{channel_type}
+            ch.queue_bind(q, DIRECT_EXCHANGE,
+                          routing_key=direct_routing_key(instance_key, channel_type))
+        # Control queue is also fanout-bound so global broadcasts hit every instance.
+        ch.queue_bind(cq, BROADCAST_EXCHANGE)
+        # Legacy pause queue — declared for the default instance only (REQ-032 alias).
+        if instance_key == DEFAULT_INSTANCE_KEY:
+            ch.queue_declare(PAUSE_REQ_QUEUE, durable=True, arguments=dlx)
 
     def declare_strategy_queue(self, queue: str, binding_pattern: str) -> None:
         """Per-strategy durable queue (REQ-023 AC-4) bound to events exchange."""

trex_core/adapters/messaging/topology.py

@@ -19,6 +19,39 @@ PAUSE_REQ_QUEUE = "trex.pause.req"      # BAT-008 / REQ-032 (legacy alias of con
 CONTROL_REQ_QUEUE = "trex.control.req"  # BAT-012 / REQ-043 operator control channel
                                         # (action: pause|resume|list|kill_switch|resume_kill_switch)
 
+# --- multi-instance topology (BAT-013 / dcy-009) ---
+DEFAULT_INSTANCE_KEY = "default"
+DIRECT_EXCHANGE = "trex.direct"        # topic, durable — directed per-instance routing (REQ-050)
+BROADCAST_EXCHANGE = "trex.broadcast"  # fanout, durable — global control to all instances (REQ-050)
+
+
+def _instance_queue(base: str, instance_key: str | None) -> str:
+    """`{base}.{instance_key}` for named instances; literal `base` for default.
+
+    The default special-case keeps existing queue names (and the entire test
+    suite + deployed clients) byte-for-byte (REQ-049 FR-5 backward-compat).
+    """
+    if instance_key in (None, DEFAULT_INSTANCE_KEY):
+        return base
+    return f"{base}.{instance_key}"
+
+
+def intent_queue(instance_key: str | None = DEFAULT_INSTANCE_KEY) -> str:
+    return _instance_queue(INTENT_REQ_QUEUE, instance_key)
+
+
+def snapshot_queue(instance_key: str | None = DEFAULT_INSTANCE_KEY) -> str:
+    return _instance_queue(SNAPSHOT_REQ_QUEUE, instance_key)
+
+
+def control_queue(instance_key: str | None = DEFAULT_INSTANCE_KEY) -> str:
+    return _instance_queue(CONTROL_REQ_QUEUE, instance_key)
+
+
+def direct_routing_key(instance_key: str, channel_type: str) -> str:
+    """Directed routing key for `trex.direct` (REQ-050): `{instance_key}.{channel_type}`."""
+    return f"{instance_key}.{channel_type}"
+
 # --- Events ---
 EVENTS_EXCHANGE = "trex.events"            # topic, durable
 EVENTS_DLQ_EXCHANGE = "trex.events.dlq"    # fanout, durable; receives unroutable/NACKed

trex_core/runtime/config.py

@@ -2,7 +2,7 @@
 from __future__ import annotations
 
 import os
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from typing import Optional
 
 
@@ -85,12 +85,44 @@ class SafetySellConfig:
     market_close_liquidation_time: Optional[str] = None  # "HH:MM" KST, optional
 
 
+@dataclass(frozen=True)
+class DaemonInstanceConfig:
+    """Per-instance TOML settings (REQ-048 / BAT-013).
+
+    `instance_key` and `portfolio_hub_token` live in a TOML file (not .env)
+    so they are not committed and so multiple instances can run distinct
+    queues. Loaded via `--config <path>.toml`.
+    """
+
+    instance_key: str
+    portfolio_hub_token: str = ""
+
+    @staticmethod
+    def from_toml(path: str) -> "DaemonInstanceConfig":
+        import tomllib
+
+        with open(path, "rb") as fh:
+            data = tomllib.load(fh)
+        instance_key = data.get("instance_key")
+        if not instance_key:
+            raise RuntimeError(
+                f"instance TOML missing required 'instance_key': {path}"
+            )
+        return DaemonInstanceConfig(
+            instance_key=str(instance_key),
+            portfolio_hub_token=str(data.get("portfolio_hub_token") or ""),
+        )
+
+
 @dataclass(frozen=True)
 class DaemonConfig:
     dsn: str
     total_slots: int
     broker: str                      # 'paper' | 'kis'
     execution_interval_sec: float
+    # BAT-013 / REQ-049: instance identity for multi-instance queue naming.
+    # "default" keeps legacy literal queue names (backward-compat).
+    instance_key: str = "default"
     kis: Optional[KISConfig] = None
     # REQ-011: paper broker tuning (only consulted when broker == 'paper').
     paper: PaperBrokerConfig = PaperBrokerConfig()
@@ -179,3 +211,18 @@ class DaemonConfig:
             snapshot_schedule=snapshot_schedule,
             safety_sell=safety_sell,
         )
+
+    @staticmethod
+    def from_config(toml_path: str) -> "DaemonConfig":
+        """Build config from env + a per-instance TOML file (REQ-048 / BAT-013).
+
+        `instance_key` and `portfolio_hub_token` come from TOML (not .env).
+        TOML `portfolio_hub_token` overrides the (env-derived) PortfolioHubConfig
+        token when a portfolio-hub base_url is configured.
+        """
+        base = DaemonConfig.from_env()
+        inst = DaemonInstanceConfig.from_toml(toml_path)
+        pf = base.portfolio_hub
+        if inst.portfolio_hub_token and pf is not None:
+            pf = replace(pf, token=inst.portfolio_hub_token)
+        return replace(base, instance_key=inst.instance_key, portfolio_hub=pf)

trex_core/runtime/daemon.py

@@ -217,7 +217,7 @@ class Daemon:
         transport = _build_transport(self.config)
         self._transports.append(transport)
         try:
-            transport.declare_topology()
+            transport.declare_topology(self.config.instance_key)
         except Exception:  # noqa: BLE001
             pass
         handler = make_intent_rpc_handler(
@@ -225,13 +225,14 @@ class Daemon:
             slot_service=self.slot_service,
             watchdog_store=self.watchdog,
         )
-        transport.consume_rpc_forever(topology.INTENT_REQ_QUEUE, handler, self.stop)
+        transport.consume_rpc_forever(
+            topology.intent_queue(self.config.instance_key), handler, self.stop)
 
     def _snapshot_rpc_loop(self) -> None:
         transport = _build_transport(self.config)
         self._transports.append(transport)
         try:
-            transport.declare_topology()
+            transport.declare_topology(self.config.instance_key)
         except Exception:  # noqa: BLE001
             pass
         handler = make_snapshot_rpc_handler(
@@ -242,20 +243,22 @@ class Daemon:
             watchdog_store=self.watchdog,
             killswitch_store=self.killswitch_store,
         )
-        transport.consume_rpc_forever(topology.SNAPSHOT_REQ_QUEUE, handler, self.stop)
+        transport.consume_rpc_forever(
+            topology.snapshot_queue(self.config.instance_key), handler, self.stop)
 
     def _control_rpc_loop(self) -> None:
         # REQ-043: operator control channel (pause/resume/list + kill_switch/resume_kill_switch).
         transport = _build_transport(self.config)
         self._transports.append(transport)
         try:
-            transport.declare_topology()
+            transport.declare_topology(self.config.instance_key)
         except Exception:  # noqa: BLE001
             pass
         handler = make_control_rpc_handler(
             self.pause_store, kill_switch_service=self.kill_switch,
         )
-        transport.consume_rpc_forever(topology.CONTROL_REQ_QUEUE, handler, self.stop)
+        transport.consume_rpc_forever(
+            topology.control_queue(self.config.instance_key), handler, self.stop)
 
     def _safety_sell_loop(self) -> None:
         # REQ-037/038/039: forced_close / stop-loss·take-profit / market-close.
@@ -281,7 +284,7 @@ class Daemon:
         )
         self.execution.reconcile()  # REQ-014 restart recovery
         try:
-            self.event_publisher.declare_topology()
+            self.event_publisher.declare_topology(self.config.instance_key)
         except Exception:  # noqa: BLE001
             _log.warning("event publisher topology declare failed", exc_info=True)
 
@@ -325,8 +328,17 @@ class Daemon:
 
 
 def main() -> None:  # pragma: no cover - process entrypoint
+    import argparse
+
     logging.basicConfig(level=logging.INFO)
-    config = DaemonConfig.from_env()
+    parser = argparse.ArgumentParser(prog="trex-core-daemon")
+    parser.add_argument(
+        "--config", required=True,
+        help="per-instance TOML config path (instance_key, portfolio_hub_token). "
+             "Required — no default (REQ-048 / dcy-009 OQ-2).",
+    )
+    args = parser.parse_args()
+    config = DaemonConfig.from_config(args.config)
     Daemon(config).run()