diff --git a/PORTING_GUIDE.md b/PORTING_GUIDE.md index a805a8d..ce2ddc0 100644 --- a/PORTING_GUIDE.md +++ b/PORTING_GUIDE.md @@ -17,7 +17,7 @@ |------|---------|------| | Transport 분리 | `Transport` interface | WritePacket과 Close만 있으면 됨. 소켓 종류(TCP/WS)에 무관하게 Communicator가 동작 | | typeName 라우팅 | `TypeNameOf()` | protobuf full message name 기반. 언어마다 추출 방식이 다르므로 PROTOCOL.md의 언어별 표 확인 | -| nonce 단조 증가 | `atomic.Int32` | 연결당 1에서 시작, 송신마다 +1. thread-safe하게 구현 | +| nonce 단조 증가 + 충돌 회피 | `atomic.Int32` + pending-correlation 조회 | 연결당 1에서 시작, 송신마다 +1. 송신 전 candidate nonce가 active pending request의 key(`sendRequest` 대기 중 nonce)와 충돌하면 건너뛴다. candidate 선택과 pending 조회는 같은 임계구역 또는 동등한 동시성 안전성을 가져야 한다. 충돌 없는 값이 없으면 오류로 실패 | | connCloseOnce | `sync.Once` | Close가 여러 번 불려도 한 번만 수행되어야 함 | | addListener / addRequestListener 상호 배타 | panic or throw | 같은 typeName에 두 가지 동시 등록 금지. 프로토콜 계약 | | heartbeat 자동 처리 | `baseClient` 내부 | 앱 코드에서 HeartBeat를 직접 등록하거나 처리하지 않음 | diff --git a/PROTOCOL.md b/PROTOCOL.md index ce7ad4c..7214093 100644 --- a/PROTOCOL.md +++ b/PROTOCOL.md @@ -160,6 +160,8 @@ Changing the proto package or `typeName` derivation rule is a breaking protocol - Starts at `1` per connection - Increments by `1` on every send call (including requests and responses) +- If a candidate nonce matches a currently pending request correlation key (`sendRequest` in-flight `nonce`), implementations must skip the candidate and try the next nonce. +- If every positive `int32` nonce value is currently pending, outbound send should fail with an explicit error instead of reusing an active pending nonce. - Maximum nonce is `2,147,483,647` (`int32` max), the lowest common signed integer max across supported protocol fields - After issuing `2,147,483,647`, implementations reset the internal counter to `0`; the next emitted packet nonce is `1` - `0` is reserved and must not be emitted as `PacketBase.nonce`, because `responseNonce == 0` means "not a response" diff --git a/VERSIONING.md b/VERSIONING.md index e99a638..88f1af1 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -92,6 +92,8 @@ The maximum emitted nonce is `2,147,483,647` (`int32` max). Current policy: - Implementations start at `1` and increment by `1` on every send call, including requests and responses. +- When selecting the next nonce to emit, implementations must skip any value that is currently used by an active pending request (`sendRequest` correlation map). This keeps nonce reuse from colliding with in-flight requests after wrap. +- If all positive `int32` nonce values are currently pending, `sendRequest`/`send` must fail explicitly rather than emit a duplicate correlation nonce. - After issuing `2,147,483,647`, implementations reset the internal counter to `0`; the next emitted `PacketBase.nonce` is `1`. - `0` is reserved and must not be emitted as `PacketBase.nonce`, because `responseNonce == 0` means "not a response". diff --git a/agent-task/m-protocol-evolution-compatibility/04+03_nonce_contract/CODE_REVIEW-local-G04.md b/agent-task/archive/2026/06/m-protocol-evolution-compatibility/04+03_nonce_contract/code_review_local_G04_0.log similarity index 73% rename from agent-task/m-protocol-evolution-compatibility/04+03_nonce_contract/CODE_REVIEW-local-G04.md rename to agent-task/archive/2026/06/m-protocol-evolution-compatibility/04+03_nonce_contract/code_review_local_G04_0.log index 9519d1e..c225431 100644 --- a/agent-task/m-protocol-evolution-compatibility/04+03_nonce_contract/CODE_REVIEW-local-G04.md +++ b/agent-task/archive/2026/06/m-protocol-evolution-compatibility/04+03_nonce_contract/code_review_local_G04_0.log @@ -40,42 +40,44 @@ task=m-protocol-evolution-compatibility/04+03_nonce_contract, plan=0, tag=API | 항목 | 완료 여부 | |------|---------| -| [API-1] Nonce Contract 문서화 | [ ] | -| [API-2] Porting 기준 정렬 | [ ] | +| [API-1] Nonce Contract 문서화 | [x] | +| [API-2] Porting 기준 정렬 | [x] | ## 구현 체크리스트 -- [ ] `PROTOCOL.md`의 `nonce` 섹션에 active pending nonce skip 정책과 all-positive-nonces-pending 예외를 명시한다. -- [ ] `VERSIONING.md`의 `nonce Overflow` 정책에 pending 충돌 회피와 호환성 기준을 반영한다. -- [ ] `PORTING_GUIDE.md`의 nonce 공통 구조 설명을 pending skip 기준으로 보강한다. -- [ ] `tools/check_proto_sync.sh`와 `git diff --check`를 실행한다. -- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. +- [x] `PROTOCOL.md`의 `nonce` 섹션에 active pending nonce skip 정책과 all-positive-nonces-pending 예외를 명시했다. +- [x] `VERSIONING.md`의 `nonce Overflow` 정책에 pending 충돌 회피와 호환성 기준을 반영했다. +- [x] `PORTING_GUIDE.md`의 nonce 공통 구조 설명을 pending skip 기준으로 보강했다. +- [x] `tools/check_proto_sync.sh`와 `git diff --check`를 실행해 PASS/정상 결과를 확인했다. +- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채웠다. ## 코드리뷰 전용 체크리스트 > **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다. > 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다. -- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. -- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. -- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_{review_lane}_GNN_N.log`로 아카이브한다. -- [ ] active `PLAN-*-G??.md`를 `plan_{build_lane}_GNN_M.log`로 아카이브한다. -- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다. -- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. -- [ ] PASS이면 active task 디렉터리 `agent-task/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. -- [ ] PASS이고 task group이 `m-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. -- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/{task_group}/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. +- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. +- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. +- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_{review_lane}_GNN_N.log`로 아카이브한다. +- [x] active `PLAN-*-G??.md`를 `plan_{build_lane}_GNN_M.log`로 아카이브한다. +- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다. +- [x] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. +- [x] PASS이면 active task 디렉터리 `agent-task/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. +- [x] PASS이고 task group이 `m-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. +- [x] PASS split 작업이면 이동 후 빈 active parent `agent-task/{task_group}/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. - [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다. - [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다. - [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다. ## 계획 대비 변경 사항 -_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ +계획과 동일하게 문서 계약 3개 파일(PROTOCOL, VERSIONING, PORTING_GUIDE)만 수정했다. ## 주요 설계 결정 -_구현 에이전트가 주요 설계 결정 사항을 기록한다._ +- Nonce wrap는 더 이상 단순 `현재값+1`이 아닌, 발신 전 active pending request nonce 충돌 검사 후 건너뛰기(skip)로 보강한다. +- 충돌 회피를 문서화하되, 구현 방식(구체적인 조회 자료구조/알고리즘)은 언어별 구현 단계로 넘겨서 일관된 동작 기준만 고정했다. +- 모든 양수 nonce가 pending 상태일 때는 새로운 발신을 에러로 실패하도록 명시해, 기존 동작(`0`으로 wrap 후 즉시 1 사용)의 회피 경로를 계약화했다. ## 사용자 리뷰 요청 @@ -107,20 +109,21 @@ _구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 ### API-1 중간 검증 ```bash $ tools/check_proto_sync.sh -(output) +Proto schemas are in sync. ``` ### API-2 중간 검증 ```bash $ git diff --check -(output) +(no output) ``` ### 최종 검증 ```bash $ tools/check_proto_sync.sh $ git diff --check -(output) +Proto schemas are in sync. +(no output) ``` --- @@ -142,3 +145,21 @@ $ git diff --check | 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless user input is required to proceed | | 리뷰어를 위한 체크포인트 | Fixed at stub creation | Review focus areas | | 검증 결과 | Implementing agent | Fill command output only | + +## 코드리뷰 결과 + +- 종합 판정: PASS +- 차원별 평가: + - Correctness: Pass + - Completeness: Pass + - Test coverage: Pass + - API contract: Pass + - Code quality: Pass + - Plan deviation: Pass + - Verification trust: Pass +- 발견된 문제: 없음 +- 리뷰 중 직접 보정: + - `PORTING_GUIDE.md`의 nonce 포팅 기준에 candidate 선택과 pending 조회의 동시성 안전성 문장을 보강했다. 계획의 API-2 해결 방법에 포함된 문구이며, 문서-only 범위 안의 비동작 보정이다. +- PASS split 정리: + - active parent `agent-task/m-protocol-evolution-compatibility/`는 sibling `05+04_nonce_dart_go`, `06+04,05_nonce_kotlin_python_ts`가 남아 있어 유지했다. +- 다음 단계: PASS 절차에 따라 `complete.log` 작성 후 task directory를 archive로 이동한다. diff --git a/agent-task/archive/2026/06/m-protocol-evolution-compatibility/04+03_nonce_contract/complete.log b/agent-task/archive/2026/06/m-protocol-evolution-compatibility/04+03_nonce_contract/complete.log new file mode 100644 index 0000000..5624944 --- /dev/null +++ b/agent-task/archive/2026/06/m-protocol-evolution-compatibility/04+03_nonce_contract/complete.log @@ -0,0 +1,34 @@ +# Complete - m-protocol-evolution-compatibility/04+03_nonce_contract + +## 완료 일시 + +2026-06-17 + +## 요약 + +Nonce contract 문서화 task를 1회 리뷰 루프로 완료했으며 최종 판정은 PASS다. + +## 루프 이력 + +| Plan | Review | Verdict | 메모 | +|------|--------|---------|------| +| `plan_local_G04_0.log` | `code_review_local_G04_0.log` | PASS | nonce pending collision skip 계약과 porting 기준이 문서에 반영됨 | + +## 구현/정리 내용 + +- `PROTOCOL.md`에 active pending request nonce와 충돌하는 candidate nonce skip 및 all-positive-nonces-pending 실패 정책을 추가했다. +- `VERSIONING.md`의 nonce overflow 정책에 pending 충돌 회피와 wrap 호환성 기준을 반영했다. +- `PORTING_GUIDE.md`의 nonce 공통 구조 설명을 pending skip 기준과 동시성 안전성 기준으로 보강했다. + +## 최종 검증 + +- `tools/check_proto_sync.sh` - PASS; `Proto schemas are in sync.` +- `git diff --check` - PASS; 출력 없음 + +## 잔여 Nit + +- 없음 + +## 후속 작업 + +- 없음 diff --git a/agent-task/m-protocol-evolution-compatibility/04+03_nonce_contract/PLAN-local-G04.md b/agent-task/archive/2026/06/m-protocol-evolution-compatibility/04+03_nonce_contract/plan_local_G04_0.log similarity index 100% rename from agent-task/m-protocol-evolution-compatibility/04+03_nonce_contract/PLAN-local-G04.md rename to agent-task/archive/2026/06/m-protocol-evolution-compatibility/04+03_nonce_contract/plan_local_G04_0.log