isthmus-cli 0.4.1 → 0.6.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,29 +22,25 @@ React Native나 Flutter 앱의 네이티브 코드는 JS/Dart가 **문자열 이
 
 isthmus는 각 언어 도구가 내보낸 **브리지 사실**(채널 이름 · 메서드 이름 · 등록 지점 ·
 호출 지점)을 문자열 키로 조인해서, 경계를 넘는 간선을 만들고 위 세 가지를 답한다.
-그리고 그 결과를 cartograph/kartograph에 **보존 근거로 돌려준다** — "Swift
+그리고 그 결과를 cartograph에 **보존 근거로 돌려준다** — "Swift
 `CameraHandler.takePhoto`는 `lib/camera.dart:42`가 채널 `com.example/camera`로 부르므로
 보존".
 
 ## 상태
 
-**0.4.1.** 0.4.0에 구조·보안·성능 리뷰 반영(패치): `mixed-targets` 단어 경계 일치,
-짝 없는 서러게이트 사전 거부(`toWellFormed()`), retentions 호출자 총예산(100만)과
-할당 절감, 빈 플래그 값(exit 64) 거부, atomic-write(0o600) 경화를 적용했다.
-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.6.0**이며 위 기능은 호환되는 producer 개발 commit이 필요하다. 발행된
+Dart/Swift MethodChannel 절차는 cartograph 0.5.3 이상과 dartograph 0.1.1 이상을 사용하며
+공개 battery 플러그인으로 검증했다. Message channel 지원은 현재 개발 producer가 필요하다.
+React Native·EventChannel 추출은 계획이고 보존 근거 내보내기는 현재 cartograph(Swift)를
+대상으로 한다. 앱 전체 적용 범위와 최초 외부 사용자 구축은 아직 검증하지 않았다.
 
 | 문서 | 내용 |
 |---|---|
@@ -86,7 +82,38 @@ npx isthmus-cli --help
 
 ## 사용
 
-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)을 참조한다. 실제 앱 전체 검증은 남아 있다.
+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 주소와
+증명된 prefix 후보를 연결한다. prefix의 suffix·instance 배선 불확실성은 유지한다.
+이 추가 기능에는 개발 producer가 필요하다.
+호환 개발 도구를 로컬 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
@@ -105,6 +132,14 @@ isthmus --version
 isthmus check dart-bridges.json swift-bridges.json --strict
 ```
 
+옵션은 어떤 명령에서든 입력 파일 앞뒤 어디에 와도 된다
+(`isthmus graph --format dot dart-bridges.json swift-bridges.json`도 동작).
+`-`로 시작하는 값은 항상 다음 옵션으로 읽히므로, `-`로 시작하는 경로나 이름은
+옵션 해석을 끝내는 `--` 구분자 뒤에 쓴다:
+`isthmus query -- -unusual-name dart-bridges.json swift-bridges.json`.
+`-h`/`--help`는 어느 위치에 있든 도움말을 내고, `isthmus help <command>`로 명령의
+사용법을 볼 수 있으며, 모르는 명령은 루트 도움말을 출력한다.
+
 ### SARIF 출력
 
 check 결과를 GitHub code scanning(또는 그 밖의 SARIF 2.1.0 소비자)에 올리려면
@@ -164,7 +199,8 @@ cartograph dead --external-retentions external-retentions.json
 여러 위치에서 호출하면 근거가 전체 호출 위치를 `callers`로 실고(대표 `caller`는 옛
 소비자를 위해 유지), 근거당 100개 상한을 넘은 호출은 조용히 버리지 않고
 `callersOmitted`로 계수를 밝힌다. `mixed-targets` 문서는 v1에서 사실별 target을
-복원할 수 없어 모든 소비 명령이 종료 코드 2로 조인을 보류한다. 먼저 생산 단계에서
+복원할 수 없어 모든 소비 명령이 종료 코드 2로 조인을 보류하며, 이때 몇 개의 문서에서
+관찰한 fact 몇 개가 조인되지 못했는지를 함께 알린다. 먼저 생산 단계에서
 target별 문서로 분리해야 한다.
 
 cartograph는 Swift 심볼만 보존하므로 `--for cartograph`는 수신 측 Swift 문서를 최소
@@ -217,6 +253,11 @@ isthmus graph dart-bridges.json swift-bridges.json --format mermaid
 
 `query`는 같은 메서드가 여러 채널에 있으면 후보를 반환하고 임의로 고르지 않는다.
 반환된 `qualifiedName`을 같은 subject 자리에 넣어 정확한 후보를 다시 조회할 수 있다.
+`qualifiedName`은 `target:` 뒤에 퍼센트 이스케이프된 구성 요소가 붙는 형태로
+`%`·`#`·`:`가 모두 이스케이프되므로, 첫 `:`와 `#` 기준으로 나눈 뒤 디코딩하면
+채널·메서드 이름이 항상 되돌아온다. `notFound`·`ambiguous` 질의는 종료 코드 64와
+함께 원인 한 줄을 stderr에 출력하므로, 스크립트가 stdout을 파싱하지 않고도
+호출 오류와 이름 부재를 구분할 수 있다.
 `graph`는 매치된 간선만 내보내며, 입력의 `limitations`를 JSON 필드 또는 DOT/Mermaid
 주석으로 보존한다. 증거의 Cartesian 곱이 100,000개 간선을 넘으면 메모리 폭주를 막기
 위해 종료 코드 2로 실패한다.
@@ -343,7 +384,8 @@ JSON으로 출력한다. 연결에는 호출자와 핸들러 위치가 포함된
 이전 불일치가 더 이상 관찰되지 않는다는 뜻이며, 동적 전환·추출기 변경 때문인지 한계를
 함께 확인해야 한다. `--strict`은 인자 위치와 무관하게 인식하며 두 번 이상 줄 수 없다.
 
-현재 diff는 Flutter의 Dart·Swift 문서만 받는다. 각 시점에 두 플랫폼이 모두 필요하며,
+개발 소스의 diff는 Flutter Dart와 Swift 또는 Kotlin 문서를 받는다. 한 비교에는 native 언어
+하나만 사용하며 각 시점에 호출/수신 문서가 모두 필요하다.
 양 시점의 `project`와 플랫폼·도구별 문서 개수가 같아야 한다. 한 checkout의 같은
 경로에서 각 revision을 빌드해 JSON을 보관한다. 일부 파일만 추출한 결과와 전체 결과를
 비교하지 말고 같은 분석 설정을 사용한다. 입력 파일은 합계 256개, 텍스트 길이 제한은

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,32 +24,26 @@ 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.4.1.** Hardens 0.4.0 with structure, security, and performance review follow-ups:
-word-boundary matching for `mixed-targets`, lone surrogate rejection via `toWellFormed()`,
-a 1,000,000 caller budget for retention documents with pre-slice allocation savings, empty
-flag validation (exit 64), and atomic-write permission hardening (`0o600`).
-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.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.
 
 | Document | Contents |
 |---|---|
@@ -94,7 +88,43 @@ 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.
+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 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
+[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
@@ -113,6 +143,13 @@ To make CI fail when bridge errors exist, add `--strict`:
 isthmus check dart-bridges.json swift-bridges.json --strict
 ```
 
+Options may appear before or after the input files in any command (`isthmus graph --format dot
+dart-bridges.json swift-bridges.json` works). Because a value that starts with `-` is always
+read as the next option, paths or names that begin with `-` go after a `--` separator, which
+ends option parsing: `isthmus query -- -unusual-name dart-bridges.json swift-bridges.json`.
+`-h`/`--help` shows help from any position, `isthmus help <command>` names a command's usage,
+and an unknown command prints the root help.
+
 ### SARIF output
 
 To upload check results to GitHub code scanning (or any SARIF 2.1.0 consumer), ask for SARIF
@@ -176,7 +213,8 @@ invoked from several caller locations, the evidence carries all of them in `call
 representative first `caller` stays for older consumers) and counts any entries beyond the
 100-per-retention cap in `callersOmitted` instead of dropping them silently. A
 `mixed-targets` document cannot have per-fact targets restored in v1, so every consuming
-command defers the join with exit code 2; split such a document per target at production time
+command defers the join with exit code 2, reporting how many observed facts across how many
+documents could not be joined; split such a document per target at production time
 first.
 
 cartograph retains Swift symbols only, so `--for cartograph` requires at least one
@@ -231,7 +269,12 @@ isthmus graph dart-bridges.json swift-bridges.json --format mermaid
 ```
 
 When the same method exists on several channels, `query` returns candidates instead of picking
-one; feed a returned `qualifiedName` back into the same subject position to disambiguate.
+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
+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
 DOT/Mermaid comments. If the Cartesian product of evidence would exceed 100,000 edges, the
 command fails with exit code 2 to prevent a memory blowup.
@@ -373,7 +416,8 @@ 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
+Development `diff` accepts Flutter Dart plus either Swift or Kotlin 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,
 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

package/Skills/isthmus/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: isthmus
 description: >-
-  Trace Flutter Dart-to-Swift bridge callers, compare bridge snapshots, or produce
-  cartograph retention evidence with isthmus. Use for native MethodChannel handler
-  changes; React Native and Kotlin extraction are not supported.
+  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.
 ---
 
 # isthmus
@@ -16,11 +16,88 @@ analysis evidence; it does not authorize source edits, deletion, publishing, or
 Use `isthmus-cli` 0.1.4+ (`isthmus` binary), cartograph 0.5.3+ and dartograph 0.1.1+.
 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
+`kartograph bridges --project <root> --target flutter --graph-file <snapshot.json>`.
+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
+not require cartograph. Fingerprint the Kartograph launcher and its runtime library directory.
+For an app-local Pigeon package, explicitly include its source in Dartograph's `source_packages`
+configuration and in capture inputs; see `docs/PREFLIGHT.md`. A runtime success alone does not
+establish a static path from the Kotlin implementation through the generated Dart API to the app caller.
 Do not fabricate missing facts or rewrite project identifiers just to make a join pass.
 If inputs are missing, identify the required files and proceed with independent authorized work.
 
 ## Choose the requested operation
 
+- Trace transitive cross-language impact when a current producer context is available
+  (development source, after 0.5.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
+  `{total, items, omitted}` for roots, affected symbols, review files and limitations.
+  Default display limit is 20; `--limit <1..100>` only applies to summary. Omitted
+  entries were analyzed and still affect status. For a requested symbol's complete
+  root-to-target path, replace `--summary` with `--explain <exact-key-or-producer-id>`
+  from the preview. Exact qualifiedName is also accepted; ambiguous matches return
+  candidates with code 64. `result.path` is a full array; each step's relations are
+  bounded. Describe those actual steps; do not substitute a similarly named root
+  from summary. A path through shared registration may be broader than the requested
+  method's execution path. Do not combine summary and explain. Omit both flags only when the full
+  report is needed; it includes `affected[].via`, `boundaries` and all evidence.
+  Distinguish language use edges
+  from bridge evidence; dependency boundaries do not imply changes to every caller
+  of an unchanged native handler. Do not repeat queries for evidence already present.
+  Use the source-generation workflow to refresh stale context; do not hand-author
+  missing producer identities or analyses. The separate `scripts/capture-preflight.mjs`
+  workflow executes configured preparation and producer commands, so use the project's
+  established configuration and existing authorization. Its fingerprint covers declared
+  inputs; inspect that scope before reusing the cache. The `.sources.json` sidecar retains
+  original producer reports. Report paths are relative to `project`; verify existence
+  before making local links. Code 1 preserves a usable report with gaps; `noChanges`
+  only means no modeled source selection. To also verify runtime evidence, use
+  `isthmus preflight <context.json> <runtime.json> [more...] --expectations <checks.json> --summary --strict --compact`.
+  Read `runtime.aligned` as well as `runtime.verification.status`, `unobservedBoundaries`,
+  `uncoveredBoundaries`, and route `staticStatus`. Passing unrelated scenarios or matching
+  old expectations/logs cannot verify the current change. Basic/Pigeon static support
+  requires optional v2 `context.messages` from both producers; without it Basic is
+  unsupported for static matching. `matching: prefix` remains a possible address
+  family, with unresolved suffix/instance wiring even after a successful runtime call.
+  Address matches remain native candidates. Raw message limitations appear separately
+  as `messageLimitations` when message inputs are present.
+  Android observations match Kotlin candidates; iOS/macOS observations match Swift candidates.
+  In a mixed native context, one platform's success does not cover the other platform.
+  Follow each route's candidateKey; do not group native candidates by channel name alone.
+  For a runtime-only dynamic route, follow `candidateKey` into `runtime.candidates` for
+  native source evidence. In summary/explanation, `candidates.items[].handlers` is a
+  bounded collection of source locations/symbols; report its `omitted` count. The full
+  report uses `handlersOmitted` for its native-candidate display cap.
+  `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).
+  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
+  `{"format":"isthmus-changes","version":1,"files":["lib/camera.dart","ios/Camera.swift"]}`.
+  Read `reviewFiles`, `methods` (callers and handlers), `issues`, `selectedFacts`,
+  `unmatchedSelectors`, and `relevantLimitations` in one response. Channel wiring
+  changes include every observed method on that channel. Compact output loses no evidence.
+  Impact already includes both sides; do not repeat a channel query just to retrieve
+  the same endpoints. Evidence paths are relative to report `project`, not the CLI
+  working directory. Make local file links only after confirming the files exist;
+  for non-local snapshots, give the reported relative path and line as evidence.
+  `--strict` returns code 1 on related errors, extraction gaps and unobserved selections;
+  read its JSON as the preflight result instead of rerunning the same inputs without the flag.
+  For deleted code use the pre-change snapshot. `scope: bridge` and `complete: false`
+  do not establish complete coverage of language-internal or runtime dependencies.
+  When current runtime evidence is available, add `--runtime <runtime.json> --revision <revision>`.
+  Inspect `runtime.routes`, failures/gaps and `runtime-observation` reasons. These add
+  native handler candidates for dynamically named calls, not proof of a particular
+  native symbol executing. Static unresolved facts remain unresolved for untested paths.
+  If the installed CLI lacks impact, use `query` on bridge names found in the source
+  and report that file-based preflight requires the newer implementation.
 - Audit the boundary: `isthmus check <dart.json> <swift.json> [--strict]`.
   Read `summary`, each `issues[].code/severity/evidence`, and `limitations`.
   `-unverified` codes are undecidable findings, not clean results.
@@ -35,15 +112,27 @@ 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):
+  `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`.
+  `passed` covers only declared scenarios; missing, stale, dropped or pending evidence
+  cannot establish coverage. `evidenceOmitted` is display truncation; `droppedEvents`
+  means collection loss. Do not fabricate logs when the runtime recorder is unavailable.
+  Expected negative scenarios can declare `allowedOutcomes` explicitly; omitted means
+  success only. Preserve expected and unexpected failure counts. Pending calls, stale
+  runs, and missing observations cannot be allowed outcomes.
 - Supply Swift retention evidence, when requested:
   `isthmus retentions <dart.json> <swift.json> --for cartograph`.
   Save stdout to a new private temporary file, check successful output, then pass its path to
   `cartograph dead --external-retentions <path>`. Clean up only artifacts created for this run.
+  This command targets Swift; it does not emit Kotlin retention rules.
 
 ## Interpret and finish
 
 Code 0 means the command ran successfully, not that code is safe to delete.
-Code 1 from check/diff strict is a finding to report; query code 64 with
+Code 1 from check/diff/impact/preflight/verify-runtime strict is a finding or evidence gap to report;
+query code 64 with
 `notFound`/`ambiguous` is a usable answer, while usage errors require corrected arguments.
 Code 2 indicates unreadable, invalid, or deferred inputs: explain the cause category and next step.
 Empty results, `resolvedIssues`, and missing callers can reflect dynamic names or incomplete coverage.

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

@@ -1,31 +1,8 @@
-import { type BridgeFactsDocument } from '../exchange/parse.ts';
-/** 파일 경로를 받아 UTF-8 텍스트를 읽는 주입 경계다. */
-export type ReadTextFile = (path: string) => Promise<string>;
-/** 파일 경로에 UTF-8 텍스트를 쓰는 주입 경계다. */
-export type WriteTextFile = (path: string, text: string) => Promise<void>;
-/** 생성 시각을 테스트 가능하게 주입하는 시계다. */
-export type Clock = () => Date;
+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';
-/** 한 입력 파일에서 허용하는 최대 UTF-16 문자열 길이다. */
-export declare const MAX_INPUT_TEXT_LENGTH: number;
-/** 한 명령에서 허용하는 전체 UTF-16 입력 문자열 길이다. */
-export declare const MAX_TOTAL_INPUT_TEXT_LENGTH: number;
-/** CLI가 프로세스 경계에 쓸 출력과 종료 코드다. */
-export interface CommandResult {
-    readonly standardOutput: string;
-    readonly standardError: string;
-    readonly exitCode: 0 | 1 | 2 | 64;
-}
 /** check 인자를 실행해 프로세스에 독립적인 결과를 반환한다. */
 export declare function runCheckCommand(arguments_: readonly string[], readTextFile: ReadTextFile, writeTextFile?: WriteTextFile, now?: Clock, producerVersion?: string): Promise<CommandResult>;
-/** 입력을 순서대로 읽어 파일 수·메모리 상한 안에서 교환 문서로 파싱한다. */
-export declare function readBridgeDocuments(inputPaths: readonly string[], readTextFile: ReadTextFile): Promise<BridgeFactsDocument[]>;
-/** 알려진 입력·조인 실패를 원인별 해결 방향을 담은 코드 2 결과로 바꾼다. */
-export declare function inputFailureResult(error: unknown): CommandResult | undefined;
-/** 전체 조인 보류를 깨끗한 결과와 구분하는 코드 2 결과로 바꾼다. */
-export declare function bridgeJoinDeferredError(): CommandResult;
-/** 내부 결함을 입력 탓으로 돌리지 않는 경로 없는 코드 2 결과다. */
-export declare function internalError(): CommandResult;
 /** check 명령의 한 줄 사용법이다. */
 export declare const checkUsage: string;