[SPEC-V3-002] Terminal Core — libghostty-vt + PTY + Shell 통합

[GoosLab]

SPEC Reference

• SPEC ID: SPEC-V3-002
• Status: draft (v0.3.1-draft, plan-auditor iter 2 PASS)
• Priority: High (Phase 2 Terminal Core)
• Created: 2026-04-21
• Depends on: SPEC-V3-001 (Phase 1 workspace scaffold, 완료)

Requirements Summary (EARS 5 모듈)

• RG-V3-002-1: libghostty-rs SHA dfac6f3e pin + 월 1회 bump 정책 + Zig 0.15.x CI 통합
• RG-V3-002-2: Pty trait cross-platform 추상화 — macOS/Linux UnixPty 실구현 + Windows ConPtyStub compile_error! gate (Phase 7 대비)
• RG-V3-002-3: PTY worker thread + PtyEvent mpsc + 적응형 buffer (4KB ↔ 64KB, p99 read ≤ 5ms)
• RG-V3-002-4: GPUI TerminalSurface 렌더 + key→ANSI + arboard 로컬 클립보드 (OSC 52 는 Phase 3)
• RG-V3-002-5: Mouse pixel→cell 매핑 + 선택 영역 하이라이트 + ghostty-spike --headless 예제

Acceptance Criteria (11개)

AC	검증
AC-T-1	빌드 ≤ 150s cold / 30s warm, debug profile
AC-T-2	Zig 미설치 시 exit 1 + 정확 에러 메시지
AC-T-3	ghostty-spike 윈도우, prompt 첫 렌더 ≤ 200ms
AC-T-4	p99 key-echo latency ≤ 16ms (60fps budget)
AC-T-5	PTY FD 누수 0 (lsof delta = 0)
AC-T-6	content_area 에 TerminalSurface 렌더
AC-T-7	CI wall-clock ≤ 5분 (Zig cache hit)
AC-T-8	신규 테스트 ≥ 10 (MockPty, Grid assertion, adaptive buffer, Pty contract)
AC-T-9	1MB byte-level 반영 + p99 PTY read ≤ 5ms + buffer 전환 log
AC-T-10	Windows target compile_error! 단일 enforcement + trybuild
AC-T-11	Pin bump PR CI gate (characterization test + HISTORY SHA + wrapper scope)

Artifacts

• SPEC: .moai/specs/SPEC-V3-002/spec.md (v0.3.1-draft, 11 AC, §9 canonical layout)
• Plan: .moai/specs/SPEC-V3-002/plan.md (T1~T10 의존성 그래프 + MX tag 14+)
• Acceptance: .moai/specs/SPEC-V3-002/acceptance.md (AC 11 + Edge Case 4 + DoD 11)
• Research: .moai/specs/SPEC-V3-002/research.md (5 주제 deep-dive, 620 lines)
• Compact: .moai/specs/SPEC-V3-002/spec-compact.md (Run phase 토큰 최적화)
• Audit: .moai/reports/plan-audit/SPEC-V3-002-review-{1,2}.md (iter 1 FAIL → iter 2 PASS)

Exclusions (§6)

• OSC 52 원격 클립보드 → Phase 3 (SPEC-V3-003 Smart Links)
• Windows ConPTY 실 구현 → Phase 7 (GPUI Windows GA 대기)
• Scrollback UI, Tab/Pane split, SSH, Font fallback/Ligature/BiDi → 후속 Phase

---

This issue was automatically created by MoAI from SPEC-V3-002.
SPEC location: .moai/specs/SPEC-V3-002/spec.md

[GoosLab]

SPEC document: .moai/specs/SPEC-V3-002/spec.md (v0.3.1-draft, plan-auditor iter 2 PASS)