isthmus-cli 0.6.0 → 0.7.0

package/README.ko.md

@@ -36,18 +36,47 @@ isthmus는 각 언어 도구가 내보낸 **브리지 사실**(채널 이름 ·
 검증 앱에서 공개 플러그인 API를 실행했다. 설정과 측정 범위는 [사전 점검](docs/PREFLIGHT.md),
 [런타임 검증](docs/RUNTIME.md), [고정 소스 구축](docs/TOOLCHAIN.md)을 참조한다.
 
-npm 발행본은 **0.6.0**이며 위 기능은 호환되는 producer 개발 commit이 필요하다. 발행된
-Dart/Swift MethodChannel 절차는 cartograph 0.5.3 이상과 dartograph 0.1.1 이상을 사용하며
-공개 battery 플러그인으로 검증했다. Message channel 지원은 현재 개발 producer가 필요하다.
-React Native·EventChannel 추출은 계획이고 보존 근거 내보내기는 현재 cartograph(Swift)를
-대상으로 한다. 앱 전체 적용 범위와 최초 외부 사용자 구축은 아직 검증하지 않았다.
+npm 발행본은 **0.7.0**이다. 공개 호환 producer 세트는 cartograph **0.18.0**,
+kartograph **0.10.2**, dartograph **0.14.0**이다 — 설치 명령·고정 예제·CI 예시는
+[호환 버전](docs/COMPATIBILITY.md)을 참조한다. MethodChannel 조인과 보존 근거 왕복은
+cartograph 0.5.3 이상·dartograph 0.1.1 이상부터 지원하며, 이전 공개 세트
+(cartograph 0.15.1·dartograph 0.10.0·isthmus 0.6.0)로 왕복을 다시 확인했다.
+React Native 모듈·컴포넌트 사실(`module-import`↔`module-export`,
+`component-require`↔`component-export`)은 `react-native` target 안에서 이름으로
+조인된다. 선택적 `mechanism` 필드가 core와 Expo 해석 경로를 구분한다. Expo의
+`requireNativeModule` 계열 수입은 TurboModuleRegistry 폴백으로 core·Expo 양쪽
+수출에 닿지만, `requireNativeViewManager`는 mechanism이 일치해야 한다. 같은 이름이
+다른 mechanism으로만 관찰되면 상대편 부재 대신 `*-mechanism-mismatch` 경고로 보고된다.
+부재를 허용하는 조회(`requireOptionalNativeModule`,
+`TurboModuleRegistry.get`/`getNullable`)로 부른 수입은 `optional: true`를 싣고,
+부재 모듈의 호출자가 전부 부재를 허용하면 error 대신
+`module-import-without-export-optional` 경고가 나온다.
+`isthmus extract-js`가 JS/TS 소스에서 호출 측 사실을 추출하고(`NativeModules.*`,
+`TurboModuleRegistry.get*`, `requireNativeComponent`/`codegenNativeComponent`,
+`requireNativeModule` 계열 호출, 해석된 멤버 호출), cartograph와 kartograph는
+Expo Modules DSL(`Module`/`definition()`, `Name`, `Function`, `View`,
+`@ExpoModule`/`@JS`)을 스캔해 그 수출에 `mechanism: "expo"`를 표시한다 —
+`GRAPH-EXCHANGE.md`에 적힌 토큰 스캔 관찰 범위 안에서 end-to-end RN 조인이
+재현된다. EventChannel v2 전송은 자매 저장소 전반에 구현됐고, `check`가 v2
+Bridge·Event 문서를 직접 소비해 transport별 진단을 낸다.
+보존 근거보내기는 현재 cartograph(Swift)를 대상으로 한다.
+앱 전체 적용 범위와 최초 외부 사용자 구축은 아직 검증하지 않았다.
+
+변경 예측은 고정된 공개 정밀도 코퍼스 — `battery_plus`·`shared_preferences_foundation`·
+`url_launcher_macos`와 **LocalSend** 앱, 파일/심볼/버전 diff 15케이스 — 로 측정한다.
+최근 실행은 **TP 83 / FN 0 / FP 0**을 기록했고, 최초의 앱 수준 Dart↔Swift↔Kotlin
+3방향 조인을 포함한다([`experiments/real-corpus/`](experiments/real-corpus/)).
+이 수치는 스텁 컴파일 Swift와 소스 스캔 Kotlin 위의 정적 브리지 경계이며,
+런타임 실행·앱 전체 정밀도는 측정하지 않았다.
 
 | 문서 | 내용 |
 |---|---|
 | [`docs/PRD.md`](docs/PRD.md) | 무엇을 · 누구를 위해 · 어디까지 |
 | [`docs/PLAN.md`](docs/PLAN.md) | 단계별 계획. **cartograph와 dartograph에 선행 작업이 있다** |
 | [`docs/GRAPH-EXCHANGE.md`](docs/GRAPH-EXCHANGE.md) | 자매 도구가 내보내는 브리지 사실의 형식. 자매 저장소들이 공유하는 계약 |
+| [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md) | 공개 호환 버전, 고정 예제, CI 설정 |
 | [`docs/RESEARCH.md`](docs/RESEARCH.md) | 확인된 사실 · 확인되지 않은 주장 |
+| [`experiments/real-corpus/`](experiments/real-corpus/) | 고정 공개 플러그인·앱 정밀도 코퍼스(TP/FN/FP 계수) |
 | [`experiments/phase-0/`](experiments/phase-0/) | Dart·Swift 임시 추출기, 고정 JSON, 손 조인 검증 |
 
 ## 의존 관계
@@ -72,20 +101,20 @@ npm install --global isthmus-cli
 isthmus --help
 ```
 
-설치 없이 한 번 실행할 때는 package 이름을 명시한다.
+설치 없이 한 번 실행할 때는 패키지 이름을 명시한다.
 
 ```bash
 npx isthmus-cli --help
 ```
 
-`npx isthmus`는 이름이 같은 다른 package를 설치하므로 사용하면 안 된다.
+`npx isthmus`는 이름이 같은 다른 패키지를 설치하므로 사용하면 안 된다.
 
 ## 사용
 
 `impact --file`·`--symbol`·`--changes` 사전 점검과 정보 손실 없는 `--compact`, 분석
 공백도 실패시키는 `--strict`를 제공한다. 빌드·계약·현재 브리지 한정 범위는
 [변경 사전 점검](docs/IMPACT.md)을 참조한다.
-Android 개발 지원은 `selection.kotlin`과 Kartograph snapshot을 사용한다. Kotlin Method/Basic
+Android 개발 지원은 `selection.kotlin`과 kartograph snapshot을 사용한다. Kotlin Method/Basic
 사실을 Dart 소비자에 연결하고 Android 실행은 Kotlin 후보에만 대조한다.
 [Android 수집 설정](docs/PREFLIGHT.md#android-수집)과 [선택적 Kotlin 도구 구축](docs/TOOLCHAIN.md)을 참조한다.
 `verify-runtime --expectations`는 revision·시나리오·플랫폼·엔진 인스턴스별
@@ -99,18 +128,24 @@ Android 개발 지원은 `selection.kotlin`과 Kartograph snapshot을 사용한
 브리지를 연결한다. 별도 수집 workflow는 명시된 입력의 내용 해시로 캐시를 재사용하며,
 실제 producer를 사용한 합성 소스 검증을 통과했다. 사용법·지원 경계·CI 설정은
 [언어 간 변경 사전 점검](docs/PREFLIGHT.md)을 참조한다. 실제 앱 전체 검증은 남아 있다.
+`isthmus init [capture.json]`은 그 capture 설정 scaffold를 쓰고(`--toolchain`을 주면
+구축한 `toolchain.json`의 실제 producer 명령을 채운다), `isthmus doctor <capture.json>`은
+설정을 검증하고 참조한 실행 파일이 `PATH`나 지정 경로에 있는지 확인만 한다 — 실행하지 않는다.
 runtime JSON과 `--expectations <checks.json>`를 함께 주면 같은 revision의 실행과
-전이 분석을 대조하고, native 후보·미관찰 경계·시나리오 누락을 기존 정적 공백과 함께 보고한다.
+전이 분석을 대조하고, 네이티브 후보·미관찰 경계·시나리오 누락을 기존 정적 공백과 함께 보고한다.
 
 `preflight <context.json> --summary --strict --compact`로 작은 개요를 읽고,
 `--explain <exact-producer-symbol-id>`로 한 심볼의 전체 원인 경로를 조회한다.
 summary는 목록당 기본 20개(`--limit 1..100`)를 표시하며 생략한 항목도 검토 상태에 반영한다.
-선택적 [Basic/Pigeon v2 입력](docs/BRIDGE-MESSAGES.md)은 개발 producer로 literal 주소와
+선택적 [Basic/Pigeon v2 입력](docs/BRIDGE-MESSAGES.md)은 literal 주소와
 증명된 prefix 후보를 연결한다. prefix의 suffix·instance 배선 불확실성은 유지한다.
-이 추가 기능에는 개발 producer가 필요하다.
-호환 개발 도구를 로컬 Git의 고정 commit에서 새로 구축하는 방법은
-[도구 구축 절차](docs/TOOLCHAIN.md)에 있다. Dart AOT 실행 파일, impact와 Basic을 함께
-제공하는 Cartograph, 격리 설치된 isthmus 패키지를 준비한다.
+이 추가 기능은 위에 나열한 공개 producer 버전의 `bridges --messages`로 사용할 수 있다.
+에이전트 클라이언트는 `isthmus serve`(MCP stdio 서버)로 같은 명령을 도구로 호출할 수 있다 —
+check·query·graph·diff·impact·preflight·retentions를 노출한다.
+[MCP 서버 계약](docs/MCP.md)을 본다.
+검증된 개발 조합을 재현하거나 도구를 직접 감사하려면 로컬 Git의 고정 commit에서
+구축하는 [도구 구축 절차](docs/TOOLCHAIN.md)를 쓴다. Dart AOT 실행 파일, impact와
+Basic을 함께 제공하는 cartograph, 격리 설치된 isthmus 패키지를 준비한다.
 
 isthmus CLI는 각 도구가 만든 JSON 파일을 읽는다. 선택적 수집 workflow는 설정에
 명시한 준비·producer 명령을 실행한다.
@@ -119,7 +154,7 @@ isthmus CLI는 각 도구가 만든 JSON 파일을 읽는다. 선택적 수집 w
 isthmus check dart-bridges.json swift-bridges.json
 ```
 
-전체 명령과 현재 package 버전은 다음과 같이 확인한다.
+전체 명령과 현재 패키지 버전은 다음과 같이 확인한다.
 
 ```bash
 isthmus --help
@@ -140,6 +175,20 @@ isthmus check dart-bridges.json swift-bridges.json --strict
 `-h`/`--help`는 어느 위치에 있든 도움말을 내고, `isthmus help <command>`로 명령의
 사용법을 볼 수 있으며, 모르는 명령은 루트 도움말을 출력한다.
 
+### React Native 호출 측 사실
+
+React Native 앱에서는 `isthmus extract-js`가 호출 측 문서를 직접 만든다 — JS/TS
+파일이나 디렉터리를 넘기고, 결과를 자매 도구가 낸 Swift·Kotlin 문서와 함께
+`check`에 넣는다:
+
+```bash
+isthmus extract-js src/ --project . > js-bridges.json
+isthmus check js-bridges.json ios-bridges.json android-bridges.json
+```
+
+출력은 자매 도구가 만드는 것과 같은 `bridge-facts` 버전 1 문서라 모든 소비
+명령이 그대로 받는다.
+
 ### SARIF 출력
 
 check 결과를 GitHub code scanning(또는 그 밖의 SARIF 2.1.0 소비자)에 올리려면
@@ -149,14 +198,32 @@ isthmus-check JSON 대신 SARIF를 요청한다.
 isthmus check dart-bridges.json swift-bridges.json --format sarif > isthmus.sarif
 ```
 
-기본값은 `--format json`으로 버전이 붙은 isthmus-check 문서를 유지한다. SARIF는 같은
+기본값인 `--format json`은 버전이 붙은 isthmus-check 문서를 유지한다. SARIF는 같은
 조인 결과의 additive·isthmus 소유 렌더링이다. 모든 이슈는 check 진단 코드를 규칙 id로
 하는 결과가 되고, 첫 증거 끝점이 주 위치가 되며(프로젝트 상대 경로가 퍼센트 인코딩된
 저장소 상대 URI가 된다), 나머지 끝점은 관련 위치로 실린다. 베이스라인이 억제한 이슈는
 `external` suppression을 달고 나온다. 결과마다 논리 이슈 식별자(code·target·channel·
 method)의 `partialFingerprints` 해시가 있어 소스 줄이 움직여도 중복 판정이 베이스라인
-억제와 같은 기준으로 살아남는다. `--strict`·`--baseline`·`--update-baseline`은 두 형식
-모두와 조합되고 문서화된 종료 코드 동작을 유지한다.
+억제와 같은 기준으로 살아남는다.
+
+### GitLab Code Quality 출력
+
+check 결과를 GitLab 머지 요청 위젯에 표시하려면 Code Quality 아티팩트를 대신 낸다.
+
+```bash
+isthmus check dart-bridges.json swift-bridges.json --format codequality > gl-code-quality-report.json
+```
+
+억제되지 않은 모든 이슈가 첫 증거 끝점의 발견 하나가 된다. `check_name`은 `isthmus:`에
+진단 코드를 붙인 값이고, `severity`는 error를 `major`로·warning을 `minor`로 내리며,
+`fingerprint`는 SARIF와 같은 논리 이슈 해시를 재사용해 실행 사이의 병합 판정이 유지된다.
+이 형식에는 억제 개념이 없으므로 베이스라인이 받아들인 이슈는 새 발견으로 다시 뜨지
+않도록 목록에서 제외한다 — 베이스라인을 머지 요청 파이프라인에만 적용하고 기본
+브랜치에는 적용하지 않으면, GitLab 비교가 받아들인 이슈를 해당 머지 요청이 "고친"
+것으로 표시할 수 있다는 점에 유의한다.
+
+`--strict`·`--baseline`·`--update-baseline`은 모든 형식과 조합되고 문서화된 종료
+코드 동작을 유지한다.
 
 ### 베이스라인
 
@@ -196,11 +263,11 @@ cartograph dead --external-retentions external-retentions.json
 ```
 
 `retentions`는 핸들러의 USR을 우선 사용하고 없으면 `qualifiedName`을 남긴다. 메서드를
-여러 위치에서 호출하면 근거가 전체 호출 위치를 `callers`로 실고(대표 `caller`는 옛
+여러 위치에서 호출하면 근거가 전체 호출 위치를 `callers`로 싣고(대표 `caller`는 옛
 소비자를 위해 유지), 근거당 100개 상한을 넘은 호출은 조용히 버리지 않고
 `callersOmitted`로 계수를 밝힌다. `mixed-targets` 문서는 v1에서 사실별 target을
 복원할 수 없어 모든 소비 명령이 종료 코드 2로 조인을 보류하며, 이때 몇 개의 문서에서
-관찰한 fact 몇 개가 조인되지 못했는지를 함께 알린다. 먼저 생산 단계에서
+관찰한 사실 몇 개가 조인되지 못했는지를 함께 알린다. 먼저 생산 단계에서
 target별 문서로 분리해야 한다.
 
 cartograph는 Swift 심볼만 보존하므로 `--for cartograph`는 수신 측 Swift 문서를 최소
@@ -231,7 +298,7 @@ node scripts/verify-public-flutter-plugin.mjs \
 
 공개 플러그인 검증은 원본 `addMethodCallDelegate` 구현에서 나온 Swift USR과 원본
 Dart 호출 위치 세 곳을 확인하고, cartograph `--explain`이 해당 심볼의 대표 근거를
-읽는지 검증한다. 이미 public인 플러그인 handler의 dead 상태 전환을 억지로 만들지는
+읽는지 검증한다. 이미 public인 플러그인 핸들러의 dead 상태 전환을 억지로 만들지는
 않는다. 그 전환과 `setMethodCallHandler` 경로는
 `verify-cartograph-roundtrip.mjs`의 합성 코퍼스가 별도로 검증한다.
 
@@ -274,7 +341,44 @@ isthmus graph dart-bridges.json swift-bridges.json --format mermaid
   핸들러를 놓쳤을 수 있다고 스스로 신고해 없는 것인지 못 본 것인지 판정할 수 없음
 - `unregistered-channel-creation-unverified` (warning): 같은 이유로 등록 여부를 판정할 수 없음
 
-`summary`는 이슈 계수와 함께 관찰량을 싣는다. `observedFacts`는 입력 문서 전체의 fact
+React Native 이름 경계도 같은 방향으로 보고한다 — `require`/`import`에 맞는
+`export`가 없으면 error, `export`에 호출자가 없으면 warning이다.
+
+- `module-import-without-export` (error) / `-unverified` (warning)
+- `module-import-without-export-optional` (warning): 호출자가 전부 부재 허용
+  API를 썼으므로 수출 부재가 크래시가 아니라 기능 저하임
+- `module-export-without-import` (warning)
+- `component-require-without-export` (error) / `-unverified` (warning)
+- `component-export-without-require` (warning)
+- `module-import-mechanism-mismatch`, `module-export-mechanism-mismatch`,
+  `component-require-mechanism-mismatch`, `component-export-mechanism-mismatch`
+  (warning): 이름이 상대편에 있지만 호환되지 않는 core/Expo 해석 경로로만
+  관찰됨
+
+`check`는 BasicMessageChannel·EventChannel bridge-facts v2 문서도 직접 소비해
+같은 짝 규칙으로 transport별 진단을 보고한다.
+
+- `unhandled-message-send` (error) / `-unverified` (warning): Dart Basic send에
+  대응 네이티브 메시지 핸들러가 없음
+- `message-handler-without-send` (warning): 네이티브 Basic 핸들러에 대응 Dart
+  send가 없음
+- `unhandled-stream-listen` (error) / `-unverified` (warning): Dart Event 스트림
+  listener에 대응 네이티브 스트림 핸들러가 없음
+- `stream-handler-without-listen` (warning): 네이티브 Event 핸들러에 대응 Dart
+  listener가 없음
+
+dynamic `channelPrefix` 경로는 판정이 아니라 후보다 — 항상
+`dynamic-message-address`·`dynamic-stream-address` 소비자 한계로 실리고, 관찰된
+상대가 없으면 `unmatched-message-boundary`·`unmatched-stream-boundary`가 더해지며,
+증명된 prefix가 없는 동적 주소는 `unresolved-message-addresses` 한계에 포함된다.
+빠진 쪽을 prefix 후보가 덮는 literal 경계도 error 대신 같은 후보 한계로 내린다.
+`summary`는 v2 입력이 있을 때만 `matchedMessages`·`matchedStreams`(literal 매치만)를
+더한다. `query`는 v2 경계를 `message`·`stream` kind 주체로, `graph`는 literal v2 경계를
+`message`·`stream` 간선으로, `diff`는 literal v2 경계의 추가·삭제와 v2 진단을 생산한다.
+`retentions --for cartograph`는 literal v2 Swift 핸들러를 method 없는 근거로 보존하고,
+`impact`는 여전히 v1 입력만 받고 version 2를 거부한다.
+
+`summary`는 이슈 계수와 함께 관찰량을 싣는다. `observedFacts`는 입력 문서 전체의 사실
 총수이고 `observedLimitations`는 보고된 분석 한계 수다. 이로써 브리지가 없는 프로젝트와
 아무것도 관찰하지 못한 실행이 같은 보고서를 내지 않는다 — `observedFacts`가 0이면
 생산자가 서술할 것을 아무것도 보지 못했다는 뜻이다.
@@ -297,15 +401,15 @@ target에 적용한다. 호출 측 한계는 네이티브 코드를 가리지
 보존된다. 생산자가 tool 이름을 isthmus로 적어도 자체 계수를 신뢰하지 않으며,
 `unjoined-*`는 소비자가 직접 붙인 `origin: "consumer"`가 있어야 완화 근거가 된다.
 
-선택적 fact 필드 `sourceLanguage: "objective-c"`는 `.m`/`.mm`의 ObjC 구현을 Swift
+선택적 사실 필드 `sourceLanguage: "objective-c"`는 `.m`/`.mm`의 ObjC 구현을 Swift
 그래프와 구분한다. 이 사실에는 symbol을 붙이지 않는다. 매치는 check/query/graph에
 남고 Swift 보존 목록에서는 제외되며, `omittedObjectiveCHandlers`가 제외 수를 알린다.
 표식 없는 Swift 핸들러가 호출자가 있는데 symbol 없이 매치되면 여전히 종료 코드 2로
 실패한다. 이 확장을 지원하는 소비자를 먼저 배포해야 한다. 옛 소비자는 스코프를
 버리고 넓게 완화하며 ObjC 보존 생성은 실패한다.
 
-모든 이슈는 관찰된 위치를 `evidence`로 제공한다. 동적 이름, 해석하지 못한 receiver나
-handler 본문, USR 누락, 입력 생성 시각 차이, 혼합 target은 `limitations`에 출처와
+모든 이슈는 관찰된 위치를 `evidence`로 제공한다. 동적 이름, 해석하지 못한 수신자나
+핸들러 본문, USR 누락, 입력 생성 시각 차이, 혼합 target은 `limitations`에 출처와
 함께 남긴다. 이 도구는 삭제 가능 여부를 판정하지 않는다.
 
 isthmus 출력 문서는 버전 1 안에서 필드 추가나 새 이슈 code를 호환 변경으로 다룬다.
@@ -330,8 +434,8 @@ isthmus 출력 문서는 버전 1 안에서 필드 추가나 새 이슈 code를
 | `2` | 파일 읽기, JSON, 교환 계약, project 불일치, 플랫폼 구성 누락, 보류된 조인, 크기 상한(입력 텍스트·그래프 간선·베이스라인 항목), 베이스라인 파일 오류·쓰기 실패, 만들 수 없는 보존 근거 등 도구 실패. stderr가 원인을 구분 |
 | `64` | 잘못된 명령·옵션·입력 개수 또는 `query`의 `notFound`·`ambiguous` |
 
-저장소 checkout에서 개발할 때는 먼저 `npm ci`를 실행한다. 개발 검증은 타입 체크,
-제품 코드 90% 커버리지, clean build, 실제 CLI·package 계약을 함께 실행한다.
+저장소 checkout에서 개발할 때는 먼저 `npm ci`를 실행한다. 개발 검증은 타입 체크와 clean build를 실행하고 제품 코드 90% 커버리지를
+강제하며 실제 CLI·패키지 계약 검증을 함께 수행한다.
 
 ```bash
 npm run verify
@@ -381,16 +485,16 @@ JSON으로 출력한다. 연결에는 호출자와 핸들러 위치가 포함된
 
 `--strict`는 새로 관찰된 error가 있을 때만 1이다. 기존 오류·경고·분석 한계만 있으면
 0이므로 성공 코드가 삭제 안전성이나 완전한 분석을 뜻하지 않는다. `resolvedIssues`도
-이전 불일치가 더 이상 관찰되지 않는다는 뜻이며, 동적 전환·추출기 변경 때문인지 한계를
+이전 불일치가 더 이상 관찰되지 않는다는 뜻이며, 동적 전환·추출기 변경 때문인지를 한계와
 함께 확인해야 한다. `--strict`은 인자 위치와 무관하게 인식하며 두 번 이상 줄 수 없다.
 
-개발 소스의 diff는 Flutter Dart와 Swift 또는 Kotlin 문서를 받는다. 한 비교에는 native 언어
-하나만 사용하며 각 시점에 호출/수신 문서가 모두 필요하다.
+`diff`는 호출 문서(Flutter Dart 또는 React Native JS)와 수신 문서(Swift
+또는 Kotlin)를 받는다. 한 비교에는 네이티브 언어 하나만 사용하며 각 시점에 호출/수신 문서가 모두 필요하다.
 양 시점의 `project`와 플랫폼·도구별 문서 개수가 같아야 한다. 한 checkout의 같은
 경로에서 각 revision을 빌드해 JSON을 보관한다. 일부 파일만 추출한 결과와 전체 결과를
 비교하지 말고 같은 분석 설정을 사용한다. 입력 파일은 합계 256개, 텍스트 길이 제한은
 기존 CLI와 동일하다. 혼합 target이나 비교 불가능한 입력은 종료 코드 2로 거부한다.
-`generatedAt`은 fact 추출 시각이며 revision 순서가 아니다. 비교 방향은 `--before`와
+`generatedAt`은 사실 추출 시각이며 revision 순서가 아니다. 비교 방향은 `--before`와
 `--after` 인자로 결정되므로 사용자가 올바른 revision의 파일을 지정해야 한다.
 
 ## 코딩 에이전트 skill

package/README.md

@@ -39,18 +39,55 @@ apps have exercised public plugin APIs. See [preflight](docs/PREFLIGHT.md),
 [runtime verification](docs/RUNTIME.md), and
 [building from pinned source commits](docs/TOOLCHAIN.md) for setup and measured limits.
 
-The published npm version is **0.6.0**; these features require compatible producer commits.
-The published Dart/Swift MethodChannel workflow uses cartograph 0.5.3+ and dartograph
-0.1.1+; message-channel support currently needs development producers.
-React Native and EventChannel extraction remain planned. Retention export currently targets
-cartograph (Swift). Full application coverage and first-time external setup remain unverified.
+The published npm version is **0.7.0**. The compatible public producer set is
+cartograph **0.18.0**, kartograph **0.10.2**, and dartograph **0.14.0** — see
+[compatible versions (Korean)](docs/COMPATIBILITY.md) for install commands, a
+fixed end-to-end example, and a CI sketch. MethodChannel joins and the retention
+round trip are supported from cartograph 0.5.3+ and dartograph 0.1.1+ — exercised on a
+public battery plugin — and the round trip was re-verified on the previous public
+set (cartograph 0.15.1, dartograph 0.10.0, isthmus 0.6.0).
+React Native module/component facts (`module-import`↔`module-export`,
+`component-require`↔`component-export`) join by name inside the `react-native`
+target. An optional `mechanism` field keeps the core and Expo resolution paths
+apart: Expo `requireNativeModule`-family imports reach core and Expo exports
+through the TurboModuleRegistry fallback, while `requireNativeViewManager`
+requires a mechanism match, and a name observed only through a different
+mechanism is reported as a `*-mechanism-mismatch` warning instead of a missing
+counterpart. Imports made through absence-tolerant lookups
+(`requireOptionalNativeModule`, `TurboModuleRegistry.get`/`getNullable`) carry
+`optional: true`; when every caller of a missing module tolerates absence, the
+finding is the `module-import-without-export-optional` warning rather than an
+error. `isthmus extract-js` extracts caller-side facts from JS/TS sources
+(`NativeModules.*`, `TurboModuleRegistry.get*`,
+`requireNativeComponent`/`codegenNativeComponent`,
+`requireNativeModule`-family calls, and resolved member calls), and cartograph
+and kartograph scan the Expo Modules DSL (`Module`/`definition()`, `Name`,
+`Function`, `View`, `@ExpoModule`/`@JS`) and mark those exports
+`mechanism: "expo"` — end-to-end RN joins are reproducible within the
+token-scan observation scope documented in `GRAPH-EXCHANGE.md`.
+EventChannel v2 transport is implemented across the sister repositories, and
+`check` now consumes the v2 Bridge/Event documents directly with
+transport-specific diagnostics. Retention export currently targets cartograph
+(Swift). Full application coverage and first-time external setup remain
+unverified.
+
+Change predictions are measured against a pinned public precision corpus —
+`battery_plus`, `shared_preferences_foundation`, `url_launcher_macos`, and the
+**LocalSend** app — over 15 file/symbol/version-diff cases. The latest run
+recorded **TP 83 / FN 0 / FP 0**, including the first app-level
+Dart↔Swift↔Kotlin join ([`experiments/real-corpus/`](experiments/real-corpus/)).
+These are static bridge-boundary numbers over stub-compiled Swift and
+source-scanned Kotlin; runtime execution and full-app precision are not
+measured.
 
 | Document | Contents |
 |---|---|
 | [`docs/PRD.md`](docs/PRD.md) | What, for whom, how far |
 | [`docs/PLAN.md`](docs/PLAN.md) | Step-by-step plan. **cartograph and dartograph have prerequisite work** |
 | [`docs/GRAPH-EXCHANGE.md`](docs/GRAPH-EXCHANGE.md) | The bridge-facts format the sister tools export — the contract shared across the sister repositories |
+| [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md) | Compatible public versions, fixed example, and CI setup |
 | [`docs/RESEARCH.md`](docs/RESEARCH.md) | Confirmed facts vs. unconfirmed claims |
+| [`experiments/real-corpus/`](experiments/real-corpus/) | Pinned public-plugin/app precision corpus (TP/FN/FP counts) |
 | [`experiments/phase-0/`](experiments/phase-0/) | Temporary Dart/Swift extractors, pinned JSON, hand-join verification |
 
 Internal documents are maintained in Korean, the maintainer's working language.
@@ -92,7 +129,7 @@ Change preflight is available with `impact --file`, `--symbol`, or `--changes`,
 lossless `--compact` JSON and a gap-aware `--strict` gate. See
 [change preflight](docs/IMPACT.md) for the build command, contract, and current
 bridge-only scope.
-Android development support uses `selection.kotlin` and a Kartograph snapshot. It connects
+Android development support uses `selection.kotlin` and a kartograph snapshot. It connects
 Kotlin Method/Basic facts to Dart consumers and matches Android observations only to Kotlin
 candidates. See [Android capture](docs/PREFLIGHT.md#android-수집) and [toolchain builds](docs/TOOLCHAIN.md).
 `verify-runtime --expectations` checks recorded calls
@@ -108,6 +145,10 @@ producer impact paths across the bridge. A separate capture workflow caches decl
 input content and has passed a synthetic source test with real producers. See
 [cross-language preflight](docs/PREFLIGHT.md) for the contract, CI setup, and remaining
 real-application validation.
+`isthmus init [capture.json]` scaffolds that capture config — `--toolchain` fills real
+producer commands from a built `toolchain.json` — and `isthmus doctor <capture.json>`
+validates the config and checks that the referenced executables resolve on `PATH` or at
+the given path, without running them.
 To combine that context with recorded execution, pass runtime JSON files and
 `--expectations <checks.json>`. Preflight reports revision alignment, native candidates,
 and static boundaries missing observations or declared scenarios; existing static gaps remain visible.
@@ -116,11 +157,16 @@ Use `preflight <context.json> --summary --strict --compact` for a bounded overvi
 `--explain <exact-producer-symbol-id>` for a complete path to one symbol. Summary defaults
 to 20 items per collection (`--limit 1..100`); omitted items still affect review status.
 Optional [Basic/Pigeon v2 inputs](docs/BRIDGE-MESSAGES.md) connect literal addresses and
-proven prefix candidates with development producers. Prefix matches preserve unresolved
-suffix and instance wiring. These additions require development producers.
-To build compatible development tools from pinned local Git commits, use the
+proven prefix candidates. Prefix matches preserve unresolved
+suffix and instance wiring. These additions are available in the public producer
+versions listed above (`bridges --messages`).
+Agent clients can call the same commands over `isthmus serve`, an MCP stdio server
+that exposes check, query, graph, diff, impact, preflight, and retentions as tools.
+See the [MCP server contract](docs/MCP.md).
+To reproduce a verified development combination or audit the toolchain, build the tools
+from pinned local Git commits with the
 [toolchain build workflow (Korean)](docs/TOOLCHAIN.md). It produces a standalone
-Dart executable, a Cartograph executable with both impact and message support,
+Dart executable, a cartograph executable with both impact and message support,
 and an isolated installation of the isthmus package.
 
 The isthmus CLI reads JSON produced by the sister tools. The optional capture workflow
@@ -150,6 +196,20 @@ ends option parsing: `isthmus query -- -unusual-name dart-bridges.json swift-bri
 `-h`/`--help` shows help from any position, `isthmus help <command>` names a command's usage,
 and an unknown command prints the root help.
 
+### React Native caller facts
+
+For a React Native app, `isthmus extract-js` produces the caller-side document
+itself — pass JS/TS files or directories, and feed the result to `check`
+alongside the Swift and Kotlin documents the sister tools emit:
+
+```bash
+isthmus extract-js src/ --project . > js-bridges.json
+isthmus check js-bridges.json ios-bridges.json android-bridges.json
+```
+
+The output is the same `bridge-facts` version 1 document the sister tools
+produce, so every consuming command accepts it unchanged.
+
 ### SARIF output
 
 To upload check results to GitHub code scanning (or any SARIF 2.1.0 consumer), ask for SARIF
@@ -166,9 +226,27 @@ additive, isthmus-owned rendering of the same join: every issue becomes a result
 endpoints as related locations, and baseline-suppressed issues carry an `external`
 suppression. Results include a
 `partialFingerprints` hash of the logical issue identity (code, target, channel, method), so
-deduplication survives source line moves exactly like baseline suppression. `--strict`,
-`--baseline`, and `--update-baseline` combine with either format and keep their documented
-exit-code behavior.
+deduplication survives source line moves exactly like baseline suppression.
+
+### GitLab Code Quality output
+
+To surface check results in GitLab merge request widgets, emit a Code Quality
+artifact instead:
+
+```bash
+isthmus check dart-bridges.json swift-bridges.json --format codequality > gl-code-quality-report.json
+```
+
+Every unsuppressed issue becomes one finding at its first evidence endpoint: `check_name`
+is `isthmus:` plus the issue code, `severity` maps errors to `major` and warnings to
+`minor`, and `fingerprint` reuses the same logical-issue hash as SARIF, so GitLab merges
+findings across runs. The format has no suppression concept, so baseline-accepted issues
+are left out rather than resurfaced as new findings — note that when the baseline is
+applied on merge request pipelines but not on the default branch, GitLab's comparison
+can present those accepted issues as "fixed" by the merge request.
+
+`--strict`, `--baseline`, and `--update-baseline` combine with any format and keep their
+documented exit-code behavior.
 
 ### Baselines
 
@@ -272,7 +350,9 @@ When the same method exists on several channels, `query` returns candidates inst
 one; feed a returned `qualifiedName` back into the same subject position to disambiguate. A
 `qualifiedName` is `target:` followed by percent-escaped components — `%`, `#`, and `:` are
 escaped — so splitting on the first `:` and on `#` and decoding the parts always recovers the
-channel and method names. A `notFound` or `ambiguous` query exits 64 and prints a one-line
+channel and method names. Module and component subjects carry a `module:`/`component:` kind
+segment before the name so a channel, a module, and a component that share a name stay
+resolvable. A `notFound` or `ambiguous` query exits 64 and prints a one-line
 cause on stderr, so a script can tell a bad invocation from a missing name without parsing
 stdout.
 `graph` emits matched edges only and preserves the input `limitations` as a JSON field or as
@@ -295,6 +375,42 @@ The output is `isthmus-check` version 1 JSON, reporting these facts:
 - `unregistered-channel-creation-unverified` (warning): registration undecidable for the same
   reason
 
+React Native name boundaries follow the same pairing — a `require`/`import` with no
+matching `export` is an error, an `export` with no caller is a warning:
+
+- `module-import-without-export` (error) / `-unverified` (warning)
+- `module-import-without-export-optional` (warning): every caller used an absence-tolerant
+  API, so the app degrades rather than crashes when the export is missing
+- `module-export-without-import` (warning)
+- `component-require-without-export` (error) / `-unverified` (warning)
+- `component-export-without-require` (warning)
+- `module-import-mechanism-mismatch`, `module-export-mechanism-mismatch`,
+  `component-require-mechanism-mismatch`, `component-export-mechanism-mismatch` (warnings):
+  the name exists on the other side but only through an incompatible core/Expo
+  resolution path
+
+`check` also consumes BasicMessageChannel and EventChannel bridge-facts v2 documents and
+reports transport-specific diagnostics with the same pairing:
+
+- `unhandled-message-send` (error) / `-unverified` (warning): a Dart Basic send has no
+  native message handler
+- `message-handler-without-send` (warning): a native Basic handler has no Dart send
+- `unhandled-stream-listen` (error) / `-unverified` (warning): a Dart Event stream listener
+  has no native stream handler
+- `stream-handler-without-listen` (warning): a native Event handler has no Dart listener
+
+A dynamic `channelPrefix` route is a candidate, not a verdict — it is carried as the
+`dynamic-message-address`/`dynamic-stream-address` consumer limitation and, with no observed
+counterpart, additionally as `unmatched-message-boundary`/`unmatched-stream-boundary`; a
+dynamic address with no proven prefix is counted as `unresolved-message-addresses`. A literal
+boundary whose missing side is covered by a prefix candidate is downgraded the same way
+rather than reported as an error. The summary adds `matchedMessages`/`matchedStreams` (literal
+matches only) when v2 inputs are present. `query` resolves v2 boundaries as `message`/`stream`
+kind subjects, `graph` emits `message`/`stream` edges for literal matches, and `diff` reports
+added/removed literal v2 boundaries plus v2 diagnostics. `retentions --for cartograph` keeps
+literal v2 Swift handlers with method-less evidence; `impact` still requires v1 inputs and
+rejects version 2.
+
 The `summary` carries the issue counts plus observation volume: `observedFacts` is the total
 number of facts across all input documents and `observedLimitations` counts the reported
 analysis limitations. This keeps a project with no bridges and a run that observed nothing
@@ -416,9 +532,11 @@ analyzed". `resolvedIssues` likewise means a previous mismatch is no longer obse
 the limitations to see whether a dynamic transition or an extractor change caused it.
 `--strict` is recognized at any argument position and cannot be given more than once.
 
-Development `diff` accepts Flutter Dart plus either Swift or Kotlin documents. Keep one native language per comparison.
+`diff` accepts caller documents (Flutter Dart or React Native JS) plus either Swift or Kotlin
+receiver documents. Keep one native language per comparison.
 Both sender and receiver documents are required at
-each point in time, and the two snapshots must agree on `project` and on the per-platform,
+each point in time, and the two snapshots must agree on `project`, on the observed set of
+bridge targets, and on the per-platform,
 per-tool document counts. Build each revision from the same checkout path and keep the JSON.
 Do not compare a partial extraction against a full one; use the same analysis settings. Input
 files are capped at 256 total, and the text size limits match the rest of the CLI. Mixed

package/Skills/isthmus/SKILL.md

@@ -3,7 +3,8 @@ name: isthmus
 description: >-
   Inspect file or symbol changes across Flutter Dart-to-Swift/Kotlin bridges, trace callers,
   compare snapshots, or produce cartograph retention evidence. Use before changing
-  MethodChannel or Pigeon/Basic handlers and their Dart callers; RN extraction is not supported.
+  MethodChannel or Pigeon/Basic handlers and their Dart callers. `extract-js` extracts
+  React Native caller-side facts from JS/TS sources within its token-scan scope.
 ---
 
 # isthmus
@@ -13,11 +14,21 @@ analysis evidence; it does not authorize source edits, deletion, publishing, or
 
 ## Inputs
 
-Use `isthmus-cli` 0.1.4+ (`isthmus` binary), cartograph 0.5.3+ and dartograph 0.1.1+.
+Use `isthmus-cli` 0.1.4+ (`isthmus` binary), cartograph 0.5.3+ and dartograph 0.1.1+
+for the basic check/query/diff/retentions workflow. `impact`, `preflight`,
+`verify-runtime`, and Basic/Pigeon (`--messages`) need isthmus-cli 0.6.0 with the
+compatible producer for each side: cartograph 0.15.1 (Swift), dartograph 0.10.0,
+plus kartograph 0.10.0 when Android/Kotlin inputs are used.
 Obtain both Dart and Swift bridge-facts JSON with identical project roots and analysis scope.
 Swift production requires a built compiler index; use `cartograph bridges --target flutter --format json`.
-Android preflight requires development Kotlin support: obtain Kotlin facts using
+Android preflight uses public Kotlin support: obtain Kotlin facts using
 `kartograph bridges --project <root> --target flutter --graph-file <snapshot.json>`.
+For React Native caller-side facts, run `isthmus extract-js <file-or-dir> [more...] [--project <dir>]`
+on the JS/TS sources; it emits a `bridge-facts` document with `platform: "js"`,
+`target: "react-native"` that joins with kartograph/cartograph RN receiver facts.
+Non-literal names stay `dynamic`, and bindings that leave the scanned file set are
+reported only through `limitations` — token-scan output is observation scope, not
+proof of complete app coverage.
 For Basic/Pigeon add `--messages`. A snapshot must come from the same prepared source/build;
 source-only names are not compiler symbol identities. Use `selection.kotlin` in the context.
 The capture workflow accepts `kartograph` and `kartographSnapshot`; Android-only capture does
@@ -31,7 +42,7 @@ If inputs are missing, identify the required files and proceed with independent
 ## Choose the requested operation
 
 - Trace transitive cross-language impact when a current producer context is available
-  (development source, after 0.5.0):
+  (isthmus-cli 0.6.0+):
   `isthmus preflight <context.json> --summary --strict --compact`.
   Add `--revision <expected-capture-revision>` when the workflow supplied that revision.
   Read the whole-report `summary` and `requiresReview`, then bounded collections
@@ -75,8 +86,7 @@ If inputs are missing, identify the required files and proceed with independent
   `passedChecks` counts expectations, not distinct scenarios. In summary/explanation,
   `runtime.verification.declaredScenarioPlatforms` counts unique declared scenario/platform
   pairs; it is not a count of passing scenarios. Multiple checks can share one scenario.
-- Preflight a source change: check `isthmus --help` for `impact` (added after the
-  published 0.5.0; currently requires a build of the development source).
+- Preflight a source change: `impact` is available since isthmus-cli 0.6.0.
   Run `isthmus impact --file <project-relative-path> <dart.json> <swift.json> --strict --compact`;
   for a precise producer symbol use `--symbol <qualifiedName-or-usr>` instead.
   For multiple files, pass `--changes <json>` with
@@ -112,7 +122,7 @@ If inputs are missing, identify the required files and proceed with independent
   Inspect added/removed logical methods, introduced/resolved issues, both sets of limitations,
   and producer versions/timestamps. Revisions come from the caller's before/after choice.
   Same-key endpoint changes and rename inference are outside this comparison.
-- Verify recorded runtime calls (development source, after 0.5.0):
+- Verify recorded runtime calls (isthmus-cli 0.6.0+):
   `isthmus verify-runtime --expectations <checks.json> <runtime.json> [more...] --strict --compact`.
   Expectations must be specified independently of the observed log. Check `status`,
   `summary`, unsuccessful `checks`, `failures`, and stale/incomplete `runs`.

package/compatibility.json

@@ -0,0 +1,10 @@
+{
+  "format": "isthmus-compatibility",
+  "version": 1,
+  "isthmus": "0.7.0",
+  "producers": {
+    "cartograph": "0.18.0",
+    "kartograph": "0.10.2",
+    "dartograph": "0.14.0"
+  }
+}

package/dist/cli/check-command.d.ts

@@ -1,7 +1,7 @@
 import { type Clock, type CommandResult, type ReadTextFile, type WriteTextFile } from './command-support.ts';
 export type { Clock, CommandResult, ReadTextFile, WriteTextFile };
-/** check가 내는 보고서 형식이다. SARIF는 isthmus 소유의 additive 출력이다. */
-export type CheckOutputFormat = 'json' | 'sarif';
+/** check가 내는 보고서 형식이다. SARIF·Code Quality는 isthmus 소유의 additive 출력이다. */
+export type CheckOutputFormat = 'json' | 'sarif' | 'codequality';
 /** check 인자를 실행해 프로세스에 독립적인 결과를 반환한다. */
 export declare function runCheckCommand(arguments_: readonly string[], readTextFile: ReadTextFile, writeTextFile?: WriteTextFile, now?: Clock, producerVersion?: string): Promise<CommandResult>;
 /** check 명령의 한 줄 사용법이다. */