d3ro-voice/docs/REFACTOR_WAVE7_REPORT.md
Yun Chan 876e72ea2f
Some checks failed
ci / 정본·보안·린트·타입·테스트 (push) Failing after 18s
ci / 워크스페이스 빌드 검증 (push) Has been skipped
ci / 모바일 린트·타입·Jest (push) Successful in 45s
ci / Supabase Edge Functions + Cloudflare Worker (push) Successful in 22s
ci / .NET API 서버 테스트 (push) Successful in 11s
deploy-site / deploy (push) Successful in 44s
docs(wave7): record peer-swarm bug fixes, metrics, and map sync
2026-11-14 15:41:48 +09:00

14 KiB
Raw Blame History

D3RO Voice — Wave 7 다중 세션 피어 스웜 코드 위생 · 최적화 · 버그 헌팅 보고서

일시: 2026-11-14 대상 브랜치: main (기준 커밋 a37dd63 -> 통합 커밋 cc3f746, 7 commits / 98 files +7,170 / -597) 실행 토폴로지: Antigravity 네이티브 swarm 6개 세션 (monitor, input-core, desktop-shell, mobile-app, cloud-surfaces, verifier) + @mention/#seq 피어 리뷰 보드(Run /swarm board (default shortcut alt+s) to open the live board.) 정책 SSOT: docs/REFACTOR_POLICY.md, .claude/skills/refactor-wave/SKILL.md


1. 운영 배포 경계와 Wave 7 범위

  1. 운영 v1.17.1 기준선 (6c6875b, 태그 v1.17.1): 데스크톱(Forgejo 1.17.1/latest.yml·.sig, runtime-1.17.1, portable-1.17.1 HTTP 200; Human Release #339 ~91MB 바이너리 첨부만 GAP-REL-16 예외), Supabase 운영 DB(74개 마이그레이션 동기화)·Edge Functions 24종, 랜딩 사이트(site/ -> Cloudflare Pages d3ro, https://d3ro.chanpaca.net/release-identity.json), Cloudflare Worker(d3ro-voice-api --keep-vars, Version ID fe6d9532-0052-48f5-b62c-45c86f6aaaa5), NAS Docker 스택(api-server :5050/health 200, admin :3001 / d3ro-admin.chanpaca.net/login 200, web :3002/app/login / d3ro.chanpaca.net/app/login 200) 배포 완료 후 a37dd63에 기록됨.
  2. Wave 7 반영 범위 (2a009e4..cc3f746): Wave 7 커밋은 v1.17.1 배포 이후에 main으로 통합·검증되었다. 따라서 Wave 7 수정사항은 현재 main 통합 및 모노레포 전 게이트 검증 완료 상태이며, v1.17.1 기배포 바이너리·컨테이너에는 포함되어 있지 않다(차기 릴리스 v1.17.2 / v1.18.0 및 재배포 반영 대상).
  3. Cloudflare Worker 운영 환경변수 경계: Wave 7(c68e81e)이 server/cloudflare-worker/wrangler.toml의 BACKEND_ORIGIN 기본값을 https://d3ro.chanpaca.net으로 수정했으나, v1.17.1 배포 당시 --keep-vars로 유지된 라이브 Worker d3ro-voice-api(fe6d9532-0052-48f5-b62c-45c86f6aaaa5)에는 기존 대시보드 변수(BACKEND_ORIGIN = "http://192.168.0.39:5050")가 남아 있어 라이브 /health는 Cloudflare Error 1003 (HTTP 403) 상태다.

2. 피어 리뷰(@verifier) 바운스 및 해소 이력

  1. #10 desktop-shell 바운스 -> 3f9e412 해소 (4 files, +103/-3):
    • 문제: LocalLLMService /api/pull 중단 및 LocalSTTService 모델 다운로드 dispose() 중단 시 raw abort 오류가 D3ROError로 래핑되지 않아 계약과 불일치.
    • 수정: LocalLLMService.ts는 D3ROError(ErrorCode.LLM_ERROR)로, LocalSTTService.ts는 D3ROError(ErrorCode.STTModelDownloadCancelled)로 래핑하고 관련 단위 테스트 보강.
  2. #11 mobile-app 바운스 -> cc3f746 해소 (5 files, +376/-45):
    • 문제: durable-processing-queue.ts cleanup 경로에서 큐 항목 제거와 오디오 파일 삭제 순서·실패 재시도 보장이 미흡했고, 다중 화면에서 계정 전환 후 busy/running 상태가 섞일 여지가 남아 있었음.
    • 수정: finishCleanupItem(item)으로 오디오 파일 먼저 삭제 후 큐 항목 제거(삭제 실패 시 60초 재시도 예약), 화면(Commands, HistoryDetail, Home, Knowledge, Meetings, Record, Teams)에 scopeGenerationRef와 try/catch/finally 가드 통일.
  3. #17 cloud-surfaces 바운스 -> 4bf0f0d 해소 (7 files, +363/-106):
    • 문제: apps/web/src/components/chat/chat-panel.tsx executeChatSendTurn과 action-runner.tsx, payple-manage-button.tsx, generate-document-button.tsx, invite-member-form.tsx에서 createTimedAbortSignal 타임아웃이 삼켜지거나 await 이후 언마운트(shouldExitAfterAwait) 판정이 일관되지 않았음.
    • 수정: edge-fetch.ts 계약 기준으로 타임아웃·abort·언마운트 가드를 전파하고 security-and-lifecycle.test.ts 회귀 보강.
  4. 최종 승인: @verifier 재검증 후 #21 @coordinator [all-verified] 수신 -> 전 커밋 main 체리픽(0 충돌) 및 커밋 메시지 위생 검증(Co-Authored-By/AI 문구 0건) 후 워커 종료(#22).

3. 워크스트림별 수정 내역

3.1 input-core (2a009e4, 8 files, +640/-53) — 문장부호 직후 무공백 영타 오타 라이브 트리거 복구

실사용 중 보고된 상황 잘 지켜보는중?dbrlgkrhdlTwlsdksgwl?(기대 변환: 유기하고있진않지)와 같은 문장부호(?) 직후 공백 없이 이어진 영타·말줄임표 오타가 라이브 파이프라인에서 누락되던 4가지 원인을 동시에 수정했다:

계층 파일 수정 내용
Telemetry apps/desktop/src/main/services/InputTelemetryService.ts TYPO_SETTLE_DELAY_MS (700ms) / _typoSettleTimer 추가로 제안 기능 비활성·지연·접두사 임계치 미달 구간에서도 >=650ms settle 스냅샷 보장; diffInsertionSpan()으로 문장부호(?) 트리밍을 걸친 _expectedInserts 계산 정확화; 만료된 _programmaticKeys 정리 및 _learnFlushTimer.unref()
Typo Service apps/desktop/src/main/services/TypoCorrectionService.ts 문장부호 경계 정규식(~…?!。) 확장; trailingWordOnly 패스에서 경계로 닫힌 단일 토큰을 최대 MAX_INPLACE_DELETE_CHARS (32)자까지 허용하고 _markRegionChecked() 영구 잠금 차단
Core Rules packages/core/src/araso-layout.ts, typo-correction.ts, personal-ngram.ts isUrlOrPathRun()으로 domain.tld? / file.ext?는 보호하되 한글+말줄임표([가-힣ㄱ-ㆎ][!?~]*\.{2,}$) 변환 허용(...props 유지); WORD_BOUNDARY_AFTER_RE 정리; PersonalNgramModel.next() 불필요한 Map 복사 제거
Regression Tests apps/desktop/tests/main/services/typo-live-punctuation.test.ts, TypoCorrectionService.test.ts, packages/core/__tests__/typo-correction.test.ts 문장부호 뒤 한/영 무공백 전환, URL/코드 접두사 비변환, 재입력·트림 복원 회귀 테스트 추가

3.2 desktop-shell (fc5d453 19 files + 3f9e412 4 files) — 메인 서비스 취소 · 해제 · 레이스 하드닝

  • apps/desktop/src/main/windows/WindowManager.ts: hideResultPopup()에서 pendingResultShow 타이머를 취소하고 lastResultCursor = null로 초기화(popup-hide-show-race.test.ts).
  • apps/desktop/src/main/services/CaptionService.ts: ensureAuxModel 성공 뒤 _captionModelId를 기록하고 이전 loadedAuxModelId를 해제, _stopPromise로 동시 stop()/dispose() 중복 실행 차단, 호출 단위 AbortController + _refineEpoch/_refineRunId 리셋(caption-lifecycle-refine.test.ts, caption-aux-release.test.ts).
  • apps/desktop/src/main/services/VoiceModeService.ts, llm/LlmGateway.ts, LocalLLMService.ts: run.controller.signal을 LocalLLMService.processText까지 전파, /api/pull AbortController 등록 및 dispose() 시 리더·요청 중단 후 D3ROError(ErrorCode.LLM_ERROR) 래핑, dispose 이후 폴링 가용성 복원 차단(local-llm-service.test.ts, llm-limits-routing-redteam-r2-1.test.ts, VoiceModeService.test.ts).
  • apps/desktop/src/main/services/{VoiceConversationService,AudioCaptureService,LocalSTTService}.ts & ipc/caption-handlers.ts: abort 시 _responseAbortController 정리, stale 마이크 시작 catch 가드, SoX 'stopping' 재개 확인 및 start() 실패 _cleanup(), dispose() 시 STT 모델 다운로드 fetch/sleep 중단 + D3ROError(ErrorCode.STTModelDownloadCancelled) 래핑, desktopCapturer.getSources fail-closed callback({})(VoiceConversationService.test.ts, audio-capture-redteam-r2-7.test.ts, stt-sidecar-redteam-r2-6.test.ts, ipc-redteam-r3-1.test.ts).

3.3 mobile-app (bd3c1a9 25 files + cc3f746 5 files) — 레코더 · 내구성 큐 · 컨텍스트 · 화면 비동기 가드

  • 레코더 (src/lib/audio-recorder.ts, src/lib/recorder/{nitro-backend,android-foreground-backend}.ts): pendingClaim + finally 해제, startGeneration/sessionGeneration 세대 가드, pollTimer 누수 방지(recorder-lifecycle-races.test.ts).
  • 큐·히스토리 (src/features/recording/durable-processing-queue.ts, src/features/history/use-history-sync.ts): running/cleanup 가드, suspendedUsers 재시도 차단, discardedItems 재검사, finishCleanupItem(item)(오디오 파일 선삭제 -> 큐 항목 제거, 삭제 실패 시 60초 재시도), request-id/scope 가드(queue-and-history-races.test.ts).
  • 서비스·컨텍스트·화면: chat-service.ts, admin-service.ts, device-service.ts, llm-stream-service.ts, 4개 컨텍스트(mobile-ads, billing, device, entitlement), 7개 화면(Commands, HistoryDetail, Home, Knowledge, Meetings, Record, Teams)에 pre-abort 가드, 세대 헤더 불일치 시 response.body 취소, 계정 전환 상태 초기화 및 scopeGenerationRef + try/catch/finally 적용(abort-and-stream-guards.test.ts, context-lifecycle-guards.test.tsx, screen-async-lifecycle.test.tsx).

3.4 cloud-surfaces (c68e81e 46 files + 4bf0f0d 7 files) — 엣지 게이트웨이 · .NET SSRF · Supabase · Web/Admin 보안

  • Cloudflare Worker & Site Bridge (server/cloudflare-worker, server/cloudflare-site-bridge): wrangler.toml BACKEND_ORIGIN을 https://d3ro.chanpaca.net으로 교정, origin-policy.ts로 비-HTTPS·사설 IP·내부 호스트·프록시 루프(508/503) 차단, 204/205/304 null-body 처리, push-drain.ts origin 검증; cloudflare-site-bridge 508 루프 가드·경로 스머글링 400·deno.json 추가.
  • .NET API (apps/api-server, apps/api-server.Tests): EndpointUrlPolicy.cs SSRF 검증, "UpstreamNoRedirect" 명명 HttpClient(AllowAutoRedirect = false), query language parameter 인코딩, EndpointSecurityAndSttProxyTests.cs 추가.
  • Supabase Edge Functions (server/supabase/functions): stt-proxy/handler.ts Content-Length 초과 선차단(413), embed-chunks/handler.ts 업스트림 프로바이더 오류 시에만 할당량 환불, _shared/quota.ts PGRST116 외 DB 오류 fail-closed 예외 전파.
  • Web & Admin (apps/web, apps/admin): safeReturnPath / public/sw.js / admin-url-safety.ts로 //evil·백슬래시·제어문자 오픈 리다이렉트 차단, OAuth callback 오류 메시지 누출 제거, apps/admin/src/proxy.ts isStaticAssetPath 정밀화; apps/web/src/lib/edge-fetch.ts (resolveSupabaseFunctionUrl, createTimedAbortSignal, shouldExitAfterAwait)를 chat-panel, action-runner, payple-*, generate-document-button, invite-member-form, document-editor, history 페이지들에 적용하고 auth-provider bindAuthSession / mic-recorder acquireGuardedMediaStream 보강 (apps/web/tests/security-and-lifecycle.test.ts, apps/admin/tests/admin-security.test.ts + Vitest 구성).

4. 통합 main (cc3f746) 전체 검증 결과

4.1 Batch 1 (정적 · 계약 · 백엔드 · 사이드카, task-587, exit 0)

게이트 / 스위트 결과
version:check 1.17.1 (1170100/1170100) PASS
contract:check / check:migrations PASS / 74 files 일치
security:secrets / check:protected-tests 0 issues / 0 protected modifications (HEAD & a37dd63)
test:hygiene / test:quality 448 test files PASS / 468 test files, 0 regression
check:i18n / check:ds-contract / check:design 2500 keys × 12 locales / 13 components / 0 violations
dotnet test (apps/api-server.Tests) 55 passed, 0 failed
Sidecar Python unittest 33 tests in 2.169s, OK
Supabase Edge (deno check + deno test) 273 passed | 0 failed
Cloudflare Worker (deno check + deno test) 15 passed | 0 failed
Cloudflare Site Bridge (deno check + deno test) 5 passed | 0 failed

4.2 Batch 2 (모노레포 TS · ESLint · Vitest · Jest · 빌드 · 지표, task-654, exit 0)

환경 복구 메모: Windows 환경에서 swarm kill로 share 워크트리가 삭제되며 루트 .bin·apps/{admin,web}/node_modules 일부와 apps/mobile-rn/node_modules/@babel/plugin-transform-runtime 등이 손상되어, 게이트 실행 전 npm install --prefer-offline + npm --prefix apps/mobile-rn ci --prefer-offline으로 복구하고 better_sqlite3.node (sqlite_abi=node_ok)를 확인했다.

게이트 / 워크스페이스 결과
typecheck / typecheck:mobile / typecheck:site PASS
lint / lint:mobile / lint:site (--max-warnings=0) PASS
@d3ro/desktop (Vitest) 212 files / 2,890 tests PASS
@d3ro/web (Vitest) 10 files / 52 tests PASS
@d3ro/admin (Vitest) 1 file / 6 tests PASS
@d3ro/api-client (Vitest) 4 files / 31 tests PASS
@d3ro/core (Vitest) 39 files / 629 tests PASS
@d3ro/i18n (Vitest) 2 files / 25 tests PASS
@d3ro/ui (Vitest) 2 files / 7 tests PASS
test:mobile (@d3ro/mobile-rn Jest --runInBand) 103 suites / 651 tests PASS (24.945 s)
npm run build + check:desktop-renderer electron-vite build + 7 page(s) PASS
npm run test:metrics:write (docs/tdd-red/metrics/2026-11-14.md) 454 files / 3,738 cases / weak 128 / ambient 203 / skip/todo 3 / 12 locales / 2,500 keys

5. 유지된 비코드 / 런타임 / 외부 경계 ([~] · [!] · RED)

  • Desktop runtime ([~]): InputTelemetryService / TypoCorrectionService / CaptionService / LocalLLMService / LocalSTTService / WindowManager 수정은 단위·서비스 테스트 및 렌더러 번들 게이트까지 검증되었으며, 실제 Windows GUI(예: 상황 잘 지켜보는중?dbrlgkrhdlTwlsdksgwl? 라이브 타이핑, 오버레이 표시/해제)는 GAP-INPUT-08/09/10/11 외부-터미널 run-desktop.bat 실행 대상으로 남는다.
  • Mobile runtime & Play Store ([~] / [!] / RED): Fold6/iOS 실기기 수동 TalkBack·초회 진입·FCM 수신·AdMob 운영 광고·Play Billing·Play 비공개 테스트(EXT-*)는 외부 게이트(RED)로 유지한다.
  • Cloudflare Worker live env ([~]): wrangler.toml BACKEND_ORIGIN 수정분을 실운영 d3ro-voice-api에 반영하려면 대시보드 변수 덮어쓰기 또는 재배포가 필요하다.