epic: SDK decomposition (Option A) — absorb contract into host, slim SDK to runtime/UI library

[ken-jo]

배경

#885 (plugin contract v6) 완료 후, @lvis/plugin-sdk 의 계약/스키마 레이어가 크로스레포 락스텝 부담(host-types→SDK-sync→tag→frozen-dist→marketplace-submodule + 순환 schema re-export; 2개월 57 태그)이라는 문제 제기. architect + critic 독립 분석 결과:

• SDK 통째 삭제 불가 — 플러그인은 ~/.lvis/plugins/ 앱 바깥 ESM 번들이고 tsup noExternal 강제로 SDK 런타임/UI 코드를 각 번들에 복사함. /ui(컴포넌트+테마), /runtime/electron(safeStorage 토큰 암호화), /runtime/network(사설 DNS egress)는 보안 민감·테스트 완비 → 공유 설치형 런타임 라이브러리는 반드시 유지.
• "SDK는 스키마만 제공" 오해의 근원 = SDK README.md 의 stale 문구 "Source/type-only ... Does not ship runtime code" (v5.22.0 표기).
• 100% first-party 확인(외부 npm 소비자 없음; ep만 "Example Corp IT" 게시자지만 first-party 레포).
• 호스트는 계약 SoT이면서 SDK로부터 non-test import가 0 — SDK 계약 절반은 순환 re-export.

결정: Option A — 계약 흡수 + SDK 슬림화

계약 레이어(스키마+검증기+타입생성)를 호스트로 흡수해 단일 SoT화하고, SDK를 락스텝 없는 런타임/UI 라이브러리로 슬림화한다. 런타임/UI 라이브러리는 유지(비협상).

이행 계획 (점진적, 호스트 우선 — big-bang 아님)

• ph1 (선행): R — host normalizeManifest legacy 제거 (feat(sdk): #885 후속 (R) — 레거시 manifest reader 제거 (0.6.0, compat window 경과 후) #1570). 계약이 types+schema로 축소된 뒤 재구성.
• ph2 (host-only, 순환 제거): lvis-app/schemas/plugin-manifest.schema.json 신설(pure v6, types.ts 옆) + 호스트 자체 AJV 검증기. manifest-validation.ts 의 await import("@lvis/plugin-sdk") + compat probe 6종 삭제. dead sync-schema-from-host.mjs 제거. in-host schema↔types 테스트 추가.
• ph3 (marketplace): config.py plugin_schema_url 을 호스트 발행 스키마로 repoint + 오프라인 폴백(vendor 서브모듈) 갱신. (schema_loader 는 이미 URL fetch.)
• ph4 (SDK 슬림): SDK에서 계약 export(types re-export/schema/normalizeManifest/compileManifestValidator) 제거 → 런타임/UI 라이브러리로. @lvis/plugin-runtime-ui 로 rename. README 재작성(stale 문구 교정). host CI가 plugins용 types(+schema) 발행하도록 배선. SDK 독립 SemVer.
• ph5 (plugins, lazy): 7 플러그인 dep rename + 생성 타입 참조로 하나씩 이행(전부 first-party라 지연 안전).

리스크 (분석 도출)

1. big-bang 과확장 — 가치는 host-only ph2-3에 있음; 10-repo 동시 컷오버는 부담 재유입. → 단계화, 플러그인 지연 허용.
2. 마켓플레이스 스키마 가용성 — repoint URL + 유효 오프라인 폴백이 함께 착지해야 schema_loader 가 stale 스키마를 조용히 서빙 안 함.
3. 자동화 갭 회귀 — drift-check(loud red) → CI 발행으로 대체 시 CI 무음 실패가 플러그인 계약 갱신을 굶길 수 있음. → in-host schema↔types 테스트 + 발행 아티팩트 freshness 체크 유지.

참고

• feat(sdk): plugin contract simplification + MCP server isolation parity #885 완료, feat(sdk): #885 후속 (R) — 레거시 manifest reader 제거 (0.6.0, compat window 경과 후) #1570 (R) 선행. 초기 설계 대비 tool schema 통일 최종보고서(별도) 예정.

[ken-jo]

ON HOLD (2026-07-10) — 사용자가 스키마 흡수(Option A) 결정을 철회하고 재고 중. 실행 보류.

호스트 측 R(legacy reader 제거, #1570) + uiActions 용어 스윕은 이 결정과 무관하게 계속(호스트 legacy-free → host 0.6.0). SDK는 현행 v6 그대로 유지, 스키마 홈도 SDK 유지. Option A(계약 흡수 + SDK 슬림화)는 사용자 재확인 시에만 재개.