<!-- task=edge_node_arch plan=1 tag=REFACTOR -->

# Code Review Reference - REFACTOR

## 개요

date=2026-05-02
task=edge_node_arch, plan=1, tag=REFACTOR

## 이 파일을 읽는 리뷰 에이전트에게

각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
리뷰 완료 후 반드시 아래 순서로 아카이브하세요.

1. `CODE_REVIEW.md` → `code_review_1.log`
2. `PLAN.md` → `plan_1.log`
3. PASS인 경우 `complete.log` 작성 후 종료. WARN/FAIL인 경우 새 `PLAN.md` + `CODE_REVIEW.md` 스텁 작성.

---

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| [REFACTOR-1] proto 컴파일 및 go.mod 업데이트 | [x] |
| [REFACTOR-2] node transport 클라이언트 계층 구현 | [x] |
| [REFACTOR-3] node.go proto 타입으로 교체 | [x] |
| [REFACTOR-4] node bootstrap DialEdge 연결 추가 | [x] |
| [REFACTOR-5] edge TCP 서버 + NodeRegistry 구현 | [x] |

## 계획 대비 변경 사항

- `make`가 환경에 설치되어 있지 않아 `make proto`는 실패했다. 동일한 Makefile 명령을 `protoc --go_out=. --go_opt=module=iop --proto_path=.`로 직접 실행해 `proto/gen/iop/*.pb.go`를 생성했다.
- 기존 Makefile의 `paths=source_relative` 옵션은 `proto/iop/*.pb.go`를 생성하므로, PLAN의 기대 경로(`proto/gen/iop`)와 import path(`iop/proto/gen/iop`)를 맞추기 위해 `--go_opt=module=iop`로 변경했다.
- CODE_REVIEW의 체크포인트 중 `RunRequest.Input`을 bytes/json으로 확인하라는 항목은 현재 `proto/iop/runtime.proto` 정의와 PLAN의 본문이 `google.protobuf.Struct`를 사용하므로 `AsMap()` 변환 기준으로 구현했다.
- `edgeParserMap`에는 `SendRequestTyped` 응답 파싱을 위해 `CapabilityResponse` 파서를 추가했다.

## 주요 설계 결정

- node는 proto-socket `TcpClient`를 `transport.Session`으로 감싸고, `RunRequest`, `CapabilityRequest`, `CancelRequest` 리스너를 세션 생성 시 등록한다.
- edge는 proto-socket `TcpServer`로 node 연결을 받고, 연결 직후 `CapabilityRequest`를 보내 `NodeRegistry`에 nodeID와 adapter 목록을 등록한다.
- `RunEvent`는 삭제된 JSON Envelope 없이 protobuf 메시지를 proto-socket으로 직접 전송한다.
- `RunRequest.Policy`와 `RunRequest.Input`은 nil-safe helper로 `google.protobuf.Struct.AsMap()` 변환한다.

## 리뷰어를 위한 체크포인트

- `go.mod`에 `replace git.toki-labs.com/toki/common-proto-socket/go => ../proto-socket/go` 존재 여부
- `proto/gen/iop/` 하위 4개 파일 생성 여부 (runtime, node, control, job)
- `transport/session.go`의 `Handler` 인터페이스가 `*iop.RunRequest`, `*iop.CapabilityResponse`, `*iop.CancelRequest` 사용 여부
- `transport/session.go`의 `newSession`에서 `AddListenerTyped`(RunRequest, CancelRequest), `AddRequestListenerTyped`(CapabilityRequest) 세 리스너 모두 등록 여부
- `transport/parser.go`의 `nodeParserMap`에 RunRequest, CancelRequest, CapabilityRequest 세 타입 등록 여부
- `node.go`의 `sessionSink.Emit`이 `*iop.RunEvent`를 `sess.Send`로 직접 전송하는지 (Envelope 없음)
- `node.go`의 `OnRunRequest`에서 `req.GetPolicy()` / `req.GetInput()` Struct를 `AsMap()`으로 `map[string]any` 변환 여부
- `bootstrap/module.go`에 `transport.DialEdge` 호출이 fx OnStart에 있고 OnStop에서 `sess.Close()` 호출 여부
- `apps/edge/internal/node/registry.go`의 NodeRegistry가 Register/Unregister/Pick/Count/All 메서드 모두 구현 여부
- edge `onNodeConnected`에서 CapabilityRequest 전송 후 nodeID를 받아 Registry에 등록하는 흐름 확인
- edge `onNodeConnected`에서 disconnect 시 Registry.Unregister 호출 여부
- `registry_test.go` 테스트 3개 통과 여부
- 최종 검증: edge 실행 후 node 연결 시 edge 로그에 `node registered` 출력 확인

## 검증 결과

_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._

### REFACTOR-1 중간 검증
```
$ PATH=/config/go-sdk/bin:$PATH make proto
/usr/bin/bash: line 1: make: command not found

$ PATH=/config/go-sdk/bin:$PATH protoc --go_out=. --go_opt=module=iop --proto_path=. proto/iop/runtime.proto proto/iop/node.proto proto/iop/control.proto proto/iop/job.proto
(no output)

$ ls proto/gen/iop/
control.pb.go
job.pb.go
node.pb.go
runtime.pb.go

$ PATH=/config/go-sdk/go/bin:/config/go-sdk/bin:$PATH go mod tidy
(no output)
```

### REFACTOR-2 중간 검증
```
$ PATH=/config/go-sdk/go/bin:/config/go-sdk/bin:$PATH go build ./apps/node/internal/transport/...
(no output)
```

### REFACTOR-3 중간 검증
```
$ PATH=/config/go-sdk/go/bin:/config/go-sdk/bin:$PATH go build ./apps/node/...
(no output)
```

### REFACTOR-4 중간 검증
```
$ PATH=/config/go-sdk/go/bin:/config/go-sdk/bin:$PATH go build ./apps/node/...
(no output)
```

### REFACTOR-5 중간 검증
```
$ PATH=/config/go-sdk/go/bin:/config/go-sdk/bin:$PATH go build ./apps/edge/...
(no output)

$ PATH=/config/go-sdk/go/bin:/config/go-sdk/bin:$PATH go test ./apps/edge/internal/node/...
ok  	iop/apps/edge/internal/node	0.002s
```

### 최종 검증
```
# 터미널 A
$ ./bin/edge serve --config configs/edge.yaml
{"level":"info","caller":"transport/server.go:66","msg":"edge listening for nodes","addr":"0.0.0.0:9090"}
{"level":"info","caller":"transport/server.go:75","msg":"node connection established"}
{"level":"info","caller":"transport/server.go:102","msg":"node registered","node_id":"node-001","adapters":1}

# 터미널 B
$ ./bin/node serve --config configs/node.yaml
{"level":"info","caller":"store/store.go:53","msg":"store ready","dsn":"file:iop.db?cache=shared&mode=rwc"}
{"level":"info","caller":"transport/client.go:35","msg":"connected to edge","addr":"localhost:9090","node_id":"node-001"}

$ PATH=/config/go-sdk/go/bin:/config/go-sdk/bin:$PATH go build ./...
(no output)

$ PATH=/config/go-sdk/go/bin:/config/go-sdk/bin:$PATH go test ./...
?   	iop/apps/control-plane/cmd/control-plane	[no test files]
?   	iop/apps/edge/cmd/edge	[no test files]
?   	iop/apps/edge/internal/bootstrap	[no test files]
ok  	iop/apps/edge/internal/node	(cached)
?   	iop/apps/edge/internal/transport	[no test files]
?   	iop/apps/node/cmd/node	[no test files]
?   	iop/apps/node/internal/adapters	[no test files]
?   	iop/apps/node/internal/adapters/cli	[no test files]
?   	iop/apps/node/internal/adapters/mock	[no test files]
?   	iop/apps/node/internal/adapters/ollama	[no test files]
?   	iop/apps/node/internal/adapters/vllm	[no test files]
?   	iop/apps/node/internal/bootstrap	[no test files]
?   	iop/apps/node/internal/node	[no test files]
?   	iop/apps/node/internal/router	[no test files]
?   	iop/apps/node/internal/runtime	[no test files]
?   	iop/apps/node/internal/store	[no test files]
?   	iop/apps/node/internal/transport	[no test files]
?   	iop/apps/worker/cmd/worker	[no test files]
?   	iop/packages/auth	[no test files]
?   	iop/packages/config	[no test files]
?   	iop/packages/jobs	[no test files]
?   	iop/packages/metadata	[no test files]
?   	iop/packages/observability	[no test files]
?   	iop/packages/policy	[no test files]
?   	iop/packages/version	[no test files]
?   	iop/proto/gen/iop	[no test files]
```

---

## 코드리뷰 결과

### 종합 판정: WARN

### 차원별 평가

| 차원 | 판정 |
|------|------|
| Correctness | Warn |
| Completeness | Pass |
| Test coverage | Pass |
| API contract | Pass |
| Code quality | Pass |
| Plan deviation | Pass |
| Verification trust | Pass |

### 발견된 문제

- **Suggested** `apps/edge/internal/transport/server.go:101-107`
  `client.AddDisconnectListener` 등록이 `s.registry.Register(entry)` 이후에 위치함.
  CapabilityResponse 수신 후 node가 즉시 disconnect되면 disconnect 이벤트가 listener 등록 전에 발생해 registry stale entry가 남을 수 있음.
  Fix: `AddDisconnectListener` 블록을 `s.registry.Register(entry)` 이전으로 이동.
  ```go
  // before:
  s.registry.Register(entry)
  s.logger.Info("node registered", ...)
  client.AddDisconnectListener(func(_ *toki.TcpClient) { ... })

  // after:
  client.AddDisconnectListener(func(_ *toki.TcpClient) {
      s.registry.Unregister(entry.NodeID)
      s.logger.Info("node unregistered", zap.String("node_id", entry.NodeID))
  })
  s.registry.Register(entry)
  s.logger.Info("node registered", ...)
  ```

- **Nit** `apps/node/internal/node/node.go:111`
  `a.Capabilities(context.Background())`가 `OnCapabilityRequest`에 전달된 `ctx`를 무시함.
  `ctx`를 직접 전달하면 호출 체인에서 cancellation이 일관성 있게 전파됨.

### 다음 단계

WARN: Suggested 이슈 수정을 위한 새 PLAN.md와 CODE_REVIEW.md 스텁을 작성한 후 구현 루프를 계속한다.