gito/agent-roadmap/phase/control-plane-foundation/milestones/branch-event-protosocket-interop-readiness.md

Milestone: Branch Event Proto-Socket Interop Readiness

위치

• Roadmap: agent-roadmap/ROADMAP.md
• Phase: agent-roadmap/phase/control-plane-foundation/PHASE.md

목표

Forgejo push webhook에서 정규화된 branch.updated event를 여러 외부 consumer가 실제 Gito /proto-socket wire protocol로 구독하고 수신할 수 있음을 증명한다. 논리 JSON envelope 예시와 실제 proto-socket binary/protobuf frame 경계를 계약에 분리해 기록하고, base schema는 consumer-neutral하게 유지하며 consumer별 확장은 metadata 같은 optional custom field로만 다루는 기준을 남긴다.

상태

[검토중]

승격 조건

• 없음

구현 잠금

• 상태: 해제
• 결정 필요: 없음

범위

• gito.forgejo-branch-events.v1 계약의 실제 /proto-socket wire format 명시
• event.subscribe request와 branch.updated broadcast의 channel/action/payload shape 고정
• NomadCode 전용 payload가 아닌 branch event 범용 base schema와 optional metadata/custom extension 경계
• proto-socket binary/protobuf client fixture로 Gito server producer 호환성 검증
• Forgejo webhook, branch listener, event fanout을 묶은 producer-side smoke 경로
• NomadCode를 초기 consumer smoke 대상으로 쓰되, 다른 consumer가 같은 schema를 재사용할 수 있는 운영 확인 절차

기능

Epic: [branch-wire] Branch event wire interop

Gito가 제공하는 branch event producer 표면을 문서상 계약이 아니라 실제 proto-socket wire 호환 기준으로 고정하되, base event schema를 특정 consumer에 종속시키지 않는다.

• [wire-contract] gito.forgejo-branch-events.v1에 /proto-socket이 binary protobuf frame을 사용하고 JSON은 논리 envelope 예시임을 명시한다. 검증: 계약 문서가 frame type, channel/action, payload 필드와 optional metadata/custom field 경계를 함께 설명한다.
• [schema-neutrality] branch.updated base payload를 repo, branch, revision, changed files 같은 범용 Git event 정보로 유지하고 consumer-specific field는 optional metadata/custom 영역으로만 허용한다. 검증: 계약 fixture에 NomadCode 전용 필수 필드가 없다.
• [producer-fixture] 실제 proto-socket Go client 또는 동등한 binary fixture로 event.subscribe를 보내고 branch.updated를 수신하는 producer-side 테스트를 추가한다. 검증: text JSON websocket client가 아니라 binary proto-socket 경로로 test가 통과한다.
• [webhook-smoke] Forgejo push webhook, watched branch listener, event outbox/fanout을 이어 branch.updated가 발행되는 smoke 절차를 남긴다. 검증: test 또는 dev smoke에서 before, after, changed_files가 consumer payload로 도달한다.
• [consumer-interop] NomadCode를 첫 smoke consumer로 사용하되 schema가 NomadCode 전용으로 좁아지지 않는 최소 interop 확인 절차를 기록한다. 검증: NomadCode dev consumer가 generic branch.updated를 받아 자기 내부 wakeup으로 매핑하고, base payload에는 NomadCode 전용 필수 필드가 없다.
• [ops-docs] listener bootstrap, /proto-socket, /api/listeners/branches, /api/events 운영 확인 절차를 README 또는 contract note에 보강한다. 검증: 필요한 endpoint와 env가 secret 없이 재현 가능하게 적힌다.

완료 리뷰

• 상태: 요청됨
• 요청일: 2026-06-15
• 완료 근거:
  • services/core/internal/controlplane/binary_interop_test.go가 branch watch 등록, binary proto-socket event.subscribe, Forgejo push callback, branch.updated 수신을 한 경로로 검증한다.
  • agent-contract/provided/gito-forgejo-branch-events-v1.md에 binary protobuf frame, consumer-neutral base payload, 운영 smoke 절차가 정리되어 있다.
  • cd services/core && go test -run TestBinaryProtoSocketBranchUpdated ./internal/controlplane -count=1 통과.
• 리뷰 필요:
  • 사용자가 완료 결과를 확인했다
  • archive 이동을 승인했다
• 리뷰 코멘트: 모든 기능 Task가 완료 근거와 함께 충족되어 완료 후보로 올린다. 사용자 확인과 archive 승인 전까지 활성 Milestone으로 유지한다.

범위 제외

• NomadCode core consumer transport 구현
• NomadCode 전용 event schema 또는 필수 payload field 추가
• Plane creation sync enqueue 구현
• Forgejo provider delivery dedupe의 고도화
• provider PR/MR ChangeRequest adapter
• Flutter control surface 표시 기능

작업 컨텍스트

• 관련 경로: agent-contract/provided/gito-forgejo-branch-events-v1.md, services/core/internal/protosocket/, services/core/internal/controlplane/, services/core/internal/provider/forgejo/, services/core/internal/events/
• 표준선(선택): Gito /proto-socket의 source of truth는 proto-socket binary/protobuf transport이며, JSON envelope는 계약 이해를 돕는 논리 표현으로만 둔다. Event base schema는 consumer-neutral하게 유지하고, 특정 consumer에만 필요한 값은 optional metadata 또는 custom extension에만 둔다.
• 선행 작업: Forgejo Branch Event MVP
• 우선순위: NomadCode 연동 MVP의 Gito-side 최우선 slice로, IOP Agent Run Bridge보다 먼저 닫는다.
• 후속 작업: NomadCode Gito Proto-Socket Consumer Wire Readiness, 이후 Gito Branch Event Creation Sync Bridge의 남은 semantic bridge 완료/검토
• 확인 필요: 없음