isthmus-cli 0.5.0 → 0.7.0

package/README.ko.md

@@ -1,7 +1,7 @@
 # isthmus
 
 크로스플랫폼 앱에서 **언어 경계를 넘는 호출**을 그래프로 잇는 도구.
-[cartograph](https://github.com/ictechgy/cartograph)(Swift) · kartograph(Kotlin, 예정) ·
+[cartograph](https://github.com/ictechgy/cartograph)(Swift) · [kartograph](https://github.com/ictechgy/kartograph)(Kotlin) ·
 [dartograph](https://github.com/ictechgy/dartograph)(Dart)가 각자 그린 지도를 하나로 붙인다.
 
 [English](README.md)
@@ -22,43 +22,61 @@ React Native나 Flutter 앱의 네이티브 코드는 JS/Dart가 **문자열 이
 
 isthmus는 각 언어 도구가 내보낸 **브리지 사실**(채널 이름 · 메서드 이름 · 등록 지점 ·
 호출 지점)을 문자열 키로 조인해서, 경계를 넘는 간선을 만들고 위 세 가지를 답한다.
-그리고 그 결과를 cartograph/kartograph에 **보존 근거로 돌려준다** — "Swift
+그리고 그 결과를 cartograph에 **보존 근거로 돌려준다** — "Swift
 `CameraHandler.takePhoto`는 `lib/camera.dart:42`가 채널 `com.example/camera`로 부르므로
 보존".
 
 ## 상태
 
-**0.5.0.** CLI 사용성을 통일하고 진단 가독성을 높였다: 모든 명령에서 옵션이 입력
-파일 앞뒤 어디에 와도 동작하고(`-`로 시작하는 경로는 `--` 구분자 뒤에 쓴다),
-`-h`/`--help`는 임의 위치에서 이기며 `help <command>`가 명령별 사용법을 낸다.
-조인이 보류되면 어느 명령이든 관찰한 fact 수·문서 수를 함께 알리고
-(check·graph·query·retentions·diff), query의 `notFound`·`ambiguous`는 원인 한 줄을
-stderr에 출력한다. query `qualifiedName`은 `:`까지 이스케이프해 첫 `:`와 `#` 기준
-분해가 가역이다. 내부로는 공유 CLI 인프라를 check-command에서 분리하고 SARIF 지문
-해싱을 주입해 report 계층이 Node 내장 모듈에 의존하지 않으며, diff 문서 형태를
-`BridgeDiffDocument`로 명시했다. 출력 문서·종료 코드·필드는 불변이고 0.4.1과 값이
-달라지는 것은 이름에 `:`를 포함하는 채널·메서드의 `qualifiedName`뿐이다.
-0.4.0의 추가 사항 — GitHub code scanning용 check SARIF 2.1.0 렌더링(`check --format sarif`,
-additive, 소스 줄 이동에 강한 논리 키 지문), 브리지가 없는 프로젝트와 아무것도
-관찰하지 못한 실행을 구분하는 check summary 관찰량(`observedFacts`·`observedLimitations`),
-다중 호출자 보존 근거(`evidence.callers` — 근거당 상한·명시적 `callersOmitted` 계수,
-단일 호출자는 기존과 바이트 동일), 인덱스 없이 빌드된 Objective-C 핸들러의 usr 없는
-`qualifiedName` 신원 — 과 0.3.0의 핵심 계약·명령은 그대로 유지된다. 외부 입력·
-혼합 target·그래프 크기·Dart/Swift Phase 0 추출 경계는 fail-closed를 유지하고,
-조인하지 못한 사실은 소비자 쪽에서 다시 세며 근거를 만들지 못한 보존 대상은 조용히
-사라지는 대신 실패로 보고한다. 수신 측이 신고한 분석 공백은 불일치가 아니라 판정
-불가로 보고되고 공백 완화는 target을 넘지 않는다. 다음 단계는 실제 Flutter 앱
-도그푸딩과 React Native 지원이다.
-
-정식 producer는 cartograph 0.5.3 이상과 dartograph 0.1.1 이상이다. 두 도구의 실제 출력과
-공개 battery 플러그인의 Swift USR·Dart 호출 근거 왕복을 검증했다.
+**0.6.0**은 Flutter Dart ↔ Swift/Kotlin 변경 사전 점검, MethodChannel·Pigeon/BasicMessageChannel
+사실, 명시한 런타임 시나리오 대조와 내용 기반 수집 캐시를 지원한다. `impact
+--file`/`--symbol`/`--changes`(정보 손실 없는 `--compact` JSON과 분석 공백도 실패시키는
+`--strict` 포함), producer 전이 영향 경로를 다루는 `preflight <context.json>`의
+`--summary`/`--explain`, `verify-runtime --expectations`가 추가됐다. 실제 macOS·Android
+검증 앱에서 공개 플러그인 API를 실행했다. 설정과 측정 범위는 [사전 점검](docs/PREFLIGHT.md),
+[런타임 검증](docs/RUNTIME.md), [고정 소스 구축](docs/TOOLCHAIN.md)을 참조한다.
+
+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, 손 조인 검증 |
 
 ## 의존 관계
@@ -83,23 +101,60 @@ npm install --global isthmus-cli
 isthmus --help
 ```
 
-설치 없이 한 번 실행할 때는 package 이름을 명시한다.
+설치 없이 한 번 실행할 때는 패키지 이름을 명시한다.
 
 ```bash
 npx isthmus-cli --help
 ```
 
-`npx isthmus`는 이름이 같은 다른 package를 설치하므로 사용하면 안 된다.
+`npx isthmus`는 이름이 같은 다른 패키지를 설치하므로 사용하면 안 된다.
 
 ## 사용
 
-isthmus는 자매 도구를 직접 실행하지 않는다. 각 도구가 만든 JSON 파일을 전달하면 된다.
+`impact --file`·`--symbol`·`--changes` 사전 점검과 정보 손실 없는 `--compact`, 분석
+공백도 실패시키는 `--strict`를 제공한다. 빌드·계약·현재 브리지 한정 범위는
+[변경 사전 점검](docs/IMPACT.md)을 참조한다.
+Android 개발 지원은 `selection.kotlin`과 kartograph snapshot을 사용한다. Kotlin Method/Basic
+사실을 Dart 소비자에 연결하고 Android 실행은 Kotlin 후보에만 대조한다.
+[Android 수집 설정](docs/PREFLIGHT.md#android-수집)과 [선택적 Kotlin 도구 구축](docs/TOOLCHAIN.md)을 참조한다.
+`verify-runtime --expectations`는 revision·시나리오·플랫폼·엔진 인스턴스별
+통신 기록을 대조한다([계약](docs/RUNTIME.md)). 선택적 [Flutter 수집기](packages/isthmus_runtime/README.md)는
+실제 macOS·Android 앱에서 핸들러와 `url_launcher_macos 3.2.2`·
+`shared_preferences_android 2.4.1`의 Pigeon 생성 API로 검증했다.
+언어 내부 전이 영향 연결과 스냅샷 수집은 구현됐으며, 더 넓은 앱 적용 범위와
+처음 설치하는 사용자의 재현 절차는 검증 중이다.
+
+0.6.0의 `preflight <context.json> --strict --compact`는 producer의 전이 영향과
+브리지를 연결한다. 별도 수집 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의 실행과
+전이 분석을 대조하고, 네이티브 후보·미관찰 경계·시나리오 누락을 기존 정적 공백과 함께 보고한다.
+
+`preflight <context.json> --summary --strict --compact`로 작은 개요를 읽고,
+`--explain <exact-producer-symbol-id>`로 한 심볼의 전체 원인 경로를 조회한다.
+summary는 목록당 기본 20개(`--limit 1..100`)를 표시하며 생략한 항목도 검토 상태에 반영한다.
+선택적 [Basic/Pigeon v2 입력](docs/BRIDGE-MESSAGES.md)은 literal 주소와
+증명된 prefix 후보를 연결한다. prefix의 suffix·instance 배선 불확실성은 유지한다.
+이 추가 기능은 위에 나열한 공개 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 명령을 실행한다.
 
 ```bash
 isthmus check dart-bridges.json swift-bridges.json
 ```
 
-전체 명령과 현재 package 버전은 다음과 같이 확인한다.
+전체 명령과 현재 패키지 버전은 다음과 같이 확인한다.
 
 ```bash
 isthmus --help
@@ -120,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 소비자)에 올리려면
@@ -129,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`은 모든 형식과 조합되고 문서화된 종료
+코드 동작을 유지한다.
 
 ### 베이스라인
 
@@ -176,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 문서를 최소
@@ -211,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`의 합성 코퍼스가 별도로 검증한다.
 
@@ -254,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이면
 생산자가 서술할 것을 아무것도 보지 못했다는 뜻이다.
@@ -277,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를 호환 변경으로 다룬다.
@@ -310,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
@@ -361,15 +485,16 @@ JSON으로 출력한다. 연결에는 호출자와 핸들러 위치가 포함된
 
 `--strict`는 새로 관찰된 error가 있을 때만 1이다. 기존 오류·경고·분석 한계만 있으면
 0이므로 성공 코드가 삭제 안전성이나 완전한 분석을 뜻하지 않는다. `resolvedIssues`도
-이전 불일치가 더 이상 관찰되지 않는다는 뜻이며, 동적 전환·추출기 변경 때문인지 한계를
+이전 불일치가 더 이상 관찰되지 않는다는 뜻이며, 동적 전환·추출기 변경 때문인지를 한계와
 함께 확인해야 한다. `--strict`은 인자 위치와 무관하게 인식하며 두 번 이상 줄 수 없다.
 
-현재 diff는 Flutter의 Dart·Swift 문서만 받는다. 각 시점에 두 플랫폼이 모두 필요하며,
+`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

@@ -1,7 +1,7 @@
 # isthmus
 
 **Cross-language bridge calls in cross-platform apps, joined into one graph.**
-[cartograph](https://github.com/ictechgy/cartograph) (Swift) · kartograph (Kotlin, planned) ·
+[cartograph](https://github.com/ictechgy/cartograph) (Swift) · [kartograph](https://github.com/ictechgy/kartograph) (Kotlin) ·
 [dartograph](https://github.com/ictechgy/dartograph) (Dart) each draw their own map; isthmus
 joins them into one.
 
@@ -24,46 +24,70 @@ see these strings. As a result:
 
 isthmus joins the **bridge facts** each language tool exports (channel names, method names,
 registration sites, invocation sites) by string key, builds the edges that cross the boundary,
-and answers those three questions. It then hands the result **back to cartograph/kartograph as
+and answers those three questions. It then hands the result **back to cartograph as
 retention evidence** — "keep Swift `CameraHandler.takePhoto`, because `lib/camera.dart:42`
 calls it over channel `com.example/camera`".
 
 ## Status
 
-**0.5.0.** Makes the CLI consistent and its diagnostics more legible: options may appear
-before or after the input files in every command (with a `--` escape for `-`-leading paths),
-`-h`/`--help` wins from any position alongside `help <command>`, deferred joins report how
-many observed facts could not be joined (check, graph, query, retentions, and diff),
-`notFound`/`ambiguous` queries state their cause on stderr, and query `qualifiedName` escapes
-`:` so splitting on the first `:` and `#` always recovers the names. Internally, shared CLI
-infrastructure moved out of check-command, the SARIF fingerprint hash is injected so the
-report layer stays free of Node built-ins, and the diff document shape is named
-(`BridgeDiffDocument`). Output documents, exit codes, and fields are unchanged — the only
-value that differs from 0.4.1 is the `qualifiedName` of channels or methods whose names
-contain `:`.
-The 0.4.0 additions — SARIF 2.1.0 rendering of check results for GitHub code scanning
-(`check --format sarif`, additive, with logic-key fingerprints that survive source line
-moves), observation volume in the check summary (`observedFacts`, `observedLimitations`),
-multi-caller retention evidence (`evidence.callers` with a per-retention cap and an explicit
-`callersOmitted` count, byte-identical for single callers), and usr-less `qualifiedName`
-identity for Objective-C handlers built without an index — and the core 0.3.0 contract and
-commands remain intact. isthmus keeps fail-closed behavior for external input, mixed targets,
-graph size, and the Dart/Swift Phase 0 extraction boundary. Facts that could not be joined
-are re-counted on the consumer side, and retention subjects whose evidence cannot be built
-are refused loudly, so neither disappears silently. Coverage gaps a receiver reports about
-itself come back as undecidable, not as mismatches, and gap mitigation never leaks across
-targets. Next: dogfooding it on a real Flutter app, and React Native support.
-
-The supported producers are cartograph 0.5.3+ and dartograph 0.1.1+. Both were verified on
-their real output, and on a Swift USR ↔ Dart invocation evidence round trip over the public
-battery plugin.
+**0.6.0** supports Flutter Dart ↔ Swift/Kotlin change preflight, MethodChannel and
+Pigeon/BasicMessageChannel facts, declared runtime scenarios, and content-based capture reuse.
+It adds `impact --file`/`--symbol`/`--changes` (with lossless `--compact` JSON and a
+gap-aware `--strict` gate), `preflight <context.json>` with `--summary`/`--explain` over
+producer impact paths, and `verify-runtime --expectations`. Actual macOS and Android fixture
+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.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.
@@ -101,7 +125,52 @@ Do not use `npx isthmus` — that installs a different package with the same nam
 
 ## Usage
 
-isthmus never runs the sister tools itself. You hand it the JSON files they produced:
+Change preflight is available with `impact --file`, `--symbol`, or `--changes`, plus
+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
+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
+by revision, scenario, platform, and engine instance. See the [runtime contract](docs/RUNTIME.md).
+The optional [Flutter recorder](packages/isthmus_runtime/README.md) has been exercised
+in real macOS and Android apps, including the Pigeon-generated APIs of
+`url_launcher_macos 3.2.2` and `shared_preferences_android 2.4.1`. Transitive producer impact
+and snapshot capture are implemented; broader application coverage and first-time setup remain
+under validation.
+
+0.6.0 exposes `preflight <context.json> --strict --compact` to compose
+producer impact paths across the bridge. A separate capture workflow caches declared
+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.
+
+Use `preflight <context.json> --summary --strict --compact` for a bounded overview, then
+`--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. 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,
+and an isolated installation of the isthmus package.
+
+The isthmus CLI reads JSON produced by the sister tools. The optional capture workflow
+runs the preparation and producer commands declared in its configuration:
 
 ```bash
 isthmus check dart-bridges.json swift-bridges.json
@@ -127,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
@@ -143,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
 
@@ -249,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
@@ -272,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
@@ -393,8 +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.
 
-`diff` currently accepts only Flutter Dart/Swift documents. Both platforms are required at
-each point in time, and the two snapshots must agree on `project` and on the per-platform,
+`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`, 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