iop/agent-task/proto-socket-iop-parser-alias/PLAN-local-G04.md

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에 기록한다.

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의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.