124 lines
8.6 KiB
Text
124 lines
8.6 KiB
Text
<!-- task=proto-socket-iop-parser-alias plan=0 tag=IOP_PARSER_ALIAS -->
|
|
# Plan: IOP proto-socket parser alias 정합성
|
|
|
|
## 이 파일을 읽는 구현 에이전트에게
|
|
|
|
이 plan은 IOP Flutter client가 sibling `../proto-socket/dart` 최신 alias 정책을 소비할 때 발생하는 parser map 초기화 실패를 IOP 소비 코드에서 정리하기 위한 실행 계약이다. proto-socket core는 변경하지 않고, IOP의 explicit short-name parser entry만 canonical full-name 등록 방식에 맞춘다.
|
|
|
|
구현 에이전트는 실제 변경과 검증 출력으로 `CODE_REVIEW-local-G04.md`의 구현 에이전트 소유 섹션을 반드시 채운다. 사용자 전용 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 충돌 없이는 안전하게 진행할 수 없는 경우 직접 질문하지 말고 review stub의 `사용자 리뷰 요청` 섹션에 정확한 blocker를 기록한 뒤 중단한다. 후속 에이전트가 재실행/증거 수집으로 해소할 수 있는 검증 공백은 사용자 리뷰 요청이 아니다.
|
|
|
|
## 사용자 리뷰 요청 흐름
|
|
|
|
구현 중 blocker는 active `CODE_REVIEW-local-G04.md`의 `사용자 리뷰 요청` 섹션에만 기록한다. 구현 에이전트는 chat에서 사용자에게 선택지를 제시하거나 `request_user_input`을 호출하지 않는다.
|
|
|
|
## Roadmap Targets
|
|
|
|
- 없음: 현재 IOP 활성 Milestone은 `agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md`이며, 이 작업은 vLLM milestone이 아니라 sibling `proto-socket` dependency 소비 정합성 follow-up이다.
|
|
|
|
## 분석 결과
|
|
|
|
### 읽은 파일
|
|
|
|
- `agent-roadmap/current.md`
|
|
- `agent-test/local/rules.md`
|
|
- `agent-test/local/client-smoke.md`
|
|
- `apps/client/lib/iop_wire/parser_map.dart`
|
|
- `apps/client/lib/iop_wire/client_wire_client.dart`
|
|
- `apps/client/test/iop_wire/parser_map_test.dart`
|
|
- `apps/client/test/iop_wire/client_wire_client_test.dart`
|
|
- `apps/client/test/client_bootstrap_test.dart`
|
|
- `apps/client/test/widget_test.dart`
|
|
- `/config/workspace/proto-socket/PROTOCOL.md`
|
|
- `/config/workspace/proto-socket/dart/lib/src/communicator.dart`
|
|
- `/config/workspace/proto-socket/dart/test/communicator_test.dart`
|
|
|
|
### 테스트 환경 규칙
|
|
|
|
- `apps/client/**` 변경이므로 `agent-test/local/client-smoke.md`를 따른다.
|
|
- Flutter client 검증의 공식 evidence는 원격 runner `ssh toki@toki-labs.com`의 `/Users/toki/agent-work/iop` 기준이다.
|
|
- 현재 checkout의 uncommitted 변경은 원격 checkout에 자동 반영되지 않는다. 원격 runner가 동기화되지 않았으면 local Flutter quick check는 보조 evidence로만 기록하고 남은 위험을 남긴다.
|
|
- 현재 IOP 작업 트리에는 이 plan과 무관한 `agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md` 수정이 있다. 이 plan에서는 건드리지 않는다.
|
|
|
|
### 문제 재현 근거
|
|
|
|
- IOP Flutter targeted test에서 `Duplicate alias mapping: ClientHelloRequest maps to both iop.ClientHelloRequest and ClientHelloRequest`로 실패했다.
|
|
- 실패 경로는 `ClientWireClient`가 `Map.from(clientParserMap)`을 `WsProtobufClient`에 넘기고, proto-socket Dart `Communicator.initialize`가 full name과 short name을 모두 registration key로 받은 뒤 자동 alias 생성 단계에서 충돌하는 흐름이다.
|
|
- proto-socket `PROTOCOL.md`는 등록/송신 기준을 canonical protobuf full message name으로 두고, legacy simple-name은 receive compatibility로만 허용한다.
|
|
|
|
### 테스트 커버리지 공백
|
|
|
|
- 기존 `parser_map_test.dart`는 short-name key가 map에 직접 들어있어야 한다고 기대한다. 최신 proto-socket 정책에서는 IOP map이 full-name key만 보유하고, short-name 수신 호환은 proto-socket 내부 canonicalize 경로가 맡는다.
|
|
- `client_wire_client_test.dart`와 `client_bootstrap_test.dart`는 `ClientWireClient` 생성 경로가 더 이상 alias 충돌로 throw하지 않는 회귀 검증으로 함께 실행한다.
|
|
- proto-socket 자체 simple-name receive compatibility는 `/config/workspace/proto-socket/dart/test/communicator_test.dart`의 legacy alias routing 테스트가 담당하므로 IOP에서 중복으로 short key를 등록하지 않는다.
|
|
|
|
### 심볼 참조
|
|
|
|
- `clientParserMap`
|
|
- `ClientWireClient`
|
|
- `WsProtobufClient`
|
|
- `Communicator.initialize`
|
|
- `ClientHelloRequest`
|
|
- `ClientHelloResponse`
|
|
|
|
### 분할 판단
|
|
|
|
- 단일 plan으로 충분하다. 변경 대상은 IOP Flutter client parser map과 해당 unit test expectation뿐이며, proto-socket core나 IOP Go runtime 변경은 포함하지 않는다.
|
|
|
|
### 범위 결정 근거
|
|
|
|
- 포함: `apps/client/lib/iop_wire/parser_map.dart`의 short-name entry 제거, `apps/client/test/iop_wire/parser_map_test.dart` 기대값 갱신, IOP client constructor/bootstrap 경로 회귀 검증.
|
|
- 제외: proto-socket core 수정, generated protobuf 재생성, IOP Go service 변경, vLLM milestone 문서 변경, 전체 remote deployment/runtime smoke.
|
|
- 사용자가 선택한 방향은 consumer-side cleanup이며, 현재 문제 소비 프로젝트는 IOP로 한정한다.
|
|
|
|
### 빌드 등급
|
|
|
|
- `local-G04`: 변경은 작지만 sibling path dependency 최신 동작과 Flutter client 공식 runner 규칙을 함께 확인해야 한다.
|
|
|
|
## 구현 체크리스트
|
|
|
|
- [ ] `apps/client/lib/iop_wire/parser_map.dart`에서 `ClientHelloRequest`, `ClientHelloResponse` short-name key를 제거하고 `iop.ClientHelloRequest`, `iop.ClientHelloResponse` full-name key만 남긴다.
|
|
- [ ] `apps/client/test/iop_wire/parser_map_test.dart`가 full-name key 존재와 short-name key 부재를 검증하도록 갱신한다.
|
|
- [ ] parser 동작 검증도 full-name key를 통해 수행한다.
|
|
- [ ] `ClientWireClient` 생성 및 bootstrap 경로가 duplicate alias error 없이 통과하는지 targeted Flutter test로 확인한다.
|
|
- [ ] `apps/client` 전체 Flutter test 또는 실행 불가 사유를 `CODE_REVIEW-local-G04.md`에 기록한다.
|
|
- [ ] `CODE_REVIEW-local-G04.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
|
|
|
|
## 구현 항목
|
|
|
|
- [IOP_PARSER_ALIAS-1] IOP client parser map canonical key 정리
|
|
- 문제: `apps/client/lib/iop_wire/parser_map.dart:4`의 `clientParserMap`이 `iop.ClientHelloRequest`와 `ClientHelloRequest`를 동시에 등록한다.
|
|
- 해결: short-name key 2개를 제거하고 canonical full-name key 2개만 유지한다.
|
|
- 변경 파일: `apps/client/lib/iop_wire/parser_map.dart`
|
|
- 중간 검증: `cd apps/client && flutter test test/iop_wire/client_wire_client_test.dart`
|
|
|
|
- [IOP_PARSER_ALIAS-2] parser map test expectation 갱신
|
|
- 문제: `apps/client/test/iop_wire/parser_map_test.dart:11`과 `:12`가 short-name key 직접 등록을 요구하고, parser lookup도 short-name key로 수행한다.
|
|
- 해결: full-name key 존재, short-name key 부재, full-name key parser round-trip을 검증한다.
|
|
- 변경 파일: `apps/client/test/iop_wire/parser_map_test.dart`
|
|
- 중간 검증: `cd apps/client && flutter test test/iop_wire/parser_map_test.dart`
|
|
|
|
- [IOP_PARSER_ALIAS-3] IOP client 생성 경로 회귀 검증
|
|
- 문제: duplicate alias error는 `ClientWireClient` 생성 시점에도 발생하므로 parser map 단독 테스트만으로는 부족하다.
|
|
- 해결: `client_wire_client_test.dart`, `client_bootstrap_test.dart`를 targeted regression으로 실행하고, 가능하면 `apps/client` 전체 Flutter test까지 확인한다.
|
|
- 변경 파일: 없음
|
|
- 중간 검증: `cd apps/client && flutter test test/iop_wire/parser_map_test.dart test/iop_wire/client_wire_client_test.dart test/client_bootstrap_test.dart`
|
|
|
|
## 수정 파일 요약
|
|
|
|
- 예상 변경: `apps/client/lib/iop_wire/parser_map.dart`
|
|
- 예상 변경: `apps/client/test/iop_wire/parser_map_test.dart`
|
|
- 변경 금지: `/config/workspace/proto-socket/**`, generated protobuf files, vLLM milestone 문서, secret/private endpoint 문서
|
|
|
|
## 최종 검증
|
|
|
|
공식 evidence는 원격 runner의 동기화된 checkout 기준이다. 동기화되지 않은 local 실행만 가능하면 그 사실과 남은 위험을 review stub에 기록한다.
|
|
|
|
```bash
|
|
cd apps/client && flutter test test/iop_wire/parser_map_test.dart test/iop_wire/client_wire_client_test.dart test/client_bootstrap_test.dart
|
|
cd apps/client && flutter test
|
|
git diff --check
|
|
```
|
|
|
|
예상 결과: duplicate alias error 없이 targeted regression과 client Flutter test가 통과하고 whitespace error가 없다.
|
|
|
|
모든 코드 변경 완료 후 반드시 `CODE_REVIEW-local-G04.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
|