# ADR-0007: 런타임 API 및 시뮬레이션 엔진 경계

## Status

Accepted

## Context

시뮬레이터는 책임이 명확히 다른 여러 계층으로 구성된다:

- 벤치마크와 사용자 코드가 사용하는 호스트 대상 API 계층,
- 요청을 실행하는 이산 이벤트 시뮬레이션 엔진,
- 하드웨어 동작을 모델링하는 디바이스 컴포넌트.

엄격한 경계가 없으면 오케스트레이션 로직이 컴포넌트로 누출되거나
시뮬레이션 내부가 사용자 대상 API와 얽힐 수 있다.

본 ADR은 다음 사이의 명확한 책임 경계를 정의한다:

- 런타임 API,
- 시뮬레이션 엔진 (sip_engine),
- 하드웨어 컴포넌트.

---

## Decision

### D1. 런타임 API는 호스트 대상 오케스트레이션만 담당

런타임 API는 호스트/드라이버 수준의 동작을 표현하며 다음을 해야 한다:

- 고수준 동작 노출 (텐서 배포, 커널 launch),
- 엔드포인트 컴포넌트(예: IO_CPU)에만 요청 제출,
- futures/handles로 완료 대기,
- 호스트측 메타데이터(텐서 할당 맵, 커널 바인딩)의 소유와 영속화.

런타임 API가 해서는 안 되는 것:

- hop-by-hop 라우팅 또는 fan-out 하드코딩,
- 내부 컴포넌트(M_CPU, PE_CPU, 엔진) 직접 호출,
- 토폴로지나 라우팅 관련 가정 내장.

---

### D2. 시뮬레이션 엔진은 컴포넌트를 연결하고 완료를 추적

시뮬레이션 엔진(sim_engine)은 다음을 해야 한다:

- 초기화 시점에 컴포넌트 연결 (컴포넌트 포트/와이어 프레임워크에 따라
  포트 store 생성 + 와이어 프로세스 시작 — ADR-0015),
- 컴파일된 토폴로지 그래프의 진입 컴포넌트(예: 메모리 동작은 PCIE_EP,
  커널 launch는 IO_CPU)에 요청 주입,
- 이산 이벤트 모델로 이벤트 스케줄링과 실행,
- correlation ID와 완료 추적 관리.

시뮬레이션 엔진이 해서는 안 되는 것:

- 텐서 시맨틱 정의,
- 커널 실행 정책 정의,
- 런타임 API에 내부 그래프 세부사항 노출,
- 요청 실행 중에 토폴로지 경로를 따라 걷기,
- 컴포넌트의 `run()` 메서드 직접 호출,
- hop별 레이턴시 추적 또는 fan-out 분해 (컴포넌트의 책임).

---

### D3. 컴포넌트가 fan-out과 집계를 담당

디바이스측 컴포넌트는 다음을 해야 한다:

- 요청을 하위 도메인으로 fan-out
  (IO_CPU → M_CPU → PE_CPU → 스케줄러/엔진),
- 완료·실패 신호 집계,
- 결정론적으로 상위로 결과 전파.

런타임 API와 시뮬레이션 엔진 모두 컴포넌트 수준의 fan-out을 명시적으로
오케스트레이션해서는 안 된다.

---

## Consequences

- 토폴로지와 라우팅이 변해도 런타임 API는 안정적이다.
- 시뮬레이션 내부는 사용자 대상 코드에 영향을 주지 않고 변경 가능하다.
- 컴포넌트 구현은 DI로 교체 가능한 상태가 유지된다.

---

## Links

- SPEC R4, R7, R8
- ADR-0008 (텐서 배포)
- ADR-0009 (커널 실행)
- ADR-0015 (컴포넌트 포트/와이어 모델과 엔진 역할)
- ADR-0010 (CLI 표면과 실행 시맨틱 — 런타임 API 소비자)