web-framework 3.0 GA flip — peer 2.6.x→3.0, beta dist-tag 승격, beta-tracking TODO 되돌리기

[DaveDev42]

배경

@apps-in-toss/web-framework@3.0.0-beta.9d42c0b 채택 wave는 beta/latest 이원화로 전환기를 흡수하고 있다(beta dist-tag=3.0 라인, latest=2.6.x 보호). web-framework가 stable 3.0.0을 GA로 출시하면 이 이원화를 일괄로 닫는 "flip" 작업이 필요하다. 현재 이 flip은 plan 파일 + 흩어진 인라인 TODO에만 있고 트래킹 이슈가 없다 — 이 이슈가 그 source of truth다.

GA 트리거

• npm view @apps-in-toss/web-framework dist-tags에서 latest가 stable 3.0.0(또는 GA 버전)을 가리키게 되는 시점. 현재는 latest=2.6.1, beta=3.0.0-beta.9d42c0b — 아직 GA 전, 이 이슈는 그때까지 대기.

flip 체크리스트 (devtools)

• package.json peer >=2.6.0 <2.7.0 → >=3.0.0 <4.0.0 (또는 합의된 transition matrix). peerDependenciesMeta.optional는 정책 재검토.
• package.json devDep exact beta pin 3.0.0-beta.9d42c0b → ^3.0.0(GA 버전).
• scripts/check-sdk-update.ts: dist-tags.beta 조회 → version(latest)로 되돌리기 (인라인 TODO 있음).
• scripts/diff-sdk-exports.ts: 동일 — dist-tags.beta → version 되돌리기 (인라인 TODO 있음).
• CLAUDE.md: peer range GA 교체 메모 반영.
• devtools latest dist-tag로 GA mock publish → npm dist-tag 정리(beta 제거 여부 결정).
• GA 아티팩트로 dog-food 전 과정 재검증(install~operate, 31146).

짝 작업 (다른 repo — 별도 이슈/PR)

• sdk-example·polyfill·docs·agent-plugin 템플릿: exact beta pin → ^3.0.0. (Type A/B repo 일괄 GA Flip Wave.)

참고

• plan: web-framework 3.0 채택 "GA Flip Wave" 섹션.
• 채택 wave PR: devtools feat: adopt @apps-in-toss/web-framework 3.0.0-beta in SDK mock #355(c40edfb), Version Packages Version Packages #367.

[DaveDev42]

진행 상태 (2026-06-02): beta 채택 wave 6 PR 전수 머지 완료, GA flip은 여전히 미착수 — npm view @apps-in-toss/web-framework dist-tags 재확인 결과 latest=2.6.1/beta=3.0.0-beta.9d42c0b로 GA 전이라 트리거 미발화. GA flip 상태는 umbrella CLAUDE.md §5.1 + devtools CLAUDE.md(#373 머지)에 무시간 정본 한 줄로 기록했고, 변동 진척의 source of truth는 이 이슈. (참고: GA용으로 비워뒀던 0.1.54 devtools 슬롯은 무관한 maintenance Version PR이 선점 → 현 @ait-co/devtools latest=0.1.54, peer >=2.6.0 <2.7.0 불변. flip 시 그 시점 latest 다음 patch를 쓴다.)

[DaveDev42]

GA flip 완료가 devtools #376(bridge-level 디스패처 역전, Option B)의 착수 트리거다 — #376은 이 GA flip에 blocked by. 탐색 정본은 #371.

[DaveDev42]

GA flip 리스크 — 콘솔 server-build가 3.0 번들을 아직 못 받음

dogfood(31146) 실측에서 GA flip의 deploy 스토리 상위 blocker를 발견 → sdk-example#149로 이슈화.

요지: web-framework 3.0.0-beta로 빌드한 .ait 번들을 aitcc app deploy로 올리면 업로드는 성공하지만 콘솔 server-side 빌드가 BUILD_FAILED로 거부한다("잘못된 앱 정보", sdkVersion=null). 2.6.0 번들은 전부 CREATED 성공했고 3.0-beta는 한 번도 통과 못 함 — 콘솔 백엔드가 3.0 세대 번들 포맷(config rename + schema + bundle.json 변경)을 아직 처리하지 못하는 플랫폼 갭이다.

GA flip 실행 시 함의: peer/pin을 3.0으로 올리고 dist-tag를 flip해도, 콘솔이 3.0 번들을 server-build 못 하면 station 5(ship)·6(operate)이 닫히지 않는다. GA flip 자체(버전 플립)는 meta/ga-flip-execution-spec.md 명세대로 진행 가능하나, dogfood deploy 검증은 콘솔 백엔드가 3.0을 수용할 때까지 막힌다. flip 실행 시 이 항목을 risk로 명시하고, deploy 검증은 콘솔 수용 확인 후로 분리한다.

추적: apps-in-toss-community/sdk-example#149.