[owjs3901]

Refs #686. #796 (feat/napi-binding) 위에 쌓인 draft PR이며, #796이 먼저 병합되어야 합니다.

요약

• A 단계로 공통 engine?: 'wasm' | 'native' 옵션, 두 실제 namespace가 만족하는 28개 함수의 구조적 compiler 타입, 동기식 지연 selector를 추가합니다. selector의 기본값은 native이며 자동 WASM fallback은 없습니다.
• 이 커밋에서 실제 Vite, Webpack, Rsbuild, Bun, Next 플러그인은 모두 기존 WASM 경로를 그대로 사용합니다. 각 플러그인의 전환은 아래 B-F 단계에서 독립적으로 검증합니다.
• plugin-utils가 native와 WASM을 모두 일반 의존성으로 보유합니다. 기존 플러그인의 일반 WASM 의존성은 유지하며, native binding의 ABI, loader 및 8개 플랫폼 패키지는 변경하지 않습니다.
• 루트 빌드는 기존 패키지 빌드 순서 앞에서 현재 호스트의 최적화 native binding을 먼저 빌드합니다. 기존 드라이버와 canonical target 표를 사용하며 설치 시 빌드나 다운로드 hook은 추가하지 않습니다.

동작

• selector 자신의 실제 설치 위치에서 public package를 해석하므로 CJS/ESM 및 junction으로 재배치된 호출자가 동일한 물리적 compiler namespace를 공유합니다. 선택하지 않은 엔진은 해석하거나 초기화하지 않습니다.
• Windows의 8.3 경로는 realpathSync.native로 정규화합니다. 해당 호출이 EISDIR일 때만 같은 경로에 일반 realpathSync를 사용하며, ENOENT 등 다른 오류는 원래 값 그대로 전달합니다. 이는 엔진 fallback이 아닙니다.
• 매핑된 네트워크 드라이브는 native realpath가 UNC 경로를 반환할 수 있습니다. 모든 엔진 로드는 한 selector에서 수행하며 selector 경로를 bundler 경로와 비교하지 않습니다.
• 두 기존 packed harness는 동일 checkout에서 binding root와 호스트 형제 패키지를 추가로 pack합니다. 한 공통 guard가 설치된 모든 Devup 패키지의 tarball 출처, 전체 payload 바이트, lock integrity 및 실제 Bun .bun-tag의 정확한 archive SRI를 확인합니다. 다른 7개 플랫폼 형제는 명시적으로 제외하고 부재를 확인합니다.
• publish.yml의 PR base 목록에 임시로 feat/napi-binding 한 항목만 추가합니다. 이 항목은 stacked CI를 위한 것이며 main에 절대로 남지 않도록 병합 순서에 맞춰 제거해야 합니다. 기존 push-to-main 전용 release/deploy 조건, read-only PR 권한 및 secret 노출 범위는 바꾸지 않습니다.

단계별 적용

단계	범위
A	공통 타입/selector/진단, 호스트 빌드, packed 출처 guard (현재 커밋)
B	Webpack source/CSS loader, reservation/watch/prewarm, 실제 CJS/ESM packed 검증
C	Rsbuild factory/config/reservation과 Rspack callbacks
D	Vite factory/config/reservation, lifecycle/cache/lease/HMR/RSC
E	Bun instance별 closure, native bootstrap reset, 기본/명시적 WASM preload
F	Next Webpack/Turbopack rules, local loader, coordinator와 handoff
G	전체 엔진 동등성/CI/성능 검증, binding 선행 publish 및 실패 시 dependent 중단 증명, 문서/릴리스 정리

각 전환은 native 기본값과 명시적 engine: 'wasm'을 함께 검증하며, 해당 플러그인의 Patch 항목을 같은 changepack log에 추가합니다. 브라우저용 styling runtime은 추가하지 않습니다.

새로 생기는 오류

• InvalidEngineError: JavaScript 호출이 native/wasm 이외의 값을 넘기면 어떠한 엔진도 로드하기 전에 거부합니다.
• NativePlatformError: 지원하지 않거나 libc를 확정할 수 없는 호스트를 임의의 패키지로 추정하지 않고 실패합니다.
• NativeCompilerLoadError: 누락된 optional sibling, 손상된 native image 또는 전이 native library 로드 실패를 정확한 플랫폼 패키지명과 engine: 'wasm' 안내로 보고합니다. 원래 예외를 cause로 유지하며 기존 중첩 cause도 보존합니다. WASM으로 자동 재시도하지 않습니다.
• HostBuildTargetError: 루트 빌드의 native 호스트를 지원하거나 확정할 수 없으면 기존 빌드 드라이버 실행 전에 실패합니다.

남는 한계

• 같은 프로세스에서 독립적인 빌드를 동시에 수행하는 기능은 제공하지 않습니다.
• 상속된 전역 Number 교체의 엔진 간 차이는 남아 있으며, 이후 fixture의 원본 출력 동등성 검증을 면제하지 않습니다.
• 로컬 packed 검증은 Windows x64 호스트만 증명합니다. 8개 플랫폼의 release 검증은 기존 native build 8개, pack collector 1개, consumer 8개 CI lane이 담당합니다.
• standalone Webpack fixture는 Next에 포함된 Webpack과 기존 minimize: false 설정을 사용합니다. production 재빌드는 dev-server HMR 증명이 아닙니다.
• WASM 크기 budget은 변경하지 않습니다. WASM 크기 job의 실패는 허용되지만 빌드 성능과 benchmark 실패는 허용하지 않습니다.

검증

• Node v26.12.0 / Bun 1.4.4 / lockfile-resolved Playwright 1.64.1, 기본 Rust stack 및 jobs=2로 현재 tree 재빌드 성공. 호스트 native 빌드는 패키지 빌드보다 먼저 완료했습니다.
• 전체 release packed harness: 10개 target/CSS-mode 조합, initial 및 edited(스타일 삭제 포함) production build, Chromium/Firefox/WebKit 총 60회 브라우저 실행, finding 0개. 안전하지 않은 runtime styling 입력은 위치가 포함된 production build error로 정확히 거부했습니다.
• 독립 최신 private Playwright 도구로 extends-theme 8/8 통과: CJS/Next Webpack/직접 ESM의 두 CSS mode 6개와 재배치된 require/import loader identity 2개. 두 harness의 모든 설치가 동일한 source/byte guard를 통과했습니다.
• 정상 pre-commit hook 1회 성공: lint, 실제 native Rust coverage 경로, root Bun 6840/0, Vite 870/0, guard controls 20/0. Bun functions/lines 모두 100%: root 10560/10560 lines 및 958/958 functions, Vite 1425/1425 lines 및 162/162 functions.
• Windows Rust mapping은 기존과 같은 98.23%(32540/33128, 증감 0.00%)입니다. Linux CI의 100% gate를 대체하지 않으며 이번 CI 결과로 별도 확인합니다. LSP 서버는 설치되어 있지 않아 clean-LSP 결과를 주장하지 않습니다.
• staged source hash 19개와 commit tree 8fd9adf6 일치. 추가 소스 수정 없이 gate를 마쳤습니다. 기존 workflow 보안 검증 및 checksum 확인된 actionlint 1.7.12의 전용 runner-label 등록 설정 검증은 같은 소스 hash에서 통과했습니다.
• 첫 CI에서 각 root-build job의 실제 host build 횟수/시간, parent baseline 대비 root-build와 전체 job wall delta를 보고합니다. 3분 초과 증가는 수치와 함께 개선안을 검토하며 이 단계에서 cache/artifact 최적화를 임의로 추가하지 않습니다.