diff --git a/.agents/skills/reverse-engineer-anything/SKILL.md b/.agents/skills/reverse-engineer-anything/SKILL.md
index 3b508af1c..f8ec45268 100644
--- a/.agents/skills/reverse-engineer-anything/SKILL.md
+++ b/.agents/skills/reverse-engineer-anything/SKILL.md
@@ -83,6 +83,12 @@ explicit path or endpoint and do not need it.
frames; use `match_offset` / `match_limit` for later pages, or explicit null
limit for complete matching output. Preserve the source digest across pages.
This does not perform live capture.
+ For address/DNS/SNI/protocol summaries use `inspect_pcap_capture` with MCP
+ detail summary, then retained kind pcap pages. Requires Wireshark 4.x tshark
+ and capinfos, with Linux prlimit or Windows Job Objects; see
+ [packet summaries](https://github.com/morluto/rea/blob/main/docs/pcap-analysis.md).
+ Select an exact DNS question for address pages; page exhaustion does not prove
+ network completeness. This reads recordings and does not acquire traffic.
- Recorded logic/signal traces: `decode_signal_recording` with explicit decoder,
channel and protocol settings. On Linux with util-linux prlimit, supply sigrok-cli 0.7.2 through
`REA_SIGROK_COMMAND`; see [recording guide](https://github.com/morluto/rea/blob/main/docs/signal-recordings.md).
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1e08d9407..e7515c0c4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -515,6 +515,7 @@ jobs:
tests/boundary/providers/native/artifactProvider.extractionCompleteness.test.ts
tests/boundary/filesystem/setupUnavailableProvider.test.ts
tests/boundary/filesystem/windowsNpxRegistration.test.ts
+ tests/acceptance/setup/homeDirectoryFallback.test.ts
tests/boundary/filesystem/webScriptManifestPaths.test.ts
tests/boundary/process/ProcessEvidence.host.test.ts
tests/acceptance/webModuleCli.test.ts
diff --git a/.github/workflows/real-packet-capture.yml b/.github/workflows/real-packet-capture.yml
index 8faf9ba99..f481ed00d 100644
--- a/.github/workflows/real-packet-capture.yml
+++ b/.github/workflows/real-packet-capture.yml
@@ -7,6 +7,13 @@ on:
- "tests/boundary/cli/captureCleanup.test.ts"
- "tests/boundary/mcp/packetCaptureMcp.test.ts"
- "src/captures/**"
+ - "src/pcap/**"
+ - "src/domain/pcap/**"
+ - "src/domain/analysisView/pcapCaptureView.ts"
+ - "src/application/pcap/**"
+ - "src/contracts/pcap/**"
+ - "src/server/registerPcapTools.ts"
+ - "tests/boundary/pcap/**"
- "src/domain/captures/**"
- "src/application/captures/**"
- "src/contracts/captures/**"
@@ -48,3 +55,4 @@ jobs:
- run: node scripts/verify-packet-capture.mjs
env:
REA_TSHARK_COMMAND: /usr/bin/tshark
+ REA_CAPINFOS_COMMAND: /usr/bin/capinfos
diff --git a/README.md b/README.md
index 49173ab4b..c4a89bcee 100644
--- a/README.md
+++ b/README.md
@@ -170,6 +170,7 @@ Additional tools and host support depend on the target:
| Flutter apps | Dart snapshot hash, per-ABI library digests and engine build provenance | None (static APK parsing); [Flutter guide](docs/flutter-analysis.md) |
| Firmware | Regions, extraction results and native-analysis handoffs | Binwalk / Unblob on Linux; [firmware guide](docs/firmware-analysis.md) |
| Recorded packets | Selected fields, repeated values, filters and decode-as rules | Linux: TShark 4.x + prlimit; [capture guide](docs/packet-captures.md) |
+| Packet summaries | Endpoints, DNS, TLS SNI, protocol distribution and HTTP requests | Caller-supplied tshark and capinfos (Linux-verified); [pcap guide](docs/pcap-analysis.md) |
| Recorded logic signals | Decoder annotations, sample ranges and diagnostics | Linux: sigrok-cli 0.7.2 + prlimit; [signal recordings](docs/signal-recordings.md) |
| Packages and resources | File inventories, digests, plists, Apple bundle anatomy and extracted resources | [Artifact and JavaScript guide](docs/javascript-artifact-reconstruction.md), [Apple applications](docs/apple-application-analysis.md) |
| Process behavior | Terminal output, interactions, exit and filesystem observations, and run comparisons | Linux/macOS with a native PTY; [process capture](docs/process-capture.md) |
@@ -321,7 +322,7 @@ Report vulnerabilities through [SECURITY.md](SECURITY.md).
## Star history
-🎉 **110,000 GitHub stars — thank you!**
+🎉 **170,000 GitHub stars — thank you!**
Thanks to everyone using REA, reporting bugs, requesting features, testing builds, and contributing fixes.
diff --git a/README_ar.md b/README_ar.md
index 0693fe67f..1c0bc367e 100644
--- a/README_ar.md
+++ b/README_ar.md
@@ -139,6 +139,7 @@ npx rea-agents@latest setup
| JavaScript / Electron | الوحدات، وعمليات الاستيراد، وخرائط المصدر، والمسارات، وIPC، وعلاقات إضافات الشيفرة الأصلية | Node.js وnpm؛ [تحليل التطبيقات](https://rea.tools/ar/guides/javascript/) |
| المواقع | بنية الصفحة، والسكربتات، وملاحظات الشبكة، ولقطات الشاشة المطلوبة | متصفح من عائلة Chrome؛ [تحليل المتصفح](https://rea.tools/ar/guides/browser/) |
| تسجيلات الشبكة المحفوظة | الطلبات، والاستجابات، ومحتويات الحمولة المتاحة، ومواضعها في المصدر | HAR؛ وmitmdump على Linux لتسجيلات mitmproxy بصيغتها الأصلية؛ [دليل تسجيلات الشبكة](docs/web-network-captures.md) |
+| التقاط الحزم | نقاط النهاية وDNS وTLS SNI وتوزيع البروتوكولات وطلبات HTTP | tshark وcapinfos يوفّرهما المُستدعي؛ [دليل pcap](docs/pcap-analysis.md) |
| تجميعات .NET | البيانات الوصفية، وتعليمات CIL، واعتماديات الشيفرة الأصلية المعلنة، ومقارنات البناء | فحص ثابت؛ [دليل الشيفرة المُدارة](docs/managed-code-analysis.md) |
| حزم Android APK | تصريحات ملف manifest، والأصناف، والدوال الناتجة عن فك الترجمة، والمراجع | JADX دون واجهة رسومية وJDK كامل على Linux/macOS/Windows x64؛ [دليل Android](docs/android-analysis.md) |
| أجهزة Android | الأجهزة والحزم والعمليات والسجلات والدامبات ولقطات الشاشة ونقل APK/الملفات | adb يوفّره المُستدعي (محاكي أو جهاز)؛ [دليل ADB](docs/adb-device-analysis.md) |
@@ -263,7 +264,7 @@ npx rea-agents@latest setup
## سجل النجوم
-🎉 **110,000 نجمة على GitHub — شكرًا لكم!**
+🎉 **170,000 نجمة على GitHub — شكرًا لكم!**
شكرًا لكل من يستخدم REA، ويبلّغ عن الأخطاء، ويقترح ميزات، ويختبر إصدارات البناء، ويساهم بالإصلاحات.
diff --git a/README_de.md b/README_de.md
index 1e96cd46b..2c6d20290 100644
--- a/README_de.md
+++ b/README_de.md
@@ -139,6 +139,7 @@ REA benötigt Node.js 22.x (>=22.19), 24.x (>=24.11) oder 26+ sowie npm. Zusätz
| JavaScript / Electron | Module, Imports, Source Maps, Routen, IPC und Beziehungen zu nativen Add-ons | Node.js und npm; [Anwendungsanalyse](https://rea.tools/de/guides/javascript/) |
| Websites | Seitenstruktur, Skripte, Netzwerkbeobachtungen und angeforderte Screenshots | Ein Browser aus der Chrome-Familie; [Browseranalyse](https://rea.tools/de/guides/browser/) |
| Gespeicherte Netzwerkaufzeichnungen | Anfragen, Antworten, zugängliche Nutzdaten und Quellpositionen | HAR; mitmdump unter Linux für Aufzeichnungen im nativen mitmproxy-Format; [Leitfaden zu Netzwerkaufzeichnungen](docs/web-network-captures.md) |
+| Paketerfassungen | Endpunkte, DNS, TLS SNI, Protokollverteilung und HTTP-Anfragen | Vom Aufrufer bereitgestellte tshark- und capinfos-Binaries; [pcap-Leitfaden](docs/pcap-analysis.md) |
| .NET-Assemblies | Metadaten, CIL-Anweisungen, deklarierte native Abhängigkeiten und Build-Vergleiche | Statische Untersuchung; [Leitfaden für verwalteten Code](docs/managed-code-analysis.md) |
| Android-APKs | Manifest-Deklarationen, Klassen, dekompilierte Methoden und Verweise | JADX ohne grafische Oberfläche und ein vollständiges JDK unter Linux/macOS/Windows x64; [Android-Leitfaden](docs/android-analysis.md) |
| Android-Geräte | Geräte, Pakete, Prozesse, Logs, Dumps, Bildschirmaufnahmen sowie APK- und Dateiübertragungen | Vom Aufrufer bereitgestelltes adb (Emulator oder Gerät); [ADB-Leitfaden](docs/adb-device-analysis.md) |
@@ -261,7 +262,7 @@ Melde Sicherheitslücken gemäß [SECURITY.md](SECURITY.md).
## Sternverlauf
-🎉 **110.000 GitHub-Sterne – vielen Dank!**
+🎉 **170.000 GitHub-Sterne – vielen Dank!**
Danke an alle, die REA nutzen, Fehler melden, Funktionswünsche äußern, Builds testen und Fehlerbehebungen beitragen.
diff --git a/README_es.md b/README_es.md
index 9a59a74d2..f955b5891 100644
--- a/README_es.md
+++ b/README_es.md
@@ -139,6 +139,7 @@ REA requiere Node.js 22.x (>=22.19), 24.x (>=24.11) o 26+, además de npm. Las h
| JavaScript / Electron | Módulos, importaciones, mapas de código fuente, rutas, IPC y relaciones con complementos nativos | Node.js y npm; [análisis de aplicaciones](https://rea.tools/es/guides/javascript/) |
| Sitios web | Estructura de la página, scripts, observaciones de red y capturas de pantalla solicitadas | Un navegador de la familia Chrome; [análisis del navegador](https://rea.tools/es/guides/browser/) |
| Capturas de red guardadas | Solicitudes, respuestas, contenido accesible de las cargas útiles y ubicaciones de origen | HAR; mitmdump en Linux para capturas en formato nativo de mitmproxy; [guía de capturas](docs/web-network-captures.md) |
+| Capturas de paquetes | Endpoints, DNS, TLS SNI, distribución de protocolos y solicitudes HTTP | tshark y capinfos suministrados por el autor de la llamada; [guía pcap](docs/pcap-analysis.md) |
| Ensamblados .NET | Metadatos, instrucciones CIL, dependencias nativas declaradas y comparaciones de compilaciones | Inspección estática; [guía de código administrado](docs/managed-code-analysis.md) |
| APK de Android | Declaraciones del manifiesto, clases, métodos descompilados y referencias | JADX sin interfaz gráfica y un JDK completo en Linux/macOS/Windows x64; [guía de Android](docs/android-analysis.md) |
| Dispositivos Android | Dispositivos, paquetes, procesos, registros, volcados, capturas de pantalla y transferencias de APK/archivos | adb suministrado por el autor de la llamada (emulador o dispositivo); [guía de ADB](docs/adb-device-analysis.md) |
@@ -261,7 +262,7 @@ Informa de vulnerabilidades siguiendo [SECURITY.md](SECURITY.md).
## Historial de estrellas
-🎉 **110.000 estrellas en GitHub: ¡gracias!**
+🎉 **170.000 estrellas en GitHub: ¡gracias!**
Gracias a quienes usan REA, informan de errores, solicitan funciones, prueban compilaciones y contribuyen con correcciones.
diff --git a/README_fa.md b/README_fa.md
index e34788e7a..54af87c57 100644
--- a/README_fa.md
+++ b/README_fa.md
@@ -139,6 +139,7 @@ REA به Node.js 22.x (>=22.19)، 24.x (>=24.11) یا 26+، بههمراه np
| برنامههای فلاتر | هش اسنپشات دارت، هش کتابخانهها به تفکیک ABI و اصالت بیلد موتور | هیچ (تحلیل ایستا APK)؛ [راهنمای فلاتر](docs/flutter-analysis.md) |
| Firmware | ناحیهها، نتایج استخراج و تحویل به ابزارهای تحلیل بومی | Binwalk / Unblob در لینوکس؛ [راهنمای Firmware](docs/firmware-analysis.md) |
| بستههای ضبطشده | فیلدهای منتخب، مقادیر تکراری، فیلترها و قواعد رمزگشایی | Linux: TShark 4.x + prlimit; [راهنمای ضبط بسته](docs/packet-captures.md) |
+| ضبط بستهها | نقاط پایانی، DNS، TLS SNI، توزیع پروتکل و درخواستهای HTTP | tshark و capinfos تأمینشده توسط فراخوانکننده؛ [راهنمای pcap](docs/pcap-analysis.md) |
| سیگنالهای منطقی ضبطشده | توضیحات رمزگشا، بازههای نمونه و اطلاعات عیبیابی | Linux: sigrok-cli 0.7.2 + prlimit; [راهنمای سیگنالها](docs/signal-recordings.md) |
| بستهها و منابع | فهرست فایلها، digestها، فایلهای plist، ساختار bundle اپل و منابع استخراجشده | [راهنمای آرتیفکت و JavaScript](docs/javascript-artifact-reconstruction.md)، [برنامههای اپل](docs/apple-application-analysis.md) |
| رفتار فرایند | خروجی ترمینال، تعاملات، وضعیت خروج، مشاهدات سیستم فایل و مقایسهٔ اجراها | Linux/macOS با PTY بومی؛ [ضبط فرایند](docs/process-capture.md) |
@@ -246,7 +247,7 @@ npx rea-agents@latest setup
## تاریخچهٔ ستارهها
-🎉 **۱۱۰٬۰۰۰ ستارهٔ GitHub — سپاسگزاریم!**
+🎉 **۱۷۰٬۰۰۰ ستارهٔ GitHub — سپاسگزاریم!**
از همهٔ کسانی که از REA استفاده میکنند، خطاها را گزارش میدهند، قابلیتهای جدید پیشنهاد میکنند، buildها را آزمایش میکنند و در بهبود پروژه مشارکت دارند سپاسگزاریم.
diff --git a/README_fr.md b/README_fr.md
index f28e53f1a..346210525 100644
--- a/README_fr.md
+++ b/README_fr.md
@@ -143,6 +143,7 @@ REA nécessite Node.js 22.x (>=22.19), 24.x (>=24.11) ou 26+, ainsi que npm. Les
| JavaScript / Electron | Modules, imports, source maps, routes, IPC et relations avec les modules natifs | Node.js et npm ; [analyse d'applications](https://rea.tools/fr/guides/javascript/) |
| Sites web | Structure des pages, scripts, observations réseau et captures d'écran demandées | Un navigateur de la famille Chrome ; [analyse du navigateur](https://rea.tools/fr/guides/browser/) |
| Captures réseau enregistrées | Requêtes, réponses, payloads exposés et emplacements dans le code source | HAR ; mitmdump sous Linux pour les captures mitmproxy natives ; [guide des captures](docs/web-network-captures.md) |
+| Captures de paquets | Points de terminaison, DNS, TLS SNI, distribution des protocoles et requêtes HTTP | tshark et capinfos fournis par l'appelant ; [guide pcap](docs/pcap-analysis.md) |
| Assemblys .NET | Métadonnées, instructions CIL, dépendances natives déclarées et comparaisons de builds | Inspection statique ; [guide du code managé](docs/managed-code-analysis.md) |
| APK Android | Déclarations du manifeste, classes, méthodes décompilées et références | JADX headless et un JDK complet sous Linux/macOS/Windows x64 ; [guide Android](docs/android-analysis.md) |
| Appareils Android | Appareils, paquets, processus, journaux, dumps, captures d'écran et transferts d'APK/fichiers | adb fourni par l'appelant (émulateur ou appareil) ; [guide ADB](docs/adb-device-analysis.md) |
@@ -265,7 +266,7 @@ Signalez les vulnérabilités via [SECURITY.md](SECURITY.md).
## Historique des étoiles
-🎉 **110 000 étoiles GitHub — merci !**
+🎉 **170 000 étoiles GitHub — merci !**
Merci à toutes les personnes qui utilisent REA, signalent des bugs, proposent des fonctionnalités, testent les builds et contribuent des correctifs.
diff --git a/README_id.md b/README_id.md
index 440a8f81b..7a564c434 100644
--- a/README_id.md
+++ b/README_id.md
@@ -146,6 +146,7 @@ Alat tambahan dan dukungan sistem host bergantung pada target yang dianalisis:
| JavaScript / Electron | Modul, impor, source map, rute, IPC, dan hubungan add-on native | Node.js dan npm; [analisis aplikasi](https://rea.tools/id/guides/javascript/) |
| Situs web | Struktur halaman, skrip, pengamatan jaringan, dan tangkapan layar yang diminta | Peramban berbasis Chrome; [analisis peramban](https://rea.tools/id/guides/browser/) |
| Rekaman jaringan tersimpan | Permintaan, respons, payload yang terekspos, dan lokasi sumber | HAR; mitmdump di Linux untuk rekaman native mitmproxy; [panduan rekaman](docs/web-network-captures.md) |
+| Capturan paket | Endpoint, DNS, TLS SNI, distribusi protokol, dan permintaan HTTP | tshark dan capinfos buatan pemanggil; [panduan pcap](docs/pcap-analysis.md) |
| Assembly .NET | Metadata, instruksi CIL, dependensi native yang dideklarasikan, dan perbandingan build | Tidak ada (hanya analisis statis); [panduan kode terkelola](docs/managed-code-analysis.md) |
| APK Android | Deklarasi manifest, kelas, metode hasil dekompilasi, dan referensi | JADX mode headless dan JDK lengkap di Linux/macOS/Windows x64; [panduan Android](docs/android-analysis.md) |
| Perangkat Android | Perangkat, paket, proses, log, dump, tangkapan layar, serta transfer APK/berkas | adb buatan pemanggil (emulator atau perangkat); [panduan ADB](docs/adb-device-analysis.md) |
@@ -286,7 +287,7 @@ Laporkan kerentanan melalui [SECURITY.md](SECURITY.md).
## Riwayat Bintang
-🎉 **110.000 bintang GitHub, terima kasih!**
+🎉 **170.000 bintang GitHub, terima kasih!**
Terima kasih kepada semua orang yang menggunakan REA, melaporkan bug, meminta fitur, menguji build, dan berkontribusi dalam perbaikan.
diff --git a/README_it.md b/README_it.md
index 24c1d35bc..8b1c55afe 100644
--- a/README_it.md
+++ b/README_it.md
@@ -143,6 +143,7 @@ REA richiede Node.js 22.x (>=22.19), 24.x (>=24.11) o 26+, oltre a npm. Strument
| JavaScript / Electron | Moduli, import, source map, route, IPC e relazioni con add-on nativi | Node.js e npm; [analisi delle applicazioni](https://rea.tools/it/guides/javascript/) |
| Siti web | Struttura della pagina, script, osservazioni di rete e screenshot richiesti | Un browser della famiglia Chrome; [analisi browser](https://rea.tools/it/guides/browser/) |
| Acquisizioni di rete salvate | Richieste, risposte, payload esposti e posizioni sorgente | HAR; mitmdump su Linux per acquisizioni mitmproxy native; [guida alle acquisizioni](docs/web-network-captures.md) |
+| Captured di pacchetti | Endpoint, DNS, TLS SNI, distribuzione dei protocolli e richieste HTTP | tshark e capinfos forniti dal chiamante; [guida pcap](docs/pcap-analysis.md) |
| Assembly .NET | Metadati, istruzioni CIL, dipendenze native dichiarate e confronti di build | Nessuno (solo statico); [guida managed-code](docs/managed-code-analysis.md) |
| APK Android | Dichiarazioni manifest, classi, metodi decompilati e riferimenti | JADX headless e un JDK completo su Linux/macOS/Windows x64; [guida Android](docs/android-analysis.md) |
| Dispositivi Android | Dispositivi, pacchetti, processi, log, dump, screenshot e trasferimenti APK/file | adb fornito dal chiamante (emulatore o hardware); [guida ADB](docs/adb-device-analysis.md) |
@@ -265,7 +266,7 @@ Segnala vulnerabilità tramite [SECURITY.md](SECURITY.md).
## Cronologia delle stelle
-🎉 **110.000 stelle su GitHub — grazie!**
+🎉 **170.000 stelle su GitHub — grazie!**
Grazie a tutti coloro che usano REA, segnalano bug, propongono funzionalità, testano le build e contribuiscono con correzioni.
diff --git a/README_ja.md b/README_ja.md
index 8b32338aa..5fb42d096 100644
--- a/README_ja.md
+++ b/README_ja.md
@@ -139,6 +139,7 @@ REA には Node.js 22.x(>=22.19)、24.x(>=24.11)、または 26+ と npm
| JavaScript / Electron | モジュール、インポート、ソースマップ、ルート、IPC、ネイティブアドオンの関係 | Node.js と npm;[アプリケーション分析](https://rea.tools/ja/guides/javascript/) |
| ウェブサイト | ページ構造、スクリプト、ネットワークの観測結果、依頼されたスクリーンショット | Chrome 系ブラウザー;[ブラウザー分析](https://rea.tools/ja/guides/browser/) |
| 保存済みのネットワークキャプチャ | リクエスト、レスポンス、取得可能なペイロード、ソース内の位置 | HAR;mitmproxy ネイティブ形式のキャプチャには Linux 上の mitmdump;[キャプチャガイド](docs/web-network-captures.md) |
+| パケットキャプチャ | エンドポイント、DNS、TLS SNI、プロトコル分布、HTTPリクエスト | 呼び出し側が用意した tshark と capinfos;[pcapガイド](docs/pcap-analysis.md) |
| .NET アセンブリ | メタデータ、CIL 命令、宣言されたネイティブ依存関係、ビルドの比較 | 静的な検査;[マネージドコードのガイド](docs/managed-code-analysis.md) |
| Android APK | マニフェストの宣言、クラス、逆コンパイルされたメソッド、参照 | Linux/macOS/Windows x64 上のヘッドレス JADX と完全な JDK;[Android ガイド](docs/android-analysis.md) |
| Android デバイス | デバイス、パッケージ、プロセス、ログ、ダンプ、スクリーンキャプチャ、APK/ファイル転送 | 呼び出し側が用意した adb(エミュレーターまたは実機);[ADB ガイド](docs/adb-device-analysis.md) |
@@ -263,7 +264,7 @@ npx rea-agents@latest setup
## スター履歴
-🎉 **GitHub スター 110,000 件、ありがとうございます!**
+🎉 **GitHub スター 170,000 件、ありがとうございます!**
REA の利用、バグ報告、機能の要望、ビルドのテスト、修正への貢献に感謝します。
diff --git a/README_ko.md b/README_ko.md
index 656753d7b..5a9e7cd5d 100644
--- a/README_ko.md
+++ b/README_ko.md
@@ -139,6 +139,7 @@ REA에는 Node.js 22.x(>=22.19), 24.x(>=24.11) 또는 26+와 npm이 필요합니
| JavaScript / Electron | 모듈, 임포트, 소스 맵, 라우트, IPC, 네이티브 애드온 관계 | Node.js와 npm; [애플리케이션 분석](https://rea.tools/ko/guides/javascript/) |
| 웹사이트 | 페이지 구조, 스크립트, 네트워크 관찰 결과, 요청한 스크린샷 | Chrome 계열 브라우저; [브라우저 분석](https://rea.tools/ko/guides/browser/) |
| 저장된 네트워크 캡처 | 요청, 응답, 접근 가능한 페이로드, 소스 위치 | HAR; mitmproxy 네이티브 캡처에는 Linux의 mitmdump; [캡처 가이드](docs/web-network-captures.md) |
+| 패킷 캡처 | 엔드포인트, DNS, TLS SNI, 프로토콜 분포, HTTP 요청 | 호출자 제공 tshark 및 capinfos; [pcap 가이드](docs/pcap-analysis.md) |
| .NET 어셈블리 | 메타데이터, CIL 명령, 선언된 네이티브 의존성, 빌드 비교 | 정적 검사; [관리 코드 가이드](docs/managed-code-analysis.md) |
| Android APK | 매니페스트 선언, 클래스, 디컴파일된 메서드, 참조 | Linux/macOS/Windows x64의 헤드리스 JADX와 전체 JDK; [Android 가이드](docs/android-analysis.md) |
| Android 기기 | 기기, 패키지, 프로세스, 로그, 덤프, 화면 캡처, APK/파일 전송 | 호출자 제공 adb(에뮬레이터 또는 실제 기기); [ADB 가이드](docs/adb-device-analysis.md) |
@@ -263,7 +264,7 @@ npx rea-agents@latest setup
## 스타 기록
-🎉 **GitHub 스타 110,000개, 감사합니다!**
+🎉 **GitHub 스타 170,000개, 감사합니다!**
REA를 사용하고, 버그를 보고하고, 기능을 요청하고, 빌드를 테스트하고, 수정에 기여해 주신 모든 분께 감사드립니다.
diff --git a/README_pl.md b/README_pl.md
index f29d5d2fe..c54af50fe 100644
--- a/README_pl.md
+++ b/README_pl.md
@@ -139,6 +139,7 @@ REA wymaga Node.js 22.x (>=22.19), 24.x (>=24.11) lub 26+ oraz npm. Dodatkowe na
| JavaScript / Electron | Moduły, importy, mapy źródeł, trasy, IPC i powiązania z natywnymi dodatkami | Node.js i npm; [analiza aplikacji](https://rea.tools/pl/guides/javascript/) |
| Strony internetowe | Struktura strony, skrypty, obserwacje sieciowe i zamówione zrzuty ekranu | Przeglądarka z rodziny Chrome; [analiza w przeglądarce](https://rea.tools/pl/guides/browser/) |
| Zapisane przechwycenia ruchu sieciowego | Żądania, odpowiedzi, dostępne dane przesyłane i lokalizacje źródłowe | HAR; mitmdump w systemie Linux dla natywnych przechwyceń mitmproxy; [przewodnik przechwytywania](docs/web-network-captures.md) |
+| Przechwytywanie pakietów | Punkty końcowe, DNS, TLS SNI, dystrybucja protokołów i żądania HTTP | Dostarczone przez wywołującego tshark i capinfos; [przewodnik pcap](docs/pcap-analysis.md) |
| Zestawy .NET | Metadane, instrukcje CIL, zadeklarowane zależności natywne i porównania kompilacji | Analiza statyczna; [przewodnik kodu zarządzanego](docs/managed-code-analysis.md) |
| Pakiety APK dla Androida | Deklaracje manifestu, klasy, zdekompilowane metody i odwołania | JADX bez interfejsu graficznego i pełny JDK w systemach Linux/macOS/Windows x64; [przewodnik Androida](docs/android-analysis.md) |
| Urządzenia z Androidem | Urządzenia, pakiety, procesy, logi, zrzuty, zrzuty ekranu oraz transfery APK/plików | adb dostarczony przez wywołującego (emulator lub urządzenie); [przewodnik ADB](docs/adb-device-analysis.md) |
@@ -261,7 +262,7 @@ Zgłaszaj podatności zgodnie z [SECURITY.md](SECURITY.md).
## Historia gwiazdek
-🎉 **110 000 gwiazdek na GitHubie — dziękujemy!**
+🎉 **170 000 gwiazdek na GitHubie — dziękujemy!**
Dziękujemy wszystkim, którzy używają REA, zgłaszają błędy, proponują nowe funkcje, testują kompilacje i przesyłają poprawki.
diff --git a/README_pt-BR.md b/README_pt-BR.md
index ec18da8ff..dd138f7ff 100644
--- a/README_pt-BR.md
+++ b/README_pt-BR.md
@@ -139,6 +139,7 @@ O REA requer Node.js 22.x (>=22.19), 24.x (>=24.11) ou 26+, além do npm. As fer
| JavaScript / Electron | Módulos, importações, source maps, rotas, IPC e relações com complementos nativos | Node.js e npm; [análise de aplicativos](https://rea.tools/pt-BR/guides/javascript/) |
| Sites | Estrutura da página, scripts, observações de rede e capturas de tela solicitadas | Um navegador da família Chrome; [análise do navegador](https://rea.tools/pt-BR/guides/browser/) |
| Capturas de rede salvas | Requisições, respostas, payloads acessíveis e localizações de origem | HAR; mitmdump no Linux para capturas no formato nativo do mitmproxy; [guia de capturas](docs/web-network-captures.md) |
+| Capturas de pacotes | Endpoints, DNS, TLS SNI, distribuição de protocolos e requisições HTTP | tshark e capinfos fornecidos pelo chamador; [guia pcap](docs/pcap-analysis.md) |
| Assemblies .NET | Metadados, instruções CIL, dependências nativas declaradas e comparações de builds | Inspeção estática; [guia de código gerenciado](docs/managed-code-analysis.md) |
| APKs Android | Declarações do manifesto, classes, métodos descompilados e referências | JADX sem interface gráfica e um JDK completo no Linux/macOS/Windows x64; [guia de Android](docs/android-analysis.md) |
| Dispositivos Android | Dispositivos, pacotes, processos, logs, despejos, capturas de tela e transferências de APK/arquivos | adb fornecido pelo chamador (emulador ou aparelho); [guia de ADB](docs/adb-device-analysis.md) |
@@ -261,7 +262,7 @@ Relate vulnerabilidades conforme [SECURITY.md](SECURITY.md).
## Histórico de estrelas
-🎉 **110.000 estrelas no GitHub — muito obrigado!**
+🎉 **170.000 estrelas no GitHub — muito obrigado!**
Obrigado a todos que usam o REA, relatam bugs, sugerem funcionalidades, testam builds e contribuem com correções.
diff --git a/README_ru.md b/README_ru.md
index 2d75af75e..34e7d3af2 100644
--- a/README_ru.md
+++ b/README_ru.md
@@ -147,6 +147,7 @@ REA требует Node.js 22.x (>=22.19), 24.x (>=24.11) или 26+, а так
| Приложения Flutter | Хеш снапшота Dart, дайджесты библиотек по ABI и происхождение сборки движка | Не требуется (статический разбор APK); [руководство по Flutter](docs/flutter-analysis.md) |
| Прошивки | Области, результаты извлечения и передача в нативный анализ | Binwalk / Unblob в Linux; [руководство по прошивкам](docs/firmware-analysis.md) |
| Записанные пакеты | Выбранные поля, повторяющиеся значения, фильтры и правила декодирования | Linux: TShark 4.x + prlimit; [руководство по захватам](docs/packet-captures.md) |
+| Захват пакетов | Конечные точки, DNS, TLS SNI, распределение протоколов и HTTP-запросы | Предоставленные вызывающей стороной tshark и capinfos; [руководство по pcap](docs/pcap-analysis.md) |
| Записанные логические сигналы | Аннотации декодера, диапазоны отсчётов и диагностика | Linux: sigrok-cli 0.7.2 + prlimit; [руководство по сигналам](docs/signal-recordings.md) |
| Пакеты и ресурсы | Списки файлов, хеши, plist, структура пакетов Apple и извлечённые ресурсы | [Руководство по артефактам и JavaScript](docs/javascript-artifact-reconstruction.md), [приложения Apple](docs/apple-application-analysis.md) |
| Поведение процессов | Вывод терминала, взаимодействия, наблюдения за завершением и файловой системой, сравнения запусков | Linux/macOS с нативным PTY; [захват процессов](docs/process-capture.md) |
@@ -261,7 +262,7 @@ npx rea-agents@latest setup
## История звёзд
-🎉 **110 000 звёзд на GitHub — спасибо!**
+🎉 **170 000 звёзд на GitHub — спасибо!**
Спасибо всем, кто использует REA, сообщает об ошибках, предлагает новые функции, тестирует сборки и помогает с исправлениями.
diff --git a/README_th.md b/README_th.md
index 9e0c6831a..d07bbb6a3 100644
--- a/README_th.md
+++ b/README_th.md
@@ -139,6 +139,7 @@ REA ต้องใช้ Node.js 22.x (>=22.19), 24.x (>=24.11) หรือ 26
| JavaScript / Electron | โมดูล การนำเข้า ซอร์สแมป เส้นทาง IPC และความสัมพันธ์กับส่วนเสริมเนทีฟ | Node.js และ npm; [การวิเคราะห์แอปพลิเคชัน](https://rea.tools/th/guides/javascript/) |
| เว็บไซต์ | โครงสร้างหน้า สคริปต์ ข้อมูลเครือข่ายที่สังเกตได้ และภาพหน้าจอที่ร้องขอ | เบราว์เซอร์ในตระกูล Chrome; [การวิเคราะห์ผ่านเบราว์เซอร์](https://rea.tools/th/guides/browser/) |
| ข้อมูลเครือข่ายที่บันทึกไว้ | คำขอ คำตอบ เพย์โหลดที่ปรากฏ และตำแหน่งต้นทาง | HAR; mitmdump บน Linux สำหรับข้อมูลที่บันทึกในรูปแบบเนทีฟของ mitmproxy; [คู่มือการบันทึกข้อมูล](docs/web-network-captures.md) |
+| การจับแพ็กเก็ต | จุดเชื่อมต่อ, DNS, TLS SNI, การกระจายโปรโตคอล และคำขอ HTTP | tshark และ capinfos ที่ผู้เรียกจัดเตรียม; [คู่มือ pcap](docs/pcap-analysis.md) |
| แอสเซมบลี .NET | เมทาดาทา คำสั่ง CIL การพึ่งพาเนทีฟที่ประกาศไว้ และการเปรียบเทียบผลการบิลด์ | การตรวจสอบแบบสถิต; [คู่มือโค้ดแบบจัดการ](docs/managed-code-analysis.md) |
| APK ของ Android | การประกาศใน manifest คลาส เมธอดที่ดีคอมไพล์ และการอ้างอิง | JADX แบบไม่มี GUI และ JDK แบบเต็มบน Linux/macOS/Windows x64; [คู่มือ Android](docs/android-analysis.md) |
| อุปกรณ์ Android | อุปกรณ์ แพ็กเกจ โพรเซส บันทึก ดัมพ์ ภาพหน้าจอ และการถ่ายโอน APK/ไฟล์ | adb ที่ผู้เรียกจัดเตรียม (โปรแกรมจำลองหรืออุปกรณ์จริง); [คู่มือ ADB](docs/adb-device-analysis.md) |
@@ -261,7 +262,7 @@ npx rea-agents@latest setup
## ประวัติดาว
-🎉 **110,000 ดาวบน GitHub — ขอบคุณทุกคน!**
+🎉 **170,000 ดาวบน GitHub — ขอบคุณทุกคน!**
ขอบคุณทุกคนที่ใช้ REA รายงานบั๊ก เสนอฟีเจอร์ ทดสอบบิลด์ และช่วยแก้ไข
diff --git a/README_tr.md b/README_tr.md
index 3c6e3f3b6..1daaaf9d0 100644
--- a/README_tr.md
+++ b/README_tr.md
@@ -139,6 +139,7 @@ REA; Node.js 22.x (>=22.19), 24.x (>=24.11) veya 26+ ve npm gerektirir. Ek araç
| JavaScript / Electron | Modüller, içe aktarmalar, kaynak haritaları, rotalar, IPC ve yerel eklenti ilişkileri | Node.js ve npm; [uygulama analizi](https://rea.tools/tr/guides/javascript/) |
| Web siteleri | Sayfa yapısı, betikler, ağ gözlemleri ve istenen ekran görüntüleri | Chrome ailesinden bir tarayıcı; [tarayıcı analizi](https://rea.tools/tr/guides/browser/) |
| Kaydedilmiş ağ yakalamaları | İstekler, yanıtlar, erişilebilir yük içerikleri ve kaynak konumları | HAR; mitmproxy'nin kendi biçimindeki yakalamalar için Linux üzerinde mitmdump; [ağ yakalama rehberi](docs/web-network-captures.md) |
+| Paket yakalamaları | Uç noktalar, DNS, TLS SNI, protokol dağılımı ve HTTP istekleri | Çağıranın sağladığı tshark ve capinfos; [pcap rehberi](docs/pcap-analysis.md) |
| .NET derlemeleri | Meta veriler, CIL talimatları, bildirilmiş yerel bağımlılıklar ve derleme karşılaştırmaları | Statik inceleme; [yönetilen kod rehberi](docs/managed-code-analysis.md) |
| Android APK'leri | Manifest bildirimleri, sınıflar, tersine derlenmiş metotlar ve referanslar | Linux/macOS/Windows x64 üzerinde arayüzsüz JADX ve tam bir JDK; [Android rehberi](docs/android-analysis.md) |
| Android cihazları | Cihazlar, paketler, süreçler, günlükler, dökümler, ekran görüntüleri ve APK/dosya aktarımları | Çağıranın sağladığı adb (emülatör veya cihaz); [ADB rehberi](docs/adb-device-analysis.md) |
@@ -261,7 +262,7 @@ Güvenlik açıklarını [SECURITY.md](SECURITY.md) üzerinden bildirin.
## Yıldız geçmişi
-🎉 **GitHub'da 110.000 yıldız — teşekkürler!**
+🎉 **GitHub'da 170.000 yıldız — teşekkürler!**
REA'yı kullanan, hata bildiren, özellik talep eden, derlemeleri test eden ve düzeltmelere katkıda bulunan herkese teşekkürler.
diff --git a/README_uk.md b/README_uk.md
index aea416718..14c3d4984 100644
--- a/README_uk.md
+++ b/README_uk.md
@@ -139,6 +139,7 @@ REA потребує Node.js 22.x (>=22.19), 24.x (>=24.11) або 26+, а та
| JavaScript / Electron | Модулі, імпорти, карти вихідного коду, маршрути, IPC і зв'язки з нативними доповненнями | Node.js і npm; [аналіз застосунків](https://rea.tools/uk/guides/javascript/) |
| Сайти | Структура сторінки, скрипти, мережеві спостереження й запитані знімки екрана | Браузер сімейства Chrome; [аналіз браузера](https://rea.tools/uk/guides/browser/) |
| Збережені мережеві захоплення | Запити, відповіді, доступні корисні дані та місця в джерелі | HAR; mitmdump у Linux для захоплень у власному форматі mitmproxy; [посібник мережевих захоплень](docs/web-network-captures.md) |
+| Захоплення пакетів | Кінцеві точки, DNS, TLS SNI, розподіл протоколів та HTTP-запити | Надані викликаючою стороною tshark та capinfos; [підручник pcap](docs/pcap-analysis.md) |
| Збірки .NET | Метадані, інструкції CIL, оголошені нативні залежності й порівняння збірок | Статична перевірка; [посібник керованого коду](docs/managed-code-analysis.md) |
| Android APK | Оголошення маніфесту, класи, декомпільовані методи й посилання | JADX без графічного інтерфейсу й повний JDK у Linux/macOS/Windows x64; [посібник Android](docs/android-analysis.md) |
| Пристрої Android | Пристрої, пакети, процеси, журнали, дампи, знімки екрана та передавання APK/файлів | adb, наданий викликаючою стороною (емулятор або пристрій); [підручник ADB](docs/adb-device-analysis.md) |
@@ -261,7 +262,7 @@ npx rea-agents@latest setup
## Історія зірок
-🎉 **110 000 зірок на GitHub — дякуємо!**
+🎉 **170 000 зірок на GitHub — дякуємо!**
Дякуємо всім, хто використовує REA, повідомляє про помилки, пропонує нові функції, тестує збірки й допомагає з виправленнями.
diff --git a/README_vi.md b/README_vi.md
index ab3fd493d..86544a535 100644
--- a/README_vi.md
+++ b/README_vi.md
@@ -139,6 +139,7 @@ REA yêu cầu Node.js 22.x (>=22.19), 24.x (>=24.11) hoặc 26+, cùng với np
| JavaScript / Electron | Mô-đun, các khai báo import, source map, tuyến, IPC và quan hệ với tiện ích mở rộng mã máy | Node.js và npm; [phân tích ứng dụng](https://rea.tools/vi/guides/javascript/) |
| Trang web | Cấu trúc trang, script, quan sát mạng và ảnh chụp màn hình được yêu cầu | Trình duyệt thuộc họ Chrome; [phân tích trình duyệt](https://rea.tools/vi/guides/browser/) |
| Bản ghi lưu lượng mạng đã lưu | Yêu cầu, phản hồi, payload có thể truy cập và vị trí nguồn | HAR; mitmdump trên Linux cho bản ghi định dạng gốc của mitmproxy; [hướng dẫn bản ghi mạng](docs/web-network-captures.md) |
+| Bắt gói tin | Điểm cuối, DNS, TLS SNI, phân bố giao thức và yêu cầu HTTP | tshark và capinfos do nơi gọi cung cấp; [hướng dẫn pcap](docs/pcap-analysis.md) |
| Assembly .NET | Siêu dữ liệu, lệnh CIL, các phụ thuộc mã máy được khai báo và so sánh bản dựng | Kiểm tra tĩnh; [hướng dẫn mã được quản lý](docs/managed-code-analysis.md) |
| APK Android | Khai báo manifest, lớp, phương thức được dịch ngược và tham chiếu | JADX không giao diện đồ họa và JDK đầy đủ trên Linux/macOS/Windows x64; [hướng dẫn Android](docs/android-analysis.md) |
| Thiết bị Android | Thiết bị, gói, tiến trình, nhật ký, dump, ảnh chụp màn hình và truyền APK/tệp | adb do nơi gọi cung cấp (trình giả lập hoặc thiết bị); [hướng dẫn ADB](docs/adb-device-analysis.md) |
@@ -261,7 +262,7 @@ Báo cáo lỗ hổng theo [SECURITY.md](SECURITY.md).
## Lịch sử sao
-🎉 **110.000 sao trên GitHub — xin cảm ơn!**
+🎉 **170.000 sao trên GitHub — xin cảm ơn!**
Cảm ơn mọi người đã sử dụng REA, báo lỗi, đề xuất tính năng, kiểm thử bản dựng và đóng góp bản sửa lỗi.
diff --git a/README_zh-TW.md b/README_zh-TW.md
index 81371e91d..62c9ab2f3 100644
--- a/README_zh-TW.md
+++ b/README_zh-TW.md
@@ -139,6 +139,7 @@ REA 需要 Node.js 22.x(>=22.19)、24.x(>=24.11)或 26+,以及 npm。
| JavaScript / Electron | 模組、匯入、source map、路由、IPC 和原生附加元件關係 | Node.js 和 npm;[應用分析](https://rea.tools/zh-TW/guides/javascript/) |
| 網站 | 頁面結構、腳本、網路觀察結果和按請求獲取的螢幕擷取畫面 | Chrome 系瀏覽器;[瀏覽器分析](https://rea.tools/zh-TW/guides/browser/) |
| 已保存的網路擷取 | 請求、回應、可訪問的酬載和來源位置 | HAR;原生 mitmproxy 擷取需要 Linux 上的 mitmdump;[擷取指南](docs/web-network-captures.md) |
+| 封包擷取 | 端點、DNS、TLS SNI、通訊協定分佈和 HTTP 請求 | 呼叫端提供的 tshark 和 capinfos;[pcap 指南](docs/pcap-analysis.md) |
| .NET 程式集 | 中繼資料、CIL 指令、聲明的原生依賴和建置對比 | 靜態檢查;[托管程式碼指南](docs/managed-code-analysis.md) |
| Android APK | 清單聲明、類別、反編譯的方法和引用 | Linux/macOS/Windows x64 上的無界面 JADX 和完整 JDK;[Android 指南](docs/android-analysis.md) |
| Android 裝置 | 裝置、套件、程序、日誌、傾印、螢幕擷取以及 APK/檔案傳輸 | 呼叫端提供的 adb(模擬器或實體裝置);[ADB 指南](docs/adb-device-analysis.md) |
@@ -263,7 +264,7 @@ npx rea-agents@latest setup
## Star 歷史
-🎉 **GitHub Star 達到 110,000 個,感謝大家!**
+🎉 **GitHub Star 達到 170,000 個,感謝大家!**
感謝每一位使用 REA、報告錯誤、提出功能需求、測試建置和貢獻修復的朋友。
diff --git a/README_zh.md b/README_zh.md
index d802cad50..c8d66ce08 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -139,6 +139,7 @@ REA 需要 Node.js 22.x(>=22.19)、24.x(>=24.11)或 26+,以及 npm。
| JavaScript / Electron | 模块、导入、source map、路由、IPC 和原生扩展关系 | Node.js 和 npm;[应用分析](https://rea.tools/zh-CN/guides/javascript/) |
| 网站 | 页面结构、脚本、网络观察结果和按请求获取的截图 | Chrome 系浏览器;[浏览器分析](https://rea.tools/zh-CN/guides/browser/) |
| 已保存的网络捕获 | 请求、响应、可访问的载荷和来源位置 | HAR;原生 mitmproxy 捕获需要 Linux 上的 mitmdump;[捕获指南](docs/web-network-captures.md) |
+| 数据包捕获 | 端点、DNS、TLS SNI、协议分布和 HTTP 请求 | 调用方提供的 tshark 和 capinfos;[pcap 指南](docs/pcap-analysis.md) |
| .NET 程序集 | 元数据、CIL 指令、声明的原生依赖和构建对比 | 静态检查;[托管代码指南](docs/managed-code-analysis.md) |
| Android APK | 清单声明、类、反编译的方法和引用 | Linux/macOS/Windows x64 上的无界面 JADX 和完整 JDK;[Android 指南](docs/android-analysis.md) |
| Android 设备 | 设备、软件包、进程、日志、转储、屏幕截图以及 APK/文件传输 | 调用方提供的 adb(模拟器或实体设备);[ADB 指南](docs/adb-device-analysis.md) |
@@ -263,7 +264,7 @@ npx rea-agents@latest setup
## Star 历史
-🎉 **GitHub Star 达到 110,000 个,感谢大家!**
+🎉 **GitHub Star 达到 170,000 个,感谢大家!**
感谢每一位使用 REA、报告错误、提出功能需求、测试构建和贡献修复的朋友。
diff --git a/docs/installation.md b/docs/installation.md
index b9285a7d4..0a8041898 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -317,8 +317,8 @@ The Hopper launcher action used by REA creates a document from an executable;
its supported command-line interface does not attach to an already-open
document. While another live REA session owns the same target and loader
profile, a second session reports the owning run ID instead of opening a
-duplicate document. Closing the owning REA session releases this guard; Hopper
-keeps its document open. A later REA session can therefore open another
+duplicate document. On macOS, closing the owning REA session releases this guard;
+Hopper keeps its document open. A later REA session can therefore open another
document for the same target. REA does not currently identify, focus, or reuse
that existing GUI document, and the supported launcher exposes no attach or
reuse action for it.
@@ -341,8 +341,14 @@ Hopper application per user across cooperating REA processes. A competing
CLI or MCP session receives the owning session ID before Hopper is launched,
for both the same target and a different target. Switch targets through that
MCP session, or close it before starting another session. Closing the owner
-releases the reservation. This does not attach to or claim ownership of
-manually opened Hopper applications.
+releases the reservation and stops REA's owned demo application and private
+display; the headless Linux demo does not retain documents after MCP shutdown.
+Its helper watches a private lifetime pipe, so an owner crash or SIGKILL also
+stops those children, without relying on a reusable PID or a process-name scan.
+A later session recovers the dead owner's stale lease after child cleanup;
+private runtime files can remain when REA itself was killed. This does not attach to
+or claim ownership of manually opened Hopper applications. An application left
+running by an older REA version must still be closed before starting a new session.
Stale lease recovery is serialized. If an interrupted recovery leaves its
reservation directory, the diagnostic identifies that exact path. Stop REA
@@ -435,8 +441,9 @@ For cursor navigation, string decoding, symbol-name limits, and regex matching,
see [Hopper analysis behavior](native-investigation.md#hopper-analysis-behavior).
Closing or switching a target closes its bound Hopper document, shuts down REA's
-bridge and removes its temporary socket directory while preserving the Hopper
-application and unrelated documents. A `cleanup_incomplete`
+bridge and removes its temporary socket directory. The macOS Hopper application
+and unrelated documents remain open; the owned Linux demo application stops.
+A `cleanup_incomplete`
result identifies resources whose cleanup could not be verified.
REA retains unresolved cleanup ownership and any confirmed shutdown phases.
After addressing the reported failure, retry `close_binary` on the same
diff --git a/docs/javascript-application-workflows.md b/docs/javascript-application-workflows.md
index af0b6ba94..2d2d9e64a 100644
--- a/docs/javascript-application-workflows.md
+++ b/docs/javascript-application-workflows.md
@@ -156,9 +156,12 @@ to the comparison Evidence in a live session.
`compare_source_to_bundle` compares one cryptographically committed
`HistoricalSourceGraph` with authenticated application-graph Evidence. The
stable scoring model reports every admitted signal and weight: exact source
-digest, source-map original path, exact current path, path suffix, basename, and
-language extension. Exact digest wins over location inference; weak basename
-or extension evidence never forces a mapping.
+digest, source-map original path, exact current path, path suffix, Unicode-
+equivalent path, basename, and language extension. Exact digest wins over
+location inference; weak basename, extension, and Unicode-equivalence evidence
+never forces a mapping. Unicode-equivalent spellings are candidate evidence
+only because distinct filesystem paths can preserve those spellings as separate
+files; multiple canonical-equivalent candidates remain unknown.
Each historical source file is classified as `unchanged`, `modified`,
`removed`, `split`, `merged`, `duplicated`, or `unknown`. Multiple equally
diff --git a/docs/mcp-contracts.md b/docs/mcp-contracts.md
index b6990b3c9..c4169dd73 100644
--- a/docs/mcp-contracts.md
+++ b/docs/mcp-contracts.md
@@ -21,6 +21,12 @@ directly to `compare_functions`, and `inspect_artifact` Evidence to
`compare_artifacts`. Use `get_evidence_bundle` when the task needs broader
retained session history or an explicit bundle for transfer.
+Evidence and bundle imports reject unsupported fields in their envelopes,
+identities, manifests and other fixed metadata before authentication. Imports
+leave retained session state unchanged when validation fails. Keep application
+metadata in the supported JSON payloads (`parameters`, `raw_result`,
+`normalized_result`, or analysis-profile parameters), where keys are preserved.
+
Tool execution failures return `isError: true` and the complete canonical
`{ "error": ... }` diagnostic as JSON in text `content`. Read that diagnostic
for the error code, target details, partial observations, and remediation.
diff --git a/docs/pcap-analysis.md b/docs/pcap-analysis.md
new file mode 100644
index 000000000..1df3e5ccd
--- /dev/null
+++ b/docs/pcap-analysis.md
@@ -0,0 +1,118 @@
+# Packet capture summaries
+
+REA summarizes already saved pcap/pcapng files through caller-selected Wireshark
+4.x `tshark` and `capinfos`. Use `inspect_packet_capture` for selected fields,
+filters and decode-as rules; use this family for address, DNS, SNI, protocol-stack
+and URI inventories. It does not acquire traffic or fetch recorded targets.
+
+## Supply tools
+
+```sh
+export REA_TSHARK_COMMAND=/absolute/path/tshark
+export REA_CAPINFOS_COMMAND=/absolute/path/capinfos
+# Linux only; default /usr/bin/prlimit
+export REA_TSHARK_PRLIMIT_COMMAND=/absolute/path/prlimit
+rea inspect-pcap-client
+rea inspect-pcap-capture /captures/session.pcapng --json
+```
+
+Without explicit tool commands, this family resolves them through PATH and
+records that selection source. Client inspection reads no capture file. Capture
+inspection requires Linux with util-linux prlimit or Windows with owned Job
+Objects. macOS capture inspection returns a capability gap because the new
+native memory boundary is unverified; its version probes remain available.
+Tools and installed libraries/plugins are caller-trusted. An empty private
+personal Wireshark configuration is used; this is not an OS sandbox.
+
+## Inspect only the needed facts
+
+MCP `inspect_pcap_capture` accepts `path` and optional `detail: "summary"`.
+Complete delivery remains the default. Summary commits and retains the same
+complete Evidence, returning identity, capture metadata, observed counts,
+retained counts, source coverage and diagnostic lengths without large lists.
+Then use its `normalized_result.parent_evidence_id` with
+`inspect_analysis_view` source kind `retained-evidence`:
+
+```json
+{"kind":"pcap","facet":"endpoints","offset":0,"limit":20}
+{"kind":"pcap","facet":"dns-queries","offset":0,"limit":20}
+{"kind":"pcap","facet":"dns-addresses","query":"example.com","offset":0,"limit":20}
+{"kind":"pcap","facet":"tls-sni","offset":0,"limit":20}
+{"kind":"pcap","facet":"diagnostics","stream":"tshark","offset":0,"limit":4096}
+```
+
+Other row facets are `protocols`, `http-uris` and `unattributed-addresses`.
+Defaults are offset 0 and limit 64. DNS question pages give address counts;
+select one exact retained question to page its addresses. Diagnostic windows
+count UTF-16 code units; other windows count rows. Missing/ambiguous selectors
+fail. Unknown legacy diagnostics remain unknown, not an observed empty stream.
+Portable CLI views use the existing `inspect-analysis-view` workflow with inline
+complete Evidence. Views never reread the source or launch Wireshark and work
+after the original file is deleted. Page exhaustion covers the retained facet;
+it does not establish network completeness or recover missing traffic.
+
+## Interpret provenance and coverage
+
+`target.sha256` binds observations to an admitted stable capture snapshot. Both
+tools read that copy, which is hashed again after analysis. Capture metadata and
+literal field values are producer observations; address/protocol counts and DNS
+associations are derivations. Capture Evidence has historical-reference authority.
+
+Addresses count once per packet, including loopback and nested IP occurrences.
+DNS addresses are associated only with one question in the same response packet;
+additional records may be included, so this does not prove final resolution.
+Ambiguous addresses remain in a separate inventory. Protocol distribution counts
+exact `frame.protocols` stack strings. TLS SNI is recorded handshake metadata,
+not process identity or proof of the destination's authenticity.
+
+All examined inventories are retained within the resource budget; no fixed
+200/100/50-item truncation is applied. HTTP transport credentials are excluded
+without rewriting other URI bytes; ambiguous credential spans cause omission.
+Counts preserve distinct observed source URIs before omission or coalescing.
+`coverage: "partial"` records unresolved DNS attribution or URI item loss;
+component credential exclusion is also counted explicitly. Diagnostics retain
+both tool stderr streams. Recorded fields do not establish decrypted payloads,
+causality, process identity, absence of unrecorded traffic or current deployments.
+
+## Resources and lifecycle
+
+One inspection is admitted at a time per provider. Concurrent calls return a
+capacity error; close drains active work before releasing resources. Captures
+are streamed into a read-only owned snapshot with a 2 GiB disk budget. Native
+capture commands enforce Linux address-space ceilings of at most 1 GiB,
+300 CPU seconds, 64 MiB per file and no core dumps, preserving stricter inherited
+limits. Windows uses a 1 GiB committed-memory limit for each owned tool tree.
+These are not aggregate machine or filesystem quotas.
+
+TShark output is bounded at 8 MiB; its known five-level selected-field shape and
+128 MiB graph-expansion estimate are checked before allocation. Retained facts
+have a separate 16 MiB estimate. Capinfos output is limited to 64 KiB. Command
+wall deadlines are 300 s for dissection, 60 s for metadata and 20 s for probes.
+Native ownership preparation has its own bounded lifecycle.
+
+Malformed/oversized output returns no partial success. Unvalidated partial JSON
+is not returned as facts. Cancellation reaches probes, acquisition, commands and
+projection. Cleanup failure returns a typed error, retains completed Evidence
+when available, and retains owned resources for retry on close.
+
+## Verification scope
+
+Current follow-up verification uses Linux/Node 24.18.0 and Wireshark 4.0.17.
+Private real recorded corpora are checked against independent raw-frame/IP
+parsing and Python aggregation, public CLI/stdio MCP parity, SDK schemas, source
+hashes and retained views. Synthetic native tools separately test malformed
+output, cancellation, source/snapshot mutation, capacity and cleanup; they do
+not establish real Wireshark or other-platform behavior.
+
+The original proposal reported Linux 4.6.6, macOS/Windows 4.6.9 verification on
+its earlier implementation. Those reports do not verify the new final memory
+boundary. Actual Windows/Bun Wireshark execution is unverified here; macOS
+capture support needs a separate enforceable-bound decision.
+
+```sh
+npm run verify:pcap -- --pcap /absolute/saved-capture.pcapng
+```
+
+This verifier exercises built CLI/stdio MCP, schemas, artifact identity and
+cleanup. Without `--pcap`, capture inspection is reported as unverified. Private
+captures, keys and provider runtime files are not committed.
diff --git a/docs/testing.md b/docs/testing.md
index 6f0b80131..a36eff6ec 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -849,6 +849,14 @@ establish passing Android coverage; inspect its execution receipt.
The `termux-browser-diagnostics` artifact retains the Termux command log, exit
status, and Android logcat on success or failure. The emulator is disposable.
+## Packet capture analysis
+
+`npm run verify:pcap -- --pcap PATH` exercises caller-supplied tshark and
+capinfos against a saved capture. Linux verification uses Wireshark 4.6.6
+and captures containing DNS, TLS and HTTP traffic. Native Windows and macOS
+engine behavior remains unverified; process fixtures do not establish it.
+See [Packet capture analysis](pcap-analysis.md) for contracts and budgets.
+
## Apple native metadata and UI
`npm run verify:apple-dispatch` compiles the Objective-C fixture (classes,
diff --git a/experiments/analysis-efficiency/README.md b/experiments/analysis-efficiency/README.md
index b028953ce..5f656a02c 100644
--- a/experiments/analysis-efficiency/README.md
+++ b/experiments/analysis-efficiency/README.md
@@ -15,6 +15,10 @@ Follow-up: [Dart AOT summary and retained string pools](flutter-aot-summary.md)
records real LocalSend delivery pairs and old Evidence continuation, preserving
ABI selection, snapshot identity, original lower bounds and partial coverage.
+Follow-up: [SQLite existing-control measurements](sqlite-existing-controls.md)
+tests QGIS's shipped GeoPackage through the existing column selection, preserving
+full selected-table schema and typed cells before considering another API.
+
Follow-up: [native PE/DOS entry views and real model verification](native-entry-views.md)
records the post-merge native continuation, including a small-function case where
four selected replies cost more bytes than the complete dossier.
diff --git a/experiments/analysis-efficiency/agent-trial.py b/experiments/analysis-efficiency/agent-trial.py
index 682be27ec..6dcc7d7f8 100644
--- a/experiments/analysis-efficiency/agent-trial.py
+++ b/experiments/analysis-efficiency/agent-trial.py
@@ -178,6 +178,7 @@ def main():
'inspect_android_package', 'search_android_classes',
'inspect_android_class', 'inspect_android_method',
'inspect_firmware_regions', 'inspect_managed_artifact',
+ 'inspect_sqlite_database',
'inspect_managed_members', 'inspect_managed_native_boundaries',
'inspect_artifact', 'inspect_wasm_artifact',
'inspect_evm_interface', 'get_evidence_bundle', 'export_evidence_bundle',
diff --git a/experiments/analysis-efficiency/corpus.json b/experiments/analysis-efficiency/corpus.json
index 3b0f5c574..163b3b49a 100644
--- a/experiments/analysis-efficiency/corpus.json
+++ b/experiments/analysis-efficiency/corpus.json
@@ -250,6 +250,19 @@
"transport_bytes": 46558706,
"derivation": "Official arm64 release APK, compared with GitHub release asset digest; byte-only analysis without execution"
}
+ },
+ {
+ "id": "qgis-world-map.gpkg",
+ "file": "qgis-world-map.gpkg",
+ "bytes": 12914688,
+ "sha256": "01d293159d1b77bd9212b5252587853f61aa9e25b2387135f34afaba8d057190",
+ "provenance": {
+ "project": "QGIS bundled world map",
+ "source_commit": "e1223b8e9e71fc50ee995ed556f711c54ccc101b",
+ "git_blob_sha1": "c9ff80228dff0de93c9acdef16a97545ba360244",
+ "url": "https://raw.githubusercontent.com/qgis/QGIS/e1223b8e9e71fc50ee995ed556f711c54ccc101b/resources/data/world_map.gpkg",
+ "derivation": "unmodified official resource file; streaming Git blob and SHA-256 verification"
+ }
}
]
}
diff --git a/experiments/analysis-efficiency/measure.mjs b/experiments/analysis-efficiency/measure.mjs
index 8774ed30b..160973aa7 100644
--- a/experiments/analysis-efficiency/measure.mjs
+++ b/experiments/analysis-efficiency/measure.mjs
@@ -28,6 +28,7 @@ const { values } = parseArgs({
"javascript-question": { type: "string", default: "inventory" },
"managed-question": { type: "string", default: "inventory" },
schemas: { type: "string", default: "default" },
+ "sqlite-selection": { type: "string", default: "all" },
},
});
if (
@@ -43,6 +44,11 @@ if (
) ||
!["inventory", "selected"].includes(values["javascript-question"]) ||
!["default", "selected"].includes(values.schemas) ||
+ !["all", "columns"].includes(values["sqlite-selection"]) ||
+ (values.artifact !== "qgis-world-map.gpkg" &&
+ values["sqlite-selection"] !== "all") ||
+ (values.artifact === "qgis-world-map.gpkg" &&
+ values.delivery !== "complete") ||
!["inventory", "identity"].includes(values["managed-question"]) ||
(!["sharex.dll", "sharex.helpers.dll"].includes(values.artifact) &&
values["managed-question"] !== "inventory") ||
@@ -518,6 +524,54 @@ const inspectEvmTarget = async () => {
};
const workflows = {
+ "qgis-world-map.gpkg": async () => {
+ const columns = ["fid", "NAME", "ISO_A3"];
+ const input = {
+ path: values.path,
+ table: "countries",
+ row_limit: 1,
+ ...(values["sqlite-selection"] === "columns" ? { columns } : {}),
+ };
+ const definition = catalogDefinitions.get("inspect_sqlite_database");
+ if (
+ definition === undefined ||
+ !new Ajv2020({ strict: false, validateFormats: false }).validate(
+ definition.inputSchema,
+ input,
+ )
+ )
+ throw new Error(
+ "Selected SQLite request is not advertised by this runtime",
+ );
+ const inspected = await call("inspect_sqlite_database", input);
+ const report = normalized(inspected);
+ if (report.rows === null || report.rows.table !== "countries")
+ throw new Error("Runtime returned no selected country sample");
+ const indexes = columns.map((column) => {
+ const index = report.rows.columns.indexOf(column);
+ if (index < 0)
+ throw new Error(`Missing requested SQLite column ${column}`);
+ return index;
+ });
+ return {
+ artifact_sha256: targetSha(inspected),
+ artifact: report.artifact,
+ wal: report.wal,
+ engine: report.engine,
+ database_encoding: report.database_encoding,
+ schema: report.schema,
+ rows: {
+ ...report.rows,
+ columns,
+ values: report.rows.values.map((row) =>
+ indexes.map((index) => row[index]),
+ ),
+ },
+ producer_limitations: report.limitations,
+ limitations: inspected.limitations,
+ evidence_ids: [inspected.evidence_id],
+ };
+ },
"obsidian.asar": async () => {
if (values["javascript-question"] === "selected") {
const inspected = await call("analyze_javascript_application", {
@@ -902,6 +956,10 @@ const report = {
)
? values["managed-question"]
: null,
+ sqlite_selection:
+ values.artifact === "qgis-world-map.gpkg"
+ ? values["sqlite-selection"]
+ : null,
provider_settings_sha256: sha(JSON.stringify(selectedProviders)),
provider_search_path_sha256: sha(
selectedProviders.PATH ?? process.env.PATH ?? "",
diff --git a/experiments/analysis-efficiency/process-trace-validation.md b/experiments/analysis-efficiency/process-trace-validation.md
new file mode 100644
index 000000000..a32848596
--- /dev/null
+++ b/experiments/analysis-efficiency/process-trace-validation.md
@@ -0,0 +1,113 @@
+# Process trace validation
+
+A 6,000-event directed cycle previously overflowed the JavaScript stack inside
+the schema refinement. Cycle detection now uses iterative topological traversal.
+Cyclic inputs retain independent declaration diagnostics without expanding all
+event pairs. Unordered declarations retain group membership, with one diagnostic
+per overlapping or conflicting group, instead of allocating a pair set and
+repeating the same error for every pair.
+
+A unique topological order proves that every event pair is ordered, allowing
+rank comparisons without retaining transitive closure. Other acyclic graphs
+retain only one origin's forward and backward reachability sets at a time.
+Complete pair validation preserves the missing count and first declaration-order
+missing pair. General partial orders still require quadratic pair examination
+and repeated graph traversal; they trade CPU time for bounded retained state.
+
+## Initial cycle fix comparison
+
+Flameox ran three randomized paired blocks (seed 917), each limited to 20 seconds
+and 512 MiB. Node 24.18.0 used a 384-MiB old-space limit on macOS arm64. Each
+process validated the same 2,500-event acyclic chain four times, then checked the
+known 6,000-event cycle failure with per-event not-before constraints and one
+unordered group containing every event. All six executions passed the embedded answer
+digest and expected rejection checks.
+
+The baseline source is from `bb540826d`; the candidate is the initial cycle fix
+in `10935b7b1`, which still memoized reachability sets for every queried origin.
+Both modules had TypeScript annotations removed with Node's identical built-in
+transform and used the same copied runtime dependencies. This isolates schema
+validation rather than comparing complete packaged CLI/MCP processes.
+
+| Median measurement | Baseline | Candidate |
+| -------------------------------------------- | -------: | --------: |
+| First validation elapsed milliseconds | 335.80 | 177.25 |
+| Warm validation elapsed milliseconds | 313.36 | 165.23 |
+| First validation CPU milliseconds | 366.85 | 218.39 |
+| Warm validation CPU milliseconds | 335.32 | 194.08 |
+| Whole-process elapsed milliseconds | 1,344.13 | 787.00 |
+| Process CPU milliseconds before final report | 1,457.67 | 941.05 |
+| Peak process-family MiB | 328.36 | 395.52 |
+
+The input is identical: 233,095 JSON bytes, estimated at 77,010 tokens by tokenx
+1.3.0. The valid parsed result digest is
+`28bd99ce83f0da8e45600ef20f114cb52bb26b5f5e6bfc1601ca3e712eaf3147`.
+Actual agent tokens, catalog injection, transport, model reasoning and provider
+costs were not measured. This is a component measurement, not an end-to-end
+investigation speed claim.
+
+First validation excludes module import and fixture preparation; warm runs reuse
+the process but create fresh per-validation graph state. Whole-process elapsed
+includes startup, imports, all four validations, the cyclic-input check, token
+estimation and reporting. CPU includes startup through metrics publication;
+peak RSS covers the complete single-process workload, with no children. Host
+caches were not flushed. Peak memory increased in this cohort. Its retained
+valid-order closure still required quadratic memory, prompting the follow-up.
+Three pairs describe this fixture only.
+
+Preserved Flameox evidence:
+`d6211639446e8b6ec2e82636913eaf471def96673e28f03e9c7f98bec07f8e13`;
+analysis `e663b6bd8f5693975542d5b5e2b18437b3c167a0be939bb7386eb68549936231`.
+An earlier cohort lost modules during another checkout build; its three failed
+executions and timing results are excluded. The successful cohort uses an
+isolated runtime copy. Source-module SHA-256 values are
+`a7729faa2183b0e493b9ac4fc55f6feaee5b2e5294be13d1b29b57a44b899788`
+(baseline) and `725409ce84902125941251037a8a214ccc3c1eec577e484c164c361ca580d693`
+(candidate).
+
+## Bounded retention follow-up
+
+Flameox compared `10935b7b1` with the rank/streaming implementation in three
+randomized paired blocks (seed 624), under the same host, Node, heap, memory and
+20-second execution bounds. Each execution validated the chain above four times,
+then a 1,200-event partial order with 600 unordered two-event layers and all four
+edges between consecutive layers four times, then the same cyclic failure.
+All six executions passed both parsed-answer digests and the cycle diagnostic.
+Runtime dependencies were copied and isolated from concurrent checkout builds.
+
+| Median measurement | Memoized closure | Rank/streaming |
+| ---------------------------------------- | ---------------: | -------------: |
+| Chain first elapsed milliseconds | 166.11 | 11.37 |
+| Chain warm elapsed milliseconds | 154.25 | 5.32 |
+| Chain first CPU milliseconds | 210.13 | 24.38 |
+| Chain warm CPU milliseconds | 184.76 | 16.84 |
+| Partial order first elapsed milliseconds | 49.44 | 116.54 |
+| Partial order warm elapsed milliseconds | 50.67 | 110.29 |
+| Partial order first CPU milliseconds | 72.47 | 137.69 |
+| Partial order warm CPU milliseconds | 70.65 | 121.77 |
+| Capture process elapsed milliseconds | 901.24 | 557.30 |
+| Process CPU milliseconds before report | 1,101.12 | 665.03 |
+| Peak process-family MiB | 391.13 | 127.72 |
+
+First samples exclude module import and fixture preparation. Partial-order first
+samples follow four chain validations, so they are first use of that fixture
+within an already running process. Warm medians pool the three subsequent samples
+from each of three processes. CPU and peak RSS cover the combined workload;
+capture elapsed additionally includes Flameox capture startup and overhead.
+Host caches were not flushed. The partial-order fixture is slower after this
+change; these results establish a retention tradeoff, not universal acceleration.
+
+The partial-order input is 165,590 JSON bytes, estimated at 52,783 tokens by tokenx
+1.3.0; its parsed-answer SHA-256 is
+`41d06e593813e497221c36793bf00d5fece7055081895b5f6c123ba6ad9a8227`.
+Chain bytes, token estimate and answer digest remain unchanged. Actual agent
+tokens, transport, catalog injection, model reasoning and provider costs remain
+unmeasured. Both cohorts are component measurements, not complete investigations.
+
+Preserved evidence:
+`e29086af99afd8e67cbbd92e43d960ea40f73b4d318ea0cbca60f493575462b8`;
+analysis `086133516f2acf031032d357a3ddb1ac611ce4f12556a24065a2becd567c5f7b`.
+The baseline module SHA-256 is
+`725409ce84902125941251037a8a214ccc3c1eec577e484c164c361ca580d693`;
+the candidate module SHA-256 is
+`2109f1096406e9ecac8bbf4f7ae8abb5113404790a9382487285d2831fcddf26`.
diff --git a/experiments/analysis-efficiency/questions/sqlite-qgis.txt b/experiments/analysis-efficiency/questions/sqlite-qgis.txt
new file mode 100644
index 000000000..636c7a685
--- /dev/null
+++ b/experiments/analysis-efficiency/questions/sqlite-qgis.txt
@@ -0,0 +1 @@
+Statically inspect the supplied QGIS world-map GeoPackage at {{artifact_path}} using only the registered REA inspect_sqlite_database tool. Select the ordinary countries table with row_limit 1 and its default selected_table schema scope. Report the complete returned schema exactly as reported, including SQL, every declared column, indexes, views, triggers, completeness and explicit nulls. For the one returned sample, report only fid, NAME and ISO_A3 in that order, preserving the original tagged SQLite cells exactly: decimal integer strings, text values with bytes_hex and encoding, and SQL null. Preserve row_limit, returned_rows, truncated and order; row order is unspecified and this is not a complete country inventory. Preserve original artifact identity, wal including null, engine, database_encoding, both normalized-result producer limitations and outer Evidence limitations exactly including order. Do not return geometry blobs or unrequested sample cells, interpret boundaries/political labels as current facts, or infer missing values. Final JSON fields: artifact_sha256, artifact, wal, engine, database_encoding, schema, rows, producer_limitations, limitations, evidence_ids. Include real response Evidence IDs. Do not use shell or host file tools, network, other agents or execute QGIS. Stop once these facts are supported.
diff --git a/experiments/analysis-efficiency/review-model.py b/experiments/analysis-efficiency/review-model.py
index b8fe16bb3..0d6e1e8d7 100644
--- a/experiments/analysis-efficiency/review-model.py
+++ b/experiments/analysis-efficiency/review-model.py
@@ -69,7 +69,7 @@ def scope_with_verified_counts(value, expected_scope, returned_counts):
def main():
parser = argparse.ArgumentParser()
- parser.add_argument('--domain', choices=['wasm', 'evm', 'android', 'flutter-aot', 'managed', 'managed-nonempty', 'firmware', 'inventory', 'javascript', 'native', 'browser'], required=True)
+ parser.add_argument('--domain', choices=['wasm', 'evm', 'android', 'flutter-aot', 'sqlite', 'managed', 'managed-nonempty', 'firmware', 'inventory', 'javascript', 'native', 'browser'], required=True)
parser.add_argument('--trial', type=Path, required=True)
parser.add_argument('--reference', type=Path)
parser.add_argument('--resource-log', type=Path, required=True)
@@ -133,6 +133,11 @@ def main():
for key, expected in {'artifact_bytes': n['artifact']['bytes'], 'bytecode_sha256': n['bytecode']['sha256'], 'bytecode_bytes': n['bytecode']['bytes'], 'functions': n['functions'], 'evidence_kind': n['evidence_kind'], 'discovery_completeness': n['discovery_completeness'], 'runtime_execution': n['runtime_execution'], 'bytecode_kind': n['bytecode']['kind'], 'hardfork': n['bytecode']['hardfork'], 'deployment_authenticity': n['bytecode']['deployment_authenticity']}.items():
check(key, answer.get(key), expected)
check('evm_original_limitations', answer.get('limitations'), n['limitations'])
+ elif domain == 'sqlite':
+ for key in ['artifact', 'wal', 'engine', 'database_encoding', 'schema', 'rows', 'producer_limitations', 'limitations']:
+ # Missing is not SQL/JSON null; booleans are not numeric counters.
+ check(key, (key in answer, json.dumps(answer.get(key), sort_keys=True)),
+ (True, json.dumps(reference[key], sort_keys=True)))
elif domain == 'flutter-aot':
for key in ['target', 'abi', 'libapp', 'string_pool', 'coverage', 'limitations']:
check(key, answer.get(key), reference[key])
diff --git a/experiments/analysis-efficiency/sqlite-existing-controls.md b/experiments/analysis-efficiency/sqlite-existing-controls.md
new file mode 100644
index 000000000..9bac9f064
--- /dev/null
+++ b/experiments/analysis-efficiency/sqlite-existing-controls.md
@@ -0,0 +1,181 @@
+# SQLite existing-control measurements
+
+Continues [#2016](https://github.com/morluto/rea/issues/2016) after the Flutter
+lane. The measured main runtime is pinned to
+`172407787f1842dedbcd27b5385177595f786ce4`. Its only post-Flutter
+commit repairs Windows transient runtime admission (#2467); this Linux round
+does not establish Windows performance. No production/API change is proposed
+merely because another summary or cache could be added.
+
+Before PR integration, main advanced to
+`bb540826d65316c164d2de8ba4ef10f81a8ad073`. Its five intervening commits cover
+MCP archive contracts/documentation, an advertised-schema inventory test,
+pwntools cleanup identity, concurrent Mach-O slice inspection, and transient
+DMG verification retries. None changes the SQLite selector. Rebase and current
+main verification do not relabel the frozen measurements below.
+
+The committed post-format driver passes a real SDK smoke against the frozen
+runtime. After rebase, a fresh build, real all/selected-column SDK pair and docs
+check pass on the updated main. Selected facts match each other and the frozen
+runtime; artifact bytes remain unchanged. These are integration checks, not
+additional model performance pairs.
+
+## Real application data and question
+
+Use QGIS's bundled `world_map.gpkg`, unmodified from official immutable source
+commit `e1223b8e9e71fc50ee995ed556f711c54ccc101b`. `corpus.json` pins its URL,
+12,914,688-byte size, Git blob `c9ff80228dff0de93c9acdef16a97545ba360244`, and
+SHA-256 `01d293159d1b77bd9212b5252587853f61aa9e25b2387135f34afaba8d057190`.
+Streaming acquisition matches the upstream blob. The upstream resource install
+list includes `data/*`; [its README](https://github.com/qgis/QGIS/blob/e1223b8e9e71fc50ee995ed556f711c54ccc101b/resources/data/README_world_map.md)
+records data provenance. This is shipped application data, not a generated REA
+fixture. QGIS is neither installed nor executed.
+
+The source question asks for the complete returned `countries` table schema
+and one sample's `fid`, `NAME`, `ISO_A3` tagged cells, in that order. It preserves
+database/WAL identity, engine/encoding, exact original SQL and columns, integer
+strings, text bytes, nulls, row limit/count, unspecified order, truncation and
+both producer/outer limitations. It does not require geometry blobs or a full
+country inventory. Neither political labels nor the sampled ordering are
+inferred to be current or globally exhaustive.
+
+SQLite already defaults to compact schema inventory without a table, detailed
+selected-table schema with a table, and exposes exact `columns`. Selecting
+columns avoids constructing unrelated cells without changing the requested
+table schema. Thus compare existing all-visible columns against exact columns
+on the same main runtime, rather than changing an old user's default or adding
+a new delivery mechanism. Inventory scope cannot substitute for the detailed
+schema requested by this question.
+
+## Public SDK observations
+
+Frozen runtime: main `172407787f1842dedbcd27b5385177595f786ce4`, compiled
+dist/bridge file-table SHA-256
+`72a4ac6c6db491c455f3e4a798f8f52ed5850c08831e7cdc9f25c1525a5a1d11`.
+Node 24.18.0, SDK client/server 2.3.1, observed SQLite 3.53.1, WAL null. Driver,
+provider settings/search-path fingerprints, artifact and locked dependencies
+remain equal. Each workflow starts a fresh server and validates the selected
+actual advertised schema. Host page caches are not flushed.
+
+The initial default inventory returns 26 table entries, including explicit
+virtual/shadow classifications, no rows and `not_requested` column details:
+27,185 compact client-result JSON bytes. Selecting `countries` reveals eight
+columns, including a geometry blob. Its one-row full reply is 485,277 bytes.
+The selected request retains every requested declared-schema field and exact
+tagged sample values while omitting unrelated sample cells.
+
+| Trial | Reply bytes | SDK workflow seconds | Payload CPU seconds | Kernel peak bytes |
+| ------------- | ----------: | -------------------: | ------------------: | ----------------: |
+| sdk-all-1 | 485,277 | 11.820 | 12.755 | 562,884,608 |
+| sdk-columns-1 | 18,509 | 14.017 | 13.715 | 557,510,656 |
+| sdk-columns-2 | 18,509 | 15.826 | 14.162 | 548,343,808 |
+| sdk-all-2 | 485,277 | 5.679 | 7.310 | 561,704,960 |
+
+Both pairs make one successful call, pass settings/selected-fact comparison,
+retain complete original schema and all requested typed cells, and preserve
+source bytes. Reply bytes fall about 96.2%. These observations **do not show SDK
+speed or CPU improvement**: selected workflows are slower in both pairs and
+timing varies substantially. No cause is inferred from these data. Payload CPU
+includes runner/catalog work outside the SDK workflow timer. Memory changes
+are small and do not establish a general reduction. Raw replies and the exact
+pre-format driver source are archived privately.
+
+Reproduce with `measure.mjs --artifact qgis-world-map.gpkg` and
+`--sqlite-selection all|columns`, using the same `--runtime-root`, `--revision`,
+artifact path and `--schemas selected`. `--delivery` stays `complete`; this is
+an existing request selection, not a new summary API. Original caller arguments
+and schemas remain in the private receipts. The source question is
+`questions/sqlite-qgis.txt` and the selected factual grader is
+`review-model.py --domain sqlite`.
+
+## Decision and scope
+
+The initial four actual Codex attempts never executed SQLite: the client rejected
+the tool because its private snapshot writes require approval and the isolated
+driver lacked this exact tool's approval override. Every factual grade fails;
+these are failed client attempts, not completed-task performance comparisons.
+All profiles are removed. The existing experiment-only per-tool approval list
+now includes `inspect_sqlite_database`; each corrected trial exposes only that
+exact enabled tool. REA annotations, target authority and global Codex configuration
+are unchanged. The [official configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference)
+documents the per-tool override. Corrected cohorts use fresh output directories
+and retain the original failures separately.
+
+Actual repeated Codex comparisons determine the task token/time benefit before
+crediting smaller replies. An existing selector that answers the question is
+evidence against adding another production mechanism. Keep negative outcomes
+and unavailable coverage, including failure/retry costs and profile cleanup.
+
+Four corrected serial trials use Codex CLI 0.161.0, requested `gpt-5.6-terra`
+high, one enabled tool, identical owned context/discovery capture, and the same
+frozen main runtime. The requested alias is not a verified server-resolved model.
+Equal treatment instructions select the existing all-visible or exact-column
+request; the source question and requested schema/sample facts stay fixed.
+
+| Corrected trial | Input | Cached | Uncached | Output | Seconds | MCP calls | Facts |
+| ------------------------ | -----: | -----: | -------: | -----: | ------: | --------: | ----- |
+| approved-model-all-1 | 88,131 | 52,480 | 35,651 | 3,369 | 84.007 | 2 | pass |
+| approved-model-columns-1 | 37,340 | 20,992 | 16,348 | 3,006 | 87.514 | 1 | pass |
+| approved-model-columns-2 | 56,148 | 36,096 | 20,052 | 3,298 | 97.466 | 2 | pass |
+| approved-model-all-2 | 88,340 | 52,480 | 35,860 | 3,084 | 113.847 | 2 | pass |
+
+Both pairs pass every selected producer fact, exact SQL/schema/null/tagged
+cells, observed response Evidence IDs, target-byte preservation and profile
+cleanup. The grader checks producer observations, not independent geometry
+semantics. Actual events contain only the chosen MCP tool and agent messages;
+no shell or other agent execution appears. Usage is the final aggregate actually
+reported by the CLI, one usage record per trial; cached input remains included
+in total input. Output includes 853 / 357 / 523 / 664 reasoning tokens.
+
+Total input falls **57.63% / 36.44%**, uncached input **54.14% / 44.08%**.
+Time is mixed: columns are **4.17% slower** in pair 1 and **14.39% faster** in
+pair 2. Output is 10.77% lower / 6.94% higher. Repeated calls remain counted;
+pair 1 has two all-column calls versus one selected call, while pair 2 has two
+calls on both sides. This supports scoped token savings from using the existing
+selector, not a dependable speedup or a new API requirement. Client context and
+usage are observed separately from raw SDK reply bytes.
+
+Model payload CPU seconds / kernel peaks are 7.596 / 763,838,464;
+7.772 / 761,143,296; 8.409 / 762,597,376; and 11.759 / 774,025,216. CPU is mixed
+and memory differences are small. Payload cleanup/limit observations pass;
+missing terminal counters keep every strict whole-resource grade false.
+
+The original blocked attempts remain separate and never provide comparison
+denominators. They each have one failed call, no SQLite result and failed facts:
+
+| Blocked trial | Input | Cached | Uncached | Output | Seconds |
+| --------------- | -----: | -----: | -------: | -----: | ------: |
+| model-all-1 | 35,290 | 29,952 | 5,338 | 798 | 59.881 |
+| model-columns-1 | 35,356 | 22,016 | 13,340 | 670 | 44.764 |
+| model-columns-2 | 35,034 | 20,992 | 14,042 | 639 | 30.007 |
+| model-all-2 | 35,104 | 20,992 | 14,112 | 673 | 25.132 |
+
+**Decision: no production/API change.** Existing column selection materially
+reduces unnecessary delivery and actual model input while retaining the complete
+requested schema and exact cells. Existing documentation already recommends
+table/column selection. No additional summary, schema-scope default change,
+automatic field omission, plugin layer or cross-session cache is justified by
+these results. Preserve the negative/mixed time, output and CPU findings.
+
+Real one-shot CLI inventory, all-column sample and exact-column sample match
+the corresponding full MCP normalized results, subjects, parameters and IDs;
+the source digest remains unchanged. An independent Python binding using SQLite
+3.40.1 opens this immutable artifact read-only and agrees with the exact stored
+table SQL, eight declared columns and selected tagged sample cells. This is a
+second engine/binding observation of this file, not a general row-order or
+geometry-semantics guarantee. The six existing context/driver regression tests
+pass; Python compilation and JavaScript syntax checks pass. No new product test
+or production implementation is added for this measurement-only finding.
+
+Manual review tightens the SQLite grader to distinguish missing fields from
+explicit null and preserve JSON scalar types. Regrading all four stored model
+answers still passes every selected fact; deliberate omission of `wal` and a
+boolean substituted for numeric `row_limit` both fail. Original transcripts,
+usage and previous review receipts stay intact; no model trial is rerun.
+
+Heavy tasks remain serial under one CPU, unchanged 3 GiB early stop / 4 GiB hard
+memory, no swap, owned task scopes and host guards. SDK payload observations
+verify cleanup and zero phase limit events; final whole-scope counters remain
+unknown. This does not establish live/WAL atomicity, all SQLite applications,
+other runtimes/platforms or geospatial geometry semantics. Other packet/signal
+and capture lanes remain incremental follow-ups using their existing controls.
diff --git a/experiments/analysis-efficiency/windows-empty-profile.md b/experiments/analysis-efficiency/windows-empty-profile.md
new file mode 100644
index 000000000..f8e5558e0
--- /dev/null
+++ b/experiments/analysis-efficiency/windows-empty-profile.md
@@ -0,0 +1,69 @@
+# Windows empty-profile startup verification
+
+Follow-up to [#2345](https://github.com/morluto/rea/pull/2345), including
+@gefrezim's diagnosis of the import-time Windows home lookup.
+
+## Source and boundary
+
+Baseline: main `172407787f1842dedbcd27b5385177595f786ce4`. Verification used
+the real Windows 11 10.0.22631.0 host, official Windows x64 Node 24.18.0,
+locked production dependencies and REA's compiled public CLI / SDK 2.3.1 MCP
+server. No IDA or Ghidra engine was used. Runtime copies and compact receipts
+live outside the checkout; no account profile path or ambient environment is
+recorded here.
+
+The tested dispatcher SHA-256 is
+`526105418604cc6e5a202a6275b700814e27450bfaffd45e7510530ba669de8d`.
+Only the dispatcher changed in the deployed runtime. It treats an empty Windows
+`USERPROFILE` as unset before dependency imports. Nonempty selections continue
+to reach the existing home resolver; no additional lookup or fallback owner is
+introduced.
+
+## Real Windows observations
+
+With `HOME` empty in each case, the baseline produced:
+
+| USERPROFILE selection | `--version` | `--help` | MCP discovery |
+| --------------------------- | ----------------------- | ----------------------- | ------------- |
+| Unset | Exit 0 | Exit 0 | Healthy |
+| Empty | Exit 1, `uv_os_homedir` | Exit 1, `uv_os_homedir` | Healthy |
+| Nonempty test-owned profile | Exit 0 | Exit 0 | Healthy |
+
+The corrected CLI passed all six invocations with no stderr. Version output
+remained 6 bytes and help output 15,497 bytes. Real setup dry runs with empty
+and nonempty profile selections both exited 0, planned their configuration
+under the expected home, preserved existing configuration bytes and created no
+configuration under the working directory. No installation was performed.
+
+MCP was already healthy in the baseline; this change does not claim to repair
+an MCP startup failure. Complete baseline discovery was 187 tools and 2,545,790
+serialized bytes, SHA-256
+`1e6bbca7f62852134eb703ea098f5a302d1fe333b8433475429f6fc1b1aba18f`.
+All three corrected MCP controls also passed with no stderr and the same
+catalogue bytes and digest.
+
+The existing `homeDirectoryFallback` acceptance test exercises the import-time
+failure through the public setup dry run. Adding it to the Windows curated lane
+makes that regression execute on the affected platform. No duplicate startup
+test was retained. Nine related tests passed, including the existing MCP doctor
+and curated-lane path checks; Linux passing alone does not prove Windows behavior.
+Review caught a missing package-scope registration for the newly listed test;
+the original CI shard failed that ownership invariant. The path is now also
+registered in `scripts/ci/scopes.mjs`, and all 84 scope checks plus the two
+curated-path checks pass. Runtime source and its tested digest are unchanged.
+
+## Efficiency and resource limits
+
+Heavy host probes ran serially at BelowNormal priority, with one CPU and a
+512 MiB CLI/server heap setting (256 MiB for the probe parent). Heap settings do
+not bound total process memory. An exit-time `process.resourceUsage()` observer
+recorded individual corrected CLI invocations: CPU time ranged from 7.968 to
+9.874 seconds and peak working set from 299,956 to 301,852 KiB. These figures
+exclude the probe parent and any observer overhead outside the CLI process.
+The six observed wall times ranged from 8.656 to 10.961 seconds.
+
+The baseline did not use that resource observer, and cold/warm caches were not
+normalized. These observations establish functional behavior and bounded probe
+scope; no CPU, memory or latency improvement is claimed. The fix adds one
+constant-time environment check, no filesystem lookup, engine call, retry or
+cache. Output bytes are not model tokens; actual model usage was not measured.
diff --git a/install.sh b/install.sh
index 46260fe71..c18726611 100755
--- a/install.sh
+++ b/install.sh
@@ -167,7 +167,7 @@ main() {
[ "$installed_version" = "$version" ] || fail "installed version $installed_version does not match $version. Reinstall the requested version, then retry."
printf 'REA %s is installed.\n' "$version"
- if [ "$start_setup" = true ] && [ -r /dev/tty ] && [ -w /dev/tty ] && [ -t 1 ]; then
+ if [ "$start_setup" = true ] && [ -r /dev/tty ] && [ -w /dev/tty ] && [ -t 1 ] && [ -t 2 ]; then
printf 'Starting REA setup...\n'
"$install_bin" setup /dev/tty
else
diff --git a/package.json b/package.json
index bc5c0edc9..6fdb0d9de 100644
--- a/package.json
+++ b/package.json
@@ -167,6 +167,7 @@
"verify:legacy-simulator": "npm run build:cached && node scripts/verify/apple/legacy-simulator.mjs",
"verify:architecture-guards": "node scripts/verify/architecture-guards.mjs",
"verify:apktool": "npm run build:cached && node scripts/verify-apktool.mjs",
+ "verify:pcap": "npm run build:cached && node scripts/verify-pcap.mjs",
"verify:flutter": "npm run build:cached && node scripts/verify-flutter.mjs",
"verify:adb": "npm run build:cached && node scripts/verify-adb.mjs",
"verify:ghidra": "npm run build:cached && node scripts/verify-real-ghidra.mjs",
diff --git a/scripts/ci/scopes.mjs b/scripts/ci/scopes.mjs
index 19e3a035b..a29748949 100644
--- a/scripts/ci/scopes.mjs
+++ b/scripts/ci/scopes.mjs
@@ -61,6 +61,7 @@ export const SCOPES = {
"tests/boundary/providers/native/artifactProvider.extractionCompleteness.test.ts",
"tests/boundary/filesystem/setupUnavailableProvider.test.ts",
"tests/boundary/filesystem/windowsNpxRegistration.test.ts",
+ "tests/acceptance/setup/homeDirectoryFallback.test.ts",
"tests/boundary/filesystem/webScriptManifestPaths.test.ts",
"tests/boundary/process/ProcessEvidence.host.test.ts",
"tests/acceptance/webModuleCli.test.ts",
diff --git a/scripts/hopper-demo-x11.py b/scripts/hopper-demo-x11.py
index 470c9fd28..da2fe884f 100644
--- a/scripts/hopper-demo-x11.py
+++ b/scripts/hopper-demo-x11.py
@@ -10,6 +10,7 @@ import json
import os
from pathlib import Path
import secrets
+import select
import stat
import subprocess
import tempfile
@@ -118,6 +119,7 @@ class XWindowAttributes(ctypes.Structure):
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser()
parser.add_argument("--probe", action="store_true")
+ parser.add_argument("--owner-stdin", action="store_true")
parser.add_argument("--hopper")
parser.add_argument("--socket")
parser.add_argument(
@@ -133,6 +135,43 @@ def parse_args() -> argparse.Namespace:
return parser.parse_args()
+class OwnerLifetime:
+ """The launcher's private pipe is a lifetime capability, independent of PIDs."""
+
+ def __init__(self, enabled: bool) -> None:
+ self._poll = select.poll() if enabled else None
+ if self._poll is not None:
+ # Node/libuv can implement piped stdio with a Unix socket pair.
+ mode = os.fstat(0).st_mode
+ if not (stat.S_ISFIFO(mode) or stat.S_ISSOCK(mode)):
+ raise AdapterFailure(
+ INVALID_LAUNCH_COMMAND,
+ "invalid_launch_command",
+ "owner lifetime requires a private stdin pipe",
+ )
+ self._poll.register(0, select.POLLIN | select.POLLHUP | select.POLLERR)
+
+ def alive(self) -> bool:
+ if self._poll is None:
+ return True
+ for _, events in self._poll.poll(0):
+ if events & (select.POLLHUP | select.POLLERR | select.POLLNVAL):
+ return False
+ if events & select.POLLIN and not os.read(0, 4096):
+ return False
+ return True
+
+
+def wait_for_hopper(child: subprocess.Popen[bytes], owner: OwnerLifetime) -> int:
+ while owner.alive():
+ try:
+ return child.wait(timeout=0.1)
+ except subprocess.TimeoutExpired:
+ continue
+ # run_launch's finally owns cleanup of both direct, unreaped children.
+ return 0
+
+
def digest(path: Path) -> str:
value = hashlib.sha256()
with path.open("rb") as file:
@@ -572,6 +611,7 @@ def start_xvfb(
"-auth",
str(authority),
],
+ stdin=subprocess.DEVNULL,
stdout=subprocess.DEVNULL,
stderr=subprocess.PIPE,
)
@@ -627,6 +667,9 @@ def run_launch(args: argparse.Namespace) -> int:
"invalid_launch_command",
"missing Hopper launch coordinates",
)
+ owner = OwnerLifetime(args.owner_stdin)
+ if not owner.alive():
+ return 0
hopper = Path(args.hopper)
socket = Path(args.socket)
try:
@@ -654,6 +697,8 @@ def run_launch(args: argparse.Namespace) -> int:
child: subprocess.Popen[bytes] | None = None
display: int | None = None
try:
+ if not owner.alive():
+ return 0
hopper_environment = dict(os.environ)
for name in ("WAYLAND_DISPLAY", "WAYLAND_SOCKET"):
hopper_environment.pop(name, None)
@@ -666,7 +711,10 @@ def run_launch(args: argparse.Namespace) -> int:
"XDG_SESSION_TYPE": "x11",
}
)
- child = subprocess.Popen(command, env=hopper_environment)
+ # Children must not consume or retain REA's lifetime pipe.
+ child = subprocess.Popen(
+ command, env=hopper_environment, stdin=subprocess.DEVNULL
+ )
leader = os.getpid()
os.environ["XAUTHORITY"] = str(authority)
@@ -702,10 +750,12 @@ def run_launch(args: argparse.Namespace) -> int:
observed: list[tuple[int, int, int, int, int]] = []
dialog: tuple[int, int, int, int, int] | None = None
while time.monotonic() < deadline:
+ if not owner.alive():
+ return 0
if socket.exists():
x11.XCloseDisplay(display)
display = None
- return child.wait()
+ return wait_for_hopper(child, owner)
if not hopper_is_owned(leader, hopper):
if child.poll() is None:
time.sleep(0.1)
@@ -749,7 +799,7 @@ def run_launch(args: argparse.Namespace) -> int:
x11.XFlush(display)
x11.XCloseDisplay(display)
display = None
- return child.wait()
+ return wait_for_hopper(child, owner)
except AdapterFailure as error:
raise error.with_stderr(capture)
finally:
diff --git a/scripts/lib/catalog-builders.mjs b/scripts/lib/catalog-builders.mjs
index f97f5ed5c..32ec51ee3 100644
--- a/scripts/lib/catalog-builders.mjs
+++ b/scripts/lib/catalog-builders.mjs
@@ -52,6 +52,11 @@ export const toolFamilyCatalog = (sources) => {
surface: "android-provider",
contracts: sources.androidContracts.ANDROID_TOOL_CONTRACTS,
},
+ {
+ id: "pcap",
+ surface: "pcap-provider",
+ contracts: sources.pcapContracts.PCAP_TOOL_CONTRACTS,
+ },
{
id: "flutter",
surface: "flutter-provider",
@@ -251,6 +256,10 @@ export const providerCatalog = (sources) => {
identity: sources.androidProvider.JADX_PROVIDER_IDENTITY,
contracts: sources.androidContracts.ANDROID_TOOL_CONTRACTS,
},
+ {
+ identity: sources.pcapProvider.PCAP_PROVIDER_IDENTITY,
+ contracts: sources.pcapContracts.PCAP_TOOL_CONTRACTS,
+ },
{
identity: sources.flutterProvider.FLUTTER_PROVIDER_IDENTITY,
contracts: sources.flutterContracts.FLUTTER_TOOL_CONTRACTS,
diff --git a/scripts/lib/catalog-core.mjs b/scripts/lib/catalog-core.mjs
index 5a3b0e909..f5488a9e6 100644
--- a/scripts/lib/catalog-core.mjs
+++ b/scripts/lib/catalog-core.mjs
@@ -68,8 +68,8 @@ const SOURCE_PATHS = {
flutterProvider: "dist/flutter/FlutterBuildProvider.js",
androidProvider: "dist/android/JadxRelease.js",
apktoolContracts: "dist/contracts/apktool/apktoolToolContracts.js",
- flutterContracts: "dist/contracts/flutter/flutterToolContracts.js",
- flutterProvider: "dist/flutter/FlutterBuildProvider.js",
+ pcapContracts: "dist/contracts/pcap/pcapToolContracts.js",
+ pcapProvider: "dist/pcap/PcapProvider.js",
apktoolProvider: "dist/apktool/ApktoolProvider.js",
jebContracts: "dist/contracts/jeb/jebToolContracts.js",
jebProvider: "dist/jeb/JebProvider.js",
diff --git a/scripts/lib/real-hopper-owner-exit.mjs b/scripts/lib/real-hopper-owner-exit.mjs
new file mode 100644
index 000000000..300b35ada
--- /dev/null
+++ b/scripts/lib/real-hopper-owner-exit.mjs
@@ -0,0 +1,130 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
+import { promisify } from "node:util";
+
+import { Client } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+
+import { verifyNoTokenOwnedProcesses } from "../../dist/process/ProcessOwnership.js";
+import {
+ observeProcessStartIdentity,
+ signalProcessWithStartIdentity,
+} from "../../dist/process/ProcessOwnershipObservation.js";
+import { startUnrelatedHopperSentinel } from "./unrelated-hopper-sentinel.mjs";
+import {
+ requireMcpEvidenceResult,
+ requireMcpLifecycleResult,
+} from "./mcp-verifier-results.mjs";
+
+const execFileAsync = promisify(execFile);
+
+/** Prove actual MCP owner exit releases the demo singleton for subsequent CLI/MCP sessions. */
+export async function verifyLinuxHopperOwnerExit({
+ primary,
+ secondary,
+ serverCommand,
+ serverArgs,
+ environment,
+}) {
+ const sentinel = await startUnrelatedHopperSentinel();
+ const outcomes = [];
+ try {
+ for (const mode of ["graceful", "SIGKILL"]) {
+ const transport = new StdioClientTransport({
+ command: serverCommand,
+ args: serverArgs,
+ env: environment,
+ stderr: "pipe",
+ });
+ // Drain launcher diagnostics even on the deliberately interrupted owner.
+ transport.stderr?.resume();
+ const client = new Client({ name: "hopper-owner-exit", version: "1" });
+ const options = { timeout: 180_000 };
+ try {
+ await client.connect(transport);
+ const ownerPid = transport.pid;
+ assert.ok(ownerPid !== null);
+ const owner = await observeProcessStartIdentity(ownerPid);
+ assert.equal(owner?.state, "readable");
+ requireMcpLifecycleResult(
+ await client.callTool(
+ {
+ name: "open_binary",
+ arguments: { path: primary },
+ },
+ options,
+ ),
+ "open_binary",
+ );
+ const procedures = requireMcpEvidenceResult(
+ await client.callTool(
+ { name: "list_procedures", arguments: {} },
+ options,
+ ),
+ "list_procedures",
+ );
+ assert.ok(procedures.length > 0);
+ const status = requireMcpLifecycleResult(
+ await client.callTool(
+ { name: "binary_session", arguments: {} },
+ options,
+ ),
+ "binary_session",
+ );
+ const runId = status.analysis_run?.run_id;
+ assert.equal(typeof runId, "string");
+ assert.equal(status.analysis_provider_binding?.provider.id, "hopper");
+ assert.equal((await verifyNoTokenOwnedProcesses(runId)).cleaned, false);
+ if (mode === "graceful") await client.close();
+ else {
+ assert.equal(
+ await signalProcessWithStartIdentity(
+ ownerPid,
+ owner.identity,
+ "SIGKILL",
+ ),
+ "signaled",
+ );
+ }
+ const deadline = Date.now() + 10_000;
+ let cleanup;
+ do {
+ cleanup = await verifyNoTokenOwnedProcesses(runId);
+ if (cleanup.cleaned) break;
+ await delay(100);
+ } while (Date.now() < deadline);
+ assert.equal(cleanup.cleaned, true, cleanup.reason);
+ // The SIGKILL case must recover the stale lease for both target identities.
+ for (const target of [primary, secondary]) {
+ const result = await execFileAsync(
+ process.execPath,
+ [
+ "scripts/rea.mjs",
+ "inspect",
+ target,
+ "--provider",
+ "hopper",
+ "--format",
+ "json",
+ ],
+ { env: environment, timeout: 180_000, maxBuffer: 16 * 1024 * 1024 },
+ );
+ assert.ok(JSON.parse(result.stdout).normalized_result);
+ }
+ outcomes.push({
+ mode,
+ ownedProcessesStopped: true,
+ sameTargetReopened: true,
+ differentTargetReopened: true,
+ });
+ } finally {
+ await client.close();
+ await transport.close();
+ }
+ }
+ } finally {
+ assert.equal(await sentinel.verifyAndClose(), true);
+ }
+ return { outcomes, unrelatedHopperSurvived: true };
+}
diff --git a/scripts/rea.mjs b/scripts/rea.mjs
index 78ffbdd21..75ee552c5 100755
--- a/scripts/rea.mjs
+++ b/scripts/rea.mjs
@@ -16,6 +16,12 @@ const isMcpMode =
const isMcpDoctorMode = args[0] === "mcp" && args[1] === "doctor";
const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+// Windows home lookup throws for an empty USERPROFILE. Dependencies resolve
+// home during import, before REA's own resolver can apply its account fallback.
+if (process.platform === "win32" && process.env.USERPROFILE === "") {
+ delete process.env.USERPROFILE;
+}
+
// Playwright's registry assumes one of its three desktop host platforms when
// it chooses the browser cache directory. Termux reports `android`, although
// its Node runtime and filesystem are POSIX-compatible. Keep the cache path
diff --git a/scripts/verify-packet-capture.mjs b/scripts/verify-packet-capture.mjs
index 371c72367..2b959e602 100644
--- a/scripts/verify-packet-capture.mjs
+++ b/scripts/verify-packet-capture.mjs
@@ -236,6 +236,52 @@ try {
const hci = await inspect({ path: bluetooth, fields: ["bthci_cmd.opcode"] });
assert.deepEqual(hci.packets[0]["bthci_cmd.opcode"], ["0x0c03"]);
assert.deepEqual(await readFile(path), source);
+ // Exercise the incremental summary workflow against the same owned bytes
+ // using real installed Wireshark tools; these inputs are format fixtures.
+ const pcapTool = (await client.listTools()).tools.find(
+ (t) => t.name === "inspect_pcap_capture",
+ );
+ assert.ok(pcapTool?.outputSchema);
+ const pcapAjv = new Ajv2020({ strict: false, validateFormats: false });
+ assert.ok(pcapAjv.validateSchema(pcapTool.inputSchema));
+ assert.ok(pcapAjv.validateSchema(pcapTool.outputSchema));
+ for (const capturePath of [path, bluetooth]) {
+ const response = await client.callTool({
+ name: pcapTool.name,
+ arguments: { path: capturePath, detail: "summary" },
+ });
+ assert.notEqual(response.isError, true, JSON.stringify(response));
+ assert.ok(
+ pcapAjv.validate(pcapTool.outputSchema, response.structuredContent),
+ pcapAjv.errorsText(),
+ );
+ const summary = parseEvidence(response.structuredContent).normalized_result;
+ assert.equal(
+ summary.summary.target.sha256,
+ createHash("sha256")
+ .update(await readFile(capturePath))
+ .digest("hex"),
+ );
+ const source = {
+ kind: "retained-evidence",
+ evidence_id: summary.parent_evidence_id,
+ };
+ const page = await client.callTool({
+ name: "inspect_analysis_view",
+ arguments: {
+ source,
+ view: { kind: "pcap", facet: "protocols", limit: 10 },
+ },
+ });
+ assert.notEqual(page.isError, true, JSON.stringify(page));
+ assert.equal(
+ parseEvidence(page.structuredContent).normalized_result
+ .parent_evidence_id,
+ source.evidence_id,
+ );
+ cases++;
+ }
+
assert.deepEqual(await readFile(bluetooth), bluetoothSource);
for (const input of [
{ path, fields: ["frame.number"], display_filter: "this is not a filter" },
diff --git a/scripts/verify-pcap.mjs b/scripts/verify-pcap.mjs
new file mode 100644
index 000000000..3adf14531
--- /dev/null
+++ b/scripts/verify-pcap.mjs
@@ -0,0 +1,131 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtemp, readdir, rmdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { Client } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { toolContract } from "../dist/contracts/toolContracts.js";
+import { hashStableFile } from "../dist/filesystem/StableFileHash.js";
+import { mcpTextValue } from "./lib/mcp-verifier-results.mjs";
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+ console.log(
+ "Usage: npm run verify:pcap -- [--pcap PATH]\nRequires caller-supplied tshark/capinfos. Without --pcap, only client readiness is verified.",
+ );
+ process.exit(0);
+}
+if (!(args.length === 0 || (args.length === 2 && args[0] === "--pcap")))
+ throw new Error("Expected --pcap PATH");
+const path = args[1] === undefined ? null : resolve(args[1]);
+// This parent is shared by independent CLI/MCP owners. A leased Windows
+// runtime root would prevent their native admission of its directory handle.
+const root = await mkdtemp(join(tmpdir(), "rea-pcap-verifier-"));
+const environment = Object.fromEntries(
+ Object.entries(process.env).filter(([, value]) => typeof value === "string"),
+);
+Object.assign(environment, {
+ TMPDIR: root,
+ TMP: root,
+ TEMP: root,
+});
+const entrypoint = resolve("scripts/rea.mjs");
+const execute = promisify(execFile);
+const client = new Client({ name: "pcap-real-verifier", version: "1" });
+const transport = new StdioClientTransport({
+ command: process.execPath,
+ args: [entrypoint, "mcp"],
+ env: environment,
+ stderr: "pipe",
+});
+transport.stderr?.resume();
+try {
+ await client.connect(transport);
+ const readiness = await run("inspect_pcap_client", {});
+ assert(readiness.client.tshark_version && readiness.client.capinfos_version);
+ if (path === null)
+ console.log("[unverified] Capture inspection: no --pcap was supplied");
+ else {
+ const identity = await hashStableFile(path);
+ const result = await run("inspect_pcap_capture", { path });
+ assert.deepEqual(result.target, { path, ...identity });
+ assert(result.packet_count >= 0);
+ assert(
+ result.endpoints.every(
+ (entry) => entry.packet_count <= result.packet_count,
+ ),
+ );
+ assert(
+ result.protocol_distribution.every(
+ (entry) => entry.packet_count <= result.packet_count,
+ ),
+ );
+ const partial =
+ result.endpoint_count > result.endpoints.length ||
+ result.dns_query_count > result.dns_queries.length ||
+ result.tls_sni_count > result.tls_sni_values.length ||
+ result.protocol_count > result.protocol_distribution.length ||
+ result.http_request_uri_count > result.http_request_uris.length ||
+ result.unattributed_dns_packet_count > 0 ||
+ result.dns_queries.some(
+ (entry) =>
+ entry.response_address_count > entry.response_addresses.length,
+ );
+ assert.equal(result.coverage, partial ? "partial" : "complete");
+ assert.deepEqual(
+ await hashStableFile(path),
+ identity,
+ "Input capture must remain unchanged",
+ );
+ console.log(
+ `[ok] ${result.packet_count} packets; ${result.endpoint_count} addresses; coverage=${result.coverage}`,
+ );
+ }
+} finally {
+ try {
+ await client.close();
+ } finally {
+ await transport.close();
+ }
+ assert.deepEqual(
+ await readdir(root),
+ [],
+ `Owned capture resources remain under ${root}`,
+ );
+ await rmdir(root);
+}
+console.log("All asserted pcap CLI/MCP checks passed");
+
+async function run(name, input) {
+ const contract = toolContract(name);
+ const { stdout } = await execute(
+ process.execPath,
+ [
+ entrypoint,
+ name.replaceAll("_", "-"),
+ ...(input.path === undefined ? [] : [input.path]),
+ "--json",
+ ],
+ { env: environment, timeout: 360_000, maxBuffer: 8 * 1024 * 1024 },
+ );
+ const cli = contract.outputSchema.parse(JSON.parse(stdout));
+ const response = await client.callTool(
+ { name, arguments: input },
+ { timeout: 360_000 },
+ );
+ assert.notEqual(response.isError, true, mcpTextValue(response));
+ const mcp = contract.outputSchema.parse(JSON.parse(mcpTextValue(response)));
+ assert.deepEqual(mcp.normalized_result, cli.normalized_result);
+ assert.deepEqual(mcp.subject, cli.subject);
+ if (input.path !== undefined) {
+ assert.equal(cli.subject.local_path, input.path);
+ assert.equal(
+ cli.subject.digest.sha256,
+ cli.normalized_result.target.sha256,
+ );
+ }
+ console.log(`[ok] ${name}: named output schema and CLI/MCP Evidence parity`);
+ return cli.normalized_result;
+}
diff --git a/scripts/verify-real-hopper.mjs b/scripts/verify-real-hopper.mjs
index 12400cb94..8cad9a256 100644
--- a/scripts/verify-real-hopper.mjs
+++ b/scripts/verify-real-hopper.mjs
@@ -47,6 +47,7 @@ import {
} from "./lib/real-hopper-boundaries.mjs";
import { startUnrelatedHopperSentinel } from "./lib/unrelated-hopper-sentinel.mjs";
import { snapshotHopperRuntime } from "./lib/real-hopper-cleanup.mjs";
+import { verifyLinuxHopperOwnerExit } from "./lib/real-hopper-owner-exit.mjs";
const execFileAsync = promisify(execFile);
const verifierRun = createVerifierRun();
const timeout = 180_000;
@@ -577,6 +578,14 @@ if (sessionsAfter.length > 0) {
}
if (summary === undefined)
throw new Error("Real-Hopper verification did not produce a summary");
+if (process.platform === "linux")
+ summary.ownerExit = await verifyLinuxHopperOwnerExit({
+ primary: targetA,
+ secondary: targetB,
+ serverCommand,
+ serverArgs,
+ environment: serverEnvironment,
+ });
const completedVerifierRun = await completeVerifierRun(verifierRun);
if (
completedVerifierRun.process_lineage.status !== "verified" ||
diff --git a/src/apktool/ApktoolProvider.test.ts b/src/apktool/ApktoolProvider.test.ts
index 5b2a32114..b6ee249e5 100644
--- a/src/apktool/ApktoolProvider.test.ts
+++ b/src/apktool/ApktoolProvider.test.ts
@@ -96,6 +96,7 @@ const decodeStub = (
readonly withStrings?: boolean;
readonly withGerman?: boolean;
readonly failDecode?: boolean;
+ readonly ymlFile?: string;
readonly manifestFile?: string;
readonly stringsFile?: string;
readonly stringsXml?: string;
@@ -104,6 +105,10 @@ const decodeStub = (
const withStrings = options.withStrings ?? true;
const withGerman = options.withGerman ?? true;
const stringsXml = options.stringsXml ?? REAL_STRINGS;
+ const ymlWrite =
+ options.ymlFile === undefined
+ ? `printf '%s\\n' '${REAL_YML.replace(/'/gu, "'\\''")}' > "$5/apktool.yml"`
+ : `cp '${options.ymlFile}' "$5/apktool.yml"`;
const manifestWrite =
options.manifestFile === undefined
? `printf '%s\\n' '${REAL_MANIFEST.replace(/'/gu, "'\\''")}' > "$5/AndroidManifest.xml"`
@@ -117,7 +122,7 @@ if [ "$1" = "d" ]; then
${
options.failDecode === true
? `printf 'Exception in thread "main" brut.androlib.AndrolibException: Could not decode the APK\\n' >&2; exit 1;`
- : `printf '%s\\n' '${REAL_YML.replace(/'/gu, "'\\''")}' > "$5/apktool.yml"
+ : `${ymlWrite}
${manifestWrite}
mkdir -p "$5/res/values"${withGerman ? ' "$5/res/values-de"' : ""}
${withStrings ? stringsWrite : ""}
@@ -192,6 +197,47 @@ it("decodes resources with target identity, metadata, and strings", async () =>
expect(result.coverage).toBe("complete");
});
+it.each([
+ {
+ name: "malformed UTF-8",
+ bytes: Buffer.concat([
+ Buffer.from("versionInfo:\n versionName: com."),
+ Buffer.from([0xff]),
+ Buffer.from(".app\n"),
+ ]),
+ valid: false,
+ },
+ {
+ name: "a literal replacement character",
+ bytes: Buffer.from("versionInfo:\n versionName: com.�.app\n", "utf8"),
+ valid: true,
+ },
+])("handles $name in producer metadata", async ({ bytes, valid }) => {
+ const { command, root } = await writeApktoolStub((root) =>
+ decodeStub({ ymlFile: join(root, "malformed-apktool.yml") })(root),
+ );
+ await writeFile(join(root, "malformed-apktool.yml"), bytes);
+ const apk = await apkFixture(root);
+ if (valid) {
+ const result = await evidenceResult(providerOver(command), {
+ operation: "decode_android_resources",
+ input: { path: apk.path, include_strings: false },
+ });
+ expect(result.metadata).toMatchObject({ version_name: "com.�.app" });
+ expect(result.coverage).toBe("complete");
+ return;
+ }
+ const result = await providerOver(command).execute({
+ operation: "decode_android_resources",
+ input: { path: apk.path, include_strings: false },
+ });
+ if (result.ok) throw new Error("expected invalid producer output");
+ const projected = projectAnalysisError(result.error);
+ expect(projected).toMatchObject({ code: "unreadable_output" });
+ expect(result.error.message).toContain("invalid UTF-8");
+ expect(result.error.message).toContain("apktool.yml");
+});
+
it("preserves empty resource strings and reports markup omissions as partial", async () => {
const stringsXml =
' A & B Hello world';
diff --git a/src/apktool/ApktoolProvider.ts b/src/apktool/ApktoolProvider.ts
index 682e2f2ea..1e1f187c0 100644
--- a/src/apktool/ApktoolProvider.ts
+++ b/src/apktool/ApktoolProvider.ts
@@ -117,13 +117,20 @@ const readBoundedText = async (
throwIfCancelled(operation, signal);
const truncated = length > budget;
// A prefix may end within a UTF-8 character; omit those trailing bytes.
- const decoder = new TextDecoder("utf-8");
- return {
- text: decoder.decode(bytes.subarray(0, Math.min(length, budget)), {
- stream: truncated,
- }),
- truncated,
- };
+ try {
+ const decoder = new TextDecoder("utf-8", { fatal: true });
+ return {
+ text: decoder.decode(bytes.subarray(0, Math.min(length, budget)), {
+ stream: truncated,
+ }),
+ truncated,
+ };
+ } catch (cause: unknown) {
+ throw new AnalysisProtocolError(
+ `apktool produced invalid UTF-8 in ${path}`,
+ { cause },
+ );
+ }
} finally {
await file.close();
}
diff --git a/src/application/AnalysisProvider.ts b/src/application/AnalysisProvider.ts
index cc17cac82..f3b51257a 100644
--- a/src/application/AnalysisProvider.ts
+++ b/src/application/AnalysisProvider.ts
@@ -54,6 +54,15 @@ export interface AnalysisExecution {
readonly subject: EvidenceSubjectTarget | null;
}
+interface CreateAnalysisExecutionOptions {
+ readonly rawResult?: unknown;
+ readonly analysisProfile?: AnalysisProfileCommitment;
+ readonly limitations?: readonly string[];
+ readonly relationshipCoverage?: RelationshipCoverage;
+ readonly locations?: readonly EvidenceLocation[];
+ readonly subject?: EvidenceSubjectTarget;
+}
+
/**
* Build a validated atomic provider observation at an adapter boundary.
*
@@ -61,38 +70,43 @@ export interface AnalysisExecution {
* `result`. Omitting it records `null` rather than a second complete copy of
* the normalized result in every Evidence record and tool response.
*/
-export const createAnalysisExecution = (
+export function createAnalysisExecution(
result: unknown,
provider: ProviderIdentity,
- options: {
- readonly rawResult?: unknown;
- readonly analysisProfile?: AnalysisProfileCommitment;
- readonly limitations?: readonly string[];
- readonly relationshipCoverage?: RelationshipCoverage;
- readonly locations?: readonly EvidenceLocation[];
- readonly subject?: EvidenceSubjectTarget;
- } = {},
-): AnalysisExecution => ({
- result: jsonValueSchema.parse(result),
- rawResult:
- options.rawResult === undefined
- ? null
- : jsonValueSchema.parse(options.rawResult),
- provider,
- ...(options.analysisProfile === undefined
- ? {}
- : { analysisProfile: structuredClone(options.analysisProfile) }),
- limitations: [...(options.limitations ?? [])],
- ...(options.relationshipCoverage === undefined
- ? {}
- : {
- relationshipCoverage: relationshipCoverageSchema.parse(
- options.relationshipCoverage,
- ),
- }),
- locations: [...(options.locations ?? [])],
- subject: options.subject ?? null,
-});
+ options: CreateAnalysisExecutionOptions & { readonly subject: Subject },
+): Omit & { readonly subject: Subject };
+export function createAnalysisExecution(
+ result: unknown,
+ provider: ProviderIdentity,
+ options?: CreateAnalysisExecutionOptions,
+): AnalysisExecution;
+export function createAnalysisExecution(
+ result: unknown,
+ provider: ProviderIdentity,
+ options: CreateAnalysisExecutionOptions = {},
+): AnalysisExecution {
+ return {
+ result: jsonValueSchema.parse(result),
+ rawResult:
+ options.rawResult === undefined
+ ? null
+ : jsonValueSchema.parse(options.rawResult),
+ provider,
+ ...(options.analysisProfile === undefined
+ ? {}
+ : { analysisProfile: structuredClone(options.analysisProfile) }),
+ limitations: [...(options.limitations ?? [])],
+ ...(options.relationshipCoverage === undefined
+ ? {}
+ : {
+ relationshipCoverage: relationshipCoverageSchema.parse(
+ options.relationshipCoverage,
+ ),
+ }),
+ locations: [...(options.locations ?? [])],
+ subject: options.subject ?? null,
+ };
+}
/** Provider-neutral application capability for one analysis operation. */
export interface AnalysisOperationPort {
diff --git a/src/application/CapabilityInventory.ts b/src/application/CapabilityInventory.ts
index c0f341506..34b418029 100644
--- a/src/application/CapabilityInventory.ts
+++ b/src/application/CapabilityInventory.ts
@@ -481,7 +481,7 @@ const workflowAvailabilityFor = ({
remediation: "Run process capture on a supported Linux or macOS host.",
};
if (kind === "application") return { reason: "available", remediation: null };
- if (kind === "flutter-provider")
+ if (kind === "pcap-provider" || kind === "flutter-provider")
return { reason: "available", remediation: null };
const electron = electronProviderAvailability(name, kind, policy);
if (electron !== null) return electron;
diff --git a/src/application/ClientRegistrationStatus.ts b/src/application/ClientRegistrationStatus.ts
index e2696e088..caeba4fb6 100644
--- a/src/application/ClientRegistrationStatus.ts
+++ b/src/application/ClientRegistrationStatus.ts
@@ -7,6 +7,7 @@ import {
clientServerForcedEnabled,
clientServerListedDisabled,
effectiveClientServer,
+ type ClientConfigurationDocument,
} from "./ClientConfigurationDocument.js";
import { access } from "node:fs/promises";
import { resolve } from "node:path";
@@ -74,24 +75,48 @@ const registrationSchema = z
})
.passthrough();
-/** Inspect supported client registrations without reading their environment. */
+interface ClientRegistrationReadOptions {
+ readonly platform?: NodeJS.Platform;
+ readonly environment?: NodeJS.ProcessEnv;
+ readonly resources?: ArtifactResourceScope;
+}
+
+/** Registration facts shared by diagnostics and update maintenance. */
+export interface ClientRegistrationInspection {
+ readonly status: ClientRegistrationStatus;
+ readonly activation: "enabled" | "disabled" | "unknown";
+}
+
+/** Project diagnostics from the same inspection used to select maintenance. */
export const readClientRegistrationStatuses = async (
home: string,
currentCommandPath: string = resolve(process.argv[1] ?? "unknown"),
- options: {
- readonly platform?: NodeJS.Platform;
- readonly environment?: NodeJS.ProcessEnv;
- readonly resources?: ArtifactResourceScope;
- } = {},
-): Promise => {
- const statuses: ClientRegistrationStatus[] = [];
+ options: ClientRegistrationReadOptions = {},
+): Promise =>
+ (
+ await readClientRegistrationInspections(home, currentCommandPath, options)
+ ).map(({ status }) => status);
+
+/** Parse effective registrations and their client-specific activation once. */
+export const readClientRegistrationInspections = async (
+ home: string,
+ currentCommandPath: string = resolve(process.argv[1] ?? "unknown"),
+ options: ClientRegistrationReadOptions = {},
+): Promise => {
+ const inspections: ClientRegistrationInspection[] = [];
+ const record = (
+ status: ClientRegistrationStatus,
+ activation: ClientRegistrationInspection["activation"] = "unknown",
+ ): void => {
+ inspections.push({ status, activation });
+ };
for (const client of supportedClients(
home,
options.platform,
options.environment,
)) {
if (client.configPathError !== undefined) {
- statuses.push({
+ record({
client: client.name,
config_path: client.configPath,
command: [],
@@ -104,7 +129,7 @@ export const readClientRegistrationStatuses = async (
const manualRemediation = manualRegistrationRemediation(client.name);
if (client.format === "unsupported") {
if (manualRemediation !== undefined)
- statuses.push({
+ record({
client: client.name,
config_path: client.markerPath ?? client.configPath,
command: [],
@@ -119,7 +144,7 @@ export const readClientRegistrationStatuses = async (
options.resources,
);
if (!files.ok) {
- statuses.push({
+ record({
client: client.name,
config_path: client.configPath,
command: [],
@@ -130,9 +155,7 @@ export const readClientRegistrationStatuses = async (
}
const parsed = effectiveClientConfiguration(files.value);
if (parsed === undefined) {
- statuses.push(
- unavailableStatus(client.name, client.configPath, "missing"),
- );
+ record(unavailableStatus(client.name, client.configPath, "missing"));
continue;
}
const policy = await readClientPolicyBlock(
@@ -142,7 +165,7 @@ export const readClientRegistrationStatuses = async (
options.resources,
);
if (!policy.ok) {
- statuses.push({
+ record({
client: client.name,
config_path: client.configPath,
command: [],
@@ -159,7 +182,7 @@ export const readClientRegistrationStatuses = async (
? dshDocument(parsed.document).editabilityError
: undefined;
if (editabilityError !== undefined) {
- statuses.push({
+ record({
client: client.name,
config_path: client.configPath,
command: [],
@@ -168,9 +191,7 @@ export const readClientRegistrationStatuses = async (
});
continue;
}
- statuses.push(
- unavailableStatus(client.name, client.configPath, "missing"),
- );
+ record(unavailableStatus(client.name, client.configPath, "missing"));
continue;
}
const registration = parseRegistration(raw, client);
@@ -178,21 +199,18 @@ export const readClientRegistrationStatuses = async (
registration.command,
...registration.args,
];
- statuses.push(
+ const activation = registrationActivation(registration, client, parsed);
+ record(
configuredStatus(
client.name,
client.configPath,
command,
- registrationAligned(
- registration,
- client,
- currentCommandPath,
- options.platform ?? process.platform,
- clientServerForcedEnabled(parsed, PRODUCT_IDENTITY.mcpServerKey),
- ) &&
- !clientServerListedDisabled(
- parsed,
- PRODUCT_IDENTITY.mcpServerKey,
+ activation === "enabled" &&
+ registrationAligned(
+ registration,
+ client,
+ currentCommandPath,
+ options.platform ?? process.platform,
) &&
(parsed.dialect !== "dsh" || dshDocument(parsed.document).ready) &&
policyBlock === undefined
@@ -200,9 +218,10 @@ export const readClientRegistrationStatuses = async (
: "stale",
policyBlock,
),
+ activation,
);
} catch (cause: unknown) {
- statuses.push(
+ record(
unavailableStatus(
client.name,
client.configPath,
@@ -211,26 +230,31 @@ export const readClientRegistrationStatuses = async (
);
}
}
- return statuses.sort((left, right) =>
- compareUnicodeCodePoints(left.client, right.client),
+ return inspections.sort((left, right) =>
+ compareUnicodeCodePoints(left.status.client, right.status.client),
);
};
+const registrationActivation = (
+ registration: z.output,
+ client: SetupClient,
+ parsed: ClientConfigurationDocument,
+): "enabled" | "disabled" =>
+ (client.format !== "grok" && registration.disabled === true) ||
+ (registration.enabled === false &&
+ !clientServerForcedEnabled(parsed, PRODUCT_IDENTITY.mcpServerKey)) ||
+ (client.format === "zcode" && registration.enable === false) ||
+ clientServerListedDisabled(parsed, PRODUCT_IDENTITY.mcpServerKey)
+ ? "disabled"
+ : "enabled";
+
const registrationAligned = (
registration: z.output,
client: SetupClient,
currentCommandPath: string,
platform: NodeJS.Platform,
- forcedEnabled = false,
): boolean => {
const command = [registration.command, ...registration.args];
- if (
- (client.format !== "grok" && registration.disabled === true) ||
- (registration.enabled === false && !forcedEnabled) ||
- // ZCode's native flag is `enable`; other dialects leave that field opaque.
- (client.format === "zcode" && registration.enable === false)
- )
- return false;
if (!isOwnedClientRegistrationCommand(command, currentCommandPath))
return false;
if (
diff --git a/src/application/UpdateMaintenance.ts b/src/application/UpdateMaintenance.ts
index 06ac1b512..fd55c8f23 100644
--- a/src/application/UpdateMaintenance.ts
+++ b/src/application/UpdateMaintenance.ts
@@ -1,19 +1,10 @@
import { z } from "zod";
-import { PRODUCT_IDENTITY } from "../identity.js";
import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
-import { readClientRegistrationStatuses } from "./ClientRegistrationStatus.js";
-import {
- clientServerForcedEnabled,
- clientServerListedDisabled,
- effectiveClientServer,
- parseClientConfiguration,
-} from "./ClientConfigurationDocument.js";
-import { supportedClients } from "./SupportedClients.js";
+import { readClientRegistrationInspections } from "./ClientRegistrationStatus.js";
import { existingSkillDestinations } from "./SetupSkill.js";
import type { SetupAction } from "./SetupTypes.js";
import type { Result } from "../domain/result.js";
-import { readRegularFileText } from "./RegularFileRead.js";
import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
/** Existing REA integrations selected for maintenance, without discovering new targets. */
@@ -61,41 +52,23 @@ export const existingMaintenanceScope = async (
environment: Readonly,
resources?: ArtifactResourceScope,
): Promise => {
- const registrations = await readClientRegistrationStatuses(home, entryPoint, {
- environment,
- ...(resources === undefined ? {} : { resources }),
- });
- const supported = supportedClients(home, process.platform, environment);
+ const registrations = await readClientRegistrationInspections(
+ home,
+ entryPoint,
+ {
+ environment,
+ ...(resources === undefined ? {} : { resources }),
+ },
+ );
const clients: string[] = [];
- for (const registration of registrations) {
+ for (const { status: registration, activation } of registrations) {
if (
+ activation !== "enabled" ||
(registration.state !== "aligned" && registration.state !== "stale") ||
!isOwnedClientRegistrationCommand(registration.command, entryPoint)
)
continue;
- const client = supported.find(({ name }) => name === registration.client);
- if (client === undefined) continue;
- const parsed = parseClientConfiguration(
- await readRegularFileText(
- client.configPath,
- resources === undefined ? {} : { resources },
- ),
- client.format,
- );
- const enabled = z
- .object({
- enabled: z.boolean().optional(),
- disabled: z.boolean().optional(),
- })
- .parse(effectiveClientServer(parsed, PRODUCT_IDENTITY.mcpServerKey));
- // Root disable lists override enabled entries and OMP's force-on allowlist.
- if (
- (enabled.enabled !== false ||
- clientServerForcedEnabled(parsed, PRODUCT_IDENTITY.mcpServerKey)) &&
- enabled.disabled !== true &&
- !clientServerListedDisabled(parsed, PRODUCT_IDENTITY.mcpServerKey)
- )
- clients.push(client.name);
+ clients.push(registration.client);
}
const skillDestinations = await existingSkillDestinations(
home,
diff --git a/src/application/evm/EvmInterfacePort.ts b/src/application/evm/EvmInterfacePort.ts
index e9e29b756..a297e092c 100644
--- a/src/application/evm/EvmInterfacePort.ts
+++ b/src/application/evm/EvmInterfacePort.ts
@@ -4,13 +4,19 @@ import type {
} from "../AnalysisProvider.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import type { InspectEvmInterfaceInput } from "../../domain/evm/evmInterface.js";
+import type { EvidenceSubjectTarget } from "../../domain/evidence.js";
import type { Result } from "../../domain/result.js";
+/** Successful EVM interface recovery must identify the selected local file. */
+export type EvmInterfaceExecution = Omit & {
+ readonly subject: EvidenceSubjectTarget & { readonly format: "file" };
+};
+
/** Replaceable offline interface-recovery engine, independent of wallets and chain clients. */
export interface EvmInterfacePort {
close?(): Promise;
inspect(
input: InspectEvmInterfaceInput,
options?: ExecutionOptions,
- ): Promise>;
+ ): Promise>;
}
diff --git a/src/application/evm/EvmInterfaceService.test.ts b/src/application/evm/EvmInterfaceService.test.ts
index 08cf15487..03f501742 100644
--- a/src/application/evm/EvmInterfaceService.test.ts
+++ b/src/application/evm/EvmInterfaceService.test.ts
@@ -1,5 +1,6 @@
import { expect, it } from "vitest";
import { EvmInterfaceService } from "./EvmInterfaceService.js";
+import type { EvmInterfaceExecution } from "./EvmInterfacePort.js";
import {
evmInterfaceExecution,
evmInterfaceFixture,
@@ -43,7 +44,8 @@ it.each(["carrier", "encoding", "digest", "no-subject"])(
},
};
const service = new EvmInterfaceService({
- inspect: () => Promise.resolve(ok(execution)),
+ inspect: () =>
+ Promise.resolve(ok(execution as unknown as EvmInterfaceExecution)),
});
expect(
await service.inspect({
diff --git a/src/application/evm/EvmInterfaceService.ts b/src/application/evm/EvmInterfaceService.ts
index eac1986d3..86ac77865 100644
--- a/src/application/evm/EvmInterfaceService.ts
+++ b/src/application/evm/EvmInterfaceService.ts
@@ -67,6 +67,7 @@ export class EvmInterfaceService {
!report.success ||
report.data.artifact.path !== input.data.path ||
report.data.artifact.encoding !== input.data.encoding ||
+ execution.subject?.format !== "file" ||
execution.subject?.path !== input.data.path ||
execution.subject.sha256 !== report.data.artifact.sha256
)
diff --git a/src/application/investigation/EvidenceLedger.residualUnknown.test.ts b/src/application/investigation/EvidenceLedger.residualUnknown.test.ts
index bb81f97ce..2885c1906 100644
--- a/src/application/investigation/EvidenceLedger.residualUnknown.test.ts
+++ b/src/application/investigation/EvidenceLedger.residualUnknown.test.ts
@@ -78,6 +78,51 @@ const update = (
});
describe("residual unknown registry reads and identity", () => {
+ it("seals mutation Evidence without freezing caller-owned inputs", () => {
+ const store = ledger();
+ const recordMutation = mutation("mutable-record-mutation");
+ const recorded = store.recordUnknown(
+ input("Does record mutation evidence stay stable?"),
+ recordMutation,
+ );
+ if (!recorded.ok) throw recorded.error;
+
+ const updateMutation = mutation("mutable-update-mutation");
+ const updated = store.updateUnknown(update(recorded.value), updateMutation);
+ if (!updated.ok) throw updated.error;
+ const atomicEvidence = evidence("mutable-atomic-evidence");
+ const atomicMutation = mutation("mutable-atomic-mutation");
+ const atomicallyRecorded = store.recordWithUnknown(
+ atomicEvidence,
+ input("Does atomic evidence stay stable?"),
+ atomicMutation,
+ );
+ if (!atomicallyRecorded.ok) throw atomicallyRecorded.error;
+
+ for (const callerEvidence of [
+ recordMutation,
+ updateMutation,
+ atomicEvidence,
+ atomicMutation,
+ ]) {
+ expect(Object.isFrozen(callerEvidence)).toBe(false);
+ const retained = store.forAnalysis(callerEvidence.evidence_id);
+ if (retained === undefined) throw new Error("Missing retained Evidence");
+ const originalResult = structuredClone(retained.normalized_result);
+ expect(Object.isFrozen(retained)).toBe(true);
+ Reflect.set(callerEvidence, "operation", "caller mutation");
+ expect(
+ Reflect.set(
+ callerEvidence.normalized_result as object,
+ "label",
+ "caller nested mutation",
+ ),
+ ).toBe(true);
+ expect(retained.operation).not.toBe("caller mutation");
+ expect(retained.normalized_result).toEqual(originalResult);
+ }
+ });
+
it("merges record-only bundles without changing retained unknown history", () => {
const store = ledger();
const created = store.recordUnknown(
diff --git a/src/application/investigation/EvidenceLedger.ts b/src/application/investigation/EvidenceLedger.ts
index ce806ad38..0cb1c5e29 100644
--- a/src/application/investigation/EvidenceLedger.ts
+++ b/src/application/investigation/EvidenceLedger.ts
@@ -11,11 +11,7 @@ import {
import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
import { UnknownRegistryError } from "../../domain/unknownRegistryError.js";
-import {
- immutableEvidence,
- parseEvidence,
- type Evidence,
-} from "../../domain/evidence.js";
+import { immutableEvidence, type Evidence } from "../../domain/evidence.js";
import {
createResidualUnknown,
updateResidualUnknown,
@@ -220,7 +216,7 @@ export class EvidenceLedger {
): Result {
let parsedMutation: Evidence;
try {
- parsedMutation = parseEvidence(mutationEvidence);
+ parsedMutation = immutableEvidence(mutationEvidence);
} catch (cause: unknown) {
return err(
new EvidenceIntegrityError("Unknown mutation evidence is invalid", {
@@ -255,8 +251,8 @@ export class EvidenceLedger {
let evidence: Evidence;
let mutation: Evidence;
try {
- evidence = parseEvidence(evidenceInput);
- mutation = parseEvidence(mutationInput);
+ evidence = immutableEvidence(evidenceInput);
+ mutation = immutableEvidence(mutationInput);
} catch (cause: unknown) {
return err(
new EvidenceIntegrityError("Atomic Evidence validation failed", {
@@ -394,7 +390,7 @@ export class EvidenceLedger {
): Result {
let mutationEvidence: Evidence;
try {
- mutationEvidence = parseEvidence(mutationEvidenceInput);
+ mutationEvidence = immutableEvidence(mutationEvidenceInput);
} catch (cause: unknown) {
return err(
new EvidenceIntegrityError("Unknown mutation evidence is invalid", {
diff --git a/src/application/javascript/JavaScriptArtifactAnalysis.sourceMaps.test.ts b/src/application/javascript/JavaScriptArtifactAnalysis.sourceMaps.test.ts
new file mode 100644
index 000000000..cbd9c745c
--- /dev/null
+++ b/src/application/javascript/JavaScriptArtifactAnalysis.sourceMaps.test.ts
@@ -0,0 +1,71 @@
+import { expect, it } from "vitest";
+import { TraceMap } from "@jridgewell/trace-mapping";
+
+import { analyzeJavaScriptArtifactFiles } from "./JavaScriptArtifactAnalysis.js";
+
+const HASH = "a".repeat(64);
+
+it("retains batched TraceMap-resolved paths and null source positions", () => {
+ const sourceMapText = JSON.stringify({
+ version: 3,
+ file: "main.js",
+ sourceRoot: "../src/",
+ sources: ["cafe\u0301.ts", null, "other.ts"],
+ sourcesContent: ["export const value = 1;", null, "export {};"],
+ names: [],
+ mappings: "",
+ });
+ const analysis = analyzeJavaScriptArtifactFiles({
+ files: [
+ {
+ path: "dist/main.js.map",
+ container_sha256: HASH,
+ sha256: HASH,
+ bytes: Buffer.byteLength(sourceMapText),
+ inventory_artifact_id: "artifact_test",
+ kind: "source-map",
+ unpacked: false,
+ text: { included: true, value: sourceMapText },
+ },
+ ],
+ containers: [],
+ text_bytes_read: Buffer.byteLength(sourceMapText),
+ invalid_utf8_files: 0,
+ });
+ const originals = analysis.source_maps[0]?.sources;
+ const original = originals?.[0];
+ const producerPath = new TraceMap(
+ {
+ version: 3,
+ file: "main.js",
+ sourceRoot: "../src/",
+ sources: ["cafe\u0301.ts", "", "other.ts"],
+ names: [],
+ mappings: "",
+ },
+ "file:///artifact/dist/main.js.map",
+ ).resolvedSources[0];
+
+ if (producerPath === undefined)
+ throw new Error("TraceMap should resolve its single source declaration");
+ expect(originals?.[1]?.reference).toBeNull();
+ expect(originals?.[2]?.reference?.resolution).toEqual({
+ kind: "artifact-relative",
+ path: "src/other.ts",
+ });
+ expect(original?.reference).toMatchObject({
+ source_name: "cafe\u0301.ts",
+ source_root: "../src/",
+ map_path: "dist/main.js.map",
+ resolution: {
+ kind: "artifact-relative",
+ path: "src/cafe\u0301.ts",
+ },
+ });
+ expect(original?.reference?.resolution).toEqual({
+ kind: "artifact-relative",
+ path: decodeURIComponent(
+ new URL(producerPath).pathname.slice("/artifact/".length),
+ ),
+ });
+});
diff --git a/src/application/javascript/JavaScriptArtifactAnalysis.ts b/src/application/javascript/JavaScriptArtifactAnalysis.ts
index e52ba04dd..dd1a50488 100644
--- a/src/application/javascript/JavaScriptArtifactAnalysis.ts
+++ b/src/application/javascript/JavaScriptArtifactAnalysis.ts
@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
import { moduleKindForJavaScriptReference } from "./JavaScriptArtifactPathResolution.js";
import { setImmediate } from "node:timers/promises";
-import { resolveJavaScriptSourceMapReference } from "../../domain/javascript/javascriptSourceMapPaths.js";
+import { resolveJavaScriptSourceMapReferences } from "../../domain/javascript/javascriptSourceMapPaths.js";
import { analyzeParsedJavaScriptStaticSourceSteps } from "../../domain/javascript/javascriptStaticAnalysis.js";
import {
analyzeParsedJavaScriptSemanticsSteps,
@@ -561,21 +561,27 @@ const collectSourceMapOriginals = (
"Source map sourceRoot must be a string or null.",
);
const root = typeof map.sourceRoot === "string" ? map.sourceRoot : null;
- for (const [index, raw] of names.entries()) {
+ const sourceNames: (string | null)[] = [];
+ for (const raw of names) {
if (raw !== null && typeof raw !== "string")
return invalidSourceMap(
file,
"Source map contains a non-string source name.",
);
+ sourceNames.push(raw);
+ }
+ const references = resolveJavaScriptSourceMapReferences(
+ sourceNames,
+ root,
+ file.path,
+ );
+ for (const [index, reference] of references.entries()) {
const rawContent = Array.isArray(contents) ? contents[index] : undefined;
const content = typeof rawContent === "string" ? rawContent : null;
sources.push({
source_index: index,
declaration_index: declarationIndex++,
- reference:
- typeof raw === "string"
- ? resolveJavaScriptSourceMapReference(raw, root, file.path)
- : null,
+ reference,
content,
content_sha256: content === null ? null : sha256(content),
});
diff --git a/src/application/managed/ManagedReconstructionService.test.ts b/src/application/managed/ManagedReconstructionService.test.ts
index 56b9d9442..793951ae9 100644
--- a/src/application/managed/ManagedReconstructionService.test.ts
+++ b/src/application/managed/ManagedReconstructionService.test.ts
@@ -22,6 +22,26 @@ const exampleMethod = () => {
};
describe("managed decompiler reconstruction import", () => {
+ it("reports UTF-8 byte totals while preserving UTF-16 text lengths", () => {
+ const text = 'return "é"; // 😀';
+ const method = exampleMethod();
+ const result = importManagedReconstructionEvidence({
+ ...MANAGED_RECONSTRUCTION_IMPORT_EXAMPLE,
+ methods: [
+ {
+ ...method,
+ reconstruction: { ...method.reconstruction, text },
+ },
+ ],
+ });
+ if (!result.ok) throw result.error;
+
+ expect(result.value.normalized_result).toMatchObject({
+ summary: { total_text_bytes: 20 },
+ methods: [{ reconstruction: { text, text_length: 17 } }],
+ });
+ });
+
it("rejects reconstruction text hash drift", () => {
expect(() =>
importManagedReconstruction({
diff --git a/src/application/pcap/PcapAnalysisPort.ts b/src/application/pcap/PcapAnalysisPort.ts
new file mode 100644
index 000000000..c5acecd38
--- /dev/null
+++ b/src/application/pcap/PcapAnalysisPort.ts
@@ -0,0 +1,23 @@
+import type {
+ AnalysisExecution,
+ ExecutionOptions,
+ ProviderAvailability,
+} from "../AnalysisProvider.js";
+import type { PcapRequest } from "../../domain/pcap/pcapAnalysis.js";
+import type { AnalysisError } from "../../domain/analysisErrorBase.js";
+import type { Result } from "../../domain/result.js";
+
+/**
+ * Packet-capture analysis boundary over caller-supplied tshark/capinfos.
+ * Implementation details belong to the provider adapter.
+ */
+export interface PcapAnalysisPort {
+ /** Probe both tools without reading any capture file. */
+ inspectAvailability(signal?: AbortSignal): Promise;
+ /** Retry cleanup of retained owned commands and capture snapshots. */
+ close(): Promise;
+ execute(
+ request: PcapRequest,
+ options?: ExecutionOptions,
+ ): Promise>;
+}
diff --git a/src/application/pcap/PcapAnalysisService.ts b/src/application/pcap/PcapAnalysisService.ts
new file mode 100644
index 000000000..23b968e58
--- /dev/null
+++ b/src/application/pcap/PcapAnalysisService.ts
@@ -0,0 +1,36 @@
+import type { PcapAnalysisPort } from "./PcapAnalysisPort.js";
+import type { ExecutionOptions } from "../AnalysisProvider.js";
+import {
+ pcapRequestSchema,
+ type PcapOperation,
+} from "../../domain/pcap/pcapAnalysis.js";
+import {
+ AnalysisCancelledError,
+ AnalysisInputError,
+} from "../../domain/analysisErrorCore.js";
+import type { AnalysisError } from "../../domain/analysisErrorBase.js";
+import type { Evidence } from "../../domain/evidence.js";
+import { createPcapEvidence } from "../../domain/pcap/pcapEvidence.js";
+import { err, ok, type Result } from "../../domain/result.js";
+
+/** Shared CLI/MCP admission, execution, and Evidence composition for pcap. */
+export class PcapAnalysisService {
+ constructor(readonly provider: PcapAnalysisPort) {}
+
+ /** Run one caller-selected pcap request and retain capture identity inline. */
+ async execute(
+ operation: PcapOperation,
+ input: unknown,
+ options?: ExecutionOptions,
+ ): Promise> {
+ if (options?.signal?.aborted === true)
+ return err(new AnalysisCancelledError(operation));
+ const request = pcapRequestSchema.safeParse({ operation, input });
+ if (!request.success)
+ return err(new AnalysisInputError(operation, { cause: request.error }));
+ const executed = await this.provider.execute(request.data, options);
+ if (!executed.ok) return executed;
+ const execution = executed.value;
+ return ok(createPcapEvidence(request.data, execution));
+ }
+}
diff --git a/src/application/wasm/WasmArtifactPort.ts b/src/application/wasm/WasmArtifactPort.ts
index 6cf6de352..90daab4b1 100644
--- a/src/application/wasm/WasmArtifactPort.ts
+++ b/src/application/wasm/WasmArtifactPort.ts
@@ -4,8 +4,14 @@ import type {
} from "../AnalysisProvider.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import type { InspectWasmArtifactInput } from "../../domain/wasm/wasmArtifact.js";
+import type { EvidenceSubjectTarget } from "../../domain/evidence.js";
import type { Result } from "../../domain/result.js";
+/** Successful WASM inspection must identify the selected local file. */
+export type WasmArtifactExecution = Omit & {
+ readonly subject: EvidenceSubjectTarget & { readonly format: "file" };
+};
+
/** Replaceable offline WASM inspection engine, independent of target execution and network clients. */
export interface WasmArtifactPort {
/** Retry removal of retained workspaces; failures preserve ownership for another attempt. */
@@ -13,5 +19,5 @@ export interface WasmArtifactPort {
inspect(
input: InspectWasmArtifactInput,
options?: ExecutionOptions,
- ): Promise>;
+ ): Promise>;
}
diff --git a/src/artifacts/NativeDmgArtifactReader.ts b/src/artifacts/NativeDmgArtifactReader.ts
index a3f3fb120..801ee4daf 100644
--- a/src/artifacts/NativeDmgArtifactReader.ts
+++ b/src/artifacts/NativeDmgArtifactReader.ts
@@ -22,6 +22,7 @@ import {
type NativeDmgInfo,
} from "./NativeDmgOwnership.js";
const HDIUTIL_COMMAND_TIMEOUT_MS = 120_000;
+const VERIFY_SETTLE_DELAYS_MS = [250, 500] as const;
// APFS ejects and busy reporting can lag a detach attempt.
const DETACH_SETTLE_DELAYS_MS = [250, 500, 1000] as const;
const delay = (milliseconds: number): Promise =>
@@ -44,22 +45,30 @@ export interface NativeDmgHost {
class NativeDmgCommandFailure extends ArtifactReaderFailure {
readonly processNotStarted: boolean;
+ readonly verifyDiagnostic: string | undefined;
+ readonly exitCode: number | null;
constructor(
- reason: ArtifactReaderFailure["reason"],
+ failure: {
+ readonly reason: ArtifactReaderFailure["reason"];
+ readonly verifyDiagnostic?: string;
+ },
message: string,
readonly stdout: string,
options?: {
readonly cause?: unknown;
readonly processNotStarted?: boolean;
+ readonly exitCode?: number;
},
) {
super(
- reason,
+ failure.reason,
message,
options?.cause === undefined ? undefined : { cause: options.cause },
);
this.processNotStarted = options?.processNotStarted ?? false;
+ this.verifyDiagnostic = failure.verifyDiagnostic;
+ this.exitCode = options?.exitCode ?? null;
}
}
@@ -84,7 +93,7 @@ const createSystemHost = (
const output = execFileOutputFailure(cause);
if (cause instanceof Error && cause.name === "AbortError")
throw new NativeDmgCommandFailure(
- "cancelled",
+ { reason: "cancelled" },
"DMG operation cancelled",
output?.stdout ?? "",
{ cause },
@@ -99,7 +108,7 @@ const createSystemHost = (
cause,
};
throw new NativeDmgCommandFailure(
- commandFailureReason(cause, arguments_[0]),
+ classifyCommandFailure(cause, arguments_[0]),
`hdiutil ${arguments_[0] ?? "operation"} failed: ${describeCommandFailure(cause, arguments_)}`,
output?.stdout ?? "",
{ cause, processNotStarted: processNotStarted(cause) },
@@ -348,8 +357,7 @@ export class NativeDmgArtifactReader implements ArtifactReader {
}
async #attach(signal?: AbortSignal): Promise {
- await runChecked(this.host, ["verify", this.path], signal);
- this.#provenance.push(command(["verify", this.path], ["read"]));
+ await this.#verify(signal);
const baseline = await this.#readInfo();
this.#baselineDevices = new Set(
baseline.images.flatMap((image) =>
@@ -431,6 +439,40 @@ export class NativeDmgArtifactReader implements ArtifactReader {
}
}
+ async #verify(signal?: AbortSignal): Promise {
+ const arguments_ = ["verify", this.path];
+ const deadline = performance.now() + HDIUTIL_COMMAND_TIMEOUT_MS;
+ for (let attempt = 0; ; attempt += 1) {
+ if (signal?.aborted === true)
+ throw new NativeDmgCommandFailure(
+ { reason: "cancelled" },
+ "DMG operation cancelled",
+ "",
+ { cause: signal.reason },
+ );
+ try {
+ await runChecked(this.host, arguments_, signal, {
+ timeoutMs: Math.max(1, Math.ceil(deadline - performance.now())),
+ });
+ this.#provenance.push(command(arguments_, ["read"]));
+ return;
+ } catch (cause: unknown) {
+ if (!(cause instanceof NativeDmgCommandFailure)) throw cause;
+ this.#provenance.push(command(arguments_, ["read"], cause.exitCode));
+ const delayMs = VERIFY_SETTLE_DELAYS_MS[attempt];
+ // Retry only the producer's explicit transient diagnostic, before any mount.
+ if (
+ cause.verifyDiagnostic !== "Resource temporarily unavailable" ||
+ delayMs === undefined ||
+ deadline - performance.now() <= delayMs
+ )
+ throw cause;
+ await (this.host.delay ?? delay)(delayMs);
+ if (performance.now() >= deadline) throw cause;
+ }
+ }
+ }
+
async #readInfo(): Promise {
const info = await runChecked(this.host, ["info", "-plist"], undefined, {
timeoutMs: HDIUTIL_COMMAND_TIMEOUT_MS,
@@ -501,14 +543,14 @@ const runChecked = async (
if (cause instanceof ArtifactReaderFailure) throw cause;
if (cause instanceof Error && cause.name === "AbortError")
throw new NativeDmgCommandFailure(
- "cancelled",
+ { reason: "cancelled" },
"DMG operation cancelled",
execFileOutputFailure(cause)?.stdout ?? "",
{ cause },
);
const output = execFileOutputFailure(cause);
throw new NativeDmgCommandFailure(
- commandFailureReason(cause, arguments_[0]),
+ classifyCommandFailure(cause, arguments_[0]),
`hdiutil ${arguments_[0] ?? "operation"} failed: ${describeCommandFailure(
cause,
arguments_,
@@ -527,17 +569,17 @@ const runChecked = async (
stdout: result.stdout,
...(result.stderr === undefined ? {} : { stderr: result.stderr }),
};
- const reason = commandFailureReason(failure, arguments_[0]);
+ const classification = classifyCommandFailure(failure, arguments_[0]);
const details = describeCommandFailure(failure, arguments_);
const unknownVerifyFailure =
- arguments_[0] === "verify" && reason === "unavailable";
+ arguments_[0] === "verify" && classification.reason === "unavailable";
throw new NativeDmgCommandFailure(
- reason,
+ classification,
unknownVerifyFailure
? `hdiutil verify failed; captured diagnostics do not establish the failure cause: ${details}`
: `hdiutil ${arguments_[0] ?? "operation"} failed: ${details}`,
result.stdout,
- { cause: result.cause ?? failure },
+ { cause: result.cause ?? failure, exitCode: result.exitCode },
);
}
return { stdout: result.stdout, exitCode: 0 };
@@ -587,20 +629,36 @@ const processOutput = (cause: unknown, field: "stdout" | "stderr"): string => {
return typeof value === "string" ? value : "";
};
-const commandFailureReason = (
+const classifyCommandFailure = (
cause: unknown,
operation: string | undefined,
-): ArtifactReaderFailure["reason"] => {
- if (typeof cause !== "object" || cause === null) return "unavailable";
+): {
+ readonly reason: ArtifactReaderFailure["reason"];
+ readonly verifyDiagnostic?: string;
+} => {
+ if (typeof cause !== "object" || cause === null)
+ return { reason: "unavailable" };
const code = Reflect.get(cause, "code");
const exitCode = Reflect.get(cause, "exitCode");
- if (typeof code === "number" || typeof exitCode === "number")
- return operation === "verify" ? verifyFailureReason(cause) : "unavailable";
+ if (typeof code === "number" || typeof exitCode === "number") {
+ if (operation !== "verify") return { reason: "unavailable" };
+ const diagnostic = verifyFailureDiagnostic(
+ processOutput(cause, "stdout"),
+ processOutput(cause, "stderr"),
+ );
+ return {
+ reason: verifyFailureReason(diagnostic),
+ ...(diagnostic === undefined ? {} : { verifyDiagnostic: diagnostic }),
+ };
+ }
if (code === "ENOENT") {
const syscall = Reflect.get(cause, "syscall");
- return typeof syscall === "string" && syscall.startsWith("spawn")
- ? "unavailable"
- : "io";
+ return {
+ reason:
+ typeof syscall === "string" && syscall.startsWith("spawn")
+ ? "unavailable"
+ : "io",
+ };
}
if (
code === "EACCES" ||
@@ -613,17 +671,13 @@ const commandFailureReason = (
code === "EMFILE" ||
code === "ENFILE"
)
- return "io";
- return "unavailable";
+ return { reason: "io" };
+ return { reason: "unavailable" };
};
const verifyFailureReason = (
- cause: unknown,
+ diagnostic: string | undefined,
): ArtifactReaderFailure["reason"] => {
- const diagnostic = verifyFailureDiagnostic(
- processOutput(cause, "stdout"),
- processOutput(cause, "stderr"),
- );
switch (diagnostic) {
// hdiutil follows AppleLanguages, so en-GB and en-AU spell it "recognised".
case "image not recognized":
@@ -656,11 +710,12 @@ const verifyFailureDiagnostic = (
const command = (
arguments_: readonly string[],
effects: ArtifactCommand["effects"],
+ exitCode: number | null = 0,
): ArtifactCommand => ({
tool: "/usr/bin/hdiutil",
arguments: [...arguments_],
tool_version: null,
executable_sha256: null,
- exit_code: 0,
+ exit_code: exitCode,
effects,
});
diff --git a/src/browser/WebSourceMapFetcher.ts b/src/browser/WebSourceMapFetcher.ts
index 0b17df0cb..b950926ee 100644
--- a/src/browser/WebSourceMapFetcher.ts
+++ b/src/browser/WebSourceMapFetcher.ts
@@ -2,7 +2,6 @@ import * as t from "@babel/types";
import {
decodeValidatedSourceMapLeaves,
isBeforeSourceMapLeafStop,
- resolveSourceMapSource,
} from "../javascript/sourceMaps/DecodedSourceMap.js";
import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
@@ -21,6 +20,7 @@ import { webSourceMapsSchema } from "../domain/webBundleAnalysis.js";
import { createWebTextArtifact } from "../domain/webContentArtifact.js";
import { safeParseJson } from "../domain/safeJson.js";
import { sourceMapJsonText } from "../domain/sourceMapEnvelope.js";
+import { resolveJavaScriptSourceMapUrl } from "../domain/javascript/javascriptSourceMapPaths.js";
import { jsonParts } from "../domain/jsonSerialization.js";
import {
inspectSourceMapValue,
@@ -867,7 +867,11 @@ const preflightResolvedSourceBytes = (
const sourceKey = source;
let resolved = sourcesForRoot.get(sourceKey);
if (resolved === undefined)
- resolved = resolveSourceMapSource(source, map.sourceRoot, mapUrl);
+ resolved = resolveJavaScriptSourceMapUrl(
+ source,
+ map.sourceRoot,
+ mapUrl,
+ );
const bytes = Buffer.byteLength(resolved, "utf8");
if (bytes > SOURCE_MAP_RESPONSE_BYTES - resolvedBytes)
throw resolvedSourceLimitFailure();
diff --git a/src/cli.ts b/src/cli.ts
index 0b545c0ba..d1bdf2912 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -24,6 +24,7 @@ import { registerManagedCommands } from "./cli/managedCommands.js";
import { registerFirmwareCommands } from "./cli/firmwareCommands.js";
import { registerAndroidCommands } from "./cli/androidCommands.js";
import { registerApktoolCommands } from "./cli/apktoolCommands.js";
+import { registerPcapCommands } from "./cli/pcapCommands.js";
import { registerFlutterCommands } from "./cli/flutterCommands.js";
import { registerJebCommands } from "./cli/jebCommands.js";
import { registerAdbCommands } from "./cli/adbCommands.js";
@@ -105,6 +106,7 @@ export const createCli = (
registerManagedCommands(cli, logger, analysis.runProviderAnalysis);
registerAndroidCommands(cli, logger, environment);
registerApktoolCommands(cli, logger, environment);
+ registerPcapCommands(cli, logger, environment);
registerFlutterCommands(cli, logger);
registerJebCommands(cli, logger, environment);
registerAdbCommands(cli, logger, environment);
diff --git a/src/cli/pcapCommands.ts b/src/cli/pcapCommands.ts
new file mode 100644
index 000000000..1b53e47cc
--- /dev/null
+++ b/src/cli/pcapCommands.ts
@@ -0,0 +1,69 @@
+import { z } from "incur";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { PcapAnalysisService } from "../application/pcap/PcapAnalysisService.js";
+import type { PcapAnalysisPort } from "../application/pcap/PcapAnalysisPort.js";
+import { createPcapAnalysisProvider } from "../composition/pcap.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { logCliCommand } from "../cliLogging.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import type { PcapOperation } from "../domain/pcap/pcapAnalysis.js";
+import type { Logger } from "pino";
+import type { CliInstance } from "./types.js";
+import { withCommandCancellation } from "./commandCancellation.js";
+
+/** Expose the same explicit pcap requests through one-shot CLI commands. */
+export const registerPcapCommands = (
+ cli: CliInstance,
+ logger: Logger,
+ environment: Readonly>,
+ provider: PcapAnalysisPort = createPcapAnalysisProvider(environment),
+): void => {
+ const service = new PcapAnalysisService(provider);
+ const execute = (name: string, operation: PcapOperation, input: unknown) =>
+ withCommandCancellation((signal) =>
+ logCliCommand(logger, name, async () => {
+ const result = await service.execute(operation, input, { signal });
+ try {
+ await provider.close();
+ } catch (cause) {
+ if (cause instanceof AnalysisError) {
+ if (result.ok) cause.retainPartialObservation(result.value);
+ return projectAnalysisError(
+ result.ok
+ ? cause
+ : analysisErrorWithCleanupFailure(
+ result.error,
+ cause,
+ operation,
+ ),
+ );
+ }
+ throw cause;
+ }
+ return result.ok ? result.value : projectAnalysisError(result.error);
+ }),
+ );
+
+ cli.command(CLI_COMMANDS.inspectPcapClient, {
+ description:
+ "Inspect the caller-selected tshark and capinfos binaries without reading a capture",
+ args: z.object({}),
+ run: () =>
+ execute(CLI_COMMANDS.inspectPcapClient, "inspect_pcap_client", {}),
+ });
+ cli.command(CLI_COMMANDS.inspectPcapCapture, {
+ description:
+ "Inspect one pcap/pcapng capture: endpoints, DNS, TLS SNI, and protocol distribution",
+ args: z.object({
+ path: z
+ .string()
+ .min(1)
+ .describe("Local pcap or pcapng capture file to inspect"),
+ }),
+ run: ({ args }) =>
+ execute(CLI_COMMANDS.inspectPcapCapture, "inspect_pcap_capture", {
+ path: args.path,
+ }),
+ });
+};
diff --git a/src/cliCommandNames.ts b/src/cliCommandNames.ts
index 1278cbea8..e7c9bc922 100644
--- a/src/cliCommandNames.ts
+++ b/src/cliCommandNames.ts
@@ -55,6 +55,8 @@ export const CLI_COMMANDS = Object.freeze({
inspectFirmwareRegions: "inspect-firmware-regions",
extractFirmware: "extract-firmware",
inspectAndroidPackage: "inspect-android-package",
+ inspectPcapClient: "inspect-pcap-client",
+ inspectPcapCapture: "inspect-pcap-capture",
identifyFlutterBuild: "identify-flutter-build",
inspectDartAot: "inspect-dart-aot",
inspectApktoolClient: "inspect-apktool-client",
diff --git a/src/composition/pcap.ts b/src/composition/pcap.ts
new file mode 100644
index 000000000..f3aaa3915
--- /dev/null
+++ b/src/composition/pcap.ts
@@ -0,0 +1,7 @@
+import type { PcapAnalysisPort } from "../application/pcap/PcapAnalysisPort.js";
+import { PcapProvider } from "../pcap/PcapProvider.js";
+
+/** Construct one pcap provider bound to the caller-selected tools. */
+export const createPcapAnalysisProvider = (
+ environment: Readonly> = process.env,
+): PcapAnalysisPort => new PcapProvider({ environment });
diff --git a/src/contracts/analysisViewToolContracts.ts b/src/contracts/analysisViewToolContracts.ts
index 1a4dbbb5c..aba5b9a93 100644
--- a/src/contracts/analysisViewToolContracts.ts
+++ b/src/contracts/analysisViewToolContracts.ts
@@ -16,7 +16,7 @@ export const ANALYSIS_VIEW_TOOL_CONTRACTS = [
...toolContractMetadata("inspect_analysis_view"),
kind: "application",
description:
- 'Inspect selected views of completed binary-layout, JavaScript application, native analyze_function, inspect_artifact, inventory_artifact, inspect_wasm_artifact, inspect_evm_interface, inspect_managed_artifact, inspect_android_package, inspect_dart_aot or inspect_web_network_capture Evidence without repeating analysis. Historical capture summaries return identity and counts without bodies or archive inventories. Capture views page retained records: view {kind: "capture", detail: "preview" | "complete", offset: 0, limit: 20}; preview selects recorded headline fields and binary descriptors, complete returns exact records with all sidecars. Offsets follow the selected parent record order, preserving original producer ordinals. Paging never reopens the source or reruns the decoder. Qlog summaries keep profile/scope and counts; kind qlog pages traces, streams, loss-declarations, incomplete-records, contributions, ranges or final-sizes. Except traces, select trace_index; stream-specific facets also require exact stream_id and direction. Facts retain all-recorded-events-before-selection scope, and interval overlap or endpoint loss declarations do not prove retransmission or network loss. The api-surface view groups retained HAR requests by method, origin and format-rule path template; templated segments are inferences. It reads no headers or bodies and reports no query values. For a retained record use source: {kind: "retained-evidence", evidence_id: ""}. Use normalized_result.parent_evidence_id from a summary receipt. Source kind is required. Portable source uses {kind: "inline", evidence: }. For layout, JavaScript, inventory, WASM, EVM, managed artifact, Android package and Dart AOT sources, request a summary with view: {kind: "summary"}; summary is a view kind and has no facet. The WASM summary gives validation, counts, WAT digest/length, tool profile and execution/network states without reading WAT text. Select a layout mitigations/linkage facet, one section/symbol/module, or a stable page. Module pages include assets, bundled and source modules; use node_id for ambiguous or unavailable paths. Inventory uses view: {kind: "inventory", collection: "occurrences", logical_paths: ["package.json"], offset: 0, limit: 64}. Inventory views page nodes, occurrences, edges or integrity contradictions; occurrence logical_paths matches exact recorded strings (omitted means all available, [] means none). source_complete distinguishes complete inventories from partial source records; page exhaustion does not prove absence in a partial source. WASM views use kind wasm and facet sections/imports/exports/candidates/glue/wat/headers/details/tool_profile; text facets use UTF-16 code units and source forms remain exact. EVM summary returns all inferred interface candidates, carrier/decoded identities and explicit unknowns without hex or duplicate stdout. EVM views use kind evm and facet functions/bytecode_hex/stdout/stderr; function pages preserve the original candidate rows, and text offsets/limits count UTF-16 code units (hex has two characters per decoded byte). Exhausting candidate pages does not establish global interface completeness. Managed artifact summaries preserve complete identity/classification, metadata status, module/MVID, frameworks, coverage and limitations without unrelated inventories. Managed pages use kind managed and collection references/resources/attributes, retaining source coverage and build-local token scope; page exhaustion does not establish complete metadata. Android package summaries retain all declarations, engine identity and counts without decoded manifest text. Android manifest pages use kind android, facet manifest, offset and limit in UTF-16 code units; source_status preserves partial decoded coverage even when the retained text page is exhausted. Dart AOT summary preserves target/ABI/library identity, snapshot headers and pool lower bounds. String pages use kind dart-aot, collection package_uris/dart_uris/class_like_tokens; source coverage remains partial when the producer says partial. Native function Evidence requires kind native: view: {kind: "native", facet: "procedure"}. Facets select procedure, pseudocode, assembly, basic blocks, comments, callers/callees, references, unresolved calls, referenced strings/names, native API and high-pcode. Use nonnegative offset and a positive caller-selected limit (defaults 0 and 64); pseudocode uses UTF-16 code units, other native pages use rows. Returns artifact identity, parent Evidence ID, a distinct view digest, coverage, limitations and unknowns. Actual serialized size determines MCP transport admission; choose a smaller page or export the complete retained Evidence if needed.',
+ 'Inspect selected views of completed binary-layout, JavaScript application, native analyze_function, inspect_artifact, inventory_artifact, inspect_wasm_artifact, inspect_evm_interface, inspect_managed_artifact, inspect_android_package, inspect_dart_aot or inspect_web_network_capture Evidence without repeating analysis. Historical capture summaries return identity and counts without bodies or archive inventories. Capture views page retained records: view {kind: "capture", detail: "preview" | "complete", offset: 0, limit: 20}; preview selects recorded headline fields and binary descriptors, complete returns exact records with all sidecars. Offsets follow the selected parent record order, preserving original producer ordinals. Paging never reopens the source or reruns the decoder. For inspect_pcap_capture parents, kind pcap pages endpoints, dns-queries, tls-sni, protocols, http-uris or unattributed-addresses. Select an exact query for dns-addresses, or a tshark/capinfos stream for UTF-16 diagnostics text. Page totals count retained facts; source coverage remains explicit. Qlog summaries keep profile/scope and counts; kind qlog pages traces, streams, loss-declarations, incomplete-records, contributions, ranges or final-sizes. Except traces, select trace_index; stream-specific facets also require exact stream_id and direction. Facts retain all-recorded-events-before-selection scope, and interval overlap or endpoint loss declarations do not prove retransmission or network loss. The api-surface view groups retained HAR requests by method, origin and format-rule path template; templated segments are inferences. It reads no headers or bodies and reports no query values. For a retained record use source: {kind: "retained-evidence", evidence_id: ""}. Use normalized_result.parent_evidence_id from a summary receipt. Source kind is required. Portable source uses {kind: "inline", evidence: }. For layout, JavaScript, inventory, WASM, EVM, managed artifact, Android package and Dart AOT sources, request a summary with view: {kind: "summary"}; summary is a view kind and has no facet. The WASM summary gives validation, counts, WAT digest/length, tool profile and execution/network states without reading WAT text. Select a layout mitigations/linkage facet, one section/symbol/module, or a stable page. Module pages include assets, bundled and source modules; use node_id for ambiguous or unavailable paths. Inventory uses view: {kind: "inventory", collection: "occurrences", logical_paths: ["package.json"], offset: 0, limit: 64}. Inventory views page nodes, occurrences, edges or integrity contradictions; occurrence logical_paths matches exact recorded strings (omitted means all available, [] means none). source_complete distinguishes complete inventories from partial source records; page exhaustion does not prove absence in a partial source. WASM views use kind wasm and facet sections/imports/exports/candidates/glue/wat/headers/details/tool_profile; text facets use UTF-16 code units and source forms remain exact. EVM summary returns all inferred interface candidates, carrier/decoded identities and explicit unknowns without hex or duplicate stdout. EVM views use kind evm and facet functions/bytecode_hex/stdout/stderr; function pages preserve the original candidate rows, and text offsets/limits count UTF-16 code units (hex has two characters per decoded byte). Exhausting candidate pages does not establish global interface completeness. Managed artifact summaries preserve complete identity/classification, metadata status, module/MVID, frameworks, coverage and limitations without unrelated inventories. Managed pages use kind managed and collection references/resources/attributes, retaining source coverage and build-local token scope; page exhaustion does not establish complete metadata. Android package summaries retain all declarations, engine identity and counts without decoded manifest text. Android manifest pages use kind android, facet manifest, offset and limit in UTF-16 code units; source_status preserves partial decoded coverage even when the retained text page is exhausted. Dart AOT summary preserves target/ABI/library identity, snapshot headers and pool lower bounds. String pages use kind dart-aot, collection package_uris/dart_uris/class_like_tokens; source coverage remains partial when the producer says partial. Native function Evidence requires kind native: view: {kind: "native", facet: "procedure"}. Facets select procedure, pseudocode, assembly, basic blocks, comments, callers/callees, references, unresolved calls, referenced strings/names, native API and high-pcode. Use nonnegative offset and a positive caller-selected limit (defaults 0 and 64); pseudocode uses UTF-16 code units, other native pages use rows. Returns artifact identity, parent Evidence ID, a distinct view digest, coverage, limitations and unknowns. Actual serialized size determines MCP transport admission; choose a smaller page or export the complete retained Evidence if needed.',
inputSchema: inspectAnalysisViewInputSchema,
outputSchema: evidenceResultOf(analysisViewResultSchema),
examples: [
diff --git a/src/contracts/applicationToolContracts.ts b/src/contracts/applicationToolContracts.ts
index 9a592b536..ade29e960 100644
--- a/src/contracts/applicationToolContracts.ts
+++ b/src/contracts/applicationToolContracts.ts
@@ -218,7 +218,7 @@ export const APPLICATION_TOOL_CONTRACTS = [
name: "evaluate_reconstruction_coverage",
...toolContractMetadata("evaluate_reconstruction_coverage"),
description:
- "Evaluate inline evidence-backed reconstruction coverage against one named boundary. Missing ownership or inventory is partial; stale, weak, truncated, skipped, or unresolved proof is unknown; contradictions, failed proof, missing owners, and authority routing fail closed.",
+ "Evaluate inline evidence-backed reconstruction coverage against one named boundary. Missing ownership or inventory is partial; stale, weak, truncated, skipped, unresolved, or conflicting tied verifier proof is unknown; contradictions, failed proof, missing owners, and authority routing fail closed.",
kind: "application",
inputSchema: reconstructionCoverageEvaluationInputSchema,
outputSchema: reconstructionClosureResultSchema,
diff --git a/src/contracts/pcap/pcapToolContracts.ts b/src/contracts/pcap/pcapToolContracts.ts
new file mode 100644
index 000000000..66f281b4e
--- /dev/null
+++ b/src/contracts/pcap/pcapToolContracts.ts
@@ -0,0 +1,46 @@
+import {
+ pcapInputSchemas,
+ pcapResultSchemas,
+} from "../../domain/pcap/pcapAnalysis.js";
+import type { ToolContract } from "../toolContractTypes.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import {
+ analysisDetailSchema,
+ analysisDetailOutputSchemaOf,
+} from "../analysisDetail.js";
+import { pcapCaptureSummaryViewResultSchema } from "../../domain/analysisView/analysisView.js";
+
+/** Packet-capture analysis served by caller-supplied tshark and capinfos. */
+export const PCAP_TOOL_CONTRACTS = [
+ {
+ name: "inspect_pcap_client",
+ ...toolContractMetadata("inspect_pcap_client"),
+ description:
+ "Inspect the caller-selected tshark and capinfos binaries: selected commands, selection sources, and versions. Both tools must be usable. Reads no capture file. REA never installs the Wireshark suite; select binaries with REA_TSHARK_COMMAND and REA_CAPINFOS_COMMAND (absolute) or from PATH.",
+ kind: "pcap-provider",
+ inputSchema: pcapInputSchemas.inspect_pcap_client,
+ outputSchema: evidenceResultOf(pcapResultSchemas.inspect_pcap_client),
+ examples: [{ title: "Check the analysis tools", input: {} }],
+ },
+ {
+ name: "inspect_pcap_capture",
+ ...toolContractMetadata("inspect_pcap_capture"),
+ description:
+ "Request detail summary for capture identity/counts, then page retained facts with inspect_analysis_view kind pcap. Default detail complete preserves inline delivery. Inspect one saved pcap or pcapng capture through an owned snapshot: metadata, exact packet count, SHA-256, IPv4/IPv6 address counts, DNS questions and address values from the same single-question response, TLS SNI, protocol distribution and HTTP URIs. All derived inventories are retained within declared resource budgets; unknown DNS attribution and excluded credentials remain explicit. Linux requires util-linux prlimit; Windows uses owned Job Objects. Requires caller-supplied capinfos and tshark; REA never captures traffic.",
+ kind: "pcap-provider",
+ inputSchema: pcapInputSchemas.inspect_pcap_capture.extend({
+ detail: analysisDetailSchema,
+ }),
+ outputSchema: analysisDetailOutputSchemaOf(
+ pcapResultSchemas.inspect_pcap_capture,
+ pcapCaptureSummaryViewResultSchema,
+ ),
+ examples: [
+ {
+ title: "Inspect a capture file",
+ input: { path: "/captures/session.pcap" },
+ },
+ ],
+ },
+] as const satisfies readonly ToolContract[];
diff --git a/src/contracts/toolContractTypes.ts b/src/contracts/toolContractTypes.ts
index d7e19d37e..de5f53411 100644
--- a/src/contracts/toolContractTypes.ts
+++ b/src/contracts/toolContractTypes.ts
@@ -33,6 +33,7 @@ export const TOOL_KINDS = [
"browser-provider",
"electron-provider",
"runtime-provider",
+ "pcap-provider",
"application",
"session",
] as const;
diff --git a/src/contracts/toolContracts.ts b/src/contracts/toolContracts.ts
index 101cca17e..2fdac1fbe 100644
--- a/src/contracts/toolContracts.ts
+++ b/src/contracts/toolContracts.ts
@@ -12,6 +12,7 @@ import { MANAGED_TOOL_CONTRACTS } from "./managed/managedToolContracts.js";
import { FIRMWARE_TOOL_CONTRACTS } from "./firmware/firmwareToolContracts.js";
import { ANDROID_TOOL_CONTRACTS } from "./android/androidToolContracts.js";
import { APKTOOL_TOOL_CONTRACTS } from "./apktool/apktoolToolContracts.js";
+import { PCAP_TOOL_CONTRACTS } from "./pcap/pcapToolContracts.js";
import { FLUTTER_TOOL_CONTRACTS } from "./flutter/flutterToolContracts.js";
import { JEB_TOOL_CONTRACTS } from "./jeb/jebToolContracts.js";
import { ADB_TOOL_CONTRACTS } from "./adb/adbToolContracts.js";
@@ -46,6 +47,7 @@ export const TOOL_CONTRACTS = [
...MANAGED_TOOL_CONTRACTS,
...ANDROID_TOOL_CONTRACTS,
...APKTOOL_TOOL_CONTRACTS,
+ ...PCAP_TOOL_CONTRACTS,
...FLUTTER_TOOL_CONTRACTS,
...JEB_TOOL_CONTRACTS,
...ADB_TOOL_CONTRACTS,
diff --git a/src/contracts/toolEffects.test.ts b/src/contracts/toolEffects.test.ts
index 5c906a170..b304ab429 100644
--- a/src/contracts/toolEffects.test.ts
+++ b/src/contracts/toolEffects.test.ts
@@ -45,6 +45,8 @@ const EXECUTION_WORDING_EXCEPTIONS: Readonly> = {
search_android_classes: "states it does not execute the APK",
inspect_apktool_client:
"inspects the operator-selected apktool launcher; never installs it",
+ inspect_pcap_client:
+ "probes the operator-selected tshark and capinfos; never installs them",
inspect_jeb_client: "talks to a caller-started JEB; never launches it",
open_jeb_project: "the engine analyzes the file; REA does not execute it",
inspect_adb_client:
diff --git a/src/contracts/toolEffects.ts b/src/contracts/toolEffects.ts
index 4b0d0b745..7ce3e4ded 100644
--- a/src/contracts/toolEffects.ts
+++ b/src/contracts/toolEffects.ts
@@ -182,6 +182,16 @@ export const TOOL_EFFECTS: Readonly> = {
launchesProcess: true,
writesFilesystem: true,
}),
+ inspect_pcap_client: effects({
+ mutatesSession: true,
+ launchesProcess: true,
+ writesFilesystem: true,
+ }),
+ inspect_pcap_capture: effects({
+ mutatesSession: true,
+ launchesProcess: true,
+ writesFilesystem: true,
+ }),
identify_flutter_build: effects({
mutatesSession: true,
writesFilesystem: true,
diff --git a/src/domain/analysisProfile.test.ts b/src/domain/analysisProfile.test.ts
index 1fb18f0ae..a39fb389d 100644
--- a/src/domain/analysisProfile.test.ts
+++ b/src/domain/analysisProfile.test.ts
@@ -65,4 +65,11 @@ describe("analysis profile commitments", () => {
analysisProfileSchema.parse({ ...profile, digest: "0".repeat(64) }),
).toThrow(/digest/u);
});
+
+ it("projects known provider identity fields at construction", () => {
+ const liveProvider = { ...PROVIDER, transient_status: "starting" };
+ const profile = createAnalysisProfile(liveProvider, { loader: "default" });
+ expect(profile.provider).toEqual(PROVIDER);
+ expect(analysisProfileSchema.parse(profile)).toEqual(profile);
+ });
});
diff --git a/src/domain/analysisProfile.ts b/src/domain/analysisProfile.ts
index 6719e2ccd..f6e6e0004 100644
--- a/src/domain/analysisProfile.ts
+++ b/src/domain/analysisProfile.ts
@@ -7,13 +7,13 @@ import { jsonObjectSchema, type JsonValue } from "./jsonValue.js";
import { digestSchema } from "./../domain/digests.js";
/** Concrete provider identity committed by an analysis profile. */
-export const committedProviderSchema = z.object({
+export const committedProviderSchema = z.strictObject({
id: z.string().min(1),
name: z.string().min(1),
version: z.string().min(1),
});
-const unsignedAnalysisProfileSchema = z.object({
+const unsignedAnalysisProfileSchema = z.strictObject({
provider: committedProviderSchema,
parameters: jsonObjectSchema,
});
@@ -40,7 +40,11 @@ export const createAnalysisProfile = (
parameters: Readonly>,
): AnalysisProfileCommitment => {
const unsigned = unsignedAnalysisProfileSchema.parse({
- provider,
+ provider: {
+ id: provider.id,
+ name: provider.name,
+ version: provider.version,
+ },
parameters,
});
return analysisProfileSchema.parse({
diff --git a/src/domain/analysisView/analysisView.test.ts b/src/domain/analysisView/analysisView.test.ts
index 631f9d506..f1aa3e829 100644
--- a/src/domain/analysisView/analysisView.test.ts
+++ b/src/domain/analysisView/analysisView.test.ts
@@ -1,6 +1,5 @@
import { expect, it } from "vitest";
-import { resolveJavaScriptSourceMapReference } from "../javascript/javascriptSourceMapPaths.js";
import { functionDossierSchema } from "../hopperValues.js";
import { ghidraFunctionDossier } from "../ghidraValues.fixture.js";
import { JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE } from "../../contracts/javascript/javascriptRuntimeReconciliationExample.js";
@@ -24,13 +23,14 @@ import {
completeWithinViewCoverage,
pageViewCoverage,
} from "./analysisViewCoverage.js";
+import { sourceMapReference } from "../javascript/javascriptApplicationGraph.fixture.js";
import { javascriptModulePath } from "./javascriptApplicationView.js";
-
import {
inspectAnalysisViewInputSchema,
projectAnalysisView,
type AnalysisViewParent,
} from "./analysisView.js";
+
const layoutParent = (): AnalysisViewParent => {
const evidence = analysisViewLayoutEvidence();
return {
@@ -532,7 +532,7 @@ it("pages actual modules, including unknown and empty paths, without unrelated r
observations: original.observations.map((observation) => ({
...(kind === "source-module"
? {
- source_map_reference: resolveJavaScriptSourceMapReference(
+ source_map_reference: sourceMapReference(
"",
null,
"renderer.js",
diff --git a/src/domain/analysisView/analysisView.ts b/src/domain/analysisView/analysisView.ts
index 48eee73f0..6cc5ae8a3 100644
--- a/src/domain/analysisView/analysisView.ts
+++ b/src/domain/analysisView/analysisView.ts
@@ -62,6 +62,12 @@ import {
captureSummarySchema,
} from "./webNetworkCaptureView.js";
import type { WebNetworkApiSurfaceAccumulator } from "./WebNetworkApiSurfaceAccumulator.js";
+import {
+ pcapViewRequestSchema,
+ pcapViewPageSchema,
+ pcapSummarySchema,
+ projectPcapCaptureView,
+} from "./pcapCaptureView.js";
import {
qlogViewRequestSchema,
qlogViewPageSchema,
@@ -196,6 +202,7 @@ export const analysisViewRequestSchema = z.discriminatedUnion("kind", [
apiSurfaceViewSchema,
captureViewRequestSchema,
qlogViewRequestSchema,
+ pcapViewRequestSchema,
dartAotViewRequestSchema,
]);
@@ -312,6 +319,7 @@ const viewResultBase = {
"inspect_managed_artifact",
"inspect_web_network_capture",
"inspect_android_package",
+ "inspect_pcap_capture",
"inspect_dart_aot",
]),
parent_digest: digestSchema,
@@ -384,6 +392,12 @@ export const androidPackageSummaryViewResultSchema = z.strictObject({
summary: androidPackageSummarySchema,
});
+export const pcapCaptureSummaryViewResultSchema = z.strictObject({
+ ...summaryViewResultBase,
+ parent_operation: z.literal("inspect_pcap_capture"),
+ summary: pcapSummarySchema,
+});
+
/** Exact snapshot and pool-coverage carrier for selected AOT delivery. */
export const dartAotSummaryViewResultSchema = z.strictObject({
...summaryViewResultBase,
@@ -415,6 +429,7 @@ export const analysisViewResultSchema = z.discriminatedUnion("kind", [
managedSummarySchema,
captureSummarySchema,
androidPackageSummarySchema,
+ pcapSummarySchema,
dartAotSummarySchema,
]),
}),
@@ -433,6 +448,14 @@ export const analysisViewResultSchema = z.discriminatedUnion("kind", [
...viewResultBase,
parent_operation: z.literal("inspect_web_network_capture"),
}),
+ z.strictObject({
+ kind: z.literal("pcap"),
+ view: pcapViewRequestSchema,
+ page: pcapViewPageSchema,
+ source_coverage: z.enum(["complete", "partial"]),
+ ...viewResultBase,
+ parent_operation: z.literal("inspect_pcap_capture"),
+ }),
z.strictObject({
kind: z.literal("facet"),
view: facetViewSchema,
@@ -562,6 +585,7 @@ export type UnsignedAnalysisView =
| Omit, "view_digest">
| Omit, "view_digest">
| Omit, "view_digest">
+ | Omit, "view_digest">
| Omit<
Extract,
"view_digest"
@@ -686,6 +710,10 @@ export const projectAnalysisView = (
const projected = projectWebNetworkCaptureView(parent, view);
return projected.ok ? ok(sealAnalysisView(projected.value)) : projected;
}
+ if (parent.operation === "inspect_pcap_capture") {
+ const projected = projectPcapCaptureView(parent, view);
+ return projected.ok ? ok(sealAnalysisView(projected.value)) : projected;
+ }
if (parent.operation === "inspect_binary_layout") {
const layout = binaryLayoutSchema.safeParse(parent.normalizedResult);
if (!layout.success)
diff --git a/src/domain/analysisView/evmInterfaceView.ts b/src/domain/analysisView/evmInterfaceView.ts
index a7b343291..d9f3994d4 100644
--- a/src/domain/analysisView/evmInterfaceView.ts
+++ b/src/domain/analysisView/evmInterfaceView.ts
@@ -76,6 +76,7 @@ export const projectEvmInterfaceView = (
const report = parsed.data;
if (
parent.subject == null ||
+ parent.subject.format !== "file" ||
parent.subject.local_path !== report.artifact.path ||
parent.subject.digest.sha256 !== report.artifact.sha256
)
diff --git a/src/domain/analysisView/pcapCaptureView.ts b/src/domain/analysisView/pcapCaptureView.ts
new file mode 100644
index 000000000..a28398d44
--- /dev/null
+++ b/src/domain/analysisView/pcapCaptureView.ts
@@ -0,0 +1,327 @@
+import { z } from "zod";
+import { pcapResultSchemas } from "../pcap/pcapAnalysis.js";
+import { analysisInputErrorFromIssues } from "../inputIssueProjection.js";
+import type { AnalysisError } from "../analysisErrorBase.js";
+import { err, ok, type Result } from "../result.js";
+import {
+ analysisViewInputError,
+ type AnalysisViewParent,
+ type AnalysisViewRequest,
+ type UnsignedAnalysisView,
+} from "./analysisView.js";
+import {
+ completeWithinViewCoverage,
+ pageViewCoverage,
+} from "./analysisViewCoverage.js";
+
+const captureSchema = pcapResultSchemas.inspect_pcap_capture;
+const fields = captureSchema.shape;
+const pageShape = {
+ kind: z.literal("pcap"),
+ offset: z.number().int().nonnegative().default(0),
+ limit: z.number().int().positive().default(64),
+};
+export const pcapViewRequestSchema = z.discriminatedUnion("facet", [
+ z.strictObject({
+ ...pageShape,
+ facet: z.enum([
+ "endpoints",
+ "dns-queries",
+ "tls-sni",
+ "protocols",
+ "http-uris",
+ "unattributed-addresses",
+ ]),
+ }),
+ z.strictObject({
+ ...pageShape,
+ facet: z.literal("dns-addresses"),
+ query: z.string().min(1),
+ }),
+ z.strictObject({
+ ...pageShape,
+ facet: z.literal("diagnostics"),
+ stream: z.enum(["tshark", "capinfos"]),
+ }),
+]);
+export const pcapViewPageSchema = z.discriminatedUnion("facet", [
+ z.strictObject({ facet: z.literal("endpoints"), items: fields.endpoints }),
+ z.strictObject({
+ facet: z.literal("dns-queries"),
+ items: z.array(
+ fields.dns_queries.element.omit({ response_addresses: true }).extend({
+ retained_response_address_count: z.number().int().nonnegative(),
+ }),
+ ),
+ }),
+ z.strictObject({ facet: z.literal("tls-sni"), items: fields.tls_sni_values }),
+ z.strictObject({
+ facet: z.literal("protocols"),
+ items: fields.protocol_distribution,
+ }),
+ z.strictObject({
+ facet: z.literal("http-uris"),
+ items: fields.http_request_uris,
+ }),
+ z.strictObject({
+ facet: z.literal("unattributed-addresses"),
+ items: fields.unattributed_dns_addresses,
+ }),
+ z.strictObject({
+ facet: z.literal("dns-addresses"),
+ items: fields.unattributed_dns_addresses,
+ }),
+ z.strictObject({
+ facet: z.literal("diagnostics"),
+ text: z.string(),
+ status: z.enum(["retained", "unknown"]),
+ }),
+]);
+export const pcapSummarySchema = captureSchema
+ .omit({
+ endpoints: true,
+ dns_queries: true,
+ tls_sni_values: true,
+ protocol_distribution: true,
+ http_request_uris: true,
+ unattributed_dns_addresses: true,
+ diagnostics: true,
+ })
+ .extend({
+ retained_counts: z.strictObject({
+ endpoints: z.number().int().nonnegative(),
+ dns_queries: z.number().int().nonnegative(),
+ tls_sni_values: z.number().int().nonnegative(),
+ protocol_distribution: z.number().int().nonnegative(),
+ http_request_uris: z.number().int().nonnegative(),
+ unattributed_dns_addresses: z.number().int().nonnegative(),
+ }),
+ diagnostics_code_units: z
+ .strictObject({
+ tshark: z.number().int().nonnegative(),
+ capinfos: z.number().int().nonnegative(),
+ })
+ .nullable(),
+ });
+type Capture = z.output;
+type PcapView = z.output;
+type Page = z.output;
+
+const parseParent = (
+ parent: AnalysisViewParent,
+): Result => {
+ const parsed = captureSchema.safeParse(parent.normalizedResult);
+ if (!parsed.success)
+ return err(
+ analysisInputErrorFromIssues(
+ "inspect_analysis_view",
+ parsed.error.issues,
+ parent.normalizedResult,
+ { cause: parsed.error },
+ ),
+ );
+ if (
+ parent.subject?.local_path !== parsed.data.target.path ||
+ parent.subject.digest.sha256 !== parsed.data.target.sha256
+ )
+ return err(
+ analysisViewInputError([
+ {
+ path: ["source", "subject"],
+ reason: "invalid_value",
+ message:
+ "Packet parent subject must identify the report's exact path and SHA-256.",
+ },
+ ]),
+ );
+ return ok(parsed.data);
+};
+const summarize = ({
+ endpoints,
+ dns_queries,
+ tls_sni_values,
+ protocol_distribution,
+ http_request_uris,
+ unattributed_dns_addresses,
+ diagnostics,
+ ...metadata
+}: Capture) => ({
+ ...metadata,
+ retained_counts: {
+ endpoints: endpoints.length,
+ dns_queries: dns_queries.length,
+ tls_sni_values: tls_sni_values.length,
+ protocol_distribution: protocol_distribution.length,
+ http_request_uris: http_request_uris.length,
+ unattributed_dns_addresses: unattributed_dns_addresses.length,
+ },
+ diagnostics_code_units:
+ diagnostics === undefined
+ ? null
+ : {
+ tshark: diagnostics.tshark_stderr.length,
+ capinfos: diagnostics.capinfos_stderr.length,
+ },
+});
+
+const selectRows = (
+ capture: Capture,
+ view: Exclude,
+): Result<
+ { page: Exclude; total: number },
+ AnalysisError
+> => {
+ const slice = (items: readonly T[]) =>
+ items.slice(view.offset, view.offset + view.limit);
+ switch (view.facet) {
+ case "endpoints":
+ return ok({
+ page: { facet: view.facet, items: slice(capture.endpoints) },
+ total: capture.endpoints.length,
+ });
+ case "dns-queries":
+ return ok({
+ page: {
+ facet: view.facet,
+ items: slice(capture.dns_queries).map(
+ ({ response_addresses, ...query }) => ({
+ ...query,
+ retained_response_address_count: response_addresses.length,
+ }),
+ ),
+ },
+ total: capture.dns_queries.length,
+ });
+ case "tls-sni":
+ return ok({
+ page: { facet: view.facet, items: slice(capture.tls_sni_values) },
+ total: capture.tls_sni_values.length,
+ });
+ case "protocols":
+ return ok({
+ page: {
+ facet: view.facet,
+ items: slice(capture.protocol_distribution),
+ },
+ total: capture.protocol_distribution.length,
+ });
+ case "http-uris":
+ return ok({
+ page: { facet: view.facet, items: slice(capture.http_request_uris) },
+ total: capture.http_request_uris.length,
+ });
+ case "unattributed-addresses":
+ return ok({
+ page: {
+ facet: view.facet,
+ items: slice(capture.unattributed_dns_addresses),
+ },
+ total: capture.unattributed_dns_addresses.length,
+ });
+ case "dns-addresses": {
+ const matches = capture.dns_queries.filter(
+ (query) => query.query === view.query,
+ );
+ if (matches.length !== 1)
+ return err(
+ analysisViewInputError([
+ {
+ path: ["view", "query"],
+ reason: "invalid_value",
+ message: "Select one unambiguous exact retained DNS question.",
+ },
+ ]),
+ );
+ return ok({
+ page: {
+ facet: view.facet,
+ items: slice(matches[0]!.response_addresses),
+ },
+ total: matches[0]!.response_addresses.length,
+ });
+ }
+ }
+};
+
+/** Historical packet facts are paged without reopening the source or rerunning Wireshark. */
+export const projectPcapCaptureView = (
+ parent: AnalysisViewParent,
+ view: AnalysisViewRequest,
+): Result => {
+ if (view.kind !== "summary" && view.kind !== "pcap")
+ return err(
+ analysisViewInputError([
+ {
+ path: ["view"],
+ reason: "invalid_value",
+ message:
+ "Packet summary parents support summary and pcap fact pages.",
+ },
+ ]),
+ );
+ const parsed = parseParent(parent);
+ if (!parsed.ok) return parsed;
+ const capture = parsed.value;
+ const shared = {
+ parent_evidence_id: parent.evidenceId,
+ parent_operation: "inspect_pcap_capture" as const,
+ parent_digest: parent.evidenceId.slice(3),
+ artifact: { path: capture.target.path, sha256: capture.target.sha256 },
+ limitations: [
+ ...parent.limitations,
+ "Page totals count retained rows or UTF-16 diagnostic code units. Exhaustion does not prove whole-network completeness; source coverage and examined counts remain separate.",
+ ],
+ unknowns: [
+ "Saved packet observations do not establish process identity, causality, encrypted payload contents or traffic missing from the recording.",
+ ],
+ };
+ if (view.kind === "summary")
+ return ok({
+ kind: "summary",
+ view,
+ ...shared,
+ summary: summarize(capture),
+ coverage: completeWithinViewCoverage(1, 1),
+ });
+ if (view.facet === "diagnostics") {
+ const value =
+ view.stream === "tshark"
+ ? capture.diagnostics?.tshark_stderr
+ : capture.diagnostics?.capinfos_stderr;
+ const text = value?.slice(view.offset, view.offset + view.limit) ?? "";
+ return ok({
+ kind: "pcap",
+ view,
+ ...shared,
+ source_coverage: capture.coverage,
+ page: {
+ facet: "diagnostics",
+ text,
+ status: value === undefined ? "unknown" : "retained",
+ },
+ coverage: pageViewCoverage(view.offset, text.length, value?.length ?? 0),
+ unknowns:
+ value === undefined
+ ? [
+ ...shared.unknowns,
+ "The parent did not retain diagnostics; an empty text page does not establish their absence.",
+ ]
+ : shared.unknowns,
+ });
+ }
+ const selected = selectRows(capture, view);
+ return selected.ok
+ ? ok({
+ kind: "pcap",
+ view,
+ ...shared,
+ source_coverage: capture.coverage,
+ page: selected.value.page,
+ coverage: pageViewCoverage(
+ view.offset,
+ selected.value.page.items.length,
+ selected.value.total,
+ ),
+ })
+ : selected;
+};
diff --git a/src/domain/analysisView/wasmArtifactView.ts b/src/domain/analysisView/wasmArtifactView.ts
index 111078600..dc3036b26 100644
--- a/src/domain/analysisView/wasmArtifactView.ts
+++ b/src/domain/analysisView/wasmArtifactView.ts
@@ -103,6 +103,7 @@ export const projectWasmArtifactView = (
: {
path: parent.subject.local_path,
sha256: parent.subject.digest.sha256,
+ format: parent.subject.format,
},
)
)
diff --git a/src/domain/evidence.test.ts b/src/domain/evidence.test.ts
index c5898aecc..5cdf30a27 100644
--- a/src/domain/evidence.test.ts
+++ b/src/domain/evidence.test.ts
@@ -52,6 +52,30 @@ it("preserves omitted relationship diagnostics and authenticates reported diagno
).toThrow("semantic identifier");
});
+it("projects known provider fields and preserves open JSON payloads", () => {
+ const liveProvider = { ...PROVIDER, transient_status: "starting" };
+ const evidence = createEvidence(TARGET, liveProvider, {
+ operation: "inspect",
+ parameters: { caller_metadata: { note: "kept" } },
+ result: { producer_extension: { value: "kept" } },
+ analysisProfile: PROFILE,
+ environment: {
+ id: "fixture",
+ platform: "linux",
+ architecture: "x86_64",
+ isolation: "process",
+ },
+ locations: [{ kind: "address", address: "0x1000" }],
+ });
+
+ expect(evidence.provider).toEqual(PROVIDER);
+ expect(evidence.parameters).toEqual({ caller_metadata: { note: "kept" } });
+ expect(evidence.normalized_result).toEqual({
+ producer_extension: { value: "kept" },
+ });
+ expect(parseEvidence(evidence)).toEqual(evidence);
+});
+
it("preserves identity and bytes when reusing an owned immutable result", () => {
const value = { nested: { values: ["observed", 1] } };
const mutable = createEvidence(TARGET, PROVIDER, {
diff --git a/src/domain/evidence.ts b/src/domain/evidence.ts
index 6aaac7226..bcf1c990e 100644
--- a/src/domain/evidence.ts
+++ b/src/domain/evidence.ts
@@ -33,14 +33,14 @@ import {
} from "./relationshipCoverage.js";
/** Provider identity schema shared by evidence-bearing persistence formats. */
-export const providerSchema = z.object({
+export const providerSchema = z.strictObject({
id: z.string().min(1),
name: z.string().min(1),
version: z.string().nullable(),
});
-const subjectSchema = z.object({
+const subjectSchema = z.strictObject({
name: z.string().min(1),
- digest: z.object({ sha256: digestSchema }),
+ digest: z.strictObject({ sha256: digestSchema }),
format: z.enum([
"hopper",
"analysis-database",
@@ -78,15 +78,18 @@ const subjectSchema = z.object({
/** Source location attached to an evidence observation. */
/** Source-location schema shared by evidence-bearing persistence formats. */
export const evidenceLocationSchema = z.discriminatedUnion("kind", [
- z.object({ kind: z.literal("address"), address: z.string().min(1) }),
- z.object({
+ z.strictObject({ kind: z.literal("address"), address: z.string().min(1) }),
+ z.strictObject({
kind: z.literal("address-range"),
start: z.string().min(1),
end: z.string().min(1),
}),
- z.object({ kind: z.literal("artifact-path"), path: z.string().min(1) }),
- z.object({ kind: z.literal("file-offset"), offset: z.number().int().min(0) }),
- z.object({
+ z.strictObject({ kind: z.literal("artifact-path"), path: z.string().min(1) }),
+ z.strictObject({
+ kind: z.literal("file-offset"),
+ offset: z.number().int().min(0),
+ }),
+ z.strictObject({
kind: z.literal("file-offset-range"),
start: z.number().int().min(0),
end: z.number().int().min(0),
@@ -101,7 +104,7 @@ const evidenceAuthoritySchema = z.enum([
"analyst-inference",
]);
-const executionEnvironmentSchema = z.object({
+const executionEnvironmentSchema = z.strictObject({
id: z.string().min(1),
platform: z.string().min(1),
architecture: z.string().min(1),
diff --git a/src/domain/evidenceBundle.ts b/src/domain/evidenceBundle.ts
index c1fa3ce1c..7e6fd2b3b 100644
--- a/src/domain/evidenceBundle.ts
+++ b/src/domain/evidenceBundle.ts
@@ -16,24 +16,27 @@ import {
} from "./residualUnknown.js";
import { freezeJsonSnapshot } from "./immutableJson.js";
-const artifactManifestSchema = evidenceSchema.shape.subject.unwrap().pick({
- digest: true,
- format: true,
- architecture: true,
-});
+const artifactManifestSchema = evidenceSchema.shape.subject
+ .unwrap()
+ .pick({
+ digest: true,
+ format: true,
+ architecture: true,
+ })
+ .strict();
const providerManifestSchema = providerSchema;
const environmentManifestSchema = evidenceSchema.shape.environment.unwrap();
-const scenarioManifestSchema = z.object({
+const scenarioManifestSchema = z.strictObject({
evidence_id: evidenceSchema.shape.evidence_id,
operation: z.string().min(1),
authority: z.literal("controlled-replay"),
});
-const captureManifestSchema = z.object({
+const captureManifestSchema = z.strictObject({
evidence_id: evidenceSchema.shape.evidence_id,
predicate_type: z.string().min(1),
});
-export const evidenceBundleSchema = z.object({
+export const evidenceBundleSchema = z.strictObject({
artifacts: z.array(artifactManifestSchema),
providers: z.array(providerManifestSchema),
environments: z.array(environmentManifestSchema),
diff --git a/src/domain/functionComparison.test.ts b/src/domain/functionComparison.test.ts
index acb505dac..e03a27748 100644
--- a/src/domain/functionComparison.test.ts
+++ b/src/domain/functionComparison.test.ts
@@ -119,6 +119,34 @@ const observe = (
);
describe("function comparison normalized identity", () => {
+ it("keeps differing generated names ambiguous and stable names mismatched", () => {
+ const named = (base: "0x1000" | "0x2000", name: string) =>
+ functionDossierSchema.parse({
+ ...dossier("return 0;", base),
+ procedure: {
+ ...procedure(base, name),
+ signature: "int helper(void)",
+ locals: [],
+ },
+ });
+ const generated = compareFunctions(
+ observe("1", named("0x1000", "sub_1000")),
+ observe("2", named("0x2000", "sub_2000")),
+ );
+ expect(generated.function_match.status).toBe("ambiguous");
+ expect(generated.status).toBe("unknown");
+ expect(
+ generated.dimensions.find(({ dimension }) => dimension === "identity"),
+ ).toMatchObject({ status: "unknown" });
+
+ const stable = compareFunctions(
+ observe("3", named("0x1000", "firstFunction")),
+ observe("4", named("0x2000", "secondFunction")),
+ );
+ expect(stable.function_match.status).toBe("mismatched");
+ expect(stable.status).toBe("changed");
+ });
+
it.each(["sub_deallocate", "sub_deadbeef_handler", "fcn.dispatch"])(
"recognizes the explicit symbol %s without a generated-name prefix false positive",
(name) => {
diff --git a/src/domain/functionComparisonNormalization.ts b/src/domain/functionComparisonNormalization.ts
index a676e1e49..5282272e1 100644
--- a/src/domain/functionComparisonNormalization.ts
+++ b/src/domain/functionComparisonNormalization.ts
@@ -16,24 +16,21 @@ export const functionMatch = (
left: FunctionSnapshot,
right: FunctionSnapshot,
): FunctionComparisonResult["function_match"] => {
- if (
- !isAutoName(left.dossier.procedure.name) &&
- left.dossier.procedure.name === right.dossier.procedure.name
- )
+ const leftName = left.dossier.procedure.name;
+ const rightName = right.dossier.procedure.name;
+ const stableNames = !isAutoName(leftName) && !isAutoName(rightName);
+ if (stableNames && leftName === rightName)
return {
status: "matched",
method: "symbol",
- left_name: left.dossier.procedure.name,
- right_name: right.dossier.procedure.name,
+ left_name: leftName,
+ right_name: rightName,
};
return {
- status:
- left.dossier.procedure.name === right.dossier.procedure.name
- ? "ambiguous"
- : "mismatched",
+ status: stableNames ? "mismatched" : "ambiguous",
method: "explicit",
- left_name: left.dossier.procedure.name,
- right_name: right.dossier.procedure.name,
+ left_name: leftName,
+ right_name: rightName,
};
};
diff --git a/src/domain/javascript/javascriptApplicationGraph.fixture.ts b/src/domain/javascript/javascriptApplicationGraph.fixture.ts
index 3002b822f..0e78e5115 100644
--- a/src/domain/javascript/javascriptApplicationGraph.fixture.ts
+++ b/src/domain/javascript/javascriptApplicationGraph.fixture.ts
@@ -6,6 +6,7 @@ import {
} from "./javascriptApplicationGraph.js";
import type { ApplicationNode } from "./javascriptApplicationGraphSchemas.js";
import type { ApplicationGraphEvidence } from "./javascriptApplicationEvidenceSchemas.js";
+import { resolveJavaScriptSourceMapReferences } from "./javascriptSourceMapPaths.js";
export const APPLICATION_GRAPH_DIGESTS = {
package: "1".repeat(64),
@@ -22,6 +23,20 @@ export const completeCoverage = {
limits: [],
} satisfies ApplicationGraphEvidence["coverage"];
+export const sourceMapReference = (
+ sourceName: string,
+ sourceRoot: string | null,
+ mapPath: string,
+) => {
+ const reference = resolveJavaScriptSourceMapReferences(
+ [sourceName],
+ sourceRoot,
+ mapPath,
+ )[0];
+ if (reference == null) throw new TypeError("Expected a source-map reference");
+ return reference;
+};
+
const extractor = (operation: string) => ({
name: "rea-test-fixture",
version: "1.0.0",
diff --git a/src/domain/javascript/javascriptApplicationGraph.test.ts b/src/domain/javascript/javascriptApplicationGraph.test.ts
index 5e396a545..5bf917480 100644
--- a/src/domain/javascript/javascriptApplicationGraph.test.ts
+++ b/src/domain/javascript/javascriptApplicationGraph.test.ts
@@ -20,10 +20,9 @@ import {
inferredArtifactEvidence,
nodeByLabel,
runtimeEvidence,
+ sourceMapReference,
unknownEvidence,
} from "./javascriptApplicationGraph.fixture.js";
-
-import { resolveJavaScriptSourceMapReference } from "./javascriptSourceMapPaths.js";
const createLargeNativeExportGraph = (): JavaScriptApplicationGraph => {
const properties = Object.fromEntries(
Array.from({ length: 1_001 }, (_, index) => [
@@ -438,7 +437,7 @@ describe("JavaScript Application Graph: source maps and observations", () => {
observations: [
{
label: "src/editor.ts",
- source_map_reference: resolveJavaScriptSourceMapReference(
+ source_map_reference: sourceMapReference(
"webpack:///src/editor.ts",
null,
"dist/app.js.map",
@@ -535,7 +534,7 @@ describe("JavaScript Application Graph: source-map digest consistency", () => {
observations: [
{
label: null,
- source_map_reference: resolveJavaScriptSourceMapReference(
+ source_map_reference: sourceMapReference(
"src/editor.ts",
null,
"dist/app.js.map",
diff --git a/src/domain/javascript/javascriptSourceMapPaths.ts b/src/domain/javascript/javascriptSourceMapPaths.ts
index d897bdd26..06b5f8265 100644
--- a/src/domain/javascript/javascriptSourceMapPaths.ts
+++ b/src/domain/javascript/javascriptSourceMapPaths.ts
@@ -1,5 +1,6 @@
import { posix } from "node:path";
import { domainToASCII, fileURLToPath, pathToFileURL } from "node:url";
+import { TraceMap } from "@jridgewell/trace-mapping";
import { z } from "zod";
@@ -25,22 +26,64 @@ export type JavaScriptSourceMapReference = z.infer<
typeof javascriptSourceMapReferenceSchema
>;
-/** Interpret a declaration once at the source-map ingestion boundary. */
-export const resolveJavaScriptSourceMapReference = (
- sourceName: string,
+/** Interpret declarations together once at their source-map ingestion boundary. */
+export const resolveJavaScriptSourceMapReferences = (
+ sourceNames: readonly (string | null)[],
sourceRoot: string | null,
mapPath: string,
-): JavaScriptSourceMapReference => {
- // TraceMap's producer prefixes sourceRoot before resolving the URL reference.
- const reference = `${sourceRoot ? `${sourceRoot}/` : ""}${sourceName}`;
- return {
- source_name: sourceName,
- source_root: sourceRoot,
- map_path: mapPath,
- resolution: resolveJavaScriptSourceMapPath(reference, mapPath),
- };
+): (JavaScriptSourceMapReference | null)[] => {
+ if (sourceNames.length === 0) return [];
+ const resolvedSources = resolveSourceMapUrls(
+ sourceNames.map((sourceName) => sourceName ?? ""),
+ sourceRoot,
+ "",
+ );
+ return sourceNames.map((sourceName, index) => {
+ if (sourceName === null) return null;
+ const reference = resolvedSources[index];
+ if (reference === undefined)
+ throw new TypeError(
+ `TraceMap did not resolve source declaration ${String(index)}`,
+ );
+ return {
+ source_name: sourceName,
+ source_root: sourceRoot,
+ map_path: mapPath,
+ resolution: resolveJavaScriptSourceMapPath(reference, mapPath),
+ };
+ });
};
+/** Resolve a source declaration using the same pinned format implementation as map consumers. */
+export const resolveJavaScriptSourceMapUrl = (
+ source: string | null,
+ sourceRoot: string | null | undefined,
+ mapUrl: string,
+): string => {
+ const resolved = resolveSourceMapUrls([source ?? ""], sourceRoot, mapUrl)[0];
+ if (resolved === undefined)
+ throw new TypeError(
+ "TraceMap did not resolve its single source declaration",
+ );
+ return resolved;
+};
+
+const resolveSourceMapUrls = (
+ sources: string[],
+ sourceRoot: string | null | undefined,
+ mapUrl: string,
+): readonly string[] =>
+ new TraceMap(
+ {
+ version: 3,
+ names: [],
+ sources,
+ ...(sourceRoot == null ? {} : { sourceRoot }),
+ mappings: "",
+ },
+ mapUrl,
+ ).resolvedSources;
+
/** Resolve a source-map URL reference without changing its recorded identity. */
const resolveJavaScriptSourceMapPath = (
source: string,
diff --git a/src/domain/javascript/sourceToBundleComparison.test.ts b/src/domain/javascript/sourceToBundleComparison.test.ts
index f488ee598..d231cb5ec 100644
--- a/src/domain/javascript/sourceToBundleComparison.test.ts
+++ b/src/domain/javascript/sourceToBundleComparison.test.ts
@@ -1,10 +1,11 @@
import { describe, expect, it } from "vitest";
+import { TraceMap } from "@jridgewell/trace-mapping";
-import { resolveJavaScriptSourceMapReference } from "./javascriptSourceMapPaths.js";
import {
createJavaScriptApplicationGraph,
createJavaScriptApplicationNode,
} from "./javascriptApplicationGraph.js";
+import type { ApplicationNode } from "./javascriptApplicationGraphSchemas.js";
import { createHistoricalSourceGraph } from "../referenceSourceGraph.js";
import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
import { compareSourceToBundle } from "./sourceToBundleComparison.js";
@@ -12,7 +13,10 @@ import {
SOURCE_TO_BUNDLE_SIGNAL_WEIGHTS,
sourceToBundleComparisonResultSchema,
} from "./sourceToBundleComparisonSchemas.js";
-import { artifactEvidence } from "./javascriptApplicationGraph.fixture.js";
+import {
+ artifactEvidence,
+ sourceMapReference,
+} from "./javascriptApplicationGraph.fixture.js";
const HASH = {
artifact: "1".repeat(64),
@@ -42,9 +46,6 @@ describe("historical source to bundle comparison", () => {
const second = compareSourceToBundle(input);
expect(first).toEqual(second);
- expect(() =>
- sourceToBundleComparisonResultSchema.parse(first),
- ).not.toThrow();
expect(first.summary).toEqual({
unchanged: 1,
modified: 0,
@@ -153,7 +154,7 @@ describe("source to bundle digest changes", () => {
observations: [
{
label: "display label",
- source_map_reference: resolveJavaScriptSourceMapReference(
+ source_map_reference: sourceMapReference(
"webpack://fixture/./src/modified.ts",
null,
"dist/main.js.map",
@@ -202,6 +203,90 @@ describe("source to bundle digest changes", () => {
});
});
+describe("source to bundle Unicode path collisions", () => {
+ it("keeps colliding canonical-equivalent current paths ambiguous", () => {
+ const historicalPath = "src/a\u0301\u0323.ts";
+ const currentPaths = ["src/a\u0323\u0301.ts", "src/\u1ea1\u0301.ts"];
+ const nodes = currentPaths.map((path, index) =>
+ moduleNode(`unicode-${index}`, { path }),
+ );
+ const result = comparePathToNodes(historicalPath, nodes);
+ const mapping = item(result, historicalPath);
+
+ expect(mapping).toMatchObject({
+ status: "unknown",
+ confidence: "unknown",
+ current_node_ids: [],
+ candidates: [
+ expect.objectContaining({
+ signals: expect.arrayContaining([
+ expect.objectContaining({ kind: "unicode-equivalent-path" }),
+ ]),
+ }),
+ expect.objectContaining({
+ signals: expect.arrayContaining([
+ expect.objectContaining({ kind: "unicode-equivalent-path" }),
+ ]),
+ }),
+ ],
+ limitations: [
+ expect.stringContaining(
+ "filesystem paths with distinct Unicode spellings",
+ ),
+ ],
+ });
+ });
+
+ it("prefers a raw source-map path over canonically equivalent alternatives", () => {
+ const historicalPath = "src/cafe\u0301.ts";
+ const exact = sourceMapNode(
+ "exact",
+ "cafe\u0301.ts",
+ "../src/",
+ HASH.modified,
+ );
+ const equivalent = sourceMapNode(
+ "equivalent",
+ "caf\u00e9.ts",
+ "../src/",
+ HASH.removed,
+ );
+ const result = comparePathToNodes(historicalPath, [exact, equivalent]);
+
+ expect(item(result, historicalPath)).toMatchObject({
+ status: "modified",
+ current_node_ids: [exact.node_id],
+ });
+ });
+
+ it("finds Unicode-equivalent suffixes of absolute source-map URLs", () => {
+ const historicalPath = "src/caf\u00e9.ts";
+ const node = sourceMapNode(
+ "remote",
+ "cafe\u0301.ts",
+ "https://cdn.example/src/",
+ HASH.modified,
+ );
+ const result = comparePathToNodes(historicalPath, [node]);
+
+ expect(item(result, historicalPath)).toMatchObject({
+ status: "unknown",
+ current_node_ids: [],
+ candidates: [
+ expect.objectContaining({
+ current_node_id: node.node_id,
+ signals: expect.arrayContaining([
+ expect.objectContaining({
+ kind: "unicode-equivalent-path",
+ current_values: ["cdn.example/src/cafe\u0301.ts"],
+ }),
+ ]),
+ }),
+ ],
+ });
+ });
+});
+
describe("source to bundle path syntax", () => {
it.each([
"src/modified#part.ts",
@@ -282,9 +367,60 @@ describe("source to bundle path syntax", () => {
}),
],
});
+ expect(
+ item(result, "src/modified.ts").candidates.flatMap(
+ ({ signals }) => signals,
+ ),
+ ).not.toContainEqual(
+ expect.objectContaining({ kind: "unicode-equivalent-path" }),
+ );
});
});
+describe("source-map resolver equivalence", () => {
+ it.each([
+ {
+ sourceRoot: "https://cdn.example/src/",
+ expectedSource: "https://cdn.example/src/a.js",
+ expectedResolution: { kind: "suffix", path: "cdn.example/src/a.js" },
+ },
+ {
+ sourceRoot: "https://cdn.example/src//",
+ expectedSource: "https://cdn.example/src/a.js",
+ expectedResolution: { kind: "suffix", path: "cdn.example/src/a.js" },
+ },
+ {
+ sourceRoot: "webpack://",
+ expectedSource: "webpack:///a.js",
+ expectedResolution: { kind: "suffix", path: "a.js" },
+ },
+ ])(
+ "matches TraceMap for sourceRoot $sourceRoot",
+ ({ sourceRoot, expectedSource, expectedResolution }) => {
+ const producerSource = new TraceMap(
+ {
+ version: 3,
+ file: "main.js",
+ sourceRoot,
+ sources: ["a.js"],
+ names: [],
+ mappings: "",
+ },
+ "file:///artifact/dist/main.js.map",
+ ).resolvedSources[0];
+ const reference = sourceMapReference(
+ "a.js",
+ sourceRoot,
+ "dist/main.js.map",
+ );
+
+ expect(producerSource).toBe(expectedSource);
+ expect(reference.source_root).toBe(sourceRoot);
+ expect(reference.resolution).toEqual(expectedResolution);
+ },
+ );
+});
+
describe("source to bundle complete metadata", () => {
it("accepts long source metadata and all reported limitations", () => {
const result = compareSourceToBundle({
@@ -328,6 +464,61 @@ describe("source to bundle complete metadata", () => {
});
});
+const sourceMapNode = (
+ key: string,
+ sourceName: string,
+ sourceRoot: string,
+ digest: string,
+) =>
+ createJavaScriptApplicationNode({
+ kind: "source-module",
+ identity: {
+ strategy: "source-map-original",
+ source_root: sourceRoot,
+ stability: "source-map-exact",
+ source_map_sha256: HASH.artifact,
+ original_source: sourceName,
+ source_sha256: digest,
+ },
+ observations: [
+ {
+ label: `${key} source-map spelling`,
+ source_map_reference: sourceMapReference(
+ sourceName,
+ sourceRoot,
+ `dist/${key}.map`,
+ ),
+ properties: { content_available: true, content_sha256: digest },
+ evidence: artifactEvidence(HASH.artifact, `dist/${key}.map`),
+ },
+ ],
+ });
+
+const comparePathToNodes = (
+ sourcePath: string,
+ nodes: readonly ApplicationNode[],
+) =>
+ compareSourceToBundle({
+ reference: historicalGraph("complete", [sourcePath]),
+ application: {
+ evidenceId: EVIDENCE_ID,
+ rootArtifactSha256: HASH.artifact,
+ graph: createJavaScriptApplicationGraph({
+ schema: "JavaScriptApplicationGraph",
+ root_node_ids: nodes.map(({ node_id: nodeId }) => nodeId),
+ nodes,
+ edges: [],
+ coverage: {
+ status: "complete",
+ truncated: false,
+ omitted_count: 0,
+ limits: [],
+ },
+ limitations: [],
+ }),
+ },
+ });
+
const historicalGraph = (
inventoryState: "complete" | "partial",
paths = [
diff --git a/src/domain/javascript/sourceToBundleComparison.ts b/src/domain/javascript/sourceToBundleComparison.ts
index ac0007cb4..5a70c57f3 100644
--- a/src/domain/javascript/sourceToBundleComparison.ts
+++ b/src/domain/javascript/sourceToBundleComparison.ts
@@ -258,7 +258,11 @@ const classifyMapping = (
confidence: "unknown",
currentNodeIds: [],
limitations: [
- "Only weak basename or extension signals were available; no mapping was forced.",
+ candidates.some((candidate) =>
+ hasSignal(candidate, "unicode-equivalent-path"),
+ )
+ ? "Unicode-equivalent paths are inferred candidates only; filesystem paths with distinct Unicode spellings may identify different files, so no mapping was forced."
+ : "Only weak basename or extension signals were available; no mapping was forced.",
],
};
return absenceComplete
diff --git a/src/domain/javascript/sourceToBundleComparisonSchemas.ts b/src/domain/javascript/sourceToBundleComparisonSchemas.ts
index 2e27cadb3..9d6bd6b2f 100644
--- a/src/domain/javascript/sourceToBundleComparisonSchemas.ts
+++ b/src/domain/javascript/sourceToBundleComparisonSchemas.ts
@@ -15,6 +15,7 @@ export const SOURCE_TO_BUNDLE_SIGNAL_WEIGHTS = [
["source-map-original-path", 70],
["current-path-exact", 60],
["current-path-suffix", 40],
+ ["unicode-equivalent-path", 20],
["basename-match", 20],
["language-extension", 5],
] as const;
@@ -24,6 +25,7 @@ const sourceToBundleSignalKindSchema = z.enum([
"source-map-original-path",
"current-path-exact",
"current-path-suffix",
+ "unicode-equivalent-path",
"basename-match",
"language-extension",
]);
diff --git a/src/domain/javascript/sourceToBundleSignals.ts b/src/domain/javascript/sourceToBundleSignals.ts
index 2190988fe..b3546aecc 100644
--- a/src/domain/javascript/sourceToBundleSignals.ts
+++ b/src/domain/javascript/sourceToBundleSignals.ts
@@ -102,8 +102,12 @@ export const buildSourceToBundleCandidateIndex = (
for (const path of projection.paths) {
for (const suffix of path.allowSuffix
? pathSuffixes(path.value)
- : [path.value])
+ : [path.value]) {
addIndexValue(byPathSuffix, suffix, projection.node.node_id);
+ const canonical = suffix.normalize("NFC");
+ if (canonical !== suffix)
+ addIndexValue(byPathSuffix, canonical, projection.node.node_id);
+ }
addIndexValue(
byBasename,
posix.basename(path.value),
@@ -126,9 +130,13 @@ export const candidateIdsForSource = (
source: SourceFile,
index: SourceToBundleCandidateIndex,
): string[] => {
+ const canonicalPath = source.path.normalize("NFC");
const groups = [
source.sha256 === null ? undefined : index.byDigest.get(source.sha256),
index.byPathSuffix.get(source.path),
+ canonicalPath === source.path
+ ? undefined
+ : index.byPathSuffix.get(canonicalPath),
index.byBasename.get(posix.basename(source.path)),
];
const seen = new Set();
@@ -220,6 +228,14 @@ const candidateSignals = (
signals.push(
signal("source-map-original-path", source.path, sourceMapPaths),
);
+ const unicodeEquivalentPaths = matchingUnicodePaths(
+ source.path,
+ current.paths,
+ );
+ if (unicodeEquivalentPaths.length > 0)
+ signals.push(
+ signal("unicode-equivalent-path", source.path, unicodeEquivalentPaths),
+ );
const otherPaths = current.paths.filter(
({ kind }) => kind !== "source-map-original",
);
@@ -286,6 +302,27 @@ const matchingPaths = (
)
.map(({ value }) => value);
+const matchingUnicodePaths = (
+ sourcePath: string,
+ currentPaths: readonly CurrentPath[],
+): string[] => {
+ const canonicalSource = sourcePath.normalize("NFC");
+ return currentPaths
+ .filter(({ value, allowSuffix }) => {
+ if (
+ value === sourcePath ||
+ (allowSuffix && value.endsWith(`/${sourcePath}`))
+ )
+ return false;
+ const canonicalValue = value.normalize("NFC");
+ return (
+ canonicalValue === canonicalSource ||
+ (allowSuffix && canonicalValue.endsWith(`/${canonicalSource}`))
+ );
+ })
+ .map(({ value }) => value);
+};
+
const addJsonPath = (paths: CurrentPath[], value: unknown): void => {
if (typeof value === "string") addPath(paths, "observation-path", value);
};
diff --git a/src/domain/managed/managedReconstruction.ts b/src/domain/managed/managedReconstruction.ts
index e10be0ffd..9600166ae 100644
--- a/src/domain/managed/managedReconstruction.ts
+++ b/src/domain/managed/managedReconstruction.ts
@@ -204,7 +204,8 @@ const buildReconstructionSummary = (
({ reconstruction }) => reconstruction.kind === "semantic-pseudocode",
).length,
total_text_bytes: methods.reduce(
- (total, { reconstruction }) => total + reconstruction.text_length,
+ (total, { reconstruction }) =>
+ total + Buffer.byteLength(reconstruction.text, "utf8"),
0,
),
});
diff --git a/src/domain/offsetDateTime.ts b/src/domain/offsetDateTime.ts
index bccda7494..b7d38550f 100644
--- a/src/domain/offsetDateTime.ts
+++ b/src/domain/offsetDateTime.ts
@@ -1,5 +1,11 @@
import { z } from "zod";
+export interface OffsetDateTimeInstant {
+ readonly epochSecond: number;
+ /** Exact fractional second with insignificant trailing zeroes removed. */
+ readonly fraction: string;
+}
+
/**
* ISO-8601 date-time that requires an explicit UTC offset.
*
@@ -19,3 +25,80 @@ export const offsetDateTimeSchema = z
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|(?:[+\x2d](?:[01]\d|2[0-3]):[0-5]\d)))$/u,
"Use an ISO-8601 date-time with an explicit UTC offset",
);
+
+/** Parse an already validated offset timestamp without losing sub-millisecond precision. */
+export const parseOffsetDateTimeInstant = (
+ value: string,
+): OffsetDateTimeInstant => {
+ const match = /^(.*?)(?:\.(\d+))?(Z|[+\x2d]\d{2}:\d{2})$/u.exec(value);
+ if (match === null)
+ throw new TypeError("Expected a validated offset date-time.");
+ const [, dateTime, fractionalDigits, offset] = match;
+ if (dateTime === undefined || offset === undefined)
+ throw new TypeError("Expected a validated offset date-time.");
+ const wholeSecondMilliseconds = Date.parse(`${dateTime}${offset}`);
+ if (
+ !Number.isSafeInteger(wholeSecondMilliseconds) ||
+ wholeSecondMilliseconds % 1000 !== 0
+ )
+ throw new TypeError(
+ "Offset date-time is outside the supported time range.",
+ );
+ return {
+ epochSecond: wholeSecondMilliseconds / 1000,
+ fraction: fractionalDigits?.replace(/0+$/u, "") ?? "",
+ };
+};
+
+/** Convert a Date.now-style integer into the same exact comparison shape. */
+export const offsetDateTimeInstantFromEpochMilliseconds = (
+ epochMilliseconds: number,
+): OffsetDateTimeInstant => {
+ if (!Number.isFinite(epochMilliseconds))
+ throw new TypeError("Expected finite epoch milliseconds.");
+ if (Math.abs(epochMilliseconds) > Number.MAX_SAFE_INTEGER)
+ return { epochSecond: epochMilliseconds / 1000, fraction: "" };
+ const epochSecond = Math.floor(epochMilliseconds / 1000);
+ const millisecondsWithinSecond = epochMilliseconds - epochSecond * 1000;
+ return {
+ epochSecond,
+ fraction: fractionalSecondFromMilliseconds(millisecondsWithinSecond),
+ };
+};
+
+const fractionalSecondFromMilliseconds = (milliseconds: number): string => {
+ if (milliseconds === 0) return "";
+ const [coefficient = "", exponentText] = String(milliseconds)
+ .toLowerCase()
+ .split("e");
+ const exponent = exponentText === undefined ? 0 : Number(exponentText);
+ const point = coefficient.indexOf(".");
+ const decimalPosition =
+ (point < 0 ? coefficient.length : point) + exponent - 3;
+ const digits = coefficient.replace(".", "");
+ const fraction =
+ decimalPosition <= 0
+ ? `0.${"0".repeat(-decimalPosition)}${digits}`
+ : decimalPosition < digits.length
+ ? `${digits.slice(0, decimalPosition)}.${digits.slice(decimalPosition)}`
+ : `${digits}${"0".repeat(decimalPosition - digits.length)}`;
+ return (
+ fraction.includes(".") ? fraction.slice(fraction.indexOf(".") + 1) : ""
+ ).replace(/0+$/u, "");
+};
+
+/** Compare instants exactly while treating absent fraction digits as zeroes. */
+export const compareOffsetDateTimeInstants = (
+ left: OffsetDateTimeInstant,
+ right: OffsetDateTimeInstant,
+): number => {
+ if (left.epochSecond !== right.epochSecond)
+ return left.epochSecond < right.epochSecond ? -1 : 1;
+ const length = Math.max(left.fraction.length, right.fraction.length);
+ for (let index = 0; index < length; index += 1) {
+ const leftDigit = left.fraction.charCodeAt(index) || 48;
+ const rightDigit = right.fraction.charCodeAt(index) || 48;
+ if (leftDigit !== rightDigit) return leftDigit < rightDigit ? -1 : 1;
+ }
+ return 0;
+};
diff --git a/src/domain/pcap/pcapAnalysis.ts b/src/domain/pcap/pcapAnalysis.ts
new file mode 100644
index 000000000..21c64f365
--- /dev/null
+++ b/src/domain/pcap/pcapAnalysis.ts
@@ -0,0 +1,110 @@
+import { z } from "zod";
+import { localPathStringSchema } from "../localPath.js";
+import { digestSchema } from "../digests.js";
+
+/**
+ * Caller intent for packet-capture analysis through caller-supplied tshark
+ * and capinfos. REA never installs Wireshark or its tools.
+ */
+export const pcapInputSchemas = {
+ inspect_pcap_client: z.strictObject({}),
+ inspect_pcap_capture: z.strictObject({
+ path: localPathStringSchema.describe(
+ "Local pcap or pcapng capture file to inspect",
+ ),
+ }),
+} as const;
+
+/** Supported pcap-backed operations. */
+export type PcapOperation = keyof typeof pcapInputSchemas;
+/** Validated pcap requests carry their selected operation. */
+export type PcapRequest = {
+ [Name in PcapOperation]: {
+ operation: Name;
+ input: z.infer<(typeof pcapInputSchemas)[Name]>;
+ };
+}[PcapOperation];
+
+/** Validate operation and input together so their types remain correlated. */
+export const pcapRequestSchema = z.discriminatedUnion("operation", [
+ z.strictObject({
+ operation: z.literal("inspect_pcap_client"),
+ input: pcapInputSchemas.inspect_pcap_client,
+ }),
+ z.strictObject({
+ operation: z.literal("inspect_pcap_capture"),
+ input: pcapInputSchemas.inspect_pcap_capture,
+ }),
+]);
+
+const client = z.strictObject({
+ tshark_command: z.string().min(1),
+ tshark_source: z.enum(["environment", "path"]),
+ tshark_version: z.string().min(1).nullable(),
+ capinfos_command: z.string().min(1),
+ capinfos_source: z.enum(["environment", "path"]),
+ capinfos_version: z.string().min(1).nullable(),
+});
+
+const endpoint = z.strictObject({
+ address: z.string().min(1),
+ port: z.number().int().positive().nullable(),
+ packet_count: z.number().int().positive(),
+});
+
+const dnsQuery = z.strictObject({
+ query: z.string().min(1),
+ response_addresses: z.array(z.string().min(1)),
+ response_address_count: z.number().int().nonnegative(),
+});
+
+const protocolCount = z.strictObject({
+ protocol: z.string().min(1),
+ packet_count: z.number().int().positive(),
+});
+
+/** Portable pcap observations with explicit coverage limitations. */
+export const pcapResultSchemas = {
+ inspect_pcap_client: z.strictObject({
+ client,
+ }),
+ inspect_pcap_capture: z.strictObject({
+ client,
+ target: z.strictObject({
+ path: localPathStringSchema,
+ bytes: z.number().int().nonnegative(),
+ sha256: digestSchema,
+ }),
+ /** File format as capinfos reports it (pcap vs pcapng). */
+ file_type: z.string().min(1).nullable(),
+ encapsulation: z.string().min(1).nullable(),
+ packet_count: z.number().int().nonnegative().nullable(),
+ capture_start: z.string().nullable(),
+ capture_end: z.string().nullable(),
+ capture_duration_seconds: z.number().nonnegative().nullable(),
+ snapshot_length: z.number().int().positive().nullable(),
+ /** Distinct endpoints with packet counts, bounded. */
+ endpoints: z.array(endpoint),
+ endpoint_count: z.number().int().nonnegative(),
+ /** DNS queries with resolved addresses, bounded. */
+ dns_queries: z.array(dnsQuery),
+ dns_query_count: z.number().int().nonnegative(),
+ /** TLS Server Name Indication values observed in handshakes. */
+ tls_sni_values: z.array(z.string().min(1)),
+ tls_sni_count: z.number().int().nonnegative(),
+ /** Protocol distribution (frame.protocols column counts). */
+ protocol_distribution: z.array(protocolCount),
+ protocol_count: z.number().int().nonnegative(),
+ /** HTTP request URIs seen on plain-text ports, bounded. */
+ http_request_uris: z.array(z.string().min(1)),
+ http_request_uri_count: z.number().int().nonnegative(),
+ http_uri_redaction_count: z.number().int().nonnegative(),
+ unattributed_dns_addresses: z.array(z.string().min(1)),
+ unattributed_dns_address_count: z.number().int().nonnegative(),
+ unattributed_dns_packet_count: z.number().int().nonnegative(),
+ coverage: z.enum(["complete", "partial"]),
+ diagnostics: z
+ .strictObject({ capinfos_stderr: z.string(), tshark_stderr: z.string() })
+ .optional(),
+ }),
+} as const;
diff --git a/src/domain/pcap/pcapEvidence.ts b/src/domain/pcap/pcapEvidence.ts
new file mode 100644
index 000000000..848350fe3
--- /dev/null
+++ b/src/domain/pcap/pcapEvidence.ts
@@ -0,0 +1,34 @@
+import { createEvidence } from "../evidence.js";
+import { jsonObjectSchema, type JsonValue } from "../jsonValue.js";
+import type { PcapRequest } from "./pcapAnalysis.js";
+
+/** Domain facts needed by both successful and retained partial observations. */
+interface PcapObservation {
+ readonly subject: Parameters[0] | null;
+ readonly provider: Parameters[1];
+ readonly result: JsonValue;
+ readonly rawResult: JsonValue | null;
+ readonly limitations: readonly string[];
+ readonly locations: NonNullable<
+ Parameters[2]["locations"]
+ >;
+}
+
+/** One owner commits packet aggregation provenance and caller intent into Evidence. */
+export const createPcapEvidence = (
+ request: PcapRequest,
+ observation: PcapObservation,
+) =>
+ createEvidence(observation.subject ?? undefined, observation.provider, {
+ operation: request.operation,
+ parameters: jsonObjectSchema.parse(request.input),
+ result: observation.result,
+ rawResult: observation.rawResult,
+ limitations: observation.limitations,
+ locations: observation.locations,
+ confidence:
+ request.operation === "inspect_pcap_capture" ? "derived" : "observed",
+ ...(request.operation === "inspect_pcap_capture"
+ ? { authority: "historical-reference" as const }
+ : {}),
+ });
diff --git a/src/domain/process/processTraceSpecification.test.ts b/src/domain/process/processTraceSpecification.test.ts
index aeedf4d31..ab649d2aa 100644
--- a/src/domain/process/processTraceSpecification.test.ts
+++ b/src/domain/process/processTraceSpecification.test.ts
@@ -39,30 +39,110 @@ const specification = (): ProcessTraceSpecification => ({
});
describe("process trace specification", () => {
- it("summarizes an incomplete language with its exact missing pair count", () => {
- const events = Array.from({ length: 200 }, (_, index) => ({
- id: `e${String(index)}`,
+ it("reports independent declaration errors alongside a cycle", () => {
+ const base = specification();
+ const result = processTraceSpecificationSchema.safeParse({
+ ...base,
+ language: {
+ ...base.language,
+ happens_before: [
+ { before: "ready", after: "worker" },
+ { before: "worker", after: "ready" },
+ ],
+ not_before: [{ event: "missing", anchor: "ready" }],
+ unordered_groups: [{ events: ["missing", "missing"] }],
+ prefix: ["missing"],
+ suffix: ["missing"],
+ },
+ });
+ if (result.success) throw new Error("Expected invalid trace declarations");
+ expect(result.error.issues).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ message: "happens-before graph must be acyclic",
+ }),
+ expect.objectContaining({
+ path: ["language", "not_before", 0, "event"],
+ }),
+ expect.objectContaining({
+ path: ["language", "unordered_groups", 0, "events"],
+ }),
+ expect.objectContaining({ path: ["language", "prefix", 0] }),
+ expect.objectContaining({ path: ["language", "suffix", 0] }),
+ ]),
+ );
+ });
+
+ it("accepts an acyclic order with shared successors and explicit unordered peers", () => {
+ const result = processTraceSpecificationSchema.parse({
+ events: ["a", "b", "c", "d"].map((id) => ({
+ id,
+ source: "lifecycle",
+ exact: { marker: id },
+ })),
+ language: {
+ kind: "partial_order",
+ happens_before: [
+ { before: "a", after: "b" },
+ { before: "a", after: "c" },
+ { before: "b", after: "d" },
+ { before: "c", after: "d" },
+ ],
+ unordered_groups: [{ events: ["b", "c"] }],
+ prefix: ["a"],
+ suffix: ["d"],
+ },
+ });
+ expect(result.language.kind).toBe("partial_order");
+ });
+});
+
+describe("process trace ordering validation", () => {
+ it("uses a unique topological order for transitive declarations and conflicts", () => {
+ const events = ["a", "b", "c"].map((id) => ({
+ id,
source: "lifecycle" as const,
- exact: { fixture: index },
+ exact: { marker: id },
cardinality: { kind: "optional" as const },
}));
- const result = processTraceSpecificationSchema.safeParse({
+ const accepted = processTraceSpecificationSchema.safeParse({
events,
- language: { kind: "partial_order" },
+ language: {
+ kind: "partial_order",
+ happens_before: [
+ { before: "a", after: "b" },
+ { before: "b", after: "c" },
+ ],
+ },
});
- expect(result.success).toBe(false);
- if (result.success)
- throw new Error("Expected incomplete pair declarations");
- expect(result.error.issues).toEqual([
+ expect(accepted.success).toBe(true);
+
+ const rejected = processTraceSpecificationSchema.safeParse({
+ events,
+ language: {
+ kind: "partial_order",
+ happens_before: [
+ { before: "a", after: "b" },
+ { before: "b", after: "c" },
+ ],
+ not_before: [{ event: "a", anchor: "c" }],
+ unordered_groups: [{ events: ["a", "b", "c"] }],
+ },
+ });
+ if (rejected.success) throw new Error("Expected ordered pair conflicts");
+ expect(rejected.error.issues).toEqual([
expect.objectContaining({
- path: ["language"],
- message:
- "19900 event pairs must be explicitly ordered or unordered; first undeclared pair: e0/e1",
+ path: ["language", "not_before", 0],
+ message: "not-before constraint conflicts with happens-before order",
+ }),
+ expect.objectContaining({
+ path: ["language", "unordered_groups", 0],
+ message: "ordered events cannot also be declared unordered",
}),
]);
});
- it("counts only undeclared pairs after transitive, not-before and unordered relations", () => {
+ it("counts only undeclared pairs across transitive and disconnected relations", () => {
const events = ["a", "b", "c", "d"].map((id) => ({
id,
source: "lifecycle" as const,
@@ -91,7 +171,7 @@ describe("process trace specification", () => {
]);
});
- it("retains duplicate unordered-pair diagnostics for reversed declarations", () => {
+ it("reports one duplicate-pair diagnostic per overlapping group", () => {
const result = processTraceSpecificationSchema.safeParse({
events: ["z", "a", "b"].map((id) => ({
id,
@@ -101,7 +181,10 @@ describe("process trace specification", () => {
})),
language: {
kind: "partial_order",
- unordered_groups: [{ events: ["z", "a", "b"] }, { events: ["a", "z"] }],
+ unordered_groups: [
+ { events: ["z", "a", "b"] },
+ { events: ["b", "a", "z"] },
+ ],
},
});
expect(result.success).toBe(false);
@@ -113,27 +196,84 @@ describe("process trace specification", () => {
}),
]);
});
+});
- it("rejects cycles, implicit ordering gaps, invalid ignores, and unsatisfiable variants", () => {
- const base = specification();
- expect(
- processTraceSpecificationSchema.safeParse({
- ...base,
- language: {
- kind: "partial_order",
- happens_before: [
- { before: "ready", after: "worker" },
- { before: "worker", after: "ready" },
- ],
+describe("malformed process trace declarations", () => {
+ it("preserves independent diagnostics when event ids are duplicated", () => {
+ const result = processTraceSpecificationSchema.safeParse({
+ events: [
+ {
+ id: "a",
+ source: "lifecycle",
+ exact: { fixture: "first" },
+ cardinality: { kind: "optional" },
},
- }).success,
- ).toBe(false);
- expect(
- processTraceSpecificationSchema.safeParse({
- ...base,
- language: { kind: "partial_order" },
- }).success,
- ).toBe(false);
+ {
+ id: "a",
+ source: "lifecycle",
+ exact: { fixture: "second" },
+ cardinality: { kind: "optional" },
+ },
+ ],
+ language: {
+ kind: "partial_order",
+ unordered_groups: [{ events: ["a", "b"] }],
+ },
+ });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error("Expected a duplicate event id");
+ expect(result.error.issues).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ path: ["events", 1, "id"],
+ message: "event ids must be unique",
+ }),
+ expect.objectContaining({
+ path: ["language", "unordered_groups", 0, "events", 1],
+ message: "unknown event id: b",
+ }),
+ ]),
+ );
+ });
+
+ it("keeps reachability diagnostics for unknown referenced successors", () => {
+ const result = processTraceSpecificationSchema.safeParse({
+ events: ["a", "b"].map((id) => ({
+ id,
+ source: "lifecycle",
+ exact: { fixture: id },
+ cardinality: { kind: "optional" },
+ })),
+ language: {
+ kind: "partial_order",
+ happens_before: [{ before: "a", after: "missing" }],
+ not_before: [{ event: "a", anchor: "missing" }],
+ },
+ });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error("Expected an unknown event reference");
+ expect(result.error.issues).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ path: ["language", "happens_before", 0, "after"],
+ message: "unknown event id: missing",
+ }),
+ expect.objectContaining({
+ path: ["language", "not_before", 0, "anchor"],
+ message: "unknown event id: missing",
+ }),
+ expect.objectContaining({
+ path: ["language", "not_before", 0],
+ message: "not-before constraint conflicts with happens-before order",
+ }),
+ ]),
+ );
+ });
+});
+
+describe("finite trace specification validation", () => {
+ it("rejects invalid ignores and unsatisfiable variants", () => {
+ const base = specification();
expect(
processTraceSpecificationSchema.safeParse({
events: [
diff --git a/src/domain/process/processTraceSpecification.ts b/src/domain/process/processTraceSpecification.ts
index 61ace7ca1..09c14cf10 100644
--- a/src/domain/process/processTraceSpecification.ts
+++ b/src/domain/process/processTraceSpecification.ts
@@ -106,6 +106,17 @@ export type ProcessTraceSpecification = z.infer<
>;
type PartialOrderLanguage = z.infer;
+type AcyclicGraphFacts =
+ | {
+ readonly kind: "total-order";
+ readonly rank: ReadonlyMap;
+ }
+ | {
+ readonly kind: "partial-order";
+ readonly reverseAdjacency: ReadonlyMap>;
+ };
+type GraphFacts = { readonly kind: "cyclic" } | AcyclicGraphFacts;
+
export const canonicalTraceJson = (value: unknown): string => {
const serialized = canonicalize(value);
if (serialized === undefined)
@@ -170,7 +181,6 @@ const validateNotBefore = (
language: PartialOrderLanguage,
context: z.RefinementCtx,
known: ReadonlySet,
- reachable: ReadonlyMap>,
): ReadonlySet => {
const pairs = new Set();
for (const [index, constraint] of language.not_before.entries()) {
@@ -191,76 +201,101 @@ const validateNotBefore = (
path,
});
pairs.add(key);
- if (reachable.get(constraint.event)?.has(constraint.anchor) === true)
- context.addIssue({
- code: "custom",
- message: "not-before constraint conflicts with happens-before order",
- path,
- });
}
return pairs;
};
-const graphHasCycle = (
+const classifyGraph = (
ids: readonly string[],
adjacency: ReadonlyMap>,
-): boolean => {
- const active = new Set();
- const complete = new Set();
- const visit = (current: string): boolean => {
- if (active.has(current)) return true;
- if (complete.has(current)) return false;
- active.add(current);
- const cyclic = [...(adjacency.get(current) ?? [])].some(visit);
- active.delete(current);
- complete.add(current);
- return cyclic;
- };
- return ids.some(visit);
-};
-
-const computeReachability = (
- ids: readonly string[],
- adjacency: ReadonlyMap>,
-): ReadonlyMap> => {
- const reachable = new Map>();
- for (const origin of ids) {
- const seen = new Set();
- const pending = [...(adjacency.get(origin) ?? [])];
- while (pending.length > 0) {
- const current = pending.pop();
- if (current === undefined || seen.has(current)) continue;
- seen.add(current);
- pending.push(...(adjacency.get(current) ?? []));
+): GraphFacts => {
+ const incoming = new Map(ids.map((id) => [id, 0]));
+ let hasUnknownSuccessor = false;
+ for (const successors of adjacency.values())
+ for (const successor of successors) {
+ const count = incoming.get(successor);
+ if (count === undefined) hasUnknownSuccessor = true;
+ else incoming.set(successor, count + 1);
+ }
+ const ready = [...incoming].flatMap(([id, count]) =>
+ count === 0 ? [id] : [],
+ );
+ const order: string[] = [];
+ let unique = true;
+ while (ready.length > 0) {
+ if (ready.length !== 1) unique = false;
+ const current = ready.pop();
+ if (current === undefined) continue;
+ order.push(current);
+ for (const successor of adjacency.get(current) ?? []) {
+ const count = incoming.get(successor);
+ if (count === undefined) continue;
+ incoming.set(successor, count - 1);
+ if (count === 1) ready.push(successor);
}
- reachable.set(origin, seen);
}
- return reachable;
+ if (order.length !== incoming.size) return { kind: "cyclic" };
+ if (unique && order.length === ids.length && !hasUnknownSuccessor) {
+ return {
+ kind: "total-order",
+ rank: new Map(order.map((id, index) => [id, index])),
+ };
+ }
+ const reverseAdjacency = new Map(
+ [...incoming.keys()].map((id) => [id, new Set()]),
+ );
+ for (const [before, successors] of adjacency)
+ for (const after of successors) reverseAdjacency.get(after)?.add(before);
+ return { kind: "partial-order", reverseAdjacency };
};
-const isOrdered = (
- reachable: ReadonlyMap>,
- left: string,
- right: string,
-): boolean =>
- reachable.get(left)?.has(right) === true ||
- reachable.get(right)?.has(left) === true;
-
-type OrderingRelations = {
- readonly reachable: ReadonlyMap>;
- readonly notBeforePairs: ReadonlySet;
+const collectReachable = (
+ origin: string,
+ adjacency: ReadonlyMap>,
+): ReadonlySet => {
+ const seen = new Set();
+ const pending = [...(adjacency.get(origin) ?? [])];
+ while (pending.length > 0) {
+ const current = pending.pop();
+ if (current === undefined || seen.has(current)) continue;
+ seen.add(current);
+ for (const successor of adjacency.get(current) ?? [])
+ pending.push(successor);
+ }
+ return seen;
};
const validateUnorderedGroups = (
language: PartialOrderLanguage,
context: z.RefinementCtx,
known: ReadonlySet,
- relations: OrderingRelations,
-): ReadonlySet => {
- const pairs = new Set();
+): {
+ readonly groups: readonly ReadonlySet[];
+ hasPair(left: string, right: string): boolean;
+ markDeclaredPairConflicts(
+ pairs: ReadonlySet,
+ conflicts: boolean[],
+ ): void;
+ markSharedGroups(left: string, right: string, conflicts: boolean[]): void;
+} => {
+ const memberships = new Map>();
+ const groups: Set[] = [];
+ const repeatedMemberships = new Map>();
for (const [groupIndex, group] of language.unordered_groups.entries()) {
const path = ["language", "unordered_groups", groupIndex];
- if (new Set(group.events).size !== group.events.length)
+ const uniqueIds = new Set();
+ const repeatedIds = new Set();
+ for (const id of group.events) {
+ if (uniqueIds.has(id)) repeatedIds.add(id);
+ else uniqueIds.add(id);
+ }
+ groups.push(uniqueIds);
+ for (const id of repeatedIds) {
+ const groupIndexes = repeatedMemberships.get(id) ?? new Set();
+ groupIndexes.add(groupIndex);
+ repeatedMemberships.set(id, groupIndexes);
+ }
+ if (uniqueIds.size !== group.events.length)
context.addIssue({
code: "custom",
message: "unordered groups must not repeat event ids",
@@ -268,46 +303,136 @@ const validateUnorderedGroups = (
});
for (const [eventIndex, id] of group.events.entries())
addReferenceIssue(context, known, id, [...path, "events", eventIndex]);
- for (const [leftIndex, leftId] of group.events.entries()) {
- for (
- let rightIndex = leftIndex + 1;
- rightIndex < group.events.length;
- rightIndex++
- ) {
- const rightId = group.events[rightIndex];
- if (rightId === undefined) continue;
- const key = pairKey(leftId, rightId);
- if (pairs.has(key))
- context.addIssue({
- code: "custom",
- message: "unordered event pairs must be declared once",
- path,
- });
- pairs.add(key);
- if (
- isOrdered(relations.reachable, leftId, rightId) ||
- relations.notBeforePairs.has(key)
- )
- context.addIssue({
- code: "custom",
- message: "ordered events cannot also be declared unordered",
- path,
- });
- }
+ const overlaps = new Map();
+ for (const id of uniqueIds) {
+ const priorGroups = memberships.get(id) ?? new Set();
+ for (const prior of priorGroups)
+ overlaps.set(prior, (overlaps.get(prior) ?? 0) + 1);
+ priorGroups.add(groupIndex);
+ memberships.set(id, priorGroups);
}
+ if ([...overlaps.values()].some((count) => count > 1))
+ context.addIssue({
+ code: "custom",
+ message: "unordered event pairs must be declared once",
+ path,
+ });
}
- return pairs;
+ const markSharedGroups = (
+ left: string,
+ right: string,
+ conflicts: boolean[],
+ ): void => {
+ if (left === right) {
+ for (const groupIndex of repeatedMemberships.get(left) ?? [])
+ conflicts[groupIndex] = true;
+ return;
+ }
+ const rightGroups = memberships.get(right);
+ for (const group of memberships.get(left) ?? [])
+ if (rightGroups?.has(group) === true) conflicts[group] = true;
+ };
+ return {
+ groups,
+ hasPair(left, right) {
+ if (left === right) return memberships.has(left);
+ const rightGroups = memberships.get(right);
+ for (const group of memberships.get(left) ?? [])
+ if (rightGroups?.has(group) === true) return true;
+ return false;
+ },
+ markDeclaredPairConflicts(pairs, conflicts) {
+ for (const key of pairs) {
+ const separator = key.indexOf("\0");
+ const left = key.slice(0, separator);
+ const right = key.slice(separator + 1);
+ markSharedGroups(left, right, conflicts);
+ }
+ },
+ markSharedGroups,
+ };
};
-const validateCompletePairDeclarations = (
+const validateTotalOrderRelations = (
+ language: PartialOrderLanguage,
+ graph: Extract,
+ unorderedGroups: ReturnType,
+ notBeforePairs: ReadonlySet,
+ context: z.RefinementCtx,
+): void => {
+ for (const [index, constraint] of language.not_before.entries()) {
+ const before = graph.rank.get(constraint.event);
+ const after = graph.rank.get(constraint.anchor);
+ if (before !== undefined && after !== undefined && before < after)
+ context.addIssue({
+ code: "custom",
+ message: "not-before constraint conflicts with happens-before order",
+ path: ["language", "not_before", index],
+ });
+ }
+
+ const conflicts = new Array(language.unordered_groups.length).fill(
+ false,
+ );
+ for (const [groupIndex, group] of unorderedGroups.groups.entries()) {
+ let comparableEvents = 0;
+ for (const id of group)
+ if (graph.rank.has(id) && ++comparableEvents === 2) {
+ conflicts[groupIndex] = true;
+ break;
+ }
+ }
+ unorderedGroups.markDeclaredPairConflicts(notBeforePairs, conflicts);
+ addUnorderedConflictIssues(conflicts, context);
+};
+
+const addUnorderedConflictIssues = (
+ conflicts: readonly boolean[],
+ context: z.RefinementCtx,
+): void => {
+ for (const [groupIndex, conflict] of conflicts.entries())
+ if (conflict)
+ context.addIssue({
+ code: "custom",
+ message: "ordered events cannot also be declared unordered",
+ path: ["language", "unordered_groups", groupIndex],
+ });
+};
+
+const validatePartialOrderRelations = (
ids: readonly string[],
- relations: OrderingRelations,
- unorderedPairs: ReadonlySet,
+ language: PartialOrderLanguage,
+ adjacency: ReadonlyMap>,
+ graph: Extract,
+ unorderedGroups: ReturnType,
+ notBeforePairs: ReadonlySet,
context: z.RefinementCtx,
): void => {
let missingPairCount = 0;
let firstMissingPair = "";
+ const groupConflicts = new Array(
+ language.unordered_groups.length,
+ ).fill(false);
+ unorderedGroups.markDeclaredPairConflicts(notBeforePairs, groupConflicts);
+ const notBeforeConflictFlags = new Uint8Array(language.not_before.length);
+ const constraintsBySource = new Map();
+ for (const [index, constraint] of language.not_before.entries()) {
+ const indexes = constraintsBySource.get(constraint.event) ?? [];
+ indexes.push(index);
+ constraintsBySource.set(constraint.event, indexes);
+ }
+
+ // Keep only one origin's forward and backward closure live at a time. Pair
+ // iteration stays in declaration order so the count and first missing pair
+ // retain the established diagnostic semantics.
for (const [leftIndex, leftId] of ids.entries()) {
+ const forward = collectReachable(leftId, adjacency);
+ const backward = collectReachable(leftId, graph.reverseAdjacency);
+ for (const constraintIndex of constraintsBySource.get(leftId) ?? []) {
+ const constraint = language.not_before[constraintIndex];
+ if (constraint !== undefined && forward.has(constraint.anchor))
+ notBeforeConflictFlags[constraintIndex] = 1;
+ }
for (
let rightIndex = leftIndex + 1;
rightIndex < ids.length;
@@ -315,14 +440,32 @@ const validateCompletePairDeclarations = (
) {
const rightId = ids[rightIndex];
if (rightId === undefined) continue;
- if (isOrdered(relations.reachable, leftId, rightId)) continue;
+ const sameEvent = leftId === rightId;
+ const ordered =
+ !sameEvent && (forward.has(rightId) || backward.has(rightId));
const key = pairKey(leftId, rightId);
- if (!relations.notBeforePairs.has(key) && !unorderedPairs.has(key)) {
+ const notBefore = notBeforePairs.has(key);
+ const unordered = unorderedGroups.hasPair(leftId, rightId);
+ if (ordered || notBefore) {
+ if (!sameEvent)
+ unorderedGroups.markSharedGroups(leftId, rightId, groupConflicts);
+ }
+ if (!ordered && !notBefore && !unordered) {
if (missingPairCount === 0) firstMissingPair = `${leftId}/${rightId}`;
missingPairCount++;
}
}
}
+
+ for (const [index, conflict] of notBeforeConflictFlags.entries())
+ if (conflict === 1)
+ context.addIssue({
+ code: "custom",
+ message: "not-before constraint conflicts with happens-before order",
+ path: ["language", "not_before", index],
+ });
+ addUnorderedConflictIssues(groupConflicts, context);
+
if (missingPairCount > 0)
context.addIssue({
code: "custom",
@@ -342,27 +485,44 @@ const validatePartialOrder = (
const ids = specification.events.map(({ id }) => id);
const known = new Set(ids);
const adjacency = buildAdjacency(specification.language, context, known);
- if (graphHasCycle(ids, adjacency))
+ const graph = classifyGraph(ids, adjacency);
+ if (graph.kind === "cyclic")
context.addIssue({
code: "custom",
message: "happens-before graph must be acyclic",
path: ["language"],
});
- const reachable = computeReachability(ids, adjacency);
const notBeforePairs = validateNotBefore(
specification.language,
context,
known,
- reachable,
);
- const relations = { reachable, notBeforePairs };
- const unorderedPairs = validateUnorderedGroups(
+ const unorderedGroups = validateUnorderedGroups(
specification.language,
context,
known,
- relations,
);
- validateCompletePairDeclarations(ids, relations, unorderedPairs, context);
+ // Preserve independent declaration diagnostics on cyclic input. Computing
+ // all pair relations cannot establish a valid partial order in that case.
+ if (graph.kind === "total-order") {
+ validateTotalOrderRelations(
+ specification.language,
+ graph,
+ unorderedGroups,
+ notBeforePairs,
+ context,
+ );
+ } else if (graph.kind === "partial-order") {
+ validatePartialOrderRelations(
+ ids,
+ specification.language,
+ adjacency,
+ graph,
+ unorderedGroups,
+ notBeforePairs,
+ context,
+ );
+ }
for (const [kind, values] of [
["prefix", specification.language.prefix],
["suffix", specification.language.suffix],
diff --git a/src/domain/reconstructionCoverage.test.ts b/src/domain/reconstructionCoverage.test.ts
index 4c0b41831..ac7552571 100644
--- a/src/domain/reconstructionCoverage.test.ts
+++ b/src/domain/reconstructionCoverage.test.ts
@@ -286,14 +286,18 @@ describe("reconstruction coverage verifier selection", () => {
});
});
-describe("reconstruction coverage verifier result ordering", () => {
- it("preserves the first input result when verifier timestamps tie", () => {
+describe("reconstruction coverage conflicting latest verifier observations", () => {
+ it("keeps conflicting tied assessments unknown regardless of input order", () => {
const workspace = completeReconstructionCoverageData();
const result = workspace.verifier_results[0];
const boundary = workspace.boundaries[0];
if (result === undefined || boundary === undefined)
throw new Error("Expected complete reconstruction coverage fixture");
- const failed = { ...result, status: "fail" as const };
+ const failed = {
+ ...result,
+ status: "fail" as const,
+ evidence_ids: [reconstructionCoverageEvidenceId("1")],
+ };
const firstPass = createReconstructionCoverageData({
...workspace,
verifier_results: [result, failed],
@@ -303,23 +307,109 @@ describe("reconstruction coverage verifier result ordering", () => {
verifier_results: [failed, result],
});
+ const firstPassResult = evaluateReconstructionClosure(
+ firstPass,
+ boundary.boundary_id,
+ RECONSTRUCTION_COVERAGE_NOW,
+ );
+ const firstFailResult = evaluateReconstructionClosure(
+ firstFail,
+ boundary.boundary_id,
+ RECONSTRUCTION_COVERAGE_NOW,
+ );
+ expect(firstPassResult).toEqual(firstFailResult);
+ expect(firstPassResult).toMatchObject({
+ status: "unknown",
+ reasons: [
+ expect.objectContaining({
+ code: "verifier-result-ambiguous",
+ subject_id: "claim.cli.help",
+ }),
+ ],
+ });
+ expect(firstPassResult.evidence_ids).toEqual(
+ expect.arrayContaining([
+ reconstructionCoverageEvidenceId("3"),
+ reconstructionCoverageEvidenceId("1"),
+ ]),
+ );
+ });
+});
+
+describe("reconstruction coverage equivalent latest verifier observations", () => {
+ it("coalesces equivalent equal-instant observations and retains all evidence", () => {
+ const workspace = completeReconstructionCoverageData();
+ const result = workspace.verifier_results[0];
+ const boundary = workspace.boundaries[0];
+ if (result === undefined || boundary === undefined)
+ throw new Error("Expected complete reconstruction coverage fixture");
+ const first = {
+ ...result,
+ observed_at: "2026-07-16T11:00:00.123456789012345678900Z",
+ };
+ const equivalent = {
+ ...first,
+ observed_at: "2026-07-16T06:00:00.1234567890123456789-05:00",
+ covered_claim_ids: [...result.covered_claim_ids].reverse(),
+ covered_dimensions: [...result.covered_dimensions].reverse(),
+ artifact_sha256s: [...result.artifact_sha256s].reverse(),
+ owner_sha256s: [...result.owner_sha256s].reverse(),
+ evidence_ids: [reconstructionCoverageEvidenceId("1")],
+ };
+ const forward = createReconstructionCoverageData({
+ ...workspace,
+ verifier_results: [first, equivalent],
+ });
+ const reversed = createReconstructionCoverageData({
+ ...workspace,
+ verifier_results: [equivalent, first],
+ });
+ const forwardResult = evaluateReconstructionClosure(
+ forward,
+ boundary.boundary_id,
+ RECONSTRUCTION_COVERAGE_NOW,
+ );
+ const reversedResult = evaluateReconstructionClosure(
+ reversed,
+ boundary.boundary_id,
+ RECONSTRUCTION_COVERAGE_NOW,
+ );
+
+ expect(forwardResult).toEqual(reversedResult);
+ expect(forwardResult.status).toBe("ready");
+ expect(forwardResult.evidence_ids).toEqual(
+ expect.arrayContaining([
+ reconstructionCoverageEvidenceId("3"),
+ reconstructionCoverageEvidenceId("1"),
+ ]),
+ );
+ });
+});
+
+describe("reconstruction coverage verifier timestamp selection", () => {
+ it("lets a later unambiguous observation supersede an older tie", () => {
+ const workspace = completeReconstructionCoverageData();
+ const result = workspace.verifier_results[0];
+ const boundary = workspace.boundaries[0];
+ if (result === undefined || boundary === undefined)
+ throw new Error("Expected complete reconstruction coverage fixture");
+ const failed = { ...result, status: "fail" as const };
+ const latestPass = {
+ ...result,
+ observed_at: "2026-07-16T11:30:00.000Z",
+ };
+ const changed = createReconstructionCoverageData({
+ ...workspace,
+ verifier_results: [result, failed, latestPass],
+ });
+
expect(
evaluateReconstructionClosure(
- firstPass,
- boundary.boundary_id,
- RECONSTRUCTION_COVERAGE_NOW,
- ).status,
- ).toBe("ready");
- expect(
- evaluateReconstructionClosure(
- firstFail,
+ changed,
boundary.boundary_id,
RECONSTRUCTION_COVERAGE_NOW,
),
- ).toMatchObject({
- status: "failed",
- reasons: [expect.objectContaining({ code: "verifier-failed" })],
- });
+ ).toMatchObject({ status: "ready", reasons: [] });
});
it("orders offset-bearing verifier timestamps chronologically", () => {
@@ -352,6 +442,68 @@ describe("reconstruction coverage verifier result ordering", () => {
});
});
+ it("selects the later result when timestamps differ below millisecond precision", () => {
+ const workspace = completeReconstructionCoverageData();
+ const result = workspace.verifier_results[0];
+ if (result === undefined)
+ throw new Error("Expected fixture verifier result");
+ const changed = createReconstructionCoverageData({
+ ...workspace,
+ verifier_results: [
+ { ...result, observed_at: "2026-07-16T11:00:00.1231Z" },
+ {
+ ...result,
+ observed_at: "2026-07-16T11:00:00.1239Z",
+ status: "fail",
+ },
+ ],
+ });
+
+ expect(
+ evaluateReconstructionClosure(
+ changed,
+ "replacement.cli",
+ RECONSTRUCTION_COVERAGE_NOW,
+ ),
+ ).toMatchObject({
+ status: "failed",
+ reasons: [expect.objectContaining({ code: "verifier-failed" })],
+ });
+ });
+});
+
+describe("reconstruction coverage verifier future timestamps", () => {
+ it("treats an observation beyond millisecond-precision now as future", () => {
+ const workspace = completeReconstructionCoverageData();
+ const result = workspace.verifier_results[0];
+ if (result === undefined)
+ throw new Error("Expected fixture verifier result");
+ const changed = createReconstructionCoverageData({
+ ...workspace,
+ verifier_results: [
+ { ...result, observed_at: "2026-07-16T12:00:00.1239Z" },
+ ],
+ });
+
+ expect(
+ evaluateReconstructionClosure(
+ changed,
+ "replacement.cli",
+ Date.parse("2026-07-16T12:00:00.123Z") + 0.5,
+ ),
+ ).toMatchObject({
+ status: "unknown",
+ reasons: [expect.objectContaining({ code: "verifier-result-stale" })],
+ });
+ });
+
+ it("rejects a non-finite evaluation clock", () => {
+ const workspace = completeReconstructionCoverageData();
+ expect(() =>
+ evaluateReconstructionClosure(workspace, "replacement.cli", Number.NaN),
+ ).toThrow("Expected finite epoch milliseconds.");
+ });
+
it("rejects verifier observations from the future", () => {
const workspace = completeReconstructionCoverageData();
const result = workspace.verifier_results[0];
diff --git a/src/domain/reconstructionCoverage.ts b/src/domain/reconstructionCoverage.ts
index 485b66a5a..04913d4ae 100644
--- a/src/domain/reconstructionCoverage.ts
+++ b/src/domain/reconstructionCoverage.ts
@@ -19,7 +19,10 @@ import {
} from "./reconstructionCoverageEvaluation.js";
import { digestSchema } from "./../domain/digests.js";
import { prefixedDigestSchema } from "./../domain/digests.js";
-import { offsetDateTimeSchema } from "./offsetDateTime.js";
+import {
+ offsetDateTimeInstantFromEpochMilliseconds,
+ offsetDateTimeSchema,
+} from "./offsetDateTime.js";
const evidenceIdSchema = prefixedDigestSchema("ev");
const stableIdSchema = z
@@ -213,6 +216,7 @@ const closureReasonSchema = z.strictObject({
"verifier-result-missing",
"verifier-result-stale",
"verifier-result-incompatible",
+ "verifier-result-ambiguous",
"verifier-failed",
"verifier-unknown",
"active-unknown",
@@ -274,10 +278,12 @@ export const evaluateReconstructionClosure = (
);
if (boundary === undefined)
throw new TypeError(`Unknown reconstruction boundary: ${boundaryId}`);
+ const nowInstant = offsetDateTimeInstantFromEpochMilliseconds(nowEpochMs);
const context: ReconstructionEvaluationContext = {
coverage,
boundary,
nowEpochMs,
+ nowInstant,
reasons: [],
evidenceIds: new Set(),
};
@@ -394,6 +400,7 @@ const closureStatus = (
[
"verifier-result-stale",
"verifier-result-incompatible",
+ "verifier-result-ambiguous",
"verifier-unknown",
"active-unknown",
"owner-path-unknown",
diff --git a/src/domain/reconstructionCoverageEvaluation.ts b/src/domain/reconstructionCoverageEvaluation.ts
index ea82e5636..f8a56b261 100644
--- a/src/domain/reconstructionCoverageEvaluation.ts
+++ b/src/domain/reconstructionCoverageEvaluation.ts
@@ -3,6 +3,16 @@ import type {
ReconstructionCoverageData,
ReconstructionVerifierContract,
} from "./reconstructionCoverage.js";
+import {
+ compareOffsetDateTimeInstants,
+ offsetDateTimeInstantFromEpochMilliseconds,
+ type OffsetDateTimeInstant,
+} from "./offsetDateTime.js";
+import {
+ latestVerifierObservationsByVerifier,
+ sameVerifierAssessment,
+ type VerifierObservation,
+} from "./reconstructionCoverageVerifierResults.js";
export const recommendedReconstructionProbes = (
reasons: readonly ClosureReason[],
@@ -29,6 +39,7 @@ export interface ReconstructionEvaluationContext {
readonly coverage: ReconstructionCoverageData;
readonly boundary: Boundary;
readonly nowEpochMs: number;
+ readonly nowInstant: OffsetDateTimeInstant;
readonly reasons: ClosureReason[];
readonly evidenceIds: Set;
}
@@ -184,7 +195,7 @@ interface VerifierIndexes {
>;
readonly latestResultsByVerifier: ReadonlyMap<
string,
- ReconstructionCoverageData["verifier_results"][number]
+ readonly VerifierObservation[]
>;
readonly artifactDigests: ReadonlySet;
readonly ownerDigests: ReadonlySet;
@@ -213,20 +224,6 @@ const createVerifierIndexes = (
contractsByClaim.set(claimId, contracts);
}
- const latestResultsByVerifier = new Map<
- string,
- ReconstructionCoverageData["verifier_results"][number]
- >();
- for (const result of coverage.verifier_results) {
- const latest = latestResultsByVerifier.get(result.verifier_id);
- // Stable descending sort used to choose the first input record on ties.
- if (
- latest === undefined ||
- Date.parse(result.observed_at) > Date.parse(latest.observed_at)
- )
- latestResultsByVerifier.set(result.verifier_id, result);
- }
-
const ownersBySurface = new Map<
string,
ReconstructionCoverageData["owners"][number][]
@@ -239,7 +236,9 @@ const createVerifierIndexes = (
return {
contractsByClaim,
- latestResultsByVerifier,
+ latestResultsByVerifier: latestVerifierObservationsByVerifier(
+ coverage.verifier_results,
+ ),
artifactDigests: new Set(
coverage.artifacts.map(({ artifact_sha256: value }) => value),
),
@@ -260,8 +259,10 @@ const evaluateVerifierResult = (
contract: ReconstructionVerifierContract,
indexes: VerifierIndexes,
): void => {
- const result = indexes.latestResultsByVerifier.get(contract.verifier_id);
- if (result === undefined) {
+ const latestResults = indexes.latestResultsByVerifier.get(
+ contract.verifier_id,
+ );
+ if (latestResults === undefined) {
addReason(
context,
"verifier-result-missing",
@@ -270,7 +271,26 @@ const evaluateVerifierResult = (
);
return;
}
- addEvidence(context, result.evidence_ids);
+ addEvidence(
+ context,
+ latestResults.flatMap(({ result }) => result.evidence_ids),
+ );
+ const latest = latestResults[0];
+ if (latest === undefined) return;
+ const { result } = latest;
+ if (
+ !latestResults.every((candidate) =>
+ sameVerifierAssessment(result, candidate.result),
+ )
+ ) {
+ addReason(
+ context,
+ "verifier-result-ambiguous",
+ claim.claim_id,
+ "Latest verifier observations have conflicting assessment content.",
+ );
+ return;
+ }
if (!verifierResultIsCompatible(claim, contract, result, indexes)) {
addReason(
context,
@@ -280,10 +300,14 @@ const evaluateVerifierResult = (
);
return;
}
- const observedAt = Date.parse(result.observed_at);
+ const cutoffEpochMs = context.nowEpochMs - contract.max_age_ms;
if (
- observedAt > context.nowEpochMs ||
- context.nowEpochMs - observedAt > contract.max_age_ms
+ compareOffsetDateTimeInstants(latest.instant, context.nowInstant) > 0 ||
+ (cutoffEpochMs >= -Number.MAX_SAFE_INTEGER &&
+ compareOffsetDateTimeInstants(
+ latest.instant,
+ offsetDateTimeInstantFromEpochMilliseconds(cutoffEpochMs),
+ ) < 0)
) {
addReason(
context,
diff --git a/src/domain/reconstructionCoverageVerifierResults.ts b/src/domain/reconstructionCoverageVerifierResults.ts
new file mode 100644
index 000000000..de7f55874
--- /dev/null
+++ b/src/domain/reconstructionCoverageVerifierResults.ts
@@ -0,0 +1,57 @@
+import type { ReconstructionCoverageData } from "./reconstructionCoverage.js";
+import { uniqueSorted } from "./canonicalOrdering.js";
+import {
+ compareOffsetDateTimeInstants,
+ parseOffsetDateTimeInstant,
+ type OffsetDateTimeInstant,
+} from "./offsetDateTime.js";
+
+type VerifierResult = ReconstructionCoverageData["verifier_results"][number];
+
+export interface VerifierObservation {
+ readonly result: VerifierResult;
+ readonly instant: OffsetDateTimeInstant;
+}
+
+/** Index each verifier's latest timestamp group without relying on array order. */
+export const latestVerifierObservationsByVerifier = (
+ results: readonly VerifierResult[],
+): ReadonlyMap => {
+ const latestByVerifier = new Map();
+ for (const result of results) {
+ const observation = {
+ result,
+ instant: parseOffsetDateTimeInstant(result.observed_at),
+ };
+ const latest = latestByVerifier.get(result.verifier_id);
+ const latestInstant = latest?.[0]?.instant;
+ const comparison =
+ latestInstant === undefined
+ ? 1
+ : compareOffsetDateTimeInstants(observation.instant, latestInstant);
+ if (latest === undefined || comparison > 0)
+ latestByVerifier.set(result.verifier_id, [observation]);
+ else if (comparison === 0) latest.push(observation);
+ }
+ return latestByVerifier;
+};
+
+/** Compare assessment content while excluding timestamp spelling and provenance. */
+export const sameVerifierAssessment = (
+ left: VerifierResult,
+ right: VerifierResult,
+): boolean =>
+ verifierAssessmentIdentity(left) === verifierAssessmentIdentity(right);
+
+const verifierAssessmentIdentity = (result: VerifierResult): string =>
+ JSON.stringify({
+ verifier_id: result.verifier_id,
+ contract_sha256: result.contract_sha256,
+ status: result.status,
+ covered_claim_ids: uniqueSorted(result.covered_claim_ids),
+ covered_dimensions: uniqueSorted(result.covered_dimensions),
+ artifact_sha256s: uniqueSorted(result.artifact_sha256s),
+ owner_sha256s: uniqueSorted(result.owner_sha256s),
+ normalization_sha256: result.normalization_sha256,
+ repeats: result.repeats,
+ });
diff --git a/src/domain/residualUnknown.ts b/src/domain/residualUnknown.ts
index 0819a3964..e5db1cc54 100644
--- a/src/domain/residualUnknown.ts
+++ b/src/domain/residualUnknown.ts
@@ -12,7 +12,7 @@ import { functionComparisonDimensionNameSchema } from "./functionComparisonSchem
const evidenceIdSchema = prefixedDigestSchema("ev");
const unknownIdSchema = prefixedDigestSchema("unk");
const text = z.string().trim().min(1);
-const environmentRequirementSchema = z.object({
+const environmentRequirementSchema = z.strictObject({
id: z.string().min(1).nullable(),
platform: z.string().min(1).nullable(),
architecture: z.string().min(1).nullable(),
@@ -39,7 +39,7 @@ const stableUnknownId = (
)
.digest("hex")}`;
-const probeSchema = z.object({
+const probeSchema = z.strictObject({
operation: z.string().min(1),
rationale: text,
});
@@ -60,17 +60,17 @@ const comparisonConclusionScopeSchema = z
message: "Comparison dimensions must be sorted and unique",
});
});
-const relationshipSchema = z.object({
+const relationshipSchema = z.strictObject({
type: z.enum(["depends-on", "related-to", "contradicts"]),
unknown_id: unknownIdSchema,
});
const resolutionSchema = z.discriminatedUnion("disposition", [
- z.object({
+ z.strictObject({
disposition: z.literal("verified"),
rationale: text,
evidence_ids: z.array(evidenceIdSchema).min(1),
}),
- z.object({
+ z.strictObject({
disposition: z.enum(["withdrawn", "out-of-scope"]),
rationale: text,
evidence_ids: z.array(evidenceIdSchema),
@@ -78,7 +78,7 @@ const resolutionSchema = z.discriminatedUnion("disposition", [
]);
/** Strict durable record for one unresolved or evidence-qualified question. */
-const residualUnknownObjectSchema = z.object({
+const residualUnknownObjectSchema = z.strictObject({
unknown_id: unknownIdSchema,
revision: z.number().int().min(1),
previous_revision_digest: z
diff --git a/src/domain/wasm/wasmArtifact.ts b/src/domain/wasm/wasmArtifact.ts
index 254a55a3a..d8c89ddf3 100644
--- a/src/domain/wasm/wasmArtifact.ts
+++ b/src/domain/wasm/wasmArtifact.ts
@@ -1,5 +1,6 @@
import { z } from "zod";
import { createHash } from "node:crypto";
+import type { EvidenceSubjectTarget } from "../evidence.js";
import { localPathStringSchema } from "../localPath.js";
@@ -137,11 +138,20 @@ export type InspectWasmArtifactInput = z.infer<
>;
export type WasmArtifact = z.infer;
-/** A WASM observation must identify the exact selected path and byte digest. */
+/** A WASM observation must identify the selected file path and byte digest. */
+export type WasmArtifactSubject = Pick<
+ EvidenceSubjectTarget,
+ "path" | "sha256" | "format"
+>;
+type WasmArtifactFileSubject = WasmArtifactSubject & {
+ readonly format: "file";
+};
+
export const wasmArtifactMatchesSubject = (
artifact: WasmArtifact["artifact"],
- subject: Pick | null | undefined,
-): subject is Pick =>
+ subject: WasmArtifactSubject | null | undefined,
+): subject is WasmArtifactFileSubject =>
subject != null &&
subject.path === artifact.path &&
- subject.sha256 === artifact.sha256;
+ subject.sha256 === artifact.sha256 &&
+ subject.format === "file";
diff --git a/src/evaluation/CodexAgentEval.ts b/src/evaluation/CodexAgentEval.ts
index bac8d8191..55ec8333e 100644
--- a/src/evaluation/CodexAgentEval.ts
+++ b/src/evaluation/CodexAgentEval.ts
@@ -1,10 +1,11 @@
import {
- deliveredCodexEvidence,
evaluateKnownAnswers,
+ parseCodexToolCall,
type FixtureClaimExpectation,
type KnownAnswerAssessment,
+ type ParsedCodexToolCall,
} from "./KnownAnswerEvaluation.js";
-import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
+import { canonicalJson } from "../domain/comparisonSemantics.js";
import { TOOL_CONTRACTS } from "../contracts/toolContracts.js";
/** One REA MCP invocation observed in a Codex JSONL transcript. */
@@ -57,17 +58,6 @@ const textValue = (value: unknown): string | undefined =>
const numberValue = (value: unknown): number =>
typeof value === "number" && Number.isFinite(value) ? value : 0;
-const canonicalValue = (value: unknown): unknown => {
- if (Array.isArray(value)) return value.map(canonicalValue);
- const object = record(value);
- if (object === undefined) return value;
- return Object.fromEntries(
- Object.entries(object)
- .sort(([left], [right]) => compareUnicodeCodePoints(left, right))
- .map(([key, child]) => [key, canonicalValue(child)]),
- );
-};
-
const toolResultError = (
item: Record,
): Record | undefined => {
@@ -113,29 +103,18 @@ const toolResultFailed = (
);
};
-const callFromEvent = (
- event: Record,
+const callFromParsed = (
+ parsed: ParsedCodexToolCall | undefined,
): CodexMcpCall | undefined => {
- const item = record(
- event.type === "item.completed"
- ? event.item
- : event.type === "mcp_tool_call"
- ? event
- : undefined,
- );
- if (item?.type !== "mcp_tool_call") return undefined;
- const tool = textValue(item.tool) ?? textValue(item.name);
- if (tool === undefined) return undefined;
- const error = toolResultError(item);
+ if (parsed === undefined) return undefined;
+ const error = toolResultError(parsed.item);
return {
- id: textValue(item.id) ?? null,
- server: textValue(item.server) ?? textValue(item.server_name) ?? null,
- tool,
- arguments: item.arguments ?? item.input ?? {},
- evidenceIds: deliveredCodexEvidence(event).map(
- ({ evidence_id }) => evidence_id,
- ),
- error: toolResultFailed(item, error),
+ id: parsed.id,
+ server: parsed.server,
+ tool: parsed.tool,
+ arguments: parsed.arguments,
+ evidenceIds: parsed.evidence.map(({ evidence_id }) => evidence_id),
+ error: toolResultFailed(parsed.item, error),
errorCode: textValue(error?.code) ?? null,
};
};
@@ -163,16 +142,20 @@ interface EvaluationState {
outputTokens: number;
}
-const consumeEvent = (state: EvaluationState, value: unknown): void => {
+const consumeEvent = (
+ state: EvaluationState,
+ value: unknown,
+ parsedCall: ParsedCodexToolCall | undefined,
+): void => {
const event = record(value);
if (event === undefined) return;
const completedItem =
event.type === "item.completed" ? event.item : undefined;
- const call = callFromEvent(event);
+ const call = callFromParsed(parsedCall);
if (call !== undefined) {
const identity =
call.id ??
- `${call.server ?? ""}:${call.tool}:${JSON.stringify(canonicalValue(call.arguments))}`;
+ `${call.server ?? ""}:${call.tool}:${canonicalJson(call.arguments)}`;
if (!state.seenCallIds.has(identity)) {
state.seenCallIds.add(identity);
state.calls.push(call);
@@ -216,7 +199,10 @@ export const evaluateCodexEvents = (
cachedInputTokens: 0,
outputTokens: 0,
};
- for (const event of events) consumeEvent(state, event);
+ const parsedCalls = events.map(parseCodexToolCall);
+ events.forEach((event, index) =>
+ consumeEvent(state, event, parsedCalls[index]),
+ );
const reaCalls = state.calls.filter(
({ server }) => server === null || server.toLowerCase() === "rea",
@@ -228,7 +214,7 @@ export const evaluateCodexEvents = (
// useful verification, not a duplicate analysis or unchanged failed retry.
const context =
call.tool === "binary_session" ? `${String(targetRevision)}:` : "";
- const signature = `${context}${call.tool}:${JSON.stringify(canonicalValue(call.arguments))}`;
+ const signature = `${context}${call.tool}:${canonicalJson(call.arguments)}`;
signatures.set(signature, (signatures.get(signature) ?? 0) + 1);
if (
!call.error &&
@@ -271,7 +257,7 @@ export const evaluateCodexEvents = (
finalMessage,
);
const factualAssessment = evaluateKnownAnswers(
- events,
+ parsedCalls,
finalMessage,
options.fixtureClaims,
);
diff --git a/src/evaluation/KnownAnswerEvaluation.ts b/src/evaluation/KnownAnswerEvaluation.ts
index 807308b59..c6e4af72b 100644
--- a/src/evaluation/KnownAnswerEvaluation.ts
+++ b/src/evaluation/KnownAnswerEvaluation.ts
@@ -3,7 +3,7 @@ import { z } from "zod";
import { parseEvidence, type Evidence } from "../domain/evidence.js";
import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";
-import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
+import { canonicalJson } from "../domain/comparisonSemantics.js";
/** One closed fixture assertion and the producer facts that must support it. */
export interface FixtureClaimExpectation {
@@ -104,23 +104,13 @@ const isRecord = (value: unknown): value is Record =>
typeof value === "object" && value !== null && !Array.isArray(value);
const record = (value: unknown): Record | undefined =>
isRecord(value) ? value : undefined;
-const canonicalValue = (value: JsonValue): JsonValue => {
- if (Array.isArray(value)) return value.map(canonicalValue);
- if (value === null || typeof value !== "object") return value;
- return Object.fromEntries(
- Object.entries(value)
- .sort(([left], [right]) => compareUnicodeCodePoints(left, right))
- .map(([key, child]) => [key, canonicalValue(child)]),
- );
-};
const sameJson = (left: unknown, right: unknown): boolean => {
const parsedLeft = jsonValueSchema.safeParse(left);
const parsedRight = jsonValueSchema.safeParse(right);
return (
parsedLeft.success &&
parsedRight.success &&
- JSON.stringify(canonicalValue(parsedLeft.data)) ===
- JSON.stringify(canonicalValue(parsedRight.data))
+ canonicalJson(parsedLeft.data) === canonicalJson(parsedRight.data)
);
};
@@ -168,6 +158,16 @@ interface DeliveredEvidence {
readonly conflicts: Set;
}
+/** One completed tool call, with aliases normalized and successful Evidence authenticated. */
+export interface ParsedCodexToolCall {
+ readonly item: Record;
+ readonly id: string | null;
+ readonly server: string | null;
+ readonly tool: string;
+ readonly arguments: JsonValue;
+ readonly evidence: readonly Evidence[];
+}
+
const consistentAliases = (
value: Record,
left: string,
@@ -177,30 +177,14 @@ const consistentAliases = (
value[right] === undefined ||
value[left] === value[right];
-const completedCall = (event: unknown): Record | undefined => {
- const value = record(event);
- const item =
- value?.type === "item.completed"
- ? record(value.item)
- : value?.type === "mcp_tool_call" && value.status === "completed"
- ? value
- : undefined;
- if (item?.type !== "mcp_tool_call") return undefined;
- const server = item.server ?? item.server_name;
- if (
- typeof server !== "string" ||
- server.toLowerCase() !== "rea" ||
- (item.status !== undefined && item.status !== "completed") ||
- (item.error !== undefined && item.error !== null)
- )
- return undefined;
- if (
- !consistentAliases(item, "server", "server_name") ||
- !consistentAliases(item, "tool", "name")
- )
- return undefined;
- return item;
-};
+const consistentJsonFields = (
+ value: Record,
+ left: string,
+ right: string,
+): boolean =>
+ value[left] === undefined ||
+ value[right] === undefined ||
+ sameJson(value[left], value[right]);
const consistentJsonAliases = (
value: Record,
@@ -215,6 +199,7 @@ const consistentJsonAliases = (
const evidenceFromCall = (
item: Record,
+ tool: string,
): Evidence | undefined => {
if (!consistentJsonAliases(item, "result", "output")) return undefined;
const result = record(item.result ?? item.output);
@@ -254,22 +239,42 @@ const evidenceFromCall = (
// Transcript output is untrusted; invalid Evidence cannot support a claim.
return undefined;
}
- if ((item.tool ?? item.name) !== evidence.operation) return undefined;
+ if (tool !== evidence.operation) return undefined;
return evidence;
};
-/** Authenticate completed REA deliveries for both citations and fixture grading. */
-export const deliveredCodexEvidence = (event: unknown): readonly Evidence[] => {
- const item = completedCall(event);
- if (item === undefined) return [];
- const evidence = evidenceFromCall(item);
- if (evidence === undefined) return [];
+const completedToolItem = (
+ event: unknown,
+): Record | undefined => {
+ const value = record(event);
+ const wrapped = value?.type === "item.completed";
+ const item = wrapped
+ ? record(value.item)
+ : value?.type === "mcp_tool_call"
+ ? value
+ : undefined;
+ if (item?.type !== "mcp_tool_call") return undefined;
+ const terminalStatus =
+ item.status === "completed" || item.status === "failed";
+ if (
+ (wrapped
+ ? item.status !== undefined && !terminalStatus
+ : !terminalStatus) ||
+ !consistentAliases(item, "server", "server_name") ||
+ !consistentAliases(item, "tool", "name") ||
+ !consistentJsonFields(item, "arguments", "input")
+ )
+ return undefined;
+ return item;
+};
+
+const artifactDelivery = (evidence: Evidence): readonly Evidence[] => {
const records = [evidence];
- // Artifact inspection delivers its inventory Evidence inline. Bare links and
- // arbitrary IDs in normalized facts are references, not delivered records.
if (evidence.operation !== "inspect_artifact") return records;
const substeps = record(evidence.normalized_result)?.substeps;
if (!Array.isArray(substeps)) return records;
+ // Artifact inspection delivers linked inventory Evidence inline; bare IDs in
+ // normalized facts are references, not authenticated deliveries.
for (const value of substeps) {
const substep = record(value);
if (
@@ -293,13 +298,56 @@ export const deliveredCodexEvidence = (event: unknown): readonly Evidence[] => {
return records;
};
+/** Parse one completed transcript call and authenticate any successful REA Evidence. */
+export const parseCodexToolCall = (
+ event: unknown,
+): ParsedCodexToolCall | undefined => {
+ const item = completedToolItem(event);
+ if (item === undefined) return undefined;
+ const status = item.status;
+ const server = item.server ?? item.server_name;
+ const tool = item.tool ?? item.name;
+ if (
+ ((item.server !== undefined || item.server_name !== undefined) &&
+ typeof server !== "string") ||
+ typeof tool !== "string" ||
+ tool.length === 0
+ )
+ return undefined;
+ const argumentsValue =
+ item.arguments !== undefined
+ ? item.arguments
+ : item.input !== undefined
+ ? item.input
+ : {};
+ const parsedArguments = jsonValueSchema.safeParse(argumentsValue);
+ if (!parsedArguments.success) return undefined;
+ const parsed: ParsedCodexToolCall = {
+ item,
+ id: typeof item.id === "string" && item.id.length > 0 ? item.id : null,
+ server: typeof server === "string" ? server : null,
+ tool,
+ arguments: parsedArguments.data,
+ evidence: [],
+ };
+ if (
+ parsed.server?.toLowerCase() !== "rea" ||
+ status === "failed" ||
+ (item.error !== undefined && item.error !== null)
+ )
+ return parsed;
+ const evidence = evidenceFromCall(item, tool);
+ if (evidence === undefined) return parsed;
+ return { ...parsed, evidence: artifactDelivery(evidence) };
+};
+
const collectDeliveredEvidence = (
- events: readonly unknown[],
+ calls: readonly (ParsedCodexToolCall | undefined)[],
): DeliveredEvidence => {
const records = new Map();
const conflicts = new Set();
- for (const event of events) {
- for (const evidence of deliveredCodexEvidence(event)) {
+ for (const call of calls) {
+ for (const evidence of call?.evidence ?? []) {
const previous = records.get(evidence.evidence_id);
if (previous !== undefined && !sameJson(previous, evidence))
conflicts.add(evidence.evidence_id);
@@ -401,7 +449,7 @@ const assessClaim = (
/** Grade closed answers only against configured fixture truth and delivered authenticated Evidence. */
export const evaluateKnownAnswers = (
- events: readonly unknown[],
+ calls: readonly (ParsedCodexToolCall | undefined)[],
finalMessage: string,
expectations: readonly FixtureClaimExpectation[] | undefined,
): KnownAnswerAssessment => {
@@ -441,7 +489,7 @@ export const evaluateKnownAnswers = (
manifestFailures.push(`unknown_claim:${claim.id}`);
submitted.set(claim.id, claim);
}
- const delivered = collectDeliveredEvidence(events);
+ const delivered = collectDeliveredEvidence(calls);
const claims = expectations.map((expected) =>
assessClaim(expected, submitted.get(expected.id), delivered),
);
diff --git a/src/evm/EvmoleInterfaceProvider.ts b/src/evm/EvmoleInterfaceProvider.ts
index 03731a92a..7437edc23 100644
--- a/src/evm/EvmoleInterfaceProvider.ts
+++ b/src/evm/EvmoleInterfaceProvider.ts
@@ -6,10 +6,12 @@ import { fileURLToPath } from "node:url";
import { z } from "zod";
import {
createAnalysisExecution,
- type AnalysisExecution,
type ExecutionOptions,
} from "../application/AnalysisProvider.js";
-import type { EvmInterfacePort } from "../application/evm/EvmInterfacePort.js";
+import type {
+ EvmInterfaceExecution,
+ EvmInterfacePort,
+} from "../application/evm/EvmInterfacePort.js";
import { readStableArtifact } from "../artifacts/readStableArtifact.js";
import { OwnedCommandFailure } from "../process/OwnedCommand.js";
import type {
@@ -98,7 +100,7 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort {
inspect(
input: InspectEvmInterfaceInput,
options?: ExecutionOptions,
- ): Promise> {
+ ): Promise> {
if (this.#closing) return Promise.resolve(err(this.#closedError()));
const operation = this.#tail.then(() =>
this.#closing ? err(this.#closedError()) : this.#inspect(input, options),
@@ -113,7 +115,7 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort {
async #inspect(
input: InspectEvmInterfaceInput,
options?: ExecutionOptions,
- ): Promise> {
+ ): Promise> {
const pending = await this.#retire();
if (pending !== undefined) return err(pending);
let root: Pick | undefined;
@@ -123,7 +125,7 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort {
let workerLimits: EvmWorkerLimits | undefined;
const limiter =
this.environment.REA_EVM_PRLIMIT_COMMAND ?? "/usr/bin/prlimit";
- let result: Result;
+ let result: Result;
try {
if (options?.signal?.aborted) throw new AnalysisCancelledError(OPERATION);
if (process.platform !== "linux" || process.arch !== "x64")
diff --git a/src/filesystem/RegularFile.ts b/src/filesystem/RegularFile.ts
index 40beae1b6..be885c93e 100644
--- a/src/filesystem/RegularFile.ts
+++ b/src/filesystem/RegularFile.ts
@@ -101,6 +101,16 @@ export const openRegularFile = async (
options.signal?.throwIfAborted();
if (!metadata.isFile())
throw new NonRegularFileReadError(path, metadata.isDirectory());
+ // O_NOFOLLOW is unavailable on Windows. Recheck the name only on hosts
+ // where open could have followed a symlink, while the descriptor is owned.
+ if (options.symlinks === "reject" && (constants.O_NOFOLLOW ?? 0) === 0) {
+ const named = await lstat(path);
+ options.signal?.throwIfAborted();
+ if (named.isSymbolicLink())
+ throw new NonRegularFileReadError(path, false);
+ if (!sameRegularFileState(metadata, named))
+ throw new RegularFileChangedError(path);
+ }
return handle;
} catch (cause: unknown) {
try {
diff --git a/src/firmware/FirmwareFiles.ts b/src/firmware/FirmwareFiles.ts
index 10201905e..d20226e76 100644
--- a/src/firmware/FirmwareFiles.ts
+++ b/src/firmware/FirmwareFiles.ts
@@ -213,19 +213,15 @@ export const inventoryFirmwareOutput = async (
});
if (handle === undefined) continue;
const names: string[] = [];
- try {
- for await (const entry of handle) {
- throwIfFirmwareInventoryCancelled(signal, operation);
- count++;
- if (count > maxEntries)
- throw new AnalysisOutputError(
- operation,
- `Staging entry budget exceeded (${maxEntries})`,
- );
- names.push(entry.name);
- }
- } finally {
- await handle.close().catch(() => undefined);
+ for await (const entry of handle) {
+ throwIfFirmwareInventoryCancelled(signal, operation);
+ count++;
+ if (count > maxEntries)
+ throw new AnalysisOutputError(
+ operation,
+ `Staging entry budget exceeded (${maxEntries})`,
+ );
+ names.push(entry.name);
}
for (const name of names.sort()) {
const path = join(directory, name);
diff --git a/src/ghidra/GhidraAnalysisSeeds.test.ts b/src/ghidra/GhidraAnalysisSeeds.test.ts
index 8af76a4da..37437ebf7 100644
--- a/src/ghidra/GhidraAnalysisSeeds.test.ts
+++ b/src/ghidra/GhidraAnalysisSeeds.test.ts
@@ -196,7 +196,7 @@ describe("Ghidra seed profile", () => {
const host: GhidraInstallationHost = {
platform: "linux",
architecture: "x64",
- readText: () => "application.version=12.1.4\n",
+ readText: () => "application.version=12.1.4\napplication.java.min=21\n",
executable: () => true,
probeJava: () => ({
version: "21.0.11",
diff --git a/src/ghidra/GhidraDoctor.test.ts b/src/ghidra/GhidraDoctor.test.ts
index e1ea7fe37..e5d20f4c8 100644
--- a/src/ghidra/GhidraDoctor.test.ts
+++ b/src/ghidra/GhidraDoctor.test.ts
@@ -15,7 +15,7 @@ const INSTALL = "/opt/ghidra_12.1.4_PUBLIC";
const installationHost = (
overrides: Partial = {},
): GhidraInstallationHost => ({
- readText: () => "application.version=12.1.4\n",
+ readText: () => "application.version=12.1.4\napplication.java.min=21\n",
executable: () => true,
probeJava: () => ({
version: "21.0.11",
@@ -111,7 +111,9 @@ describe("Ghidra doctor integration", () => {
"wrong version",
inspection(
{ installDir: INSTALL },
- { readText: () => "application.version=11.4\n" },
+ {
+ readText: () => "application.version=11.4\napplication.java.min=21\n",
+ },
),
"ghidra-version",
],
@@ -136,6 +138,14 @@ describe("Ghidra doctor integration", () => {
),
"ghidra-java",
],
+ [
+ "missing Java minimum",
+ inspection(
+ { installDir: INSTALL },
+ { readText: () => "application.version=12.1.4\n" },
+ ),
+ "ghidra-java",
+ ],
[
"unsupported architecture",
inspection({ installDir: INSTALL, architecture: "arm" }),
diff --git a/src/ghidra/GhidraInstallation.test.ts b/src/ghidra/GhidraInstallation.test.ts
index 21c4195ad..776c10308 100644
--- a/src/ghidra/GhidraInstallation.test.ts
+++ b/src/ghidra/GhidraInstallation.test.ts
@@ -12,6 +12,8 @@ import {
import {
SUPPORTED_GHIDRA_JAVA_MAJOR,
SUPPORTED_GHIDRA_VERSION,
+ ghidraApplicationProperties,
+ ghidraJavaRequirement,
} from "./GhidraInstallationPolicy.js";
const INSTALL = "/opt/ghidra";
@@ -42,7 +44,7 @@ const host = (
): GhidraInstallationHost => ({
readText: (path) =>
path === PROPERTIES
- ? `application.version=${SUPPORTED_GHIDRA_VERSION}\n`
+ ? `application.version=${SUPPORTED_GHIDRA_VERSION}\napplication.java.min=${String(SUPPORTED_GHIDRA_JAVA_MAJOR)}\n`
: undefined,
executable: (path) =>
path === HEADLESS || path === MAC_DECOMPILER || path === LINUX_DECOMPILER,
@@ -190,7 +192,7 @@ describe("Ghidra installation inspection", () => {
architecture: "x64",
readText: (path) =>
path === WINDOWS_PROPERTIES
- ? `application.version=${SUPPORTED_GHIDRA_VERSION}\n`
+ ? `application.version=${SUPPORTED_GHIDRA_VERSION}\napplication.java.min=21\n`
: undefined,
executable: (path) =>
path === WINDOWS_HEADLESS || path === WINDOWS_DECOMPILER,
@@ -275,7 +277,9 @@ describe("Ghidra installation rejection diagnostics", () => {
platform: "linux" as const,
architecture: "x64" as const,
},
- override: { readText: () => "application.version=11.4\n" },
+ override: {
+ readText: () => "application.version=11.4\napplication.java.min=21\n",
+ },
failed: "version",
code: "unsupported_version",
},
@@ -350,6 +354,167 @@ describe("Ghidra installation rejection diagnostics", () => {
});
describe("Ghidra release line and JDK bounds", () => {
+ it("uses Java Properties last-key, delimiter, escape, and continuation rules", () => {
+ const properties = ghidraApplicationProperties(
+ [
+ "application.version=11.4",
+ "# comment ending with a slash " + "\\",
+ "application.\\u0076ersion : 12.\\",
+ " 1.\\u0034",
+ "! another comment " + "\\",
+ "application.java.\\u006din\t21",
+ "application.java.max=",
+ ].join("\n"),
+ );
+ expect(properties).toEqual({
+ providerVersion: "12.1.4",
+ javaMinimum: { status: "major", major: 21 },
+ javaMaximum: { status: "absent" },
+ parseError: null,
+ });
+ expect(
+ ghidraApplicationProperties("application.version=12.1.4").javaMinimum,
+ ).toEqual({
+ status: "absent",
+ });
+ expect(
+ ghidraApplicationProperties(
+ "application.version=12.1.4\napplication.java.min=\n",
+ ).javaMinimum,
+ ).toEqual({ status: "unresolved", raw: "" });
+ expect(
+ ghidraApplicationProperties("application.version=12.1.4\\")
+ .providerVersion,
+ ).toBe("12.1.4");
+ expect(
+ ghidraApplicationProperties("application.version=12.\\\n #.1")
+ .providerVersion,
+ ).toBe("12.#.1");
+ expect(
+ ghidraApplicationProperties(
+ "application.version=12.\\\n\napplication.version=12.1.4",
+ ).providerVersion,
+ ).toBe("12.1.4");
+ });
+
+ it("matches Ghidra integer Java bounds and zero maximum semantics", () => {
+ const properties = ghidraApplicationProperties(
+ "application.java.min=21.0\napplication.java.max=0\n",
+ );
+ expect(properties.javaMinimum).toEqual({
+ status: "unresolved",
+ raw: "21.0",
+ });
+ expect(properties.javaMaximum).toEqual({ status: "absent" });
+ expect(
+ ghidraApplicationProperties("application.java.max=+0").javaMaximum,
+ ).toEqual({
+ status: "absent",
+ });
+ expect(
+ ghidraApplicationProperties("application.java.max=+0").javaMaximum,
+ ).toEqual({ status: "absent" });
+ expect(
+ ghidraApplicationProperties("application.java.min=+21").javaMinimum,
+ ).toEqual({
+ status: "major",
+ major: 21,
+ });
+ expect(
+ ghidraApplicationProperties("application.java.min=٢١").javaMinimum,
+ ).toEqual({
+ status: "major",
+ major: 21,
+ });
+ expect(
+ ghidraApplicationProperties("application.java.min=21").javaMinimum,
+ ).toEqual({
+ status: "major",
+ major: 21,
+ });
+ expect(
+ ghidraApplicationProperties("application.java.max=+0").javaMaximum,
+ ).toEqual({
+ status: "unresolved",
+ raw: "+0",
+ });
+ expect(
+ ghidraApplicationProperties("application.java.min=②").javaMinimum,
+ ).toEqual({
+ status: "unresolved",
+ raw: "②",
+ });
+ expect(
+ ghidraApplicationProperties("application.java.min=2147483648")
+ .javaMinimum,
+ ).toEqual({ status: "unresolved", raw: "2147483648" });
+ });
+
+ it("keeps an unavailable properties file unresolved for Java admission", () => {
+ expect(ghidraJavaRequirement(undefined).unresolved).toBe(
+ "application.properties is unavailable",
+ );
+ });
+
+ it("preserves property value trailing whitespace instead of normalizing it", () => {
+ const properties = ghidraApplicationProperties(
+ "application.version=12.1.4 \napplication.java.min=21 \n",
+ );
+ expect(properties.providerVersion).toBe("12.1.4 ");
+ expect(properties.javaMinimum).toEqual({
+ status: "unresolved",
+ raw: "21 ",
+ });
+ expect(properties.parseError).toBeNull();
+ });
+});
+
+describe("Ghidra malformed property admission", () => {
+ it("fails installation and doctor admission closed on malformed Unicode escapes", () => {
+ const result = inspectGhidraInstallation(
+ {
+ environment: {},
+ installDir: INSTALL,
+ platform: "linux",
+ architecture: "x64",
+ },
+ host({
+ readText: () =>
+ "application.version=12.1.4\nbroken=\\u12G4\napplication.java.min=17\n",
+ }),
+ );
+ expect(result.status).toBe("unavailable");
+ expect(result.providerVersion).toBeNull();
+ expect(result.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ name: "version",
+ status: "failed",
+ code: "version_unresolved",
+ detail: expect.stringContaining("Malformed Unicode escape"),
+ }),
+ expect.objectContaining({
+ name: "java",
+ status: "failed",
+ code: "version_unresolved",
+ remediation: expect.stringContaining(
+ "application.properties parse failed",
+ ),
+ }),
+ ]),
+ );
+ expect(projectGhidraDoctorInspection(result)).toMatchObject({
+ available: false,
+ registrationEnvironment: {},
+ checks: expect.arrayContaining([
+ expect.objectContaining({ name: "version", ok: false }),
+ expect.objectContaining({ name: "java", ok: false }),
+ ]),
+ });
+ });
+});
+
+describe("Ghidra installation version admission", () => {
it.each([
{
name: "JDK above the installation maximum",
@@ -367,16 +532,23 @@ describe("Ghidra release line and JDK bounds", () => {
failed: "java",
code: "version_unresolved",
},
+ {
+ name: "missing Java minimum",
+ readText: () => "application.version=12.1.4\n",
+ probeJava: () => JAVA,
+ failed: "java",
+ code: "version_unresolved",
+ },
{
name: "unparseable Ghidra version",
- readText: () => "application.version=latest\n",
+ readText: () => "application.version=latest\napplication.java.min=21\n",
probeJava: () => JAVA,
failed: "version",
code: "version_unresolved",
},
{
name: "different Ghidra line",
- readText: () => "application.version=12.2.0\n",
+ readText: () => "application.version=12.2.0\napplication.java.min=21\n",
probeJava: () => JAVA,
failed: "version",
code: "unsupported_version",
@@ -422,7 +594,7 @@ describe("Ghidra release line and JDK bounds", () => {
});
});
- it("honors an installation that declares a lower Java minimum", () => {
+ it("accepts a lower Java minimum declared by the installation", () => {
expect(
inspectGhidraInstallation(
{
diff --git a/src/ghidra/GhidraInstallation.ts b/src/ghidra/GhidraInstallation.ts
index 713fe820f..c6ca5212d 100644
--- a/src/ghidra/GhidraInstallation.ts
+++ b/src/ghidra/GhidraInstallation.ts
@@ -641,14 +641,20 @@ const versionCheck = (
properties: GhidraApplicationProperties | undefined,
): GhidraInstallationCheck => {
const raw = properties?.providerVersion;
+ const parseError = properties?.parseError;
return installationCheck({
name: "version",
- passed: ghidraReleaseAccepted(raw),
+ passed: parseError == null && ghidraReleaseAccepted(raw),
code:
- ghidraReleaseCompatibility(raw).status === "unsupported"
- ? "unsupported_version"
- : "version_unresolved",
- detail: ghidraVersionDetail(raw),
+ parseError != null
+ ? "version_unresolved"
+ : ghidraReleaseCompatibility(raw).status === "unsupported"
+ ? "unsupported_version"
+ : "version_unresolved",
+ detail:
+ parseError == null
+ ? ghidraVersionDetail(raw)
+ : `application.properties could not be parsed: ${parseError}`,
remediation: `Install a Ghidra ${ghidraReleaseLine()} release (verified with ${SUPPORTED_GHIDRA_VERSION}), or update REA for another Ghidra line.`,
});
};
@@ -701,7 +707,9 @@ const javaRemediation = (
const systemGhidraInstallationHost = (): GhidraInstallationHost => ({
readText(path) {
try {
- return readFileSync(path, "utf8");
+ // Ghidra loads this file with Properties.load(InputStream), which maps
+ // bytes as ISO-8859-1 rather than decoding UTF-8.
+ return readFileSync(path).toString("latin1");
} catch (cause: unknown) {
// best-effort cleanup: optional install probing; unreadable means unknown.
void cause;
diff --git a/src/ghidra/GhidraInstallationPolicy.ts b/src/ghidra/GhidraInstallationPolicy.ts
index bd19dc1d1..ead513cd8 100644
--- a/src/ghidra/GhidraInstallationPolicy.ts
+++ b/src/ghidra/GhidraInstallationPolicy.ts
@@ -1,10 +1,8 @@
+import { err, ok, type Result } from "../domain/result.js";
+
/** Ghidra build whose bridge behavior this REA release verifies. */
export const SUPPORTED_GHIDRA_VERSION = "12.1.4";
-/**
- * JDK major used when an installation omits `application.java.min`.
- * Admission uses that installation's `application.java.min` and
- * `application.java.max`. An empty maximum means the release sets no upper bound.
- */
+/** Verified JDK major; admission uses the installation's declared bounds. */
export const SUPPORTED_GHIDRA_JAVA_MAJOR = 21;
/** Numeric Ghidra release read from `application.version`. */
@@ -40,30 +38,49 @@ type GhidraJavaBound =
| { readonly status: "unresolved"; readonly raw: string };
/** JDK majors this installation admits, after reading its own properties. */
-export interface GhidraJavaRequirement {
- readonly minimumMajor: number;
- readonly maximumMajor: number | null;
- readonly unresolved: string | null;
-}
+export type GhidraJavaRequirement =
+ | {
+ readonly minimumMajor: number;
+ readonly maximumMajor: number | null;
+ readonly unresolved: null;
+ }
+ | { readonly unresolved: string };
/** Version and Java bounds read from one `application.properties` file. */
export interface GhidraApplicationProperties {
readonly providerVersion: string | null;
readonly javaMinimum: GhidraJavaBound;
readonly javaMaximum: GhidraJavaBound;
+ /** A malformed Java properties escape invalidates the entire file. */
+ readonly parseError: string | null;
}
const GHIDRA_RELEASE_PATTERN = /^(\d+)\.(\d+)(?:\.(\d+))?([-+].*)?$/u;
-const JAVA_MAJOR_PATTERN = /^(\d+)(?:\.\d+)*$/u;
/** Read the version and Java bounds Ghidra publishes for one installation. */
export const ghidraApplicationProperties = (
content: string,
-): GhidraApplicationProperties => ({
- providerVersion: propertyValue(content, "application.version"),
- javaMinimum: parseJavaBound(propertyValue(content, "application.java.min")),
- javaMaximum: parseJavaBound(propertyValue(content, "application.java.max")),
-});
+): GhidraApplicationProperties => {
+ const parsed = parseJavaProperties(content);
+ if (!parsed.ok)
+ return {
+ providerVersion: null,
+ javaMinimum: { status: "unresolved", raw: parsed.error },
+ javaMaximum: { status: "unresolved", raw: parsed.error },
+ parseError: parsed.error,
+ };
+ const providerVersion = parsed.value.get("application.version");
+ const minimum = parsed.value.get("application.java.min");
+ const maximum = parsed.value.get("application.java.max");
+ return {
+ providerVersion: providerVersion ?? null,
+ javaMinimum:
+ minimum === undefined ? { status: "absent" } : parseJavaBound(minimum),
+ // Ghidra uses an explicitly empty maximum to mean no upper bound.
+ javaMaximum: parseJavaMaximum(maximum),
+ parseError: null,
+ };
+};
/** Classify `application.version` against the verified release line. */
export const ghidraReleaseCompatibility = (
@@ -130,14 +147,21 @@ export const ghidraReleaseAccepted = (
export const ghidraJavaRequirement = (
properties: GhidraApplicationProperties | undefined,
): GhidraJavaRequirement => {
- const minimum = properties?.javaMinimum ?? { status: "absent" };
- const maximum = properties?.javaMaximum ?? { status: "absent" };
+ if (properties?.parseError !== null && properties?.parseError !== undefined)
+ return unresolvedJavaRequirement(
+ `application.properties parse failed: ${properties.parseError}`,
+ );
+ if (properties === undefined)
+ return unresolvedJavaRequirement("application.properties is unavailable");
+ const minimum = properties.javaMinimum;
+ const maximum = properties.javaMaximum;
if (minimum.status === "unresolved")
return unresolvedJavaRequirement(`application.java.min=${minimum.raw}`);
+ if (minimum.status === "absent")
+ return unresolvedJavaRequirement("application.java.min is missing");
if (maximum.status === "unresolved")
return unresolvedJavaRequirement(`application.java.max=${maximum.raw}`);
- const minimumMajor =
- minimum.status === "major" ? minimum.major : SUPPORTED_GHIDRA_JAVA_MAJOR;
+ const minimumMajor = minimum.major;
const maximumMajor = maximum.status === "major" ? maximum.major : null;
if (maximumMajor !== null && maximumMajor < minimumMajor)
return unresolvedJavaRequirement(
@@ -187,14 +211,56 @@ const parseGhidraRelease = (raw: string): GhidraReleaseVersion | undefined => {
return patch === undefined ? undefined : { major, minor, patch };
};
-const parseJavaBound = (raw: string | null): GhidraJavaBound => {
- if (raw === null) return { status: "absent" };
- const major = integerGroup(JAVA_MAJOR_PATTERN.exec(raw)?.[1]);
+const parseJavaBound = (raw: string): GhidraJavaBound => {
+ const major = parseJavaInteger(raw);
return major === undefined
? { status: "unresolved", raw }
: { status: "major", major };
};
+const parseJavaMaximum = (raw: string | undefined): GhidraJavaBound => {
+ if (raw === undefined || raw === "") return { status: "absent" };
+ const bound = parseJavaBound(raw);
+ return bound.status === "major" && bound.major === 0
+ ? { status: "absent" }
+ : bound;
+};
+
+const parseJavaInteger = (raw: string): number | undefined => {
+ let index = 0;
+ let sign = 1;
+ if (raw[index] === "+" || raw[index] === "-") {
+ if (raw[index] === "-") sign = -1;
+ index += 1;
+ }
+ if (index === raw.length) return undefined;
+ const limit = sign < 0 ? 2_147_483_648 : 2_147_483_647;
+ let value = 0;
+ for (; index < raw.length; index += 1) {
+ const character = raw[index];
+ if (character === undefined) return undefined;
+ const digit = javaDecimalDigit(character);
+ if (digit === undefined) return undefined;
+ if (value > Math.floor((limit - digit) / 10)) return undefined;
+ value = value * 10 + digit;
+ }
+ return sign * value;
+};
+
+/** Match Integer.parseInt(charAt) for BMP Decimal_Number characters. */
+const javaDecimalDigit = (character: string): number | undefined => {
+ const code = character.charCodeAt(0);
+ if (code >= 48 && code <= 57) return code - 48;
+ if (!/^\p{Decimal_Number}$/u.test(character)) return undefined;
+ let blockStart = code;
+ while (
+ blockStart > 0 &&
+ /^\p{Decimal_Number}$/u.test(String.fromCharCode(blockStart - 1))
+ )
+ blockStart -= 1;
+ return (code - blockStart) % 10;
+};
+
const integerGroup = (value: string | undefined): number | undefined => {
if (value === undefined) return undefined;
const parsed = Number(value);
@@ -204,17 +270,119 @@ const integerGroup = (value: string | undefined): number | undefined => {
const unresolvedJavaRequirement = (
unresolved: string,
): GhidraJavaRequirement => ({
- minimumMajor: SUPPORTED_GHIDRA_JAVA_MAJOR,
- maximumMajor: null,
unresolved,
});
-const propertyValue = (content: string, name: string): string | null => {
- for (const line of content.split(/\r?\n/u)) {
- const separator = line.indexOf("=");
- if (separator < 0 || line.slice(0, separator).trim() !== name) continue;
- const value = line.slice(separator + 1).trim();
- return value.length === 0 ? null : value;
+/** Parse Java Properties.load(InputStream) syntax from its ISO-8859-1 text. */
+const parseJavaProperties = (
+ content: string,
+): Result, string> => {
+ const values = new Map();
+ for (const line of logicalPropertyLines(content)) {
+ let start = 0;
+ while (isPropertyWhitespace(line[start])) start += 1;
+ if (start === line.length || line[start] === "#" || line[start] === "!")
+ continue;
+ let end = start;
+ let escaped = false;
+ while (end < line.length) {
+ const character = line[end];
+ if (
+ !escaped &&
+ (character === "=" ||
+ character === ":" ||
+ isPropertyWhitespace(character))
+ )
+ break;
+ if (character === "\\") escaped = !escaped;
+ else escaped = false;
+ end += 1;
+ }
+ let valueStart = end;
+ while (isPropertyWhitespace(line[valueStart])) valueStart += 1;
+ if (line[valueStart] === "=" || line[valueStart] === ":") valueStart += 1;
+ while (isPropertyWhitespace(line[valueStart])) valueStart += 1;
+ const key = decodePropertyEscapes(line.slice(start, end));
+ if (!key.ok) return err(key.error);
+ const value = decodePropertyEscapes(line.slice(valueStart));
+ if (!value.ok) return err(value.error);
+ values.set(key.value, value.value);
}
- return null;
+ return ok(values);
+};
+
+const isPropertyWhitespace = (value: string | undefined): boolean =>
+ value === " " || value === "\t" || value === "\f";
+
+/** Join odd-backslash continuations while stripping leading continuation space. */
+function* logicalPropertyLines(content: string): Generator {
+ let physicalStart = 0;
+ let logical = "";
+ let continuing = false;
+ while (physicalStart <= content.length) {
+ let physicalEnd = physicalStart;
+ while (
+ physicalEnd < content.length &&
+ content[physicalEnd] !== "\n" &&
+ content[physicalEnd] !== "\r"
+ )
+ physicalEnd += 1;
+ let line = content.slice(physicalStart, physicalEnd);
+ let leading = 0;
+ while (isPropertyWhitespace(line[leading])) leading += 1;
+ const comment =
+ !continuing && (line[leading] === "#" || line[leading] === "!");
+ if (continuing) line = line.slice(leading);
+ let continued = false;
+ if (!comment) {
+ let slashes = 0;
+ for (
+ let index = line.length - 1;
+ index >= 0 && line[index] === "\\";
+ index -= 1
+ )
+ slashes += 1;
+ continued = slashes % 2 === 1;
+ logical += continued ? line.slice(0, -1) : line;
+ }
+ if (!continued) {
+ yield logical;
+ logical = "";
+ }
+ continuing = continued;
+ if (physicalEnd === content.length) break;
+ physicalStart =
+ content[physicalEnd] === "\r" && content[physicalEnd + 1] === "\n"
+ ? physicalEnd + 2
+ : physicalEnd + 1;
+ }
+ // Properties.load still consumes the accumulated line when EOF follows a
+ // continuation marker; the marker itself was already removed above.
+ if (continuing) yield logical;
+}
+
+const decodePropertyEscapes = (value: string): Result => {
+ let result = "";
+ for (let index = 0; index < value.length; index += 1) {
+ const character = value[index];
+ if (character !== "\\") {
+ result += character;
+ continue;
+ }
+ const escaped = value[++index];
+ if (escaped === undefined)
+ return err("Trailing escape in Java properties value");
+ if (escaped === "t") result += "\t";
+ else if (escaped === "n") result += "\n";
+ else if (escaped === "r") result += "\r";
+ else if (escaped === "f") result += "\f";
+ else if (escaped === "u") {
+ const digits = value.slice(index + 1, index + 5);
+ if (digits.length !== 4 || !/^[0-9a-f]{4}$/iu.test(digits))
+ return err("Malformed Unicode escape in Java properties file");
+ result += String.fromCharCode(Number.parseInt(digits, 16));
+ index += 4;
+ } else result += escaped;
+ }
+ return ok(result);
};
diff --git a/src/ghidra/GhidraLanguageOverride.test.ts b/src/ghidra/GhidraLanguageOverride.test.ts
index a355b39fa..5f90a1454 100644
--- a/src/ghidra/GhidraLanguageOverride.test.ts
+++ b/src/ghidra/GhidraLanguageOverride.test.ts
@@ -42,7 +42,7 @@ const X86_LDEFS = `
const host: GhidraInstallationHost = {
platform: "linux",
architecture: "x64",
- readText: () => "application.version=12.1.4\n",
+ readText: () => "application.version=12.1.4\napplication.java.min=21\n",
executable: () => true,
probeJava: () => ({
version: "21.0.11",
diff --git a/src/ghidra/GhidraMipsProfile.test.ts b/src/ghidra/GhidraMipsProfile.test.ts
index 31a121cd1..ae72a3069 100644
--- a/src/ghidra/GhidraMipsProfile.test.ts
+++ b/src/ghidra/GhidraMipsProfile.test.ts
@@ -19,7 +19,7 @@ import { ghidraProfileLanguageOverride } from "./GhidraAnalysisProfile.js";
const host: GhidraInstallationHost = {
platform: "linux",
architecture: "x64",
- readText: () => "application.version=12.1.4\n",
+ readText: () => "application.version=12.1.4\napplication.java.min=21\n",
executable: () => true,
probeJava: () => ({
version: "21.0.11",
diff --git a/src/ghidra/GhidraProvider.behavior.test.ts b/src/ghidra/GhidraProvider.behavior.test.ts
index 8b9c25461..3979222d9 100644
--- a/src/ghidra/GhidraProvider.behavior.test.ts
+++ b/src/ghidra/GhidraProvider.behavior.test.ts
@@ -38,7 +38,7 @@ const INSTALL = "/opt/ghidra_12.1.4_PUBLIC";
const installationHost = (): GhidraInstallationHost => ({
platform: "linux",
architecture: "x64",
- readText: () => "application.version=12.1.4\n",
+ readText: () => "application.version=12.1.4\napplication.java.min=21\n",
executable: () => true,
probeJava: () => ({
version: "21.0.11",
diff --git a/src/ghidra/GhidraRiscvProfile.test.ts b/src/ghidra/GhidraRiscvProfile.test.ts
index 9bbb65cf3..881ba0078 100644
--- a/src/ghidra/GhidraRiscvProfile.test.ts
+++ b/src/ghidra/GhidraRiscvProfile.test.ts
@@ -53,7 +53,7 @@ const RISCV_LDEFS = `
const host: GhidraInstallationHost = {
platform: "linux",
architecture: "x64",
- readText: () => "application.version=12.1.4\n",
+ readText: () => "application.version=12.1.4\napplication.java.min=21\n",
executable: () => true,
probeJava: () => ({
version: "21.0.11",
diff --git a/src/ghidra/GhidraSnapshotCache.test.ts b/src/ghidra/GhidraSnapshotCache.test.ts
index 703bb4906..9cf5c24ad 100644
--- a/src/ghidra/GhidraSnapshotCache.test.ts
+++ b/src/ghidra/GhidraSnapshotCache.test.ts
@@ -39,7 +39,8 @@ const fixture = (version = "12.1.4") => {
{
platform: "linux",
architecture: "x64",
- readText: () => `application.version=${version}\n`,
+ readText: () =>
+ `application.version=${version}\napplication.java.min=21\n`,
executable: () => true,
probeJava: () => ({
version: "21.0.11",
diff --git a/src/hopper/BridgeLauncher.ts b/src/hopper/BridgeLauncher.ts
index 8201ee2df..043d394a4 100644
--- a/src/hopper/BridgeLauncher.ts
+++ b/src/hopper/BridgeLauncher.ts
@@ -413,6 +413,8 @@ const launchHopperProcess = async (input: {
runId: input.session.runId,
expectedCommand: ownershipCommand,
hostEnvironment: input.options.environment,
+ // The helper observes EOF when this REA process exits, including SIGKILL.
+ stdin: "pipe",
...(input.signal === undefined ? {} : { signal: input.signal }),
});
return spawn(input.argumentsForTarget);
@@ -434,6 +436,7 @@ export const linuxDemoLaunch = (
return undefined;
const helperArguments = [
options.demoHelperPath,
+ "--owner-stdin",
"--strategy",
strategy ?? "direct",
...(strategy === "user-mount-namespace" ? ["--mount-private-x11"] : []),
diff --git a/src/javascript/sourceMaps/DecodedSourceMap.ts b/src/javascript/sourceMaps/DecodedSourceMap.ts
index 60bfcfc0e..e9ed304e1 100644
--- a/src/javascript/sourceMaps/DecodedSourceMap.ts
+++ b/src/javascript/sourceMaps/DecodedSourceMap.ts
@@ -19,31 +19,6 @@ export const isBeforeSourceMapLeafStop = (
);
};
-/** Resolve one declaration with the same pinned upstream implementation used by full maps. */
-export const resolveSourceMapSource = (
- source: string | null,
- sourceRoot: string | null | undefined,
- mapUrl: string,
-): string => {
- const map = new TraceMap(
- {
- version: 3,
- names: [],
- sources: [source ?? ""],
- ...(sourceRoot == null ? {} : { sourceRoot }),
- mappings: "",
- },
- mapUrl,
- );
- const resolved = map.resolvedSources[0];
- if (resolved === undefined)
- throw new SourceMapFormatFailure(
- "format",
- "Source-map resolver did not return the requested source identity.",
- );
- return resolved;
-};
-
/** Decode leaf mappings and validate producer indices before any consumer publishes them. */
export const decodeValidatedSourceMapLeaves = (
leaves: readonly SourceMapLeaf[],
diff --git a/src/native/AppleDispatchCoverage.ts b/src/native/AppleDispatchCoverage.ts
index c49e35acc..a6c68ca51 100644
--- a/src/native/AppleDispatchCoverage.ts
+++ b/src/native/AppleDispatchCoverage.ts
@@ -42,14 +42,62 @@ export const pushDispatchCoverage = (input: {
vtables,
swift,
} = input;
+ const classOwnedMethods = result.objc_dispatch_implementations.filter(
+ ({ category }) => category === undefined,
+ );
+ const classRecords = [
+ ...result.objc_classes.flatMap((record) =>
+ record.decode?.status === "decoded"
+ ? []
+ : [
+ `class ${record.name}: ${record.decode?.reason ?? record.decode?.status ?? "decode_status_missing"}`,
+ ],
+ ),
+ ...result.objc_protocol_records.flatMap((record) =>
+ record.decode.status === "decoded"
+ ? []
+ : [
+ `protocol ${record.name}: ${record.decode.reason ?? record.decode.status}`,
+ ],
+ ),
+ ...classOwnedMethods.flatMap((record) =>
+ record.decode.status === "decoded"
+ ? []
+ : [
+ `method ${record.class_name} ${record.method_type} ${record.selector}: ${record.decode.reason ?? record.decode.status}`,
+ ],
+ ),
+ ...result.objc_ivars.flatMap((record) =>
+ record.decode.status === "decoded"
+ ? []
+ : [
+ `ivar ${record.class_name}.${record.name}: ${record.decode.reason ?? record.decode.status}`,
+ ],
+ ),
+ ];
+ const classReasons = [
+ ...failures,
+ ...classRecords,
+ ...(truncated ? ["max_records_reached"] : []),
+ ];
+ const categoryMethods = result.objc_dispatch_implementations.filter(
+ ({ category }) => category !== undefined,
+ );
+ const categoryMethodReasons = categoryMethods.flatMap((record) =>
+ record.decode.status === "decoded"
+ ? []
+ : [
+ `category method ${record.category} ${record.class_name} ${record.method_type} ${record.selector}: ${record.decode.reason ?? record.decode.status}`,
+ ],
+ );
result.coverage.push({
facet: "objc_class_method_ivar_metadata",
- status: failures.length > 0 || truncated ? "partial" : "complete",
- reason:
- [...failures, ...(truncated ? ["max_records_reached"] : [])].join("; ") ||
- null,
+ status: classReasons.length > 0 ? "partial" : "complete",
+ reason: classReasons.join("; ") || null,
examined,
- decoded: result.objc_classes.length,
+ decoded: result.objc_classes.filter(
+ ({ decode }) => decode?.status === "decoded",
+ ).length,
});
result.coverage.push({
facet: "binary_relative_pointers",
@@ -79,13 +127,18 @@ export const pushDispatchCoverage = (input: {
status:
truncated ||
categoryFailures.length > 0 ||
- result.objc_categories.some(({ decode }) => decode.status !== "decoded")
+ result.objc_categories.some(
+ ({ decode }) => decode.status !== "decoded",
+ ) ||
+ categoryMethodReasons.length > 0
? "partial"
: "complete",
reason:
- [...categoryFailures, ...(truncated ? ["max_records_reached"] : [])].join(
- "; ",
- ) || null,
+ [
+ ...categoryFailures,
+ ...categoryMethodReasons,
+ ...(truncated ? ["max_records_reached"] : []),
+ ].join("; ") || null,
examined: categoriesExamined,
decoded: result.objc_categories.filter(
({ decode }) => decode.status === "decoded",
@@ -110,7 +163,7 @@ export const pushDispatchCoverage = (input: {
: "complete",
reason: fixupReason.length > 0 ? fixupReason : null,
examined: fixups.examined,
- decoded: fixups.issues.length > 0 ? 0 : fixups.examined,
+ decoded: fixups.decoded,
});
result.coverage.push({
facet: "swift_generic_resilient_witnesses_overrides_async_coroutines",
diff --git a/src/native/AppleDispatchMetadata.test.ts b/src/native/AppleDispatchMetadata.test.ts
index 6791ba1b0..244a35aeb 100644
--- a/src/native/AppleDispatchMetadata.test.ts
+++ b/src/native/AppleDispatchMetadata.test.ts
@@ -2,7 +2,10 @@ import { describe, expect, it } from "vitest";
import { decodeAppleDispatchMetadata } from "./AppleDispatchMetadata.js";
const base = 0x100000000n;
-const fixture = (relative = false) => {
+const fixture = (
+ relative = false,
+ category?: "partial-method" | "unmapped-pointer",
+) => {
const bytes = Buffer.alloc(4096);
const u32 = (offset: number, value: number) =>
bytes.writeUInt32LE(value, offset);
@@ -11,19 +14,26 @@ const fixture = (relative = false) => {
u32(0, 0xfeedfacf);
u32(4, 0x0100000c);
u32(16, 1);
- u32(20, 152);
+ u32(20, category === undefined ? 152 : 232);
u32(32, 0x19);
- u32(36, 152);
+ u32(36, category === undefined ? 152 : 232);
bytes.write("__DATA", 40);
ptr(56, 0);
bytes.writeBigUInt64LE(4096n, 64);
bytes.writeBigUInt64LE(4096n, 80);
u32(92, 5);
- u32(96, 1);
+ u32(96, category === undefined ? 1 : 2);
bytes.write("__objc_classlist", 104);
bytes.write("__DATA", 120);
ptr(136, 0x180);
bytes.writeBigUInt64LE(8n, 144);
+ if (category !== undefined) {
+ bytes.write("__objc_catlist", 184);
+ bytes.write("__DATA", 200);
+ ptr(216, 0xb00);
+ bytes.writeBigUInt64LE(8n, 224);
+ u32(232, 0xb00);
+ }
u32(152, 0x180);
ptr(0x180, 0x200);
ptr(0x200, 0x280);
@@ -86,10 +96,58 @@ const fixture = (relative = false) => {
bytes.write("FixtureProtocol\0", 0x900);
bytes.write("requiredAction:\0", 0x920);
bytes.write("optionalAction:\0", 0x940);
+ if (category !== undefined) {
+ if (category === "unmapped-pointer") {
+ bytes.writeBigUInt64LE(0xffffffffffffffffn, 0xb00);
+ } else {
+ ptr(0xb00, 0xb40);
+ ptr(0xb40, 0xbc0);
+ ptr(0xb48, 0x200);
+ ptr(0xb50, 0xb80);
+ u32(0xb80, 24);
+ u32(0xb84, 1);
+ ptr(0xb88, 0x460);
+ ptr(0xb90, 0x5c0);
+ bytes.writeBigUInt64LE(0xffffffffffffffffn, 0xb98);
+ bytes.write("FixtureCategory\0", 0xbc0);
+ }
+ }
return bytes;
};
const provenance = { path: "/fixture/app", sha256: "a".repeat(64) };
-describe("chained Apple dispatch binary metadata", () => {
+describe("Apple dispatch pointer fixup metadata", () => {
+ it("keeps decoded bindings and their coverage when an independent stream fails", () => {
+ const bytes = fixture();
+ bytes.writeUInt32LE(2, 16);
+ bytes.writeUInt32LE(200, 20);
+ bytes.writeUInt32LE(0x80000022, 184);
+ bytes.writeUInt32LE(48, 188);
+ const bindings = Buffer.from([
+ 0x40,
+ ...Buffer.from("_OBJC_CLASS_$_NSObject\0"),
+ 0x70,
+ 0x88,
+ 0x04,
+ 0x90,
+ 0x00,
+ ]);
+ bindings.copy(bytes, 0xc00);
+ bytes[0xc80] = 0xd0;
+ bytes.writeUInt32LE(0xc00, 200);
+ bytes.writeUInt32LE(bindings.length, 204);
+ bytes.writeUInt32LE(0xc80, 208);
+ bytes.writeUInt32LE(1, 212);
+
+ const result = decodeAppleDispatchMetadata(bytes, 100, provenance);
+ expect(result.objc_classes[0]).toMatchObject({
+ name: "Fixture",
+ super_class: "NSObject",
+ });
+ expect(
+ result.coverage.find(({ facet }) => facet === "pointer_fixups"),
+ ).toMatchObject({ status: "partial", examined: 2, decoded: 1 });
+ });
+
it("keeps absolute metadata pointers between declared chained fixups", () => {
const bytes = fixture();
bytes.writeUInt32LE(2, 16);
@@ -120,7 +178,7 @@ describe("chained Apple dispatch binary metadata", () => {
});
expect(
result.coverage.find(({ facet }) => facet === "pointer_fixups"),
- ).toMatchObject({ status: "complete" });
+ ).toMatchObject({ status: "complete", examined: 1, decoded: 1 });
});
});
describe("Apple dispatch binary metadata", () => {
@@ -221,6 +279,9 @@ describe("Apple dispatch binary metadata", () => {
});
},
);
+});
+
+describe("Apple dispatch coverage ownership", () => {
it("keeps unsupported pointers and record truncation explicit", () => {
const bytes = fixture();
bytes.writeBigUInt64LE(0xffffffffffffffffn, 0x498);
@@ -229,6 +290,14 @@ describe("Apple dispatch binary metadata", () => {
implementation_address: null,
decode: { status: "partial" },
});
+ expect(
+ result.coverage.find(
+ ({ facet }) => facet === "objc_class_method_ivar_metadata",
+ ),
+ ).toMatchObject({
+ status: "partial",
+ reason: expect.stringContaining("method Fixture instance performAction:"),
+ });
const truncated = decodeAppleDispatchMetadata(fixture(), 1, provenance);
expect(truncated.coverage[0]?.reason).toContain("max_records_reached");
expect(
@@ -237,6 +306,67 @@ describe("Apple dispatch binary metadata", () => {
),
).toMatchObject({ status: "partial", reason: "max_records_reached" });
});
+ it("keeps partial category methods in category coverage only", () => {
+ const baseline = decodeAppleDispatchMetadata(fixture(), 100, provenance);
+ const result = decodeAppleDispatchMetadata(
+ fixture(false, "partial-method"),
+ 100,
+ provenance,
+ );
+
+ expect(result.objc_dispatch_implementations).toContainEqual(
+ expect.objectContaining({
+ category: "FixtureCategory",
+ decode: {
+ status: "partial",
+ reason: "implementation_pointer_unmapped_or_encoded",
+ },
+ }),
+ );
+ const baselineClassCoverage = baseline.coverage.find(
+ ({ facet }) => facet === "objc_class_method_ivar_metadata",
+ );
+ const classCoverage = result.coverage.find(
+ ({ facet }) => facet === "objc_class_method_ivar_metadata",
+ );
+ expect(baselineClassCoverage).toBeDefined();
+ expect(classCoverage).toEqual(baselineClassCoverage);
+ expect(
+ result.coverage.find(
+ ({ facet }) => facet === "objc_properties_categories",
+ ),
+ ).toMatchObject({
+ status: "partial",
+ reason: expect.stringContaining("category method FixtureCategory"),
+ });
+ });
+ it("keeps malformed category pointers out of class failure coverage", () => {
+ const baseline = decodeAppleDispatchMetadata(fixture(), 100, provenance);
+ const result = decodeAppleDispatchMetadata(
+ fixture(false, "unmapped-pointer"),
+ 100,
+ provenance,
+ );
+ const baselineClassCoverage = baseline.coverage.find(
+ ({ facet }) => facet === "objc_class_method_ivar_metadata",
+ );
+ const classCoverage = result.coverage.find(
+ ({ facet }) => facet === "objc_class_method_ivar_metadata",
+ );
+ expect(baselineClassCoverage).toBeDefined();
+ expect(classCoverage).toEqual(baselineClassCoverage);
+ expect(
+ result.coverage.find(
+ ({ facet }) => facet === "objc_properties_categories",
+ ),
+ ).toMatchObject({
+ status: "partial",
+ reason: expect.stringContaining("category_decode_failed"),
+ });
+ });
+});
+
+describe("malformed Apple dispatch metadata", () => {
it("rejects malformed command and section boundaries", () => {
const bytes = fixture();
bytes.writeUInt32LE(7, 36);
diff --git a/src/native/AppleMachoFixups.test.ts b/src/native/AppleMachoFixups.test.ts
index 40c50c59b..bf4ae348f 100644
--- a/src/native/AppleMachoFixups.test.ts
+++ b/src/native/AppleMachoFixups.test.ts
@@ -149,6 +149,64 @@ const SEGMENTS: Segment[] = [
{ address: BASE + 0x4000n, size: 0x4000n, offset: 0x4000, executable: false },
];
+describe("independent chained segment coverage", () => {
+ it("counts successfully decoded chained segments alongside an unsupported segment", () => {
+ const starts = 28;
+ const startsSize = 4 + 2 * 4;
+ const firstInfo = starts + startsSize;
+ const secondInfo = firstInfo + 24;
+ const imports = secondInfo + 24;
+ const data = Buffer.alloc(0x3000);
+ data.writeUInt32LE(starts, 4);
+ data.writeUInt32LE(imports, 8);
+ data.writeUInt32LE(imports, 12);
+ data.writeUInt32LE(1, 20);
+ data.writeUInt32LE(2, starts);
+ data.writeUInt32LE(firstInfo - starts, starts + 4);
+ data.writeUInt32LE(secondInfo - starts, starts + 8);
+ for (const [info, format, segmentOffset] of [
+ [firstInfo, 6, 0],
+ [secondInfo, 99, 0x1000],
+ ] as const) {
+ data.writeUInt32LE(24, info);
+ data.writeUInt16LE(0x1000, info + 4);
+ data.writeUInt16LE(format, info + 6);
+ data.writeBigUInt64LE(BigInt(segmentOffset), info + 8);
+ data.writeUInt16LE(1, info + 20);
+ data.writeUInt16LE(8, info + 22);
+ }
+ const segments: Segment[] = [
+ { address: BASE, size: 0x1000n, offset: 0x1000, executable: false },
+ {
+ address: BASE + 0x1000n,
+ size: 0x1000n,
+ offset: 0x2000,
+ executable: false,
+ },
+ ];
+ const fixups = parsePointerFixups(
+ data,
+ {
+ chained: { offset: 0, size: imports },
+ binds: [],
+ rebases: [],
+ dylibs: [],
+ },
+ segments,
+ BASE,
+ );
+
+ expect(fixups).toMatchObject({ examined: 2, decoded: 1 });
+ expect(fixups.issues).toMatchObject([
+ { code: "unsupported_pointer_format" },
+ ]);
+ expect(fixups.decode(BASE + 8n, 0n)).toEqual({
+ kind: "rebase",
+ target: BASE,
+ });
+ });
+});
+
describe("pointer fixup tables", () => {
it("reports unsupported pointer formats even when no pointer is visited", () => {
const data = chainedData(1);
@@ -196,20 +254,27 @@ describe("pointer fixup tables", () => {
{
chained: { offset: 0, size: 128 },
binds: [],
- rebases: [],
+ rebases: [{ offset: 8, size: 12 }],
dylibs: [],
},
SEGMENTS,
BASE,
);
+ expect(fixups).toMatchObject({
+ examined: 1,
+ decoded: 1,
+ unreadRebaseBytes: 12,
+ });
expect(fixups.decode(BASE + 0x4008n, field(1n, 63))).toMatchObject({
kind: "bind",
symbol: "_OBJC_CLASS_$_NSObject",
});
expect(fixups.issues).toEqual([]);
+ expect(fixups.decoded).toBe(1);
expect(fixups.decode(BASE + 0x4008n, 1n | field(1n, 63))).toMatchObject({
kind: "unsupported",
});
+ expect(fixups.decoded).toBe(0);
expect(fixups.issues).toMatchObject([
{ code: "chained_pointer_decode_failed" },
]);
diff --git a/src/native/AppleMachoFixups.ts b/src/native/AppleMachoFixups.ts
index 2ec711cc8..09080ec1d 100644
--- a/src/native/AppleMachoFixups.ts
+++ b/src/native/AppleMachoFixups.ts
@@ -42,6 +42,8 @@ export interface PointerFixups {
readonly issues: readonly DecodeIssue[];
/** Fixup segments or bind streams this reader walked. */
readonly examined: number;
+ /** Fully decoded fixup segments or bind streams, in the same units as `examined`. */
+ readonly decoded: number;
/** Rebase opcode bytes present in the load command and not decoded. */
readonly unreadRebaseBytes: number;
/** Decode the pointer stored at `address` whose raw 64-bit value is `raw`. */
@@ -260,6 +262,7 @@ const readChainedPage = (
const chainedFixups = (
image: FixupImage,
range: { readonly offset: number; readonly size: number },
+ unreadRebaseBytes: number,
): PointerFixups => {
const { bytes, segments, dylibs, baseAddress } = image;
const base = range.offset;
@@ -400,19 +403,25 @@ const chainedFixups = (
]
: [],
);
- const examinedViews = new Set();
- for (const chain of ranges) {
+ const examinedViews = new Map();
+ const decodedRanges = new Set();
+ for (const [chainIndex, chain] of ranges.entries()) {
// Unknown formats retain their compact starts table; only a queried page
// needs its NONE/presence value. Do not expand unsupported declarations.
if (POINTER_FORMATS[chain.format] === undefined) continue;
- const view = `${chain.pageStarts}:${chain.segment.offset}:${chain.segment.size}:${chain.segment.address}`;
- if (examinedViews.has(view)) continue;
- examinedViews.add(view);
+ const view = `${chain.pageStarts}:${chain.segment.offset}:${chain.segment.size}:${chain.segment.address}:${chain.format}:${chain.pageSize}:${chain.pageCount}`;
+ const prior = examinedViews.get(view);
+ if (prior !== undefined) {
+ if (prior) decodedRanges.add(chainIndex);
+ continue;
+ }
+ let complete = true;
for (let page = 0; page < chain.pageCount; page++) {
const start = bytes.readUInt16LE(chain.pageStarts + page * 2);
if (start === 0xffff) continue;
const facts = pageFacts(chain, page, start);
if (facts.failure !== undefined) {
+ complete = false;
issues.push(
issue(
"pointer_fixups",
@@ -427,6 +436,8 @@ const chainedFixups = (
break;
}
}
+ examinedViews.set(view, complete);
+ if (complete) decodedRanges.add(chainIndex);
}
const failures = issues.map(({ message }) => message);
return {
@@ -435,13 +446,17 @@ const chainedFixups = (
failures,
issues,
examined: Math.max(ranges.length, 1),
- unreadRebaseBytes: 0,
+ get decoded() {
+ return ranges.length === 0 ? 1 : decodedRanges.size;
+ },
+ unreadRebaseBytes,
decode(address, raw) {
- const chain = ranges.find(
+ const chainIndex = ranges.findIndex(
({ segment }) =>
address >= segment.address &&
address < segment.address + segment.size,
);
+ const chain = ranges[chainIndex];
// Pointers outside fixup segments, such as in __TEXT, are stored plainly.
if (chain === undefined) return { kind: "rebase", target: raw };
const within = Number(address - chain.segment.address);
@@ -486,6 +501,7 @@ const chainedFixups = (
);
failures.push(reason);
}
+ decodedRanges.delete(chainIndex);
return { kind: "unsupported", reason };
}
},
@@ -684,10 +700,7 @@ export const parsePointerFixups = (
0,
);
if (commands.chained !== null) {
- const chained = chainedFixups(image, commands.chained);
- return unreadRebaseBytes === 0
- ? chained
- : { ...chained, unreadRebaseBytes };
+ return chainedFixups(image, commands.chained, unreadRebaseBytes);
}
if (commands.binds.length === 0)
return {
@@ -696,14 +709,17 @@ export const parsePointerFixups = (
failures: [],
issues: [],
examined: 0,
+ decoded: 0,
unreadRebaseBytes,
decode: (_address, raw) => ({ kind: "rebase", target: raw }),
};
const binds: BindRun[] = [];
const failures: string[] = [];
+ let decoded = 0;
for (const stream of commands.binds)
try {
readBindStream(image, stream, binds);
+ decoded++;
} catch (cause: unknown) {
failures.push(
`${stream.stream} bind opcodes: ${cause instanceof Error ? cause.message : String(cause)}`,
@@ -717,6 +733,7 @@ export const parsePointerFixups = (
issue("pointer_fixups", "bind_stream_decode_failed", message),
),
examined: commands.binds.length,
+ decoded,
unreadRebaseBytes,
decode(address, raw) {
let match: BindRun | undefined;
diff --git a/src/native/AppleObjcCategories.ts b/src/native/AppleObjcCategories.ts
index bd936e0ce..7beb7fc03 100644
--- a/src/native/AppleObjcCategories.ts
+++ b/src/native/AppleObjcCategories.ts
@@ -23,7 +23,6 @@ export const decodeObjcCategories = (input: {
readonly sections: readonly Section[];
readonly read: ObjcDispatchReaders;
readonly result: ObjcSwiftMetadata;
- readonly failures: string[];
readonly issues: DecodeIssue[];
readonly admit: () => boolean;
/** Decode a method list into implementations attributed to the category. */
@@ -37,7 +36,7 @@ export const decodeObjcCategories = (input: {
/** Name of a class defined in this image, from its class_ro_t. */
readonly localClassName: (address: bigint) => string;
}): number => {
- const { read, result, failures } = input;
+ const { read, result } = input;
let examined = 0;
for (const section of input.sections.filter(
({ name }) => name === "__objc_catlist",
@@ -93,7 +92,6 @@ export const decodeObjcCategories = (input: {
});
} catch (cause: unknown) {
const message = cause instanceof Error ? cause.message : String(cause);
- failures.push(`Category at 0x${field.toString(16)}: ${message}`);
input.issues.push(
issue(
"objc_properties_categories",
diff --git a/src/native/AppleObjcDispatchFacets.ts b/src/native/AppleObjcDispatchFacets.ts
index 14f0b42b8..b52545840 100644
--- a/src/native/AppleObjcDispatchFacets.ts
+++ b/src/native/AppleObjcDispatchFacets.ts
@@ -335,7 +335,6 @@ export const decodeObjcDispatchFacets = (input: {
sections,
read,
result,
- failures,
issues: categoryIssues,
admit: () => budget.admit(),
methods,
diff --git a/src/native/AppleSwiftVtables.test.ts b/src/native/AppleSwiftVtables.test.ts
index dbb1c12b5..fb1615820 100644
--- a/src/native/AppleSwiftVtables.test.ts
+++ b/src/native/AppleSwiftVtables.test.ts
@@ -67,6 +67,7 @@ describe("Swift vtable coverage facts: unresolved Swift dispatch slots", () => {
issues: [],
decode: (_address, raw) => ({ kind: "rebase", target: raw }),
examined: 0,
+ decoded: 0,
unreadRebaseBytes: 0,
},
swift: {
@@ -181,6 +182,7 @@ describe("Swift vtable coverage facts: unsupported pointer fixup coverage", () =
reason: "Unsupported chained pointer format 99",
}),
examined: 0,
+ decoded: 0,
unreadRebaseBytes: 0,
},
swift: {
diff --git a/src/native/NativeMachoInspection.test.ts b/src/native/NativeMachoInspection.test.ts
index 4ed533c2e..6fe24eb90 100644
--- a/src/native/NativeMachoInspection.test.ts
+++ b/src/native/NativeMachoInspection.test.ts
@@ -1,6 +1,9 @@
import { describe, expect, it } from "vitest";
-import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import {
+ AnalysisCancelledError,
+ AnalysisOutputError,
+} from "../domain/analysisErrorCore.js";
import { err, ok } from "../domain/result.js";
import type { NativeCommandCapture } from "./CommandRunner.js";
import { inspectNativeMacho } from "./NativeMachoInspection.js";
@@ -186,3 +189,64 @@ describe("Mach-O UUID reconciliation", () => {
);
});
});
+
+describe("Mach-O slice command scheduling", () => {
+ const SLICE_TOOLS = ["otool", "nm", "dyld_info", "dyld_info", "dwarfdump"];
+
+ /** Finish later-launched slice commands first and record overlap. */
+ const reorderingRunner = (failing: ReadonlySet = new Set()) => {
+ const fixtures = new NativeFixtureRunner();
+ let inFlight = 0;
+ let maxInFlight = 0;
+ let launched = 0;
+ const run = async (tool: string, args: readonly string[]) => {
+ if (tool === "file" || tool === "lipo") return fixtures.run(tool, args);
+ const order = launched++;
+ inFlight += 1;
+ maxInFlight = Math.max(maxInFlight, inFlight);
+ for (let turn = 0; turn < 12 - order * 2; turn += 1)
+ await new Promise((resolve) => setImmediate(resolve));
+ inFlight -= 1;
+ if (failing.has(tool))
+ return err(new AnalysisOutputError("inspect_macho", `${tool} failed`));
+ return fixtures.run(tool, args);
+ };
+ return { run, maxInFlight: () => maxInFlight };
+ };
+
+ const inspectWith = (run: ReturnType["run"]) =>
+ inspectNativeMacho({
+ target: nativeMachoTarget("/fixture/app"),
+ run,
+ invocation: (capture) => ({
+ tool: capture.tool,
+ command: [capture.executable, ...capture.arguments],
+ tool_version: capture.toolVersion,
+ version_reason: capture.versionReason,
+ executable_sha256: capture.executableSha256,
+ exit: { code: capture.exitCode, signal: capture.signal },
+ stdout_bytes: capture.stdoutBytes,
+ stderr_bytes: capture.stderrBytes,
+ }),
+ });
+
+ it("runs independent slice commands together and keeps provenance in declared order", async () => {
+ const runner = reorderingRunner();
+ const result = await inspectWith(runner.run);
+ if (!result.ok) throw result.error;
+ expect(runner.maxInFlight()).toBe(SLICE_TOOLS.length + 1);
+ expect(result.value.result).toMatchObject({
+ provenance: ["file", "lipo", ...SLICE_TOOLS, "vtool"].map((tool) => ({
+ tool,
+ })),
+ });
+ });
+
+ it("reports the first failing slice command in declared order", async () => {
+ const runner = reorderingRunner(new Set(["nm", "dwarfdump"]));
+ const result = await inspectWith(runner.run);
+ expect(result.ok).toBe(false);
+ if (result.ok) return;
+ expect(result.error).toMatchObject({ reason: "nm failed" });
+ });
+});
diff --git a/src/native/NativeMachoInspection.ts b/src/native/NativeMachoInspection.ts
index 2ec6cd4a9..24ccb2514 100644
--- a/src/native/NativeMachoInspection.ts
+++ b/src/native/NativeMachoInspection.ts
@@ -79,8 +79,11 @@ export const inspectNativeMacho = async (
);
const selectedArchitecture =
selection.status === "selected" ? selection.architecture : null;
- for (const [tool, prefix] of REQUIRED_SLICE_COMMANDS) {
- const captured = await context.run(
+ const runSliceCommand = ([tool, prefix]: readonly [
+ string,
+ readonly string[],
+ ]) =>
+ context.run(
tool,
[
...prefix,
@@ -89,20 +92,18 @@ export const inspectNativeMacho = async (
],
context.signal,
);
+ // Slice commands only read the selected artifact, so launch them together.
+ // Every launch settles before return; declared order fixes provenance and
+ // which failure is reported.
+ const [required, optional] = await Promise.all([
+ Promise.all(REQUIRED_SLICE_COMMANDS.map(runSliceCommand)),
+ runSliceCommand(OPTIONAL_VTOOL_COMMAND),
+ ]);
+ for (const captured of required) {
if (!captured.ok) return err(captured.error);
captures.push(captured.value);
}
const limitations: string[] = [];
- const [tool, prefix] = OPTIONAL_VTOOL_COMMAND;
- const optional = await context.run(
- tool,
- [
- ...prefix,
- ...selectedArchitectureArguments(tool, selectedArchitecture),
- context.target.path,
- ],
- context.signal,
- );
if (optional.ok) captures.push(optional.value);
else if (optional.error._tag === "AnalysisCapabilityUnavailableError")
limitations.push(VTOOL_UNAVAILABLE_LIMITATION);
diff --git a/src/native/pwntools/PwntoolsDecoder.ts b/src/native/pwntools/PwntoolsDecoder.ts
index 3a28edbfa..d8cad3d2e 100644
--- a/src/native/pwntools/PwntoolsDecoder.ts
+++ b/src/native/pwntools/PwntoolsDecoder.ts
@@ -518,6 +518,13 @@ export class PwntoolsDecoder<
[
pending.process.launch.ownership?.runId ?? "owned-decoder",
...(pending.root === undefined ? [] : [pending.root.path]),
+ // The retained group may still be live; name it as OwnedCommand does.
+ ...(pending.process.launch.ownership === undefined
+ ? []
+ : [
+ `pid:${pending.process.launch.ownership.leaderPid}`,
+ `process-group:${pending.process.launch.ownership.processGroupId}`,
+ ]),
],
{
reason: stopped.reason,
diff --git a/src/pcap/PcapCommand.ts b/src/pcap/PcapCommand.ts
new file mode 100644
index 000000000..0d28a3d75
--- /dev/null
+++ b/src/pcap/PcapCommand.ts
@@ -0,0 +1,205 @@
+import { randomUUID } from "node:crypto";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import {
+ AnalysisCancelledError,
+ AnalysisProtocolError,
+ AnalysisResourceConstraintError,
+ AnalysisTimeoutError,
+ AnalysisUnsupportedTargetError,
+} from "../domain/analysisErrorCore.js";
+import {
+ OwnedCommandFailure,
+ runOwnedCommand,
+} from "../process/OwnedCommand.js";
+import type { ProviderProcessSupervisor } from "../process/ProviderProcess.js";
+import { prepareProcessOwnershipInspection } from "../process/ProcessOwnershipObservation.js";
+import {
+ isWindowsBatchFile,
+ windowsBatchCommand,
+ WindowsBatchCommandError,
+} from "../process/WindowsBatchCommand.js";
+import { pcapToolUnavailable } from "./PcapConfiguration.js";
+
+export interface PcapCommandLimits {
+ readonly timeoutMs: number;
+ readonly maxOutputBytes: number;
+}
+
+/** Owned process execution shared by version probes and capture reads. */
+export const runPcapCommand = async (options: {
+ readonly operation: string;
+ readonly command: string;
+ readonly arguments: readonly string[];
+ readonly limits: PcapCommandLimits;
+ readonly environment: Readonly>;
+ readonly signal: AbortSignal | undefined;
+ readonly inputPath?: string;
+ readonly nativeBound?: {
+ readonly limiter?: { command: string; arguments: readonly string[] };
+ readonly memoryLimitBytes?: number;
+ };
+ readonly retain: (
+ owner: ProviderProcessSupervisor,
+ resources: readonly string[],
+ ) => void;
+}): Promise<{ stdout: string; stderr: string }> => {
+ const { operation, command, limits, signal } = options;
+ if (signal?.aborted)
+ throw new AnalysisCancelledError(operation, { cause: signal.reason });
+ const hostEnvironment = {
+ ...process.env,
+ ...options.environment,
+ LC_ALL: "C",
+ LANG: "C",
+ };
+ try {
+ const batch = process.platform === "win32" && isWindowsBatchFile(command);
+ const invocation = batch
+ ? windowsBatchCommand({
+ environment: hostEnvironment,
+ batchPath: command,
+ arguments: options.arguments,
+ })
+ : { command, arguments: options.arguments };
+ const boundedInvocation =
+ options.nativeBound?.limiter === undefined
+ ? invocation
+ : {
+ command: options.nativeBound.limiter.command,
+ arguments: [
+ ...options.nativeBound.limiter.arguments,
+ invocation.command,
+ ...invocation.arguments,
+ ],
+ };
+ // Native ownership preparation has its own bounded compiler lifecycle;
+ // do not spend the tool's execution deadline rebuilding a cold SDK cache.
+ await prepareProcessOwnershipInspection(signal);
+ const output = await runOwnedCommand(
+ {
+ ...boundedInvocation,
+ runId: randomUUID(),
+ hostEnvironment,
+ windowsVerbatimArguments: batch,
+ expectedCommand: null,
+ ...(options.nativeBound?.memoryLimitBytes === undefined
+ ? {}
+ : { memoryLimitBytes: options.nativeBound.memoryLimitBytes }),
+ },
+ { timeoutMs: limits.timeoutMs, diagnosticBytes: limits.maxOutputBytes },
+ signal === undefined ? {} : { signal },
+ );
+ return { stdout: output.stdout.text, stderr: output.stderr.text };
+ } catch (cause) {
+ if (cause instanceof AnalysisError) throw cause;
+ if (
+ cause instanceof OwnedCommandFailure &&
+ cause.cleanupOwner !== undefined
+ )
+ options.retain(cause.cleanupOwner, cause.resources);
+ const details = {
+ cause,
+ ...(cause instanceof OwnedCommandFailure && cause.snapshot !== null
+ ? {
+ capturedOutput: {
+ stdout: "",
+ stderr: cause.snapshot.stderr.text,
+ truncated:
+ cause.snapshot.stdout.observedBytes > 0 ||
+ (cause.snapshot.diagnosticTruncated ?? false),
+ exit_code: cause.snapshot.exitCode ?? null,
+ signal: cause.snapshot.signal ?? null,
+ },
+ }
+ : {}),
+ ...(cause instanceof OwnedCommandFailure && cause.cleanupFailure !== null
+ ? {
+ cleanup: {
+ reason: cause.cleanupFailure,
+ resources: cause.resources,
+ },
+ }
+ : {}),
+ };
+ if (
+ signal?.aborted ||
+ (cause instanceof OwnedCommandFailure && cause.reason === "cancelled")
+ )
+ throw new AnalysisCancelledError(operation, details);
+ if (
+ cause instanceof OwnedCommandFailure &&
+ cause.snapshot?.memoryLimitReached === true
+ )
+ throw new AnalysisResourceConstraintError(
+ operation,
+ "memory",
+ "The owned Windows tool tree reached its enforced committed-memory limit.",
+ {
+ process_memory_limit_bytes:
+ options.nativeBound?.memoryLimitBytes ?? null,
+ },
+ details,
+ );
+ if (
+ cause instanceof OwnedCommandFailure &&
+ (cause.snapshot?.signal === "SIGXCPU" ||
+ cause.snapshot?.signal === "SIGXFSZ")
+ )
+ throw new AnalysisResourceConstraintError(
+ operation,
+ cause.snapshot.signal === "SIGXCPU" ? "cpu" : "file-size",
+ `Producer terminated with ${cause.snapshot.signal}; its exact cause is not independently established.`,
+ null,
+ details,
+ );
+ if (cause instanceof OwnedCommandFailure && cause.reason === "timeout")
+ throw new AnalysisTimeoutError(operation, limits.timeoutMs, details);
+ if (cause instanceof OwnedCommandFailure && cause.reason === "output-limit")
+ throw new AnalysisResourceConstraintError(
+ operation,
+ "memory",
+ "Tool output exceeded its complete-output budget",
+ { max_output_bytes: limits.maxOutputBytes },
+ details,
+ );
+ if (
+ cause instanceof WindowsBatchCommandError ||
+ (cause instanceof Error &&
+ "code" in cause &&
+ (cause.code === "ENOENT" || cause.code === "EACCES"))
+ )
+ throw pcapToolUnavailable(
+ operation,
+ `Cannot run selected tool ${command}: ${cause.message}`,
+ details,
+ );
+ const diagnostic =
+ cause instanceof OwnedCommandFailure
+ ? cause.snapshot?.stderr.text.trim() || cause.message
+ : cause instanceof Error
+ ? cause.message
+ : String(cause);
+ if (options.inputPath === undefined)
+ throw pcapToolUnavailable(
+ operation,
+ `The selected tool ${command} cannot report its version: ${diagnostic}`,
+ details,
+ );
+ if (
+ options.inputPath !== undefined &&
+ /not a capture file|file.*isn't a capture file|file format.*not supported/iu.test(
+ diagnostic,
+ )
+ )
+ throw new AnalysisUnsupportedTargetError(
+ operation,
+ options.inputPath,
+ diagnostic,
+ details,
+ );
+ throw new AnalysisProtocolError(
+ `Packet capture tool ${command} failed: ${diagnostic}`,
+ details,
+ );
+ }
+};
diff --git a/src/pcap/PcapConfiguration.test.ts b/src/pcap/PcapConfiguration.test.ts
new file mode 100644
index 000000000..edbd223b2
--- /dev/null
+++ b/src/pcap/PcapConfiguration.test.ts
@@ -0,0 +1,170 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ CAPINFOS_COMMAND_ENV,
+ TSHARK_COMMAND_ENV,
+ resolvePcapTools,
+} from "./PcapConfiguration.js";
+import { parseCapinfosOutput, parseTsharkJsonOutput } from "./PcapOutput.js";
+
+describe("resolvePcapTools", () => {
+ it("prefers absolute environment paths for both tools", () => {
+ expect(
+ resolvePcapTools({
+ [TSHARK_COMMAND_ENV]: "/usr/bin/tshark",
+ [CAPINFOS_COMMAND_ENV]: "/usr/bin/capinfos",
+ }),
+ ).toEqual({
+ tshark: { command: "/usr/bin/tshark", source: "environment" },
+ capinfos: { command: "/usr/bin/capinfos", source: "environment" },
+ });
+ });
+
+ it("falls back to PATH resolution without the environment keys", () => {
+ expect(resolvePcapTools({})).toEqual({
+ tshark: { command: "tshark", source: "path" },
+ capinfos: { command: "capinfos", source: "path" },
+ });
+ });
+
+ it("rejects a relative tshark path explicitly", () => {
+ expect(() =>
+ resolvePcapTools({ [TSHARK_COMMAND_ENV]: "bin/tshark" }),
+ ).toThrow(/must be an absolute path/u);
+ });
+
+ it("rejects a relative capinfos path explicitly", () => {
+ expect(() =>
+ resolvePcapTools({ [CAPINFOS_COMMAND_ENV]: "capinfos" }),
+ ).toThrow(/must be an absolute path/u);
+ });
+});
+
+const REAL_CAPINFOS = [
+ "File name: /work/rich-capture.pcap",
+ "File type: Wireshark/tcpdump/... - pcap",
+ "File encapsulation: Linux cooked-mode capture v2",
+ "Packet size limit: file hdr: 262144 bytes",
+ "Number of packets: 50",
+ "File size: 23279 bytes",
+ "Capture duration: 0.373473 seconds",
+ "Earliest packet time: 2026-10-11 14:13:40.608505",
+ "Latest packet time: 2026-10-11 14:13:40.981978",
+ "SHA256: c94f94742b3288b9a979711509ed5eab3028576301f8938319de3c22a6f5c40b",
+].join("\n");
+
+describe("parseCapinfosOutput", () => {
+ it("projects metadata from real capinfos output", () => {
+ expect(parseCapinfosOutput(REAL_CAPINFOS)).toEqual({
+ fileType: "Wireshark/tcpdump/... - pcap",
+ encapsulation: "Linux cooked-mode capture v2",
+ packetCount: 50,
+ captureStart: "2026-10-11 14:13:40.608505",
+ captureEnd: "2026-10-11 14:13:40.981978",
+ captureDurationSeconds: 0.373473,
+ snapshotLength: 262144,
+ sha256:
+ "c94f94742b3288b9a979711509ed5eab3028576301f8938319de3c22a6f5c40b",
+ });
+ });
+
+ it("rejects empty metadata rather than reporting complete unknown facts", () => {
+ expect(() => parseCapinfosOutput("")).toThrow(/machine-readable/u);
+ });
+});
+
+const REAL_TSHARK_JSON = JSON.stringify([
+ {
+ _source: {
+ layers: {
+ "frame.number": ["1"],
+ "frame.protocols": ["sll:ethertype:ip:udp:dns"],
+ "ip.src": ["192.168.1.1"],
+ "ip.dst": ["8.8.8.8"],
+ "dns.qry.name": ["example.com"],
+ "dns.flags.response": ["1"],
+ "dns.a": ["93.184.216.34"],
+ },
+ },
+ },
+ {
+ _source: {
+ layers: {
+ "frame.number": ["2"],
+ "frame.protocols": ["sll:ethertype:ip:tcp:tls"],
+ "ip.src": ["192.168.1.1"],
+ "ip.dst": ["93.184.216.34"],
+ "tls.handshake.extensions_server_name": ["example.com"],
+ },
+ },
+ },
+ {
+ _source: {
+ layers: {
+ "frame.number": ["3"],
+ "frame.protocols": ["sll:ethertype:ip:tcp:http"],
+ "ip.src": ["192.168.1.1"],
+ "ip.dst": ["93.184.216.34"],
+ "http.request.full_uri": ["http://example.com/page"],
+ },
+ },
+ },
+]);
+
+describe("parseTsharkJsonOutput", () => {
+ it("projects endpoints, DNS, TLS SNI, protocols, and HTTP URIs", async () => {
+ const result = await parseTsharkJsonOutput(REAL_TSHARK_JSON);
+ expect(result.endpoints).toEqual(
+ expect.arrayContaining([
+ { address: "192.168.1.1", port: null, packet_count: 3 },
+ { address: "8.8.8.8", port: null, packet_count: 1 },
+ { address: "93.184.216.34", port: null, packet_count: 2 },
+ ]),
+ );
+ expect(result.dnsQueries).toEqual([
+ {
+ query: "example.com",
+ response_addresses: ["93.184.216.34"],
+ response_address_count: 1,
+ },
+ ]);
+ expect(result.tlsSniValues).toEqual(["example.com"]);
+ expect(result.httpRequestUris).toEqual(["http://example.com/page"]);
+ expect(result.protocolDistribution).toEqual(
+ expect.arrayContaining([
+ { protocol: "sll:ethertype:ip:udp:dns", packet_count: 1 },
+ { protocol: "sll:ethertype:ip:tcp:tls", packet_count: 1 },
+ { protocol: "sll:ethertype:ip:tcp:http", packet_count: 1 },
+ ]),
+ );
+ });
+
+ it("retains every endpoint within the aggregate resource budget", async () => {
+ const packets = Array.from({ length: 10 }, (_, index) => ({
+ _source: {
+ layers: {
+ "frame.number": [String(index + 1)],
+ "frame.protocols": ["ip:tcp"],
+ "ip.src": [`10.0.0.${index}`],
+ "ip.dst": ["10.0.1.1"],
+ },
+ },
+ }));
+ const result = await parseTsharkJsonOutput(JSON.stringify(packets));
+ expect(result.endpoints).toHaveLength(11);
+ expect(result.endpointCount).toBe(11); // 10 src + 1 dst
+ });
+
+ it.each([
+ "",
+ "not json",
+ "{}",
+ "null",
+ "[null]",
+ '[{"_source":{"layers":{"ip.src":[3]}}}]',
+ ])("rejects malformed producer output %s", async (text) => {
+ await expect(parseTsharkJsonOutput(text)).rejects.toMatchObject({
+ _tag: "AnalysisProtocolError",
+ });
+ });
+});
diff --git a/src/pcap/PcapConfiguration.ts b/src/pcap/PcapConfiguration.ts
new file mode 100644
index 000000000..b2a6212d1
--- /dev/null
+++ b/src/pcap/PcapConfiguration.ts
@@ -0,0 +1,172 @@
+import { isAbsolute } from "node:path";
+
+import type { ProviderAvailability } from "../application/AnalysisProvider.js";
+import type { ProviderRejectionCode } from "../contracts/providerSelection.js";
+import type { AnalysisErrorOptions } from "../domain/analysisErrorBase.js";
+import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
+import type { JsonValue } from "../domain/jsonValue.js";
+
+/** Environment keys selecting the caller's tshark and capinfos binaries. */
+export const TSHARK_COMMAND_ENV = "REA_TSHARK_COMMAND";
+export const CAPINFOS_COMMAND_ENV = "REA_CAPINFOS_COMMAND";
+
+const TOOL_REMEDIATION = `Supply Wireshark 4.x tshark and capinfos on PATH or through absolute ${TSHARK_COMMAND_ENV} and ${CAPINFOS_COMMAND_ENV}; REA does not install them.`;
+
+/**
+ * Host-tool refusals concern the caller's Wireshark installation, not the
+ * target, so they carry their own guidance instead of the generic advice to
+ * choose another target.
+ */
+export const pcapToolUnavailable = (
+ operation: string,
+ reason: string,
+ options?: AnalysisErrorOptions,
+): AnalysisCapabilityUnavailableError =>
+ new AnalysisCapabilityUnavailableError("pcap", operation, reason, {
+ ...options,
+ userMessage: `${/[.!?]$/u.test(reason) ? reason : `${reason}.`} ${TOOL_REMEDIATION}`,
+ });
+
+/** How each tool was selected for this provider instance. */
+export interface PcapToolSelection {
+ readonly tshark: { command: string; source: "environment" | "path" };
+ readonly capinfos: { command: string; source: "environment" | "path" };
+}
+
+/**
+ * Resolve the caller-supplied tshark and capinfos binaries. Each accepts an
+ * absolute environment path or falls back to PATH resolution, mirroring the
+ * mitmdump pattern. REA never installs the Wireshark suite.
+ */
+export const resolvePcapTools = (
+ environment: Readonly>,
+): PcapToolSelection => {
+ const tsharkEnv = environment[TSHARK_COMMAND_ENV];
+ const capinfosEnv = environment[CAPINFOS_COMMAND_ENV];
+ if (
+ tsharkEnv !== undefined &&
+ tsharkEnv.trim() !== "" &&
+ !isAbsolute(tsharkEnv)
+ )
+ throw new PcapConfigurationFailure(
+ "tshark_not_absolute",
+ `${TSHARK_COMMAND_ENV} must be an absolute path to the tshark binary`,
+ { configured: tsharkEnv },
+ );
+ if (
+ capinfosEnv !== undefined &&
+ capinfosEnv.trim() !== "" &&
+ !isAbsolute(capinfosEnv)
+ )
+ throw new PcapConfigurationFailure(
+ "capinfos_not_absolute",
+ `${CAPINFOS_COMMAND_ENV} must be an absolute path to the capinfos binary`,
+ { configured: capinfosEnv },
+ );
+ return {
+ tshark: {
+ command:
+ tsharkEnv === undefined || tsharkEnv.trim() === ""
+ ? "tshark"
+ : tsharkEnv,
+ source:
+ tsharkEnv === undefined || tsharkEnv.trim() === ""
+ ? "path"
+ : "environment",
+ },
+ capinfos: {
+ command:
+ capinfosEnv === undefined || capinfosEnv.trim() === ""
+ ? "capinfos"
+ : capinfosEnv,
+ source:
+ capinfosEnv === undefined || capinfosEnv.trim() === ""
+ ? "path"
+ : "environment",
+ },
+ };
+};
+
+export type PcapConfigurationFailureCode =
+ | "tshark_not_absolute"
+ | "capinfos_not_absolute"
+ | "tshark_missing"
+ | "capinfos_missing"
+ | "tshark_version_unresolved"
+ | "capinfos_version_unresolved"
+ | "tshark_version_unsupported"
+ | "capinfos_version_unsupported";
+
+export class PcapConfigurationFailure extends Error {
+ constructor(
+ readonly code: PcapConfigurationFailureCode,
+ message: string,
+ readonly diagnostics: Readonly> = {},
+ options?: ErrorOptions,
+ ) {
+ super(message, options);
+ }
+}
+
+/** Recognize the selected Wireshark tool's version banner. */
+const parseVersion = (
+ stdout: string,
+ tool: "tshark" | "capinfos",
+): string | null => {
+ const line = stdout
+ .split(/\r?\n/u)
+ .map((entry) => entry.trim())
+ .find((entry) => entry !== "");
+ const parsed =
+ line === undefined
+ ? null
+ : new RegExp(`^${tool} \\(Wireshark\\) (\\d+)\\.\\d+\\.\\d+`, "iu").exec(
+ line,
+ );
+ if (parsed === null || line === undefined) return null;
+ if (parsed[1] !== "4")
+ throw new PcapConfigurationFailure(
+ `${tool}_version_unsupported`,
+ "Packet summary inspection currently requires Wireshark 4.x tools; select an installation with the admitted output profile.",
+ { version: line },
+ );
+ return line;
+};
+
+export interface PcapClientIdentity {
+ readonly tsharkVersion: string | null;
+ readonly capinfosVersion: string | null;
+}
+
+/** Probe both tools without reading any capture file. */
+export const inspectPcapClient = async (
+ selection: PcapToolSelection,
+ probe: (command: string) => Promise,
+): Promise => ({
+ tsharkVersion: parseVersion(await probe(selection.tshark.command), "tshark"),
+ capinfosVersion: parseVersion(
+ await probe(selection.capinfos.command),
+ "capinfos",
+ ),
+});
+
+/** Availability in the shape shared by every provider. */
+const rejectionCodeOf = (
+ code: PcapConfigurationFailureCode,
+): ProviderRejectionCode =>
+ code.includes("missing")
+ ? "executable_missing"
+ : code.includes("unsupported")
+ ? "unsupported_version"
+ : code.includes("not_absolute")
+ ? "not_configured"
+ : "version_unresolved";
+
+export const pcapConfigurationAvailability = (
+ cause: PcapConfigurationFailure,
+): ProviderAvailability => ({
+ status: "unavailable",
+ code: rejectionCodeOf(cause.code),
+ reason: cause.message,
+ diagnostics: { ...cause.diagnostics },
+});
diff --git a/src/pcap/PcapNativeBound.ts b/src/pcap/PcapNativeBound.ts
new file mode 100644
index 000000000..dc98bfca0
--- /dev/null
+++ b/src/pcap/PcapNativeBound.ts
@@ -0,0 +1,78 @@
+import { access, realpath } from "node:fs/promises";
+import { constants } from "node:fs";
+import { isAbsolute } from "node:path";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
+import type { ArtifactAnalysisResources } from "../process/ArtifactAnalysisResources.js";
+import type { runPcapCommand } from "./PcapCommand.js";
+
+const PRLIMIT_COMMAND_ENV = "REA_TSHARK_PRLIMIT_COMMAND";
+
+/** Own native capture admission and the exact enforced resource profile. */
+export const preparePcapNativeBound = async (
+ environment: Readonly>,
+ resources: ArtifactAnalysisResources,
+): Promise<{
+ nativeBound: NonNullable[0]["nativeBound"]>;
+ limitations: readonly string[];
+}> => {
+ if (process.platform === "win32") {
+ return {
+ nativeBound: { memoryLimitBytes: 1024 ** 3 },
+ limitations: [
+ "Each owned Windows tool tree has a 1 GiB Job Object committed-memory limit; this is not a machine-wide quota.",
+ ],
+ };
+ }
+ if (process.platform !== "linux") {
+ const reason =
+ "Packet summaries require an enforceable native memory bound: Linux with util-linux prlimit, or Windows with owned Job Objects. This host's capture boundary remains unsupported.";
+ throw new AnalysisCapabilityUnavailableError(
+ "pcap",
+ "inspect_pcap_capture",
+ reason,
+ { userMessage: reason },
+ );
+ }
+ const configured = environment[PRLIMIT_COMMAND_ENV] ?? "/usr/bin/prlimit";
+ try {
+ if (!isAbsolute(configured))
+ throw new Error(`${PRLIMIT_COMMAND_ENV} must be absolute.`);
+ const limiter = await realpath(configured);
+ await access(limiter, constants.X_OK);
+ const limits = await resources.readLimits({
+ address_space_bytes: 1024 ** 3,
+ file_bytes: 64 * 1024 ** 2,
+ cpu_seconds: 300,
+ });
+ const nativeBound = {
+ limiter: {
+ command: limiter,
+ arguments: [
+ `--as=${limits.address_space_bytes}:${limits.address_space_bytes}`,
+ `--fsize=${limits.file_bytes}:${limits.file_bytes}`,
+ `--cpu=${limits.cpu_seconds}:${limits.cpu_seconds}`,
+ "--core=0:0",
+ "--",
+ ],
+ },
+ };
+ const limitations = [
+ `Linux prlimit preserves stricter inherited ceilings: ${limits.address_space_bytes} bytes of per-process address space, ${limits.file_bytes} bytes per file and ${limits.cpu_seconds} CPU seconds; core dumps are disabled. These are not aggregate machine quotas.`,
+ ];
+ return { nativeBound, limitations };
+ } catch (cause) {
+ if (cause instanceof AnalysisError) throw cause;
+ const reason =
+ "Cannot establish the selected Linux resource limiter before processing capture bytes.";
+ throw new AnalysisCapabilityUnavailableError(
+ "pcap",
+ "inspect_pcap_capture",
+ reason,
+ {
+ cause,
+ userMessage: `${reason} (${cause instanceof Error ? cause.message : String(cause)}) Check that ${PRLIMIT_COMMAND_ENV} (default /usr/bin/prlimit) names an absolute, executable util-linux prlimit.`,
+ },
+ );
+ }
+};
diff --git a/src/pcap/PcapOutput.test.ts b/src/pcap/PcapOutput.test.ts
new file mode 100644
index 000000000..6cfa6b0d3
--- /dev/null
+++ b/src/pcap/PcapOutput.test.ts
@@ -0,0 +1,149 @@
+import { expect, it } from "vitest";
+import { parseCapinfosOutput, parseTsharkJsonOutput } from "./PcapOutput.js";
+
+const capture = (layers: ReadonlyArray>) =>
+ JSON.stringify(
+ layers.map((fields, index) => ({
+ _source: {
+ layers: {
+ "frame.number": [String(index + 1)],
+ "frame.protocols": ["ip:udp:dns"],
+ ...fields,
+ },
+ },
+ })),
+ );
+
+it("binds interleaved DNS answers to the question in their response packet", async () => {
+ const result = await parseTsharkJsonOutput(
+ capture([
+ { "dns.qry.name": ["alpha.example"], "dns.flags.response": ["False"] },
+ { "dns.qry.name": ["beta.example"], "dns.flags.response": ["False"] },
+ {
+ "dns.qry.name": ["alpha.example"],
+ "dns.flags.response": ["True"],
+ "dns.a": ["192.0.2.10"],
+ },
+ {
+ "dns.qry.name": ["beta.example"],
+ "dns.flags.response": ["True"],
+ "dns.a": ["192.0.2.20"],
+ },
+ ]),
+ );
+ expect(result.dnsQueries).toEqual([
+ {
+ query: "alpha.example",
+ response_addresses: ["192.0.2.10"],
+ response_address_count: 1,
+ },
+ {
+ query: "beta.example",
+ response_addresses: ["192.0.2.20"],
+ response_address_count: 1,
+ },
+ ]);
+ expect(result.partial).toBe(false);
+});
+
+it("retains unassignable DNS addresses without inventing a query relationship", async () => {
+ const result = await parseTsharkJsonOutput(
+ capture([
+ {
+ "dns.qry.name": ["alpha.example", "beta.example"],
+ "dns.flags.response": ["True"],
+ "dns.a": ["192.0.2.9"],
+ },
+ { "dns.flags.response": ["True"], "dns.aaaa": ["2001:db8::9"] },
+ ]),
+ );
+ expect(
+ result.dnsQueries.every((query) => query.response_addresses.length === 0),
+ ).toBe(true);
+ expect(result.unattributedDnsAddresses).toEqual(["192.0.2.9", "2001:db8::9"]);
+ expect(result.unattributedDnsPackets).toBe(2);
+ expect(result.partial).toBe(true);
+});
+
+it("counts IPv6 endpoints once per packet and preserves every examined fact", async () => {
+ const packets = Array.from({ length: 51 }, (_, index) => ({
+ "ipv6.src": ["2001:db8::1"],
+ "ipv6.dst": ["2001:db8::1"],
+ "tls.handshake.extensions_server_name": [`host${String(index)}.example`],
+ "frame.protocols": [`ipv6:protocol${String(index)}`],
+ }));
+ const result = await parseTsharkJsonOutput(capture(packets));
+ expect(result.endpoints).toEqual([
+ { address: "2001:db8::1", port: null, packet_count: 51 },
+ ]);
+ expect(result.tlsSniCount).toBe(51);
+ expect(result.tlsSniValues).toHaveLength(51);
+ expect(result.protocolCount).toBe(51);
+ expect(result.protocolDistribution).toHaveLength(51);
+ expect(result.partial).toBe(false);
+});
+
+it("preserves all DNS addresses and their exact examined count", async () => {
+ const result = await parseTsharkJsonOutput(
+ capture(
+ Array.from({ length: 101 }, (_, index) => ({
+ "dns.qry.name": ["rotating.example"],
+ "dns.flags.response": ["True"],
+ "dns.a": [`192.0.2.${String(index)}`],
+ })),
+ ),
+ );
+ expect(result.dnsQueries[0]?.response_addresses).toHaveLength(101);
+ expect(result.dnsQueries[0]?.response_address_count).toBe(101);
+ expect(result.partial).toBe(false);
+});
+
+it("accepts exact machine packet counts and rejects scaled human counts", () => {
+ const prefix =
+ "File type: pcap\nFile encapsulation: Ethernet\nNumber of packets: ";
+ expect(parseCapinfosOutput(`${prefix}20010`).packetCount).toBe(20010);
+ expect(() => parseCapinfosOutput(`${prefix}20 k`)).toThrow(
+ /machine-readable/u,
+ );
+});
+
+it("excludes transport credentials without normalizing observed URL bytes", async () => {
+ const result = await parseTsharkJsonOutput(
+ capture([
+ {
+ "http.request.full_uri": [
+ "http://user:password@Example.com/a/../b?token=local-evidence#keep",
+ ],
+ },
+ {
+ "http.request.full_uri": [
+ "http://other:secret@Example.com/a/../b?token=local-evidence#keep",
+ ],
+ },
+ ]),
+ );
+ expect(result.httpRequestUris).toEqual([
+ "http://Example.com/a/../b?token=local-evidence#keep",
+ ]);
+ expect(result.httpRequestUriCount).toBe(2);
+ expect(result.httpUriRedactionCount).toBe(2);
+ expect(result.partial).toBe(true);
+});
+
+it("refuses dense JSON before its expanded graph exceeds the decoding budget", async () => {
+ await expect(
+ parseTsharkJsonOutput(`[${"{},".repeat(600_000)}{}]`),
+ ).rejects.toMatchObject({
+ _tag: "AnalysisResourceConstraintError",
+ });
+});
+
+it("permits cancellation while validating and aggregating producer output", async () => {
+ const controller = new AbortController();
+ const result = parseTsharkJsonOutput(
+ capture([{ "ip.src": ["192.0.2.1"] }]),
+ controller.signal,
+ );
+ controller.abort(new Error("stopped"));
+ await expect(result).rejects.toThrow("stopped");
+});
diff --git a/src/pcap/PcapOutput.ts b/src/pcap/PcapOutput.ts
new file mode 100644
index 000000000..95cb81926
--- /dev/null
+++ b/src/pcap/PcapOutput.ts
@@ -0,0 +1,315 @@
+import { setImmediate as yieldToEventLoop } from "node:timers/promises";
+import {
+ AnalysisProtocolError,
+ AnalysisResourceConstraintError,
+} from "../domain/analysisErrorCore.js";
+import { parseRecordedTransportUrl } from "../domain/recordedTransportUrl.js";
+
+const OPERATION = "inspect_pcap_capture";
+/** Bounds JSON decoding plus its expanded object graph before JSON.parse. */
+export const TSHARK_JSON_MAX_BYTES = 8 * 1024 * 1024;
+const MAX_RETAINED_BYTES = 16 * 1024 * 1024;
+const MAX_DECODED_BYTES = 128 * 1024 * 1024;
+
+const protocolFailure = (reason: string): never => {
+ throw new AnalysisProtocolError(`Invalid packet-capture output: ${reason}`);
+};
+
+export interface CapinfosMetadata {
+ readonly fileType: string;
+ readonly encapsulation: string;
+ readonly packetCount: number;
+ readonly captureStart: string | null;
+ readonly captureEnd: string | null;
+ readonly captureDurationSeconds: number | null;
+ readonly snapshotLength: number | null;
+ readonly sha256: string | null;
+}
+
+/** capinfos -M with a C locale provides exact numbers instead of "20 k". */
+export const parseCapinfosOutput = (stdout: string): CapinfosMetadata => {
+ const lines = new Map();
+ for (const line of stdout.split(/\r?\n/u)) {
+ const at = line.indexOf(":");
+ if (at >= 0 && !/^\s/u.test(line))
+ lines.set(line.slice(0, at), line.slice(at + 1).trim());
+ }
+ const fileType = lines.get("File type");
+ const encapsulation = lines.get("File encapsulation");
+ const countText = lines.get("Number of packets");
+ if (
+ !fileType ||
+ !encapsulation ||
+ countText === undefined ||
+ !/^\d+$/u.test(countText)
+ )
+ return protocolFailure(
+ "capinfos did not provide machine-readable type, encapsulation and packet count",
+ );
+ const packetCount = Number(countText);
+ if (!Number.isSafeInteger(packetCount))
+ return protocolFailure("packet count is not representable");
+ const durationText = lines.get("Capture duration");
+ const duration =
+ durationText === undefined
+ ? null
+ : /^(\d+(?:\.\d+)?)(?:\s+seconds?)?$/u.exec(durationText);
+ const snapshot = /^file hdr:\s*(\d+) bytes$/u.exec(
+ lines.get("Packet size limit") ?? "",
+ );
+ const snapshotLength = snapshot === null ? null : Number(snapshot[1]);
+ const sha256 = lines.get("SHA256") ?? null;
+ if (sha256 !== null && !/^[0-9a-f]{64}$/u.test(sha256))
+ return protocolFailure("capinfos SHA256 is malformed");
+ return {
+ fileType,
+ encapsulation,
+ packetCount,
+ captureStart: lines.get("Earliest packet time") ?? null,
+ captureEnd: lines.get("Latest packet time") ?? null,
+ captureDurationSeconds: duration === null ? null : Number(duration[1]),
+ snapshotLength:
+ snapshotLength !== null &&
+ Number.isSafeInteger(snapshotLength) &&
+ snapshotLength > 0
+ ? snapshotLength
+ : null,
+ sha256,
+ };
+};
+
+export interface TsharkFields {
+ readonly endpoints: { address: string; port: null; packet_count: number }[];
+ readonly endpointCount: number;
+ readonly dnsQueries: {
+ query: string;
+ response_addresses: string[];
+ response_address_count: number;
+ }[];
+ readonly dnsQueryCount: number;
+ readonly tlsSniValues: string[];
+ readonly tlsSniCount: number;
+ readonly protocolDistribution: { protocol: string; packet_count: number }[];
+ readonly protocolCount: number;
+ readonly httpRequestUris: string[];
+ readonly httpRequestUriCount: number;
+ readonly httpUriRedactionCount: number;
+ readonly unattributedDnsAddresses: string[];
+ readonly unattributedDnsAddressCount: number;
+ readonly unattributedDnsPackets: number;
+ readonly packetCount: number;
+ readonly partial: boolean;
+}
+
+const object = (value: unknown): value is Record =>
+ typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Validate the fixed JSON field representation before retaining aggregate facts. */
+export const parseTsharkJsonOutput = async (
+ stdout: string,
+ signal?: AbortSignal,
+): Promise => {
+ signal?.throwIfAborted();
+ if (Buffer.byteLength(stdout) > TSHARK_JSON_MAX_BYTES)
+ throw new AnalysisResourceConstraintError(
+ OPERATION,
+ "memory",
+ "tshark JSON exceeds the bounded decoding budget",
+ { max_json_bytes: TSHARK_JSON_MAX_BYTES },
+ );
+ // The selected-field protocol has five container levels. Reject deeper
+ // graphs before materializing them; quoted brackets are string data.
+ let depth = 0,
+ quoted = false,
+ escaped = false;
+ let decodedBytes = stdout.length * 2;
+ for (let index = 0; index < stdout.length; index += 1) {
+ if (index % 65536 === 0) {
+ await yieldToEventLoop();
+ signal?.throwIfAborted();
+ }
+ const char = stdout[index];
+ if (quoted) {
+ if (escaped) escaped = false;
+ else if (char === "\\") escaped = true;
+ else if (char === '"') quoted = false;
+ } else if (char === '"') {
+ quoted = true;
+ decodedBytes += 64;
+ } else if (char === "{" || char === "[") {
+ decodedBytes += 128;
+ if (++depth > 5) protocolFailure("unexpected JSON nesting");
+ } else if (char === "}" || char === "]") depth -= 1;
+ else if (char === ":" || char === ",") decodedBytes += 128;
+ if (decodedBytes > MAX_DECODED_BYTES)
+ throw new AnalysisResourceConstraintError(
+ OPERATION,
+ "memory",
+ "tshark JSON expansion exceeds the decoding budget",
+ { max_decoded_bytes: MAX_DECODED_BYTES },
+ );
+ }
+ let packets: unknown;
+ try {
+ packets = JSON.parse(stdout) as unknown;
+ } catch (cause) {
+ throw new AnalysisProtocolError("tshark emitted malformed JSON", { cause });
+ }
+ if (!Array.isArray(packets))
+ return protocolFailure("tshark packet root must be an array");
+ const endpoints = new Map();
+ const dns = new Map>();
+ const sni = new Set();
+ const protocols = new Map();
+ const uris = new Set();
+ const observedUris = new Set();
+ let uriRedactions = 0;
+ const unattributed = new Set();
+ let unattributedPackets = 0;
+ let retainedBytes = 0;
+ const charge = (value: string): void => {
+ retainedBytes += 192 + 2 * Buffer.byteLength(value);
+ if (retainedBytes > MAX_RETAINED_BYTES)
+ throw new AnalysisResourceConstraintError(
+ OPERATION,
+ "memory",
+ "Packet inventory exceeds the retained-fact budget",
+ { max_retained_bytes: MAX_RETAINED_BYTES },
+ );
+ };
+ const add = (set: Set, value: string): void => {
+ if (!set.has(value)) {
+ charge(value);
+ set.add(value);
+ }
+ };
+ for (let index = 0; index < packets.length; index += 1) {
+ if (index % 256 === 0) {
+ await yieldToEventLoop();
+ signal?.throwIfAborted();
+ }
+ const packet: unknown = packets[index];
+ if (
+ !object(packet) ||
+ !object(packet._source) ||
+ !object(packet._source.layers)
+ )
+ return protocolFailure(
+ `packet ${String(index + 1)} lacks _source.layers`,
+ );
+ const layers = packet._source.layers;
+ for (const [key, value] of Object.entries(layers))
+ if (
+ !Array.isArray(value) ||
+ !value.every((item) => typeof item === "string")
+ )
+ return protocolFailure(
+ `packet ${String(index + 1)} field ${key} must be an array of strings`,
+ );
+ const field = (name: string): readonly string[] =>
+ (layers[name] as string[] | undefined) ?? [];
+ const frame = field("frame.number");
+ if (
+ frame.length !== 1 ||
+ !/^\d+$/u.test(frame[0]!) ||
+ Number(frame[0]) !== index + 1
+ )
+ return protocolFailure(
+ "frame inventory is missing, duplicated or out of order",
+ );
+ if (
+ field("frame.protocols").length !== 1 ||
+ field("frame.protocols")[0] === ""
+ )
+ return protocolFailure(
+ "packet protocol inventory is missing or ambiguous",
+ );
+ // Count one occurrence per packet even for loopback or nested IP layers.
+ for (const address of new Set([
+ ...field("ip.src"),
+ ...field("ip.dst"),
+ ...field("ipv6.src"),
+ ...field("ipv6.dst"),
+ ])) {
+ if (address === "") continue;
+ if (!endpoints.has(address)) charge(address);
+ endpoints.set(address, (endpoints.get(address) ?? 0) + 1);
+ }
+ const questions = new Set(
+ field("dns.qry.name").filter((value) => value !== ""),
+ );
+ for (const question of questions)
+ if (!dns.has(question)) {
+ charge(question);
+ dns.set(question, new Set());
+ }
+ const addresses = [...field("dns.a"), ...field("dns.aaaa")].filter(
+ (value) => value !== "",
+ );
+ const response = field("dns.flags.response");
+ if (addresses.length > 0) {
+ if (
+ questions.size === 1 &&
+ response.length > 0 &&
+ response.every((value) => value === "True" || value === "1")
+ ) {
+ const values = dns.get(questions.values().next().value!)!;
+ for (const address of addresses) add(values, address);
+ } else {
+ unattributedPackets += 1;
+ for (const address of addresses) add(unattributed, address);
+ }
+ }
+ for (const value of field("tls.handshake.extensions_server_name"))
+ if (value !== "") add(sni, value);
+ for (const value of new Set(field("frame.protocols"))) {
+ if (value === "") continue;
+ if (!protocols.has(value)) charge(value);
+ protocols.set(value, (protocols.get(value) ?? 0) + 1);
+ }
+ for (const value of field("http.request.full_uri")) {
+ if (value === "" || observedUris.has(value)) continue;
+ add(observedUris, value);
+ const { credentials } = parseRecordedTransportUrl(value);
+ if (credentials !== null) uriRedactions += 1;
+ if (credentials === "ambiguous") continue;
+ add(
+ uris,
+ credentials === null
+ ? value
+ : value.slice(0, credentials.start) + value.slice(credentials.end),
+ );
+ }
+ }
+ signal?.throwIfAborted();
+ return {
+ endpoints: [...endpoints]
+ .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+ .map(([address, packet_count]) => ({
+ address,
+ port: null,
+ packet_count,
+ })),
+ endpointCount: endpoints.size,
+ dnsQueries: [...dns].map(([query, addresses]) => ({
+ query,
+ response_addresses: [...addresses],
+ response_address_count: addresses.size,
+ })),
+ dnsQueryCount: dns.size,
+ tlsSniValues: [...sni],
+ tlsSniCount: sni.size,
+ protocolDistribution: [...protocols]
+ .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+ .map(([protocol, packet_count]) => ({ protocol, packet_count })),
+ protocolCount: protocols.size,
+ httpRequestUris: [...uris],
+ httpRequestUriCount: observedUris.size,
+ httpUriRedactionCount: uriRedactions,
+ unattributedDnsAddresses: [...unattributed],
+ unattributedDnsAddressCount: unattributed.size,
+ unattributedDnsPackets: unattributedPackets,
+ packetCount: packets.length,
+ partial: observedUris.size > uris.size || unattributedPackets > 0,
+ };
+};
diff --git a/src/pcap/PcapProvider.ts b/src/pcap/PcapProvider.ts
new file mode 100644
index 000000000..be2c12ed2
--- /dev/null
+++ b/src/pcap/PcapProvider.ts
@@ -0,0 +1,491 @@
+import type {
+ ExecutionOptions,
+ ProviderAvailability,
+} from "../application/AnalysisProvider.js";
+import {
+ createAnalysisExecution,
+ type AnalysisExecution,
+} from "../application/AnalysisProvider.js";
+import {
+ pcapResultSchemas,
+ type PcapRequest,
+ type PcapOperation,
+} from "../domain/pcap/pcapAnalysis.js";
+import {
+ AnalysisCancelledError,
+ AnalysisCapabilityUnavailableError,
+ AnalysisProtocolError,
+} from "../domain/analysisErrorCore.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { err, ok, type Result } from "../domain/result.js";
+import type { ProviderProcessSupervisor } from "../process/ProviderProcess.js";
+import {
+ PcapConfigurationFailure,
+ inspectPcapClient,
+ resolvePcapTools,
+ pcapConfigurationAvailability,
+ pcapToolUnavailable,
+ type PcapToolSelection,
+} from "./PcapConfiguration.js";
+import {
+ parseCapinfosOutput,
+ parseTsharkJsonOutput,
+ TSHARK_JSON_MAX_BYTES,
+} from "./PcapOutput.js";
+import { runPcapCommand, type PcapCommandLimits } from "./PcapCommand.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { createPcapEvidence } from "../domain/pcap/pcapEvidence.js";
+import { preparePcapNativeBound } from "./PcapNativeBound.js";
+import { PcapSnapshot } from "./PcapSnapshot.js";
+import { readStableArtifact } from "../artifacts/readStableArtifact.js";
+import { ArtifactAnalysisResources } from "../process/ArtifactAnalysisResources.js";
+import { readLinuxResourceLimits } from "../process/LinuxResourceLimits.js";
+
+export const PCAP_PROVIDER_IDENTITY = {
+ id: "pcap",
+ name: "Packet capture analysis",
+ version: null,
+} as const;
+const FIELDS = [
+ "frame.number",
+ "frame.protocols",
+ "ip.src",
+ "ip.dst",
+ "ipv6.src",
+ "ipv6.dst",
+ "dns.flags.response",
+ "dns.qry.name",
+ "dns.a",
+ "dns.aaaa",
+ "tls.handshake.extensions_server_name",
+ "http.request.full_uri",
+];
+
+export interface PcapProviderOptions {
+ readonly environment?: Readonly>;
+}
+
+/** Inspect saved captures through bounded, owned tool processes and one stable input copy. */
+export class PcapProvider {
+ readonly #resources = new ArtifactAnalysisResources(
+ "pcap",
+ "inspect_pcap_capture",
+ readStableArtifact,
+ readLinuxResourceLimits,
+ {
+ message: "A packet summary is already active; retry after it completes.",
+ details: { max_concurrent_inspections: 1 },
+ },
+ );
+ private readonly environment: Readonly>;
+ private readonly snapshots = new Set();
+ private readonly commands = new Map<
+ ProviderProcessSupervisor,
+ { snapshot: PcapSnapshot | undefined; resources: readonly string[] }
+ >();
+
+ constructor(options: PcapProviderOptions = {}) {
+ this.environment = options.environment ?? process.env;
+ }
+
+ private run(
+ operation: PcapOperation,
+ command: string,
+ args: readonly string[],
+ limits: PcapCommandLimits,
+ signal: AbortSignal | undefined,
+ snapshot?: PcapSnapshot,
+ inputPath?: string,
+ ) {
+ return runPcapCommand({
+ operation,
+ command,
+ arguments: args,
+ limits,
+ signal,
+ environment:
+ snapshot === undefined
+ ? this.environment
+ : {
+ ...this.environment,
+ WIRESHARK_CONFIG_DIR: snapshot.configurationPath,
+ },
+ ...(inputPath === undefined ? {} : { inputPath }),
+ ...(inputPath === undefined || this.nativeBound === undefined
+ ? {}
+ : { nativeBound: this.nativeBound }),
+ retain: (owner, resources) => {
+ this.commands.set(owner, { snapshot, resources });
+ },
+ });
+ }
+
+ private nativeBound: Parameters[0]["nativeBound"];
+ private nativeLimitations: readonly string[] = [];
+
+ private async prepareCaptureBound(): Promise {
+ const prepared = await preparePcapNativeBound(
+ this.environment,
+ this.#resources,
+ );
+ this.nativeBound = prepared.nativeBound;
+ this.nativeLimitations = prepared.limitations;
+ }
+
+ private async client(operation: PcapOperation, signal?: AbortSignal) {
+ const selection = resolvePcapTools(this.environment);
+ const identity = await inspectPcapClient(
+ selection,
+ async (command) =>
+ (
+ await this.run(
+ operation,
+ command,
+ ["--version"],
+ { timeoutMs: 20_000, maxOutputBytes: 64 * 1024 },
+ signal,
+ )
+ ).stdout,
+ );
+ for (const [name, version] of [
+ ["tshark", identity.tsharkVersion],
+ ["capinfos", identity.capinfosVersion],
+ ] as const) {
+ if (version === null)
+ throw new PcapConfigurationFailure(
+ `${name}_version_unresolved`,
+ `The selected ${name} command did not report a version. Set REA_${name.toUpperCase()}_COMMAND to its absolute executable path.`,
+ );
+ }
+ return {
+ selection,
+ client: {
+ tshark_command: selection.tshark.command,
+ tshark_source: selection.tshark.source,
+ tshark_version: identity.tsharkVersion,
+ capinfos_command: selection.capinfos.command,
+ capinfos_source: selection.capinfos.source,
+ capinfos_version: identity.capinfosVersion,
+ },
+ };
+ }
+
+ async inspectAvailability(
+ signal?: AbortSignal,
+ ): Promise {
+ const result = await this.#resources.run(
+ async () => ok(await this.inspectAvailabilityAdmitted(signal)),
+ signal,
+ );
+ if (!result.ok) throw result.error;
+ return result.value;
+ }
+
+ private async inspectAvailabilityAdmitted(
+ signal?: AbortSignal,
+ ): Promise {
+ try {
+ const { client } = await this.client("inspect_pcap_client", signal);
+ if (process.platform !== "linux" && process.platform !== "win32")
+ return {
+ status: "unavailable",
+ code: "unsupported_host",
+ reason:
+ "No enforceable native memory boundary is available for capture summaries on this host.",
+ diagnostics: client,
+ };
+ await this.prepareCaptureBound();
+ return {
+ status: "available",
+ code: null,
+ reason: null,
+ diagnostics: client,
+ };
+ } catch (cause) {
+ if (signal?.aborted || cause instanceof AnalysisCancelledError)
+ throw new AnalysisCancelledError("inspect_pcap_client", { cause });
+ if (cause instanceof PcapConfigurationFailure)
+ return pcapConfigurationAvailability(cause);
+ return {
+ status: "unavailable",
+ code:
+ cause instanceof AnalysisCapabilityUnavailableError
+ ? "executable_missing"
+ : "version_unresolved",
+ reason: cause instanceof Error ? cause.message : String(cause),
+ diagnostics: {},
+ };
+ }
+ }
+
+ private async discard(
+ snapshot: PcapSnapshot,
+ ): Promise {
+ try {
+ if (
+ [...this.commands.values()].some(
+ (command) => command.snapshot === snapshot,
+ )
+ )
+ throw new Error(
+ "An unreleased command still owns the capture snapshot",
+ );
+ await snapshot.close();
+ this.snapshots.delete(snapshot);
+ return undefined;
+ } catch (cause) {
+ return new ProviderCleanupError(
+ "pcap",
+ [snapshot.path],
+ { reason: String(cause) },
+ { operation: "inspect_pcap_capture", cause },
+ );
+ }
+ }
+
+ async close(): Promise {
+ const failures: unknown[] = [];
+ try {
+ await this.#resources.close();
+ } catch (cause) {
+ failures.push(cause);
+ }
+ for (const owner of this.commands.keys()) {
+ try {
+ const result = await owner.stop();
+ if (result.status === "incomplete") failures.push(result.reason);
+ else if (result.status === "not-owned")
+ failures.push("Command ownership remains unresolved");
+ else this.commands.delete(owner);
+ } catch (cause) {
+ failures.push(cause);
+ }
+ }
+ for (const snapshot of this.snapshots) {
+ const failure = await this.discard(snapshot);
+ if (failure !== undefined) failures.push(failure);
+ }
+ if (failures.length > 0)
+ throw new ProviderCleanupError(
+ "pcap",
+ [...this.snapshots]
+ .map((snapshot) => snapshot.path)
+ .concat(
+ [...this.commands.values()].flatMap((command) => command.resources),
+ ),
+ { reason: "Owned process or snapshot cleanup failed" },
+ { operation: "pcap.close", cause: new AggregateError(failures) },
+ );
+ }
+
+ async execute(
+ request: PcapRequest,
+ options?: ExecutionOptions,
+ ): Promise> {
+ return this.#resources.run(
+ () => this.executeAdmitted(request, options),
+ options?.signal,
+ );
+ }
+
+ private async executeAdmitted(
+ request: PcapRequest,
+ options?: ExecutionOptions,
+ ): Promise> {
+ const signal = options?.signal;
+ let snapshot: PcapSnapshot | undefined;
+ let result: Result;
+ try {
+ signal?.throwIfAborted();
+ const { selection, client } = await this.client(
+ request.operation,
+ signal,
+ );
+ const provider = {
+ ...PCAP_PROVIDER_IDENTITY,
+ version: client.tshark_version,
+ };
+ if (request.operation === "inspect_pcap_client")
+ result = ok(
+ createAnalysisExecution(
+ pcapResultSchemas.inspect_pcap_client.parse({ client }),
+ provider,
+ ),
+ );
+ else {
+ await this.prepareCaptureBound();
+ snapshot = await PcapSnapshot.create();
+ this.snapshots.add(snapshot);
+ const identity = await snapshot.capture(request.input.path, signal);
+ const captured = await this.inspectCapture(
+ selection,
+ snapshot,
+ request.input.path,
+ identity,
+ signal,
+ );
+ const data = pcapResultSchemas.inspect_pcap_capture.parse({
+ client,
+ ...captured.result,
+ });
+ result = ok(
+ createAnalysisExecution(data, provider, {
+ subject: {
+ path: request.input.path,
+ format: "file",
+ sha256: identity.sha256,
+ },
+ limitations: captured.limitations,
+ }),
+ );
+ }
+ } catch (cause) {
+ result = err(
+ cause instanceof AnalysisError
+ ? cause
+ : signal?.aborted
+ ? new AnalysisCancelledError(request.operation, { cause })
+ : cause instanceof PcapConfigurationFailure
+ ? pcapToolUnavailable(request.operation, cause.message, {
+ cause,
+ })
+ : new AnalysisProtocolError(
+ `Packet-capture analysis failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+ { cause },
+ ),
+ );
+ }
+ if (signal?.aborted && result.ok)
+ result = err(
+ new AnalysisCancelledError(request.operation, {
+ cause: signal.reason,
+ partialObservation: createPcapEvidence(request, result.value),
+ }),
+ );
+ if (snapshot !== undefined) {
+ const cleanup = await this.discard(snapshot);
+ if (signal?.aborted && result.ok)
+ result = err(
+ new AnalysisCancelledError(request.operation, {
+ cause: signal.reason,
+ partialObservation: createPcapEvidence(request, result.value),
+ }),
+ );
+ if (cleanup !== undefined)
+ result = result.ok
+ ? err(
+ cleanup.retainPartialObservation(
+ createPcapEvidence(request, result.value),
+ ),
+ )
+ : err(
+ analysisErrorWithCleanupFailure(
+ result.error,
+ cleanup,
+ request.operation,
+ ),
+ );
+ }
+ return result;
+ }
+
+ private async inspectCapture(
+ selection: PcapToolSelection,
+ snapshot: PcapSnapshot,
+ path: string,
+ identity: { bytes: number; sha256: string },
+ signal: AbortSignal | undefined,
+ ) {
+ const info = await this.run(
+ "inspect_pcap_capture",
+ selection.capinfos.command,
+ ["-M", "--", snapshot.path],
+ { timeoutMs: 60_000, maxOutputBytes: 64 * 1024 },
+ signal,
+ snapshot,
+ path,
+ );
+ const metadata = parseCapinfosOutput(info.stdout);
+ if (metadata.sha256 !== null && metadata.sha256 !== identity.sha256)
+ throw new AnalysisProtocolError(
+ "capinfos SHA256 disagrees with the owned capture snapshot",
+ );
+ const dissected = await this.run(
+ "inspect_pcap_capture",
+ selection.tshark.command,
+ [
+ "-n",
+ "-r",
+ snapshot.path,
+ "-T",
+ "json",
+ "--no-duplicate-keys",
+ `--temp-dir=${snapshot.configurationPath}`,
+ ...FIELDS.flatMap((field) => ["-e", field]),
+ ],
+ { timeoutMs: 300_000, maxOutputBytes: TSHARK_JSON_MAX_BYTES },
+ signal,
+ snapshot,
+ path,
+ );
+ const fields = await parseTsharkJsonOutput(dissected.stdout, signal);
+ await snapshot.verify(identity, path, signal);
+ if (fields.packetCount !== metadata.packetCount)
+ throw new AnalysisProtocolError(
+ `capinfos counted ${String(metadata.packetCount)} packets but tshark returned ${String(fields.packetCount)}`,
+ );
+ return {
+ result: {
+ target: { path, ...identity },
+ file_type: metadata.fileType,
+ encapsulation: metadata.encapsulation,
+ packet_count: metadata.packetCount,
+ capture_start: metadata.captureStart,
+ capture_end: metadata.captureEnd,
+ capture_duration_seconds: metadata.captureDurationSeconds,
+ diagnostics: {
+ capinfos_stderr: info.stderr,
+ tshark_stderr: dissected.stderr,
+ },
+ snapshot_length: metadata.snapshotLength,
+ endpoints: fields.endpoints,
+ endpoint_count: fields.endpointCount,
+ dns_queries: fields.dnsQueries,
+ dns_query_count: fields.dnsQueryCount,
+ tls_sni_values: fields.tlsSniValues,
+ tls_sni_count: fields.tlsSniCount,
+ protocol_distribution: fields.protocolDistribution,
+ protocol_count: fields.protocolCount,
+ http_request_uris: fields.httpRequestUris,
+ http_request_uri_count: fields.httpRequestUriCount,
+ http_uri_redaction_count: fields.httpUriRedactionCount,
+ unattributed_dns_addresses: fields.unattributedDnsAddresses,
+ unattributed_dns_address_count: fields.unattributedDnsAddressCount,
+ unattributed_dns_packet_count: fields.unattributedDnsPackets,
+ coverage: fields.partial ? "partial" : "complete",
+ },
+ limitations: [
+ ...this.nativeLimitations,
+ "Both tools read one owned snapshot; target identity comes from its admitted source descriptor",
+ "DNS address values are associated only with a single question in the same response packet; values may include additional DNS records, not only final resolution answers",
+ "Only bytes present in the saved capture are examined; encryption and capture truncation can hide higher-level fields",
+ ...(fields.partial
+ ? [
+ "One or more projected categories were capped, credential-bearing URIs were omitted or coalesced, or DNS address attribution remains unresolved; counts retain the examined totals",
+ ]
+ : []),
+ ...(fields.httpUriRedactionCount > 0
+ ? [
+ "HTTP transport credentials were excluded; ambiguous credential spans cause the URI to be omitted",
+ ]
+ : []),
+ ...(fields.unattributedDnsPackets > 0
+ ? [
+ `DNS address attribution was unresolved in ${String(fields.unattributedDnsPackets)} packet(s); unattributed addresses are retained separately`,
+ ]
+ : []),
+ ],
+ };
+ }
+}
diff --git a/src/pcap/PcapSnapshot.ts b/src/pcap/PcapSnapshot.ts
new file mode 100644
index 000000000..2e9082ccd
--- /dev/null
+++ b/src/pcap/PcapSnapshot.ts
@@ -0,0 +1,269 @@
+import { createHash } from "node:crypto";
+import { chmod, open, stat, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import {
+ AnalysisAccessDeniedError,
+ AnalysisArtifactChangedError,
+ AnalysisCancelledError,
+ AnalysisCapabilityUnavailableError,
+ AnalysisInputError,
+ AnalysisResourceConstraintError,
+} from "../domain/analysisErrorCore.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import {
+ openRegularFile,
+ RegularFileAdmissionFailure,
+ sameRegularFileState,
+} from "../filesystem/RegularFile.js";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+import { PrivateRuntimeRootUnavailableError } from "../process/PrivateRuntimeRootUnavailableError.js";
+
+const OPERATION = "inspect_pcap_capture";
+const MAX_CAPTURE_BYTES = 2 * 1024 ** 3;
+
+/** An owned capture copy and every descriptor needed to release it safely. */
+export class PcapSnapshot {
+ private readonly handles = new Set();
+ readonly path: string;
+ readonly configurationPath: string;
+ private constructor(private readonly root: PrivateRuntimeRoot) {
+ this.path = join(root.path, "capture.pcap");
+ this.configurationPath = join(root.path, "configuration");
+ }
+
+ static async create(): Promise {
+ try {
+ return new PcapSnapshot(
+ await PrivateRuntimeRoot.create({ prefix: "rea-pcap-" }),
+ );
+ } catch (cause) {
+ if (cause instanceof PrivateRuntimeRootUnavailableError)
+ throw new AnalysisCapabilityUnavailableError(
+ "pcap",
+ OPERATION,
+ cause.message,
+ { cause, retryable: cause.retryable },
+ );
+ throw new AnalysisResourceConstraintError(
+ OPERATION,
+ "file-size",
+ "Cannot allocate the owned capture workspace",
+ null,
+ { cause },
+ );
+ }
+ }
+
+ private own(handle: OwnedFileHandle): OwnedFileHandle {
+ this.handles.add(handle);
+ return handle;
+ }
+ private async release(handle: OwnedFileHandle): Promise {
+ await handle.close();
+ this.handles.delete(handle);
+ }
+
+ async capture(
+ path: string,
+ signal?: AbortSignal,
+ ): Promise<{ bytes: number; sha256: string }> {
+ const sourceRead = async (read: () => Promise): Promise => {
+ try {
+ return await read();
+ } catch (cause) {
+ if (signal?.aborted)
+ throw new AnalysisCancelledError(OPERATION, { cause });
+ if (cause instanceof AnalysisError) throw cause;
+ if (
+ cause instanceof Error &&
+ "code" in cause &&
+ (cause.code === "EACCES" || cause.code === "EPERM")
+ )
+ throw new AnalysisAccessDeniedError(OPERATION, path, cause.code, {
+ cause,
+ });
+ throw new AnalysisInputError(OPERATION, { cause }, [
+ {
+ path: ["path"],
+ reason: "invalid_value",
+ message: `Cannot read selected capture ${path}: ${cause instanceof Error ? cause.message : String(cause)}`,
+ },
+ ]);
+ }
+ };
+ try {
+ signal?.throwIfAborted();
+ await mkdir(this.configurationPath, { mode: 0o700 });
+ const source = await sourceRead(async () => {
+ try {
+ return this.own(
+ new OwnedFileHandle(
+ await openRegularFile(path, { symlinks: "follow", signal }),
+ ),
+ );
+ } catch (cause) {
+ if (cause instanceof RegularFileAdmissionFailure) {
+ this.own(cause.owner);
+ throw cause.cause;
+ }
+ throw cause;
+ }
+ });
+ const before = await sourceRead(() =>
+ source.handle.stat({ bigint: true }),
+ );
+ if (before.size > BigInt(MAX_CAPTURE_BYTES))
+ throw new AnalysisResourceConstraintError(
+ OPERATION,
+ "file-size",
+ "Capture exceeds the owned-snapshot disk budget",
+ { max_capture_bytes: MAX_CAPTURE_BYTES },
+ );
+ const destination = this.own(
+ new OwnedFileHandle(await open(this.path, "wx", 0o600)),
+ );
+ const buffer = Buffer.alloc(64 * 1024);
+ const hash = createHash("sha256");
+ let copied = 0;
+ while (copied <= Number(before.size)) {
+ signal?.throwIfAborted();
+ const { bytesRead } = await sourceRead(() =>
+ source.handle.read(
+ buffer,
+ 0,
+ Math.min(buffer.length, Number(before.size) - copied + 1),
+ copied,
+ ),
+ );
+ signal?.throwIfAborted();
+ if (bytesRead === 0) break;
+ copied += bytesRead;
+ if (BigInt(copied) > before.size)
+ throw new AnalysisArtifactChangedError(
+ OPERATION,
+ path,
+ "Capture grew during acquisition",
+ );
+ const chunk = buffer.subarray(0, bytesRead);
+ await destination.handle.writeFile(chunk);
+ hash.update(chunk);
+ }
+ const after = await sourceRead(() =>
+ source.handle.stat({ bigint: true }),
+ );
+ const selected = await stat(path, { bigint: true }).catch(
+ (cause: unknown) => {
+ if (
+ cause instanceof Error &&
+ "code" in cause &&
+ (cause.code === "EACCES" || cause.code === "EPERM")
+ )
+ throw new AnalysisAccessDeniedError(OPERATION, path, cause.code, {
+ cause,
+ });
+ throw new AnalysisArtifactChangedError(
+ OPERATION,
+ path,
+ "Selected path became unavailable during acquisition",
+ { cause },
+ );
+ },
+ );
+ if (
+ BigInt(copied) !== before.size ||
+ !sameRegularFileState(before, after) ||
+ !sameRegularFileState(before, selected)
+ )
+ throw new AnalysisArtifactChangedError(
+ OPERATION,
+ path,
+ "Capture identity or contents changed during acquisition",
+ );
+ await this.release(source);
+ await this.release(destination);
+ await chmod(this.path, 0o400);
+ signal?.throwIfAborted();
+ return { bytes: copied, sha256: hash.digest("hex") };
+ } catch (cause) {
+ if (signal?.aborted)
+ throw new AnalysisCancelledError(OPERATION, { cause });
+ if (cause instanceof AnalysisError) throw cause;
+ throw new AnalysisResourceConstraintError(
+ OPERATION,
+ "file-size",
+ "Owned capture snapshot I/O failed",
+ null,
+ { cause },
+ );
+ }
+ }
+
+ /** Recheck byte identity after both tools; a read-only mode alone is not proof. */
+ async verify(
+ expected: { bytes: number; sha256: string },
+ selectedPath: string,
+ signal?: AbortSignal,
+ ): Promise {
+ try {
+ const file = this.own(
+ new OwnedFileHandle(
+ await openRegularFile(this.path, { symlinks: "reject", signal }),
+ ),
+ );
+ const before = await file.handle.stat({ bigint: true });
+ const buffer = Buffer.alloc(64 * 1024);
+ const hash = createHash("sha256");
+ let bytes = 0;
+ while (bytes <= expected.bytes) {
+ signal?.throwIfAborted();
+ const read = await file.handle.read(
+ buffer,
+ 0,
+ Math.min(buffer.length, expected.bytes - bytes + 1),
+ bytes,
+ );
+ if (read.bytesRead === 0) break;
+ bytes += read.bytesRead;
+ hash.update(buffer.subarray(0, read.bytesRead));
+ }
+ const after = await file.handle.stat({ bigint: true });
+ const selected = await stat(this.path, { bigint: true });
+ if (
+ bytes !== expected.bytes ||
+ hash.digest("hex") !== expected.sha256 ||
+ !sameRegularFileState(before, after) ||
+ !sameRegularFileState(before, selected)
+ )
+ throw new AnalysisArtifactChangedError(
+ OPERATION,
+ selectedPath,
+ "Owned packet snapshot changed during tool analysis.",
+ );
+ await this.release(file);
+ } catch (cause) {
+ if (signal?.aborted)
+ throw new AnalysisCancelledError(OPERATION, { cause });
+ if (cause instanceof RegularFileAdmissionFailure) this.own(cause.owner);
+ if (cause instanceof AnalysisError) throw cause;
+ throw new AnalysisArtifactChangedError(
+ OPERATION,
+ selectedPath,
+ "Cannot establish the owned packet snapshot's post-analysis identity.",
+ { cause },
+ );
+ }
+ }
+
+ async close(): Promise {
+ const results = await Promise.allSettled(
+ [...this.handles].map((handle) => this.release(handle)),
+ );
+ const failures = results.flatMap((result) =>
+ result.status === "rejected" ? [result.reason as unknown] : [],
+ );
+ if (failures.length > 0)
+ throw new AggregateError(failures, "Capture descriptor cleanup failed");
+ await this.root.close();
+ }
+}
diff --git a/src/process/DarwinProcessRunTokenReader.ts b/src/process/DarwinProcessRunTokenReader.ts
index 5aafcd787..335e72fbe 100644
--- a/src/process/DarwinProcessRunTokenReader.ts
+++ b/src/process/DarwinProcessRunTokenReader.ts
@@ -74,7 +74,9 @@ const sourceFiles = [
export const SWIFTC_INTERRUPT = "SIGINT";
/** Deadline for the one-shot helper compilation. */
-const COMPILER_TIMEOUT_MS = 60_000;
+// A fresh Swift SDK cache took 88 seconds on the supported Intel macOS VM.
+// Keep compilation bounded independently of short provider version probes.
+const COMPILER_TIMEOUT_MS = 120_000;
/** Bound on compiler diagnostics embedded in the inspection failure text. */
const STDERR_EXCERPT_LIMIT = 512;
@@ -253,7 +255,7 @@ export type DarwinProcessReaderCompiler =
export const createDarwinProcessRunTokenReader = (
options: {
readonly compiler?: DarwinProcessReaderCompiler;
- /** Deadline for the helper compilation; the default keeps verification fast. */
+ /** Deadline for helper compilation, independent of provider execution. */
readonly compileTimeoutMs?: number;
/**
* Caller-owned directory holding the compiler's module cache. Unset keeps
diff --git a/src/server/createServer.ts b/src/server/createServer.ts
index 4929142c4..294984339 100644
--- a/src/server/createServer.ts
+++ b/src/server/createServer.ts
@@ -84,6 +84,7 @@ import type { FirmwareAnalysisPort } from "../application/firmware/FirmwareAnaly
import { createFirmwareAnalysisProvider } from "../composition/firmware.js";
import { registerAndroidTools } from "./registerAndroidTools.js";
import { registerApktoolTools } from "./registerApktoolTools.js";
+import { registerPcapTools } from "./registerPcapTools.js";
import { registerFlutterTools } from "./registerFlutterTools.js";
import { registerJebTools } from "./registerJebTools.js";
import { registerAdbTools } from "./registerAdbTools.js";
@@ -91,11 +92,14 @@ import { AndroidAnalysisService } from "../application/android/AndroidAnalysisSe
import { JebAnalysisService } from "../application/jeb/JebAnalysisService.js";
import type { AndroidAnalysisPort } from "../application/android/AndroidAnalysisPort.js";
import type { ApktoolResourceAnalysisPort } from "../application/apktool/ApktoolResourceAnalysisPort.js";
+import type { PcapAnalysisPort } from "../application/pcap/PcapAnalysisPort.js";
+import { PcapAnalysisService } from "../application/pcap/PcapAnalysisService.js";
import { ApktoolResourceAnalysisService } from "../application/apktool/ApktoolResourceAnalysisService.js";
import type { FlutterBuildAnalysisPort } from "../application/flutter/FlutterBuildAnalysisPort.js";
import { FlutterBuildAnalysisService } from "../application/flutter/FlutterBuildAnalysisService.js";
import { createAndroidAnalysisProvider } from "../composition/android.js";
import { createApktoolResourceAnalysisProvider } from "../composition/apktool.js";
+import { createPcapAnalysisProvider } from "../composition/pcap.js";
import { createFlutterBuildAnalysisProvider } from "../composition/flutter.js";
import type { JebAnalysisPort } from "../application/jeb/JebAnalysisPort.js";
import { createJebAnalysisProvider } from "../composition/jeb.js";
@@ -146,6 +150,7 @@ export interface CreateServerOptions {
readonly webNetworkCapture?: WebNetworkCaptureService;
readonly androidAnalysis?: AndroidAnalysisPort;
readonly apktoolAnalysis?: ApktoolResourceAnalysisPort;
+ readonly pcapAnalysis?: PcapAnalysisPort;
readonly flutterAnalysis?: FlutterBuildAnalysisPort;
readonly jebAnalysis?: JebAnalysisPort;
readonly adbDeviceAnalysis?: AdbDeviceAnalysisPort;
@@ -303,6 +308,7 @@ export const createServer = (
);
const android =
options.androidAnalysis ?? createAndroidAnalysisProvider(environment);
+ const pcap = options.pcapAnalysis ?? createPcapAnalysisProvider(environment);
const flutter =
options.flutterAnalysis ?? createFlutterBuildAnalysisProvider();
const fridaInstrumentation =
@@ -333,6 +339,7 @@ export const createServer = (
jeb.close(),
adbDevice.close(),
flutter.close(),
+ pcap.close(),
evmInterface.close(),
sqliteDatabase.close(),
binaryLayout.close(),
@@ -438,6 +445,14 @@ export const createServer = (
recordEvidence,
analysisAdmission,
);
+ registerPcapTools(
+ server,
+ new PcapAnalysisService(pcap),
+ toolLogger,
+ recordEvidence,
+ analysisAdmission,
+ evidenceById,
+ );
registerFlutterTools(
server,
new FlutterBuildAnalysisService(flutter),
diff --git a/src/server/registerPcapTools.ts b/src/server/registerPcapTools.ts
new file mode 100644
index 000000000..b2ebd239a
--- /dev/null
+++ b/src/server/registerPcapTools.ts
@@ -0,0 +1,83 @@
+import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";
+import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
+import { PcapAnalysisService } from "../application/pcap/PcapAnalysisService.js";
+import { toolContract } from "../contracts/toolContracts.js";
+import type { WithAdmittedAnalysis } from "./analysisAdmission.js";
+import type { Logger } from "pino";
+import {
+ createContractToolHandler,
+ createEvidenceToolHandler,
+} from "./contractToolHandler.js";
+import {
+ toolRegistrationOptions,
+ applicationValidatedInputSchema,
+} from "./toolRegistrationOptions.js";
+import type { EvidenceLookup } from "../application/EvidenceInputResolver.js";
+import {
+ requireAnalysisViewRetention,
+ summarizeRetainedAnalysis,
+} from "../application/analysisView/AnalysisViewService.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
+import { err } from "../domain/result.js";
+
+/** Bind pcap handlers to their exact named contracts through admission. */
+export const registerPcapTools = (
+ server: EvidenceMcpServer,
+ service: PcapAnalysisService,
+ logger: Logger,
+ recordEvidence?: EvidenceWriter["recordEvidence"],
+ withAdmittedAnalysis?: WithAdmittedAnalysis,
+ evidenceById?: EvidenceLookup,
+): void => {
+ const handler = createContractToolHandler(
+ server,
+ service,
+ logger,
+ recordEvidence,
+ withAdmittedAnalysis,
+ );
+ const clientContract = toolContract("inspect_pcap_client");
+ server.registerTool(
+ clientContract.name,
+ toolRegistrationOptions(clientContract),
+ handler(clientContract),
+ );
+ const contract = toolContract("inspect_pcap_capture");
+ const registration = toolRegistrationOptions(contract);
+ const capture = createEvidenceToolHandler(
+ server,
+ async (rawInput, options) => {
+ const parsed = contract.inputSchema.safeParse(rawInput);
+ if (!parsed.success)
+ return err(
+ analysisInputErrorFromIssues(
+ contract.name,
+ parsed.error.issues,
+ rawInput,
+ { cause: parsed.error },
+ ),
+ );
+ const { detail, ...input } = parsed.data;
+ const retention = { recordEvidence, evidenceById };
+ if (detail === "summary") {
+ const ready = requireAnalysisViewRetention(contract.name, retention);
+ if (!ready.ok) return ready;
+ }
+ const result = await service.execute(contract.name, input, options);
+ return detail === "summary" && result.ok
+ ? summarizeRetainedAnalysis(result.value, retention)
+ : result;
+ },
+ logger,
+ recordEvidence,
+ withAdmittedAnalysis,
+ );
+ server.registerTool(
+ contract.name,
+ {
+ ...registration,
+ inputSchema: applicationValidatedInputSchema(registration.inputSchema),
+ },
+ capture(contract),
+ );
+};
diff --git a/src/wasm/WabtArtifactProvider.ts b/src/wasm/WabtArtifactProvider.ts
index ffed3871b..fe79914ca 100644
--- a/src/wasm/WabtArtifactProvider.ts
+++ b/src/wasm/WabtArtifactProvider.ts
@@ -2,12 +2,12 @@ import { randomUUID, createHash } from "node:crypto";
import { access, realpath, writeFile } from "node:fs/promises";
import { constants } from "node:fs";
import { isAbsolute, join } from "node:path";
-import type {
- AnalysisExecution,
- ExecutionOptions,
-} from "../application/AnalysisProvider.js";
+import type { ExecutionOptions } from "../application/AnalysisProvider.js";
import { createAnalysisExecution } from "../application/AnalysisProvider.js";
-import type { WasmArtifactPort } from "../application/wasm/WasmArtifactPort.js";
+import type {
+ WasmArtifactExecution,
+ WasmArtifactPort,
+} from "../application/wasm/WasmArtifactPort.js";
import { readStableArtifact } from "../artifacts/readStableArtifact.js";
import type {
AnalysisError,
@@ -76,10 +76,10 @@ export class WabtArtifactProvider implements WasmArtifactPort {
async inspect(
input: InspectWasmArtifactInput,
options?: ExecutionOptions,
- ): Promise> {
+ ): Promise> {
let root: Pick | undefined;
let phase: "configuration" | "artifact" | "producer" = "configuration";
- let result: Result;
+ let result: Result;
let capturedOutput: AnalysisCapturedOutput | undefined;
try {
if (options?.signal?.aborted) throw new AnalysisCancelledError(OPERATION);
diff --git a/tests/boundary/cli/developmentTests.test.ts b/tests/boundary/cli/developmentTests.test.ts
index 21d8c5127..2987206c8 100644
--- a/tests/boundary/cli/developmentTests.test.ts
+++ b/tests/boundary/cli/developmentTests.test.ts
@@ -1,100 +1,175 @@
-import { execFile } from "node:child_process";
-import { mkdir, symlink, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
-import { promisify } from "node:util";
+import {
+ copyFile,
+ mkdir,
+ readFile,
+ symlink,
+ writeFile,
+} from "node:fs/promises";
+import { join } from "node:path";
import { describe, expect, it } from "vitest";
+import { execFileOutput } from "../../../src/process/ExecFileOutput.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
-const execute = promisify(execFile);
-const runner = resolve("scripts/run-development-tests.mjs");
-
-describe("development test runner", () => {
- it("rejects nonexistent explicit paths instead of returning a zero-test success", async () => {
- await expect(
- execute(process.execPath, [
- runner,
- "focused",
- "src/missing.test.ts",
- "--dry-run",
- ]),
- ).rejects.toMatchObject({ code: 1 });
+const run = (root: string, command: string, arguments_: readonly string[]) =>
+ execFileOutput(command, arguments_, {
+ cwd: root,
+ stopSignal: "SIGTERM",
+ timeout: 30_000,
+ maxBuffer: 1024 * 1024,
});
- it("reports actionable remediation when the comparison base is unavailable", async () => {
- await expect(
- execute(process.execPath, [
- runner,
- "changed",
- "--base",
- "missing-test-base",
- "--dry-run",
+const git = (root: string, ...arguments_: string[]) =>
+ run(root, "git", arguments_);
+
+const commit = (root: string, message: string) =>
+ git(
+ root,
+ "-c",
+ "user.name=REA fixture",
+ "-c",
+ "user.email=fixture@example.test",
+ "-c",
+ "commit.gpgSign=false",
+ "commit",
+ "--quiet",
+ "-m",
+ message,
+ );
+
+const fixture = async () => {
+ const root = await createTestTempDirectory("rea-development-tests-");
+ await mkdir(join(root, "scripts", "lib"), { recursive: true });
+ await mkdir(join(root, "src"));
+ for (const path of [
+ "scripts/run-development-tests.mjs",
+ "scripts/lib/development-tests.mjs",
+ ])
+ await copyFile(join(process.cwd(), path), join(root, path));
+ await symlink(
+ join(process.cwd(), "node_modules"),
+ join(root, "node_modules"),
+ process.platform === "win32" ? "junction" : undefined,
+ );
+ await writeFile(join(root, "package.json"), '{"type":"module"}\n');
+ await writeFile(join(root, ".gitignore"), "node_modules\nselected.txt\n");
+ await writeFile(
+ join(root, "vitest.config.mjs"),
+ 'export default { test: { projects: [{ test: { name: "domain", include: ["src/**/*.test.ts"] } }] } };\n',
+ );
+ await writeFile(join(root, "src/value.ts"), "export const value = 1;\n");
+ await writeFile(
+ join(root, "src/value.test.ts"),
+ 'import { expect, it } from "vitest"; import { writeFileSync } from "node:fs"; import { value } from "./value.js"; it("checks the selected source", () => { expect(value).toBe(1); writeFileSync("selected.txt", String(value)); });\n',
+ );
+ await git(root, "init", "--quiet", "-b", "main");
+ await git(root, "add", ".");
+ await commit(root, "fixture");
+ return root;
+};
+
+const testCommand = (root: string, ...arguments_: string[]) =>
+ run(root, process.execPath, [
+ "scripts/run-development-tests.mjs",
+ ...arguments_,
+ ]);
+
+describe("development test runner public CLI", () => {
+ it("runs an explicitly selected source test on a clean tree without build artifacts", async () => {
+ const root = await fixture();
+ const { stdout: status } = await git(root, "status", "--porcelain");
+ expect(status).toBe("");
+ await testCommand(root, "local", "src/value.test.ts");
+ expect(await readFile(join(root, "selected.txt"), "utf8")).toBe("1");
+ });
+
+ it("plans an exact local test without building", async () => {
+ const root = await fixture();
+ const { stdout } = await testCommand(
+ root,
+ "local",
+ "src/value.test.ts",
+ "--dry-run",
+ );
+ expect(JSON.parse(stdout)).toMatchObject({
+ needsBuild: false,
+ artifactTasks: [],
+ vitestArguments: expect.arrayContaining([
+ "run",
+ "--project",
+ "domain",
+ "--project",
+ "services",
+ "--project",
+ "adapters",
+ "--project",
+ "composition",
+ "--project",
+ "conformance",
+ "--project",
+ "evaluation",
+ "src/value.test.ts",
]),
+ });
+ });
+
+ it("uses committed dependency changes to select source tests and reports failures", async () => {
+ const root = await fixture();
+ const { stdout: base } = await git(root, "rev-parse", "HEAD");
+ await writeFile(join(root, "src/value.ts"), "export const value = 2;\n");
+ await git(root, "add", "src/value.ts");
+ await commit(root, "change dependency");
+ await expect(
+ testCommand(root, "changed", "--base", base.trim()),
+ ).rejects.toMatchObject({
+ code: 1,
+ stdout: expect.stringContaining("src/value.test.ts"),
+ stderr: expect.stringContaining("expected 2 to be 1"),
+ });
+ });
+
+ it("runs changed and focused tests from a committed branch regression", async () => {
+ const root = await fixture();
+ const { stdout: baseline } = await git(root, "rev-parse", "HEAD");
+ await git(root, "update-ref", "refs/remotes/origin/main", baseline.trim());
+ await git(root, "switch", "--quiet", "-c", "regression");
+ await writeFile(join(root, "src/value.ts"), "export const value = 2;\n");
+ await writeFile(
+ join(root, "src/value.test.ts"),
+ 'import { expect, it } from "vitest"; import { value } from "./value.js"; it("checks current source", () => expect(value).toBe(2));\n',
+ );
+ await git(root, "add", "src");
+ await commit(root, "regression fix");
+ expect((await git(root, "status", "--porcelain")).stdout).toBe("");
+
+ const changed = await testCommand(root, "changed");
+ expect(changed.stdout).toContain("1 passed");
+ const focused = await testCommand(root, "focused", "src/value.test.ts");
+ expect(focused.stdout).toContain("1 passed");
+ }, 60_000);
+
+ it("reports a missing comparison base and rejects missing or compiled-boundary paths", async () => {
+ const root = await fixture();
+ await expect(
+ testCommand(root, "changed", "--base", "missing-test-base", "--dry-run"),
).rejects.toMatchObject({
code: 1,
stderr: expect.stringContaining(
"Fetch origin/main or pass --base REVISION",
),
});
- });
-
- it("runs a committed branch regression through real Git and Vitest without dist", async () => {
- const root = await createTestTempDirectory("rea-development-tests-");
- await mkdir(join(root, "src"));
- await symlink(
- resolve("node_modules"),
- join(root, "node_modules"),
- "junction",
- );
- await writeFile(
- join(root, "package.json"),
- JSON.stringify({ type: "module" }),
- );
- await writeFile(join(root, ".gitignore"), "node_modules\n");
- await writeFile(
- join(root, "vitest.config.ts"),
- `export default { test: { projects: [{ test: { name: "domain", include: ["src/**/*.test.ts"] } }] } };`,
- );
- await writeFile(join(root, "src/value.ts"), "export const value = 1;\n");
- await writeFile(
- join(root, "src/value.test.ts"),
- `import { it, expect } from "vitest"; import { value } from "./value"; it("checks current source", () => expect(value).toBe(1));\n`,
- );
- const git = (arguments_: string[]) =>
- execute("git", arguments_, { cwd: root });
- await git(["init", "-b", "main"]);
- await git(["add", ".gitignore", "package.json", "vitest.config.ts", "src"]);
- const commit = [
- "-c",
- "user.name=REA fixture",
- "-c",
- "user.email=fixture@example.test",
- "commit",
- "-m",
- "fixture",
- ];
- await git(commit);
- const { stdout: baseline } = await git(["rev-parse", "HEAD"]);
- await git(["update-ref", "refs/remotes/origin/main", baseline.trim()]);
- await git(["switch", "-c", "regression"]);
- await writeFile(join(root, "src/value.ts"), "export const value = 2;\n");
- await writeFile(
- join(root, "src/value.test.ts"),
- `import { it, expect } from "vitest"; import { value } from "./value"; it("checks current source", () => expect(value).toBe(2));\n`,
- );
- await git(["add", "src"]);
- await git(commit);
- expect((await git(["status", "--porcelain"])).stdout).toBe("");
- const { stdout } = await execute(process.execPath, [runner, "changed"], {
- cwd: root,
+ await expect(
+ testCommand(root, "focused", "src/missing.test.ts"),
+ ).rejects.toMatchObject({
+ code: 1,
+ stderr: expect.stringContaining("ENOENT"),
});
- expect(stdout).toContain("1 passed");
- const explicit = await execute(
- process.execPath,
- [runner, "focused", "src/value.test.ts"],
- { cwd: root },
- );
- expect(explicit.stdout).toContain("1 passed");
- }, 30_000);
+ await expect(
+ testCommand(root, "local", "tests/acceptance/runtime.test.ts"),
+ ).rejects.toMatchObject({
+ code: 1,
+ stderr: expect.stringContaining("Use test:focused"),
+ });
+ });
});
diff --git a/tests/boundary/cli/pcapCli.test.ts b/tests/boundary/cli/pcapCli.test.ts
new file mode 100644
index 000000000..1eb61cdcf
--- /dev/null
+++ b/tests/boundary/cli/pcapCli.test.ts
@@ -0,0 +1,37 @@
+import { expect, it } from "vitest";
+
+import { expectConfigurationRefusal, serveCli } from "./cliServeHarness.js";
+
+it.each(["inspect-pcap-client", "inspect-pcap-capture"])(
+ "%s advertises a schema through the public CLI",
+ async (command) => {
+ const result = await serveCli([command, "--schema", "--json"]);
+ expect(result.exitCode).toBe(0);
+ expect(JSON.parse(result.stdout)).toBeTruthy();
+ },
+);
+
+it.each([
+ ["inspect-pcap-client"],
+ ["inspect-pcap-capture", "/nonexistent/capture.pcap"],
+])("%s names the missing Wireshark tool to configure", async (...argv) => {
+ const result = await serveCli([...argv, "--json"], {
+ REA_TSHARK_COMMAND: "/nonexistent/tshark",
+ REA_CAPINFOS_COMMAND: "/nonexistent/capinfos",
+ });
+ expectConfigurationRefusal(
+ result,
+ "Cannot run selected tool /nonexistent/tshark",
+ );
+ expectConfigurationRefusal(result, "through absolute REA_TSHARK_COMMAND");
+});
+
+it("names a relative tool selection as configuration to fix", async () => {
+ const result = await serveCli(["inspect-pcap-client", "--json"], {
+ REA_TSHARK_COMMAND: "tshark",
+ });
+ expectConfigurationRefusal(
+ result,
+ "REA_TSHARK_COMMAND must be an absolute path to the tshark binary",
+ );
+});
diff --git a/tests/boundary/filesystem/developmentTests.test.ts b/tests/boundary/filesystem/developmentTests.test.ts
deleted file mode 100644
index 1b52bb475..000000000
--- a/tests/boundary/filesystem/developmentTests.test.ts
+++ /dev/null
@@ -1,110 +0,0 @@
-import {
- copyFile,
- mkdir,
- readFile,
- symlink,
- writeFile,
-} from "node:fs/promises";
-import { join } from "node:path";
-
-import { expect, it } from "vitest";
-
-import { execFileOutput } from "../../../src/process/ExecFileOutput.js";
-import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
-
-const run = (root: string, command: string, arguments_: readonly string[]) =>
- execFileOutput(command, arguments_, {
- cwd: root,
- stopSignal: "SIGTERM",
- timeout: 20_000,
- });
-
-const commit = (root: string, message: string) =>
- run(root, "git", [
- "-c",
- "user.name=REA fixture",
- "-c",
- "user.email=fixture@example.invalid",
- "-c",
- "commit.gpgSign=false",
- "commit",
- "--quiet",
- "-m",
- message,
- ]);
-
-const fixture = async () => {
- const root = await createTestTempDirectory("rea-development-tests-");
- await mkdir(join(root, "scripts", "lib"), { recursive: true });
- await mkdir(join(root, "src"));
- for (const path of [
- "scripts/run-development-tests.mjs",
- "scripts/lib/development-tests.mjs",
- ])
- await copyFile(join(process.cwd(), path), join(root, path));
- await symlink(
- join(process.cwd(), "node_modules"),
- join(root, "node_modules"),
- process.platform === "win32" ? "junction" : undefined,
- );
- await writeFile(join(root, "package.json"), '{"type":"module"}\n');
- await writeFile(join(root, ".gitignore"), "node_modules\nselected.txt\n");
- await writeFile(
- join(root, "vitest.config.mjs"),
- 'export default { test: { projects: [{ test: { name: "domain", include: ["src/**/*.test.ts"] } }] } };\n',
- );
- await writeFile(join(root, "src", "value.ts"), "export const value = 1;\n");
- await writeFile(
- join(root, "src", "value.test.ts"),
- 'import { expect, it } from "vitest"; import { writeFileSync } from "node:fs"; import { value } from "./value.js"; it("checks the selected source", () => { expect(value).toBe(1); writeFileSync("selected.txt", String(value)); });\n',
- );
- await run(root, "git", ["init", "--quiet"]);
- await run(root, "git", ["add", "."]);
- await commit(root, "fixture");
- return root;
-};
-
-const testCommand = (root: string, ...arguments_: string[]) =>
- run(root, process.execPath, [
- "scripts/run-development-tests.mjs",
- ...arguments_,
- ]);
-
-it("executes an explicitly selected source test on a clean tree without build artifacts", async () => {
- const root = await fixture();
- const { stdout: status } = await run(root, "git", ["status", "--porcelain"]);
- expect(status).toBe("");
- await testCommand(root, "local", "src/value.test.ts");
- expect(await readFile(join(root, "selected.txt"), "utf8")).toBe("1");
-});
-
-it("uses committed dependency changes since the requested Git base to select source tests", async () => {
- const root = await fixture();
- const { stdout: base } = await run(root, "git", ["rev-parse", "HEAD"]);
- await writeFile(join(root, "src", "value.ts"), "export const value = 2;\n");
- await run(root, "git", ["add", "src/value.ts"]);
- await commit(root, "change dependency");
- await expect(
- testCommand(root, "changed", "--base", base.trim()),
- ).rejects.toMatchObject({
- code: 1,
- stdout: expect.stringContaining("src/value.test.ts"),
- stderr: expect.stringContaining("expected 2 to be 1"),
- });
-});
-
-it("rejects a compiled boundary in the source-only command and a missing exact test", async () => {
- const root = await fixture();
- await expect(
- testCommand(root, "local", "tests/acceptance/runtime.test.ts"),
- ).rejects.toMatchObject({
- code: 1,
- stderr: expect.stringContaining("Use test:focused"),
- });
- await expect(
- testCommand(root, "local", "src/missing.test.ts"),
- ).rejects.toMatchObject({
- code: 1,
- stderr: expect.stringContaining("ENOENT"),
- });
-});
diff --git a/tests/boundary/filesystem/ghidraPspExtension.test.ts b/tests/boundary/filesystem/ghidraPspExtension.test.ts
index 88e25939a..0e07ad629 100644
--- a/tests/boundary/filesystem/ghidraPspExtension.test.ts
+++ b/tests/boundary/filesystem/ghidraPspExtension.test.ts
@@ -52,7 +52,7 @@ const target = {
const host: GhidraInstallationHost = {
platform: "linux",
architecture: "x64",
- readText: () => "application.version=12.1.3\n",
+ readText: () => "application.version=12.1.3\napplication.java.min=21\n",
executable: () => true,
probeJava: () => ({
version: "21.0.12",
diff --git a/tests/boundary/filesystem/installScript.test.ts b/tests/boundary/filesystem/installScript.test.ts
index 3fbcf7a3c..0f2e14730 100644
--- a/tests/boundary/filesystem/installScript.test.ts
+++ b/tests/boundary/filesystem/installScript.test.ts
@@ -11,6 +11,7 @@ import {
import { join } from "node:path";
import { promisify } from "node:util";
+import { spawn as spawnPty } from "@lydell/node-pty";
import { describe, expect, it } from "vitest";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
@@ -185,6 +186,69 @@ describe("curl installer scenarios", { timeout: 20_000 }, () => {
});
});
+describe("installer TTY fallback", { timeout: 20_000 }, () => {
+ it("skips automatic setup when stderr is redirected", async () => {
+ const fixture = await createFixture();
+ const script = join(process.cwd(), "install.sh");
+ const wrapper = `
+ const { spawnSync } = require("node:child_process");
+ const { openSync, closeSync } = require("node:fs");
+ const stderr = openSync(process.argv[2], "w");
+ const child = spawnSync("/bin/bash", [process.argv[1], ...process.argv.slice(3)], {
+ stdio: ["inherit", "inherit", stderr],
+ env: process.env,
+ });
+ closeSync(stderr);
+ process.exit(child.status ?? 1);
+ `;
+ let output = "";
+ const terminal = spawnPty(
+ process.execPath,
+ ["-e", wrapper, script, fixture.installerStderrLog, "--version", "0.3.0"],
+ {
+ cwd: process.cwd(),
+ env: {
+ ...process.env,
+ HOME: fixture.home,
+ TMPDIR: fixture.temporary,
+ PATH: `${fixture.bin}:/usr/bin:/bin`,
+ FAKE_NPM_LOG: fixture.npmLog,
+ FAKE_REA_LOG: fixture.reaLog,
+ FAKE_REA_SOURCE: join(fixture.bin, "rea-source"),
+ FAKE_NPM_PREFIX: join(fixture.home, ".npm-global"),
+ TERM: "xterm-256color",
+ },
+ name: "xterm-256color",
+ cols: 120,
+ rows: 40,
+ },
+ );
+ let timedOut = false;
+ const exitCode = await new Promise((resolve, reject) => {
+ const timeout = setTimeout(() => {
+ timedOut = true;
+ terminal.kill();
+ }, 10_000);
+ terminal.onData((data) => {
+ output += data;
+ });
+ terminal.onExit(({ exitCode: code }) => {
+ clearTimeout(timeout);
+ if (timedOut)
+ reject(new Error(`Installer PTY timed out after output: ${output}`));
+ else resolve(code);
+ });
+ });
+
+ expect(exitCode).toBe(0);
+ expect(output).toContain(
+ `Run ${join(fixture.home, ".local/bin/rea")} setup to configure Hopper and agents.`,
+ );
+ expect(await readFile(fixture.reaLog, "utf8")).toBe("--version\n");
+ expect(await readFile(fixture.installerStderrLog, "utf8")).toBe("");
+ });
+});
+
describe("truncated installer download", { timeout: 20_000 }, () => {
it("runs nothing from a download truncated after the npm install line", async () => {
const fixture = await createFixture();
@@ -433,6 +497,7 @@ interface InstallerFixture {
readonly temporary: string;
readonly npmLog: string;
readonly reaLog: string;
+ readonly installerStderrLog: string;
}
const getProcessOutput = (
@@ -456,6 +521,7 @@ const createFixture = async (): Promise => {
const temporary = join(root, "tmp");
const npmLog = join(root, "npm.log");
const reaLog = join(root, "rea.log");
+ const installerStderrLog = join(root, "installer.stderr.log");
await Promise.all([mkdir(home), mkdir(bin), mkdir(temporary)]);
await Promise.all([
executable(
@@ -507,7 +573,7 @@ exit 0
symlink(`/usr/bin/${command}`, join(bin, command)),
),
]);
- return { home, bin, temporary, npmLog, reaLog };
+ return { home, bin, temporary, npmLog, reaLog, installerStderrLog };
};
const executable = async (path: string, source: string): Promise => {
diff --git a/tests/boundary/filesystem/sourceToBundlePaths.test.ts b/tests/boundary/filesystem/sourceToBundlePaths.test.ts
index 19aa07a1a..8bc9caa27 100644
--- a/tests/boundary/filesystem/sourceToBundlePaths.test.ts
+++ b/tests/boundary/filesystem/sourceToBundlePaths.test.ts
@@ -6,7 +6,7 @@ import { analyzeJavaScriptApplication } from "../../support/javascriptApplicatio
import { parseApplicationGraphEvidence } from "../../../src/application/javascript/JavaScriptApplicationEvidenceGraph.js";
import { findApplicationFeatureSeeds } from "../../../src/domain/javascript/javascriptFeatureSeed.js";
import { compareSourceToBundle } from "../../../src/domain/javascript/sourceToBundleComparison.js";
-import { resolveSourceMapSource } from "../../../src/javascript/sourceMaps/DecodedSourceMap.js";
+import { resolveJavaScriptSourceMapUrl } from "../../../src/domain/javascript/javascriptSourceMapPaths.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
import { importReferenceSource } from "../../support/referenceSourceResourceScope.js";
@@ -180,7 +180,7 @@ it.each([
decoy: decoyPath = "src/a.js",
}) => {
if (sourceRoot !== undefined) {
- const resolved = resolveSourceMapSource(
+ const resolved = resolveJavaScriptSourceMapUrl(
source,
sourceRoot,
`https://example.test/${mapPath}`,
diff --git a/tests/boundary/mcp/analysisViewMcp.test.ts b/tests/boundary/mcp/analysisViewMcp.test.ts
index 5b2fe98af..b95aebe57 100644
--- a/tests/boundary/mcp/analysisViewMcp.test.ts
+++ b/tests/boundary/mcp/analysisViewMcp.test.ts
@@ -39,6 +39,8 @@ import {
} from "../../fixtures/analysisView.js";
import { createTestBinarySession } from "../../fixtures/binarySession.js";
import { BINARY_LAYOUT_TEST_PROVIDER } from "../../fixtures/binaryDiagnostics/layout.js";
+import { wasmArtifactFixture } from "../../fixtures/wasm/artifact.js";
+import { evmInterfaceFixture } from "../../fixtures/evm/interface.js";
const connect = async (
binaryLayout?: BinaryLayoutService,
@@ -310,6 +312,65 @@ it("reports a tampered inline Evidence ID at its full MCP source path", async ()
});
});
+it("rejects self-contained WASM and EVM Evidence views when the subject format differs", async () => {
+ const { client } = await connect();
+ const wasm = wasmArtifactFixture();
+ const evm = evmInterfaceFixture();
+ const cases = [
+ {
+ evidence: createEvidence(
+ {
+ path: wasm.artifact.path,
+ format: "elf",
+ sha256: wasm.artifact.sha256,
+ },
+ { id: "fixture-wabt", name: "WABT", version: "1" },
+ {
+ operation: "inspect_wasm_artifact",
+ parameters: { path: wasm.artifact.path },
+ result: wasm,
+ },
+ ),
+ },
+ {
+ evidence: createEvidence(
+ {
+ path: evm.artifact.path,
+ format: "elf",
+ sha256: evm.artifact.sha256,
+ },
+ { id: "fixture-evm", name: "EVMole", version: "1" },
+ {
+ operation: "inspect_evm_interface",
+ parameters: { path: evm.artifact.path, encoding: "hex" },
+ result: evm,
+ },
+ ),
+ },
+ ] as const;
+
+ for (const { evidence } of cases) {
+ const response = await client.callTool({
+ name: "inspect_analysis_view",
+ arguments: {
+ source: { kind: "inline", evidence },
+ view: { kind: "summary" },
+ },
+ });
+ expect(parseMcpToolError(response).error).toMatchObject({
+ code: "invalid_request",
+ details: {
+ issues: [
+ expect.objectContaining({
+ path: ["source", "subject"],
+ reason: "invalid_value",
+ }),
+ ],
+ },
+ });
+ }
+});
+
it("admits portable captures before SDK Evidence parsing and preserves capture caveats", async () => {
const { client } = await connect();
const dense = analysisViewCaptureEvidence(analysisViewObjectDenseCapture());
diff --git a/tests/boundary/mcp/applicationEvidenceMcp.test.ts b/tests/boundary/mcp/applicationEvidenceMcp.test.ts
index 16dfc142c..ba71b7921 100644
--- a/tests/boundary/mcp/applicationEvidenceMcp.test.ts
+++ b/tests/boundary/mcp/applicationEvidenceMcp.test.ts
@@ -2,6 +2,7 @@ import { parseMcpToolError } from "../../fixtures/mcpToolError.js";
import type { Client } from "@modelcontextprotocol/client";
import { describe, expect, it } from "vitest";
import { Ajv2020 } from "ajv/dist/2020.js";
+import type { AnySchema } from "ajv";
import type { BinarySession } from "../../../src/application/binary/BinarySession.js";
import {
@@ -10,12 +11,143 @@ import {
SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE,
} from "../../../src/contracts/javascript/javascriptApplicationWorkflowExamples.js";
import { createEvidence } from "../../../src/domain/evidence.js";
+import { javascriptApplicationAnalysisResultSchema } from "../../../src/domain/javascript/javascriptApplicationAnalysis.js";
+import {
+ createJavaScriptApplicationGraph,
+ createJavaScriptApplicationNode,
+} from "../../../src/domain/javascript/javascriptApplicationGraph.js";
+import { createJavaScriptSemanticGraph } from "../../../src/domain/javascript/javascriptSemanticGraph.js";
+import {
+ artifactEvidence,
+ sourceMapReference,
+} from "../../../src/domain/javascript/javascriptApplicationGraph.fixture.js";
import {
createApplicationMcpHarness,
type ApplicationMcpHarness,
} from "../../fixtures/applicationMcpHarness.js";
import { createHistoricalSourceGraph } from "../../../src/domain/referenceSourceGraph.js";
+async function runUnicodeSourceMapComparison(
+ harness: ApplicationMcpHarness,
+): Promise {
+ const baseApplication = SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE.application;
+ const subject = baseApplication.subject;
+ if (subject === null) throw new Error("Application Evidence has no subject");
+ const baseResult = javascriptApplicationAnalysisResultSchema.parse(
+ baseApplication.normalized_result,
+ );
+ const baseGraph = baseResult.graph;
+ const decomposedSource = "cafe\u0301.ts";
+ const unicodeSourceNode = createJavaScriptApplicationNode({
+ kind: "source-module",
+ identity: {
+ strategy: "source-map-original",
+ source_root: "../src/",
+ stability: "source-map-exact",
+ source_map_sha256: "1".repeat(64),
+ original_source: decomposedSource,
+ source_sha256: "3".repeat(64),
+ },
+ observations: [
+ {
+ label: "decomposed source-map spelling",
+ source_map_reference: sourceMapReference(
+ decomposedSource,
+ "../src/",
+ "dist/main.js.map",
+ ),
+ properties: { content_available: true, content_sha256: "3".repeat(64) },
+ evidence: artifactEvidence("1".repeat(64), "dist/main.js.map"),
+ },
+ ],
+ });
+ const applicationGraph = createJavaScriptApplicationGraph({
+ schema: "JavaScriptApplicationGraph",
+ root_node_ids: [...baseGraph.root_node_ids, unicodeSourceNode.node_id],
+ nodes: [...baseGraph.nodes, unicodeSourceNode],
+ edges: baseGraph.edges,
+ coverage: baseGraph.coverage,
+ limitations: baseGraph.limitations,
+ });
+ const semantic = baseResult.semantic_graph;
+ const { graph_id: _semanticGraphId, ...semanticInput } = semantic;
+ const semanticGraph = createJavaScriptSemanticGraph({
+ ...semanticInput,
+ application_graph_id: applicationGraph.graph_id,
+ });
+ const unicodeApplication = createEvidence(
+ {
+ path: baseResult.input_path,
+ sha256: subject.digest.sha256,
+ format: subject.format,
+ },
+ baseApplication.provider,
+ {
+ predicateType: baseApplication.predicate_type,
+ operation: baseApplication.operation,
+ parameters: baseApplication.parameters,
+ result: {
+ ...baseResult,
+ graph: applicationGraph,
+ semantic_graph: semanticGraph,
+ },
+ confidence: baseApplication.confidence,
+ authority: baseApplication.authority,
+ limitations: baseApplication.limitations,
+ evidenceLinks: baseApplication.evidence_links,
+ },
+ );
+ const historicalUnicodePath = "src/caf\u00e9.ts";
+ const unicodeReference = createHistoricalSourceGraph({
+ ...SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE.reference,
+ root_sha256: undefined,
+ entries: SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE.reference.entries.map(
+ (entry) =>
+ entry.path === "src/main.ts"
+ ? { ...entry, path: historicalUnicodePath }
+ : entry,
+ ),
+ });
+ const reply = await harness.client.callTool({
+ name: "compare_source_to_bundle",
+ arguments: { reference: unicodeReference, application: unicodeApplication },
+ });
+ expect(reply.isError).not.toBe(true);
+ expect(reply.structuredContent).toMatchObject({
+ normalized_result: {
+ items: [
+ {
+ source_path: historicalUnicodePath,
+ status: "unknown",
+ current_node_ids: [],
+ candidates: [
+ expect.objectContaining({
+ confidence: "low",
+ signals: expect.arrayContaining([
+ expect.objectContaining({
+ kind: "unicode-equivalent-path",
+ source_value: historicalUnicodePath,
+ current_values: ["src/cafe\u0301.ts"],
+ }),
+ ]),
+ }),
+ ],
+ },
+ ],
+ },
+ });
+ const advertised = (await harness.client.listTools()).tools.find(
+ ({ name }) => name === "compare_source_to_bundle",
+ );
+ if (advertised?.outputSchema === undefined)
+ throw new Error("Comparison tool output schema is missing");
+ const ajv = new Ajv2020({ strict: false, validateFormats: false });
+ const outputSchema = advertised.outputSchema as AnySchema;
+ expect(ajv.validateSchema(outputSchema)).toBe(true);
+ const validateOutput = ajv.compile(outputSchema);
+ expect(validateOutput(reply.structuredContent)).toBe(true);
+}
+
async function runInlineWorkflowScenarios(
harness: ApplicationMcpHarness,
): Promise {
@@ -92,6 +224,8 @@ async function runInlineWorkflowScenarios(
},
});
+ await runUnicodeSourceMapComparison(harness);
+
const referenceWithExclusion = createHistoricalSourceGraph({
...SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE.reference,
root_sha256: undefined,
diff --git a/tests/boundary/mcp/evidenceBundleInline.test.ts b/tests/boundary/mcp/evidenceBundleInline.test.ts
index adb95ef8f..ae07a1be5 100644
--- a/tests/boundary/mcp/evidenceBundleInline.test.ts
+++ b/tests/boundary/mcp/evidenceBundleInline.test.ts
@@ -1,10 +1,20 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
import { ok as resultOk } from "../../../src/domain/result.js";
import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
import { expect, it } from "vitest";
import { createTestBinarySession } from "../../fixtures/binarySession.js";
import { observed } from "../../fixtures/analysisExecution.js";
+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+import { parseMcpToolError } from "../../fixtures/mcpToolError.js";
+import { createAnalysisProfile } from "../../../src/domain/analysisProfile.js";
import { createEvidence } from "../../../src/domain/evidence.js";
+import { ANALYSIS_SNAPSHOT_TARGET } from "../../../src/domain/analysisSnapshot.fixture.js";
+import { jsonValueSchema } from "../../../src/domain/jsonValue.js";
+import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../../../src/domain/process/processCaptureExample.js";
+import { PROCESS_PROVIDER } from "../../../src/domain/process/processEvidenceProvider.js";
import { createServer } from "../../../src/server/createServer.js";
it("returns the complete session Evidence bundle in the tool result", async () => {
@@ -44,3 +54,251 @@ it("returns the complete session Evidence bundle in the tool result", async () =
await Promise.allSettled([client.close(), server.close(), session.close()]);
}
});
+
+it("rejects bundle field stripping at MCP import without changing retained evidence", async () => {
+ const root = await createTestTempDirectory("rea-evidence-bundle-mcp-");
+ const sourceSession = createBundleSourceSession();
+ const targetSession = createTestBinarySession(() => ({
+ execute: () => Promise.resolve(observed(null)),
+ close: () => Promise.resolve(resultOk(null)),
+ }));
+ const source = await connectEvidenceMcp("bundle-source", sourceSession);
+ const target = await connectEvidenceMcp("bundle-target", targetSession);
+ const { client: sourceClient } = source;
+ const { client: targetClient } = target;
+ const bundlePath = join(root, "exported.json");
+ const targetExportPath = join(root, "round-trip.json");
+
+ try {
+ const { sourceJson, records, evidenceIndex } = await exportFixtureBundle(
+ sourceClient,
+ bundlePath,
+ );
+ const initial = structured(
+ await targetClient.callTool({
+ name: "get_evidence_bundle",
+ arguments: {},
+ }),
+ ).result;
+ for (const [label, path] of unsupportedBundleFields(evidenceIndex)) {
+ const candidate = structuredClone(sourceJson);
+ setPath(candidate, path, "unsupported-metadata");
+ const malformedPath = join(root, `${label.replaceAll(" ", "-")}.json`);
+ await writeFile(malformedPath, JSON.stringify(candidate));
+ const rejected = await targetClient.callTool({
+ name: "import_evidence_bundle",
+ arguments: { path: malformedPath },
+ });
+ expect(parseMcpToolError(rejected), label).toMatchObject({
+ error: { code: "evidence_integrity_mismatch" },
+ });
+ expect(
+ structured(
+ await targetClient.callTool({
+ name: "get_evidence_bundle",
+ arguments: {},
+ }),
+ ).result,
+ label,
+ ).toEqual(initial);
+ }
+
+ const imported = await targetClient.callTool({
+ name: "import_evidence_bundle",
+ arguments: { path: bundlePath },
+ });
+ if (imported.isError === true)
+ throw new Error(JSON.stringify(parseMcpToolError(imported)));
+ await targetClient.callTool({
+ name: "export_evidence_bundle",
+ arguments: { path: targetExportPath },
+ });
+ expect(JSON.parse(await readFile(targetExportPath, "utf8"))).toEqual(
+ sourceJson,
+ );
+ const observedRecord = records[evidenceIndex]!;
+ expect(observedRecord.parameters).toEqual({ caller: { note: "preserve" } });
+ expect(observedRecord.normalized_result).toEqual({
+ producer: { extension: "preserve" },
+ });
+ expect(object(observedRecord.analysis_profile).parameters).toEqual({
+ loader: { mode: "full" },
+ });
+ } finally {
+ await Promise.allSettled([
+ sourceClient.close(),
+ source.server.close(),
+ sourceSession.close(),
+ targetClient.close(),
+ target.server.close(),
+ targetSession.close(),
+ ]);
+ }
+});
+
+const createBundleSourceSession = () => {
+ const provider = { id: "fixture", name: "Fixture", version: "1" };
+ const evidence = createEvidence(ANALYSIS_SNAPSHOT_TARGET, provider, {
+ operation: "observe",
+ parameters: { caller: { note: "preserve" } },
+ result: { producer: { extension: "preserve" } },
+ analysisProfile: createAnalysisProfile(provider, {
+ loader: { mode: "full" },
+ }),
+ environment: {
+ id: "fixture-linux",
+ platform: "linux",
+ architecture: "x86_64",
+ isolation: "process",
+ },
+ locations: [{ kind: "address", address: "0x1000" }],
+ });
+ const session = createTestBinarySession(() => ({
+ execute: () => Promise.resolve(observed(null)),
+ close: () => Promise.resolve(resultOk(null)),
+ }));
+ expect(session.recordEvidence(evidence).ok).toBe(true);
+ for (const extra of [
+ createEvidence(ANALYSIS_SNAPSHOT_TARGET, provider, {
+ operation: "controlled_replay",
+ parameters: {},
+ result: { completed: true },
+ authority: "controlled-replay",
+ }),
+ createEvidence(undefined, PROCESS_PROVIDER, {
+ predicateType: "rea.process-capture",
+ operation: "capture_process_scenario",
+ parameters: {},
+ result: jsonValueSchema.parse(EMPTY_PROCESS_CAPTURE_EXAMPLE),
+ confidence: "observed",
+ authority: "controlled-replay",
+ }),
+ ])
+ expect(session.recordEvidence(extra).ok).toBe(true);
+ return session;
+};
+
+const exportFixtureBundle = async (
+ client: Client,
+ path: string,
+): Promise<{
+ readonly sourceJson: unknown;
+ readonly records: Record[];
+ readonly evidenceIndex: number;
+}> => {
+ const unknown = await client.callTool({
+ name: "record_unknown",
+ arguments: {
+ question: "Does this remain unknown?",
+ severity: "medium",
+ domain: "bundle-format",
+ required_authority: null,
+ required_confidence: "derived",
+ required_environment: null,
+ recommended_probes: [{ operation: "observe", rationale: "Inspect it." }],
+ relationships: [],
+ },
+ });
+ expect(unknown.isError).not.toBe(true);
+ const exported = await client.callTool({
+ name: "export_evidence_bundle",
+ arguments: { path },
+ });
+ expect(exported.isError).not.toBe(true);
+ const sourceJson = JSON.parse(await readFile(path, "utf8")) as unknown;
+ const records = array(object(sourceJson).records).map(object);
+ const evidenceIndex = records.findIndex(
+ (record) => record.operation === "observe",
+ );
+ expect(evidenceIndex).toBeGreaterThanOrEqual(0);
+ return { sourceJson, records, evidenceIndex };
+};
+
+const unsupportedBundleFields = (
+ evidenceIndex: number,
+): readonly [string, readonly (string | number)[]][] => [
+ ["bundle envelope", ["schema_version"]],
+ ["record provider", ["records", evidenceIndex, "provider", "future_field"]],
+ ["provider manifest", ["providers", 0, "future_field"]],
+ ["record subject", ["records", evidenceIndex, "subject", "future_field"]],
+ [
+ "subject digest",
+ ["records", evidenceIndex, "subject", "digest", "future_field"],
+ ],
+ ["artifact manifest", ["artifacts", 0, "future_field"]],
+ [
+ "record environment",
+ ["records", evidenceIndex, "environment", "future_field"],
+ ],
+ ["environment manifest", ["environments", 0, "future_field"]],
+ [
+ "source location",
+ ["records", evidenceIndex, "locations", 0, "future_field"],
+ ],
+ ["scenario manifest", ["scenarios", 0, "future_field"]],
+ ["capture manifest", ["captures", 0, "future_field"]],
+ [
+ "analysis profile",
+ ["records", evidenceIndex, "analysis_profile", "future_field"],
+ ],
+ [
+ "profile provider",
+ ["records", evidenceIndex, "analysis_profile", "provider", "future_field"],
+ ],
+ ["unknown revision", ["unknowns", 0, "future_field"]],
+ ["unknown probe", ["unknowns", 0, "recommended_probes", 0, "future_field"]],
+];
+
+const connectEvidenceMcp = async (
+ name: string,
+ session: ReturnType,
+) => {
+ const server = createServer({ kind: "session", session });
+ const client = new Client({ name, version: "1" });
+ const [clientTransport, serverTransport] =
+ InMemoryTransport.createLinkedPair();
+ await server.connect(serverTransport);
+ await client.connect(clientTransport);
+ return { client, server };
+};
+
+const object = (value: unknown): Record => {
+ if (typeof value !== "object" || value === null || Array.isArray(value))
+ throw new Error("Expected object in exported Evidence bundle");
+ return value as Record;
+};
+
+const array = (value: unknown): unknown[] => {
+ if (!Array.isArray(value))
+ throw new Error("Expected array in Evidence bundle");
+ return value;
+};
+
+const setPath = (
+ root: unknown,
+ path: readonly (string | number)[],
+ value: unknown,
+): void => {
+ const [last, ...parents] = [...path].reverse();
+ if (last === undefined) throw new Error("Expected a nonempty bundle path");
+ const target = parents
+ .reverse()
+ .reduce(
+ (current, segment) =>
+ typeof segment === "number"
+ ? array(current)[segment]
+ : object(current)[segment],
+ root,
+ );
+ object(target)[String(last)] = value;
+};
+
+const structured = (result: Awaited>) => {
+ if (result.isError === true) throw parseMcpToolError(result);
+ if (
+ typeof result.structuredContent !== "object" ||
+ result.structuredContent === null
+ )
+ throw new Error("Missing structured MCP result");
+ return result.structuredContent as Record;
+};
diff --git a/tests/boundary/mcp/evmInterfaceMcp.test.ts b/tests/boundary/mcp/evmInterfaceMcp.test.ts
index f3594dd89..823a4d3cf 100644
--- a/tests/boundary/mcp/evmInterfaceMcp.test.ts
+++ b/tests/boundary/mcp/evmInterfaceMcp.test.ts
@@ -107,6 +107,30 @@ it("advertises exact valid schemas and records inline EVM interface evidence wit
).toBe(true);
});
+it("rejects an EVM provider response with a non-file subject before recording Evidence", async () => {
+ const value = evmInterfaceFixture();
+ const execution = evmInterfaceExecution(value);
+ const malformed = {
+ ...execution,
+ subject: { ...execution.subject, format: "elf" },
+ } as unknown as typeof execution;
+ const harness = await createApplicationMcpHarness({
+ serverOptions: {
+ evmInterface: new EvmInterfaceService({
+ inspect: () => Promise.resolve(ok(malformed)),
+ }),
+ },
+ });
+ onTestFinished(harness.close);
+ const before = harness.session.exportEvidenceBundle().records.length;
+ const response = await harness.client.callTool({
+ name: "inspect_evm_interface",
+ arguments: { path: value.artifact.path, encoding: "hex" },
+ });
+ expect(parseMcpToolError(response).error.code).toBe("unreadable_output");
+ expect(harness.session.exportEvidenceBundle().records).toHaveLength(before);
+});
+
it.each(["unavailable", "incompatible-output"])(
"preserves a healthy WASM peer and explicit EVM failure: %s",
async (scenario) => {
diff --git a/tests/boundary/mcp/ghidraMcpHarness.ts b/tests/boundary/mcp/ghidraMcpHarness.ts
index 7e2c3ae73..ad3565992 100644
--- a/tests/boundary/mcp/ghidraMcpHarness.ts
+++ b/tests/boundary/mcp/ghidraMcpHarness.ts
@@ -95,7 +95,7 @@ export const sessionEvidence = (session: BinarySession, value: unknown) => {
const installationHost = (): GhidraInstallationHost => ({
platform: "linux",
architecture: "x64",
- readText: () => "application.version=12.1.4\n",
+ readText: () => "application.version=12.1.4\napplication.java.min=21\n",
executable: () => true,
probeJava: () => ({
version: "21.0.11",
diff --git a/tests/boundary/mcp/ghidraReopen.test.ts b/tests/boundary/mcp/ghidraReopen.test.ts
index bdac57233..6a90f0118 100644
--- a/tests/boundary/mcp/ghidraReopen.test.ts
+++ b/tests/boundary/mcp/ghidraReopen.test.ts
@@ -99,7 +99,7 @@ class FixtureLauncher implements GhidraLauncher {
const installationHost: GhidraInstallationHost = {
platform: "linux",
architecture: "x64",
- readText: () => "application.version=12.1.4\n",
+ readText: () => "application.version=12.1.4\napplication.java.min=21\n",
executable: () => true,
probeJava: () => ({
version: "21.0.11",
diff --git a/tests/boundary/mcp/pcapMcp.test.ts b/tests/boundary/mcp/pcapMcp.test.ts
new file mode 100644
index 000000000..d3a6d203d
--- /dev/null
+++ b/tests/boundary/mcp/pcapMcp.test.ts
@@ -0,0 +1,118 @@
+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
+import { expect, it, onTestFinished } from "vitest";
+
+import type { PcapAnalysisPort } from "../../../src/application/pcap/PcapAnalysisPort.js";
+import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js";
+import { assertAdvertisedMcpContracts } from "./mcpContractHarness.js";
+import { parseEvidence } from "../../../src/domain/evidence.js";
+import { ok } from "../../../src/domain/result.js";
+import { createServer } from "../../../src/server/createServer.js";
+import { createTestBinarySession } from "../../fixtures/binarySession.js";
+
+const identity = { id: "pcap", name: "Packet capture analysis", version: null };
+
+const clientIdentity = {
+ tshark_command: "/usr/bin/tshark",
+ tshark_source: "path",
+ tshark_version: "TShark (Wireshark) 4.6.6",
+ capinfos_command: "/usr/bin/capinfos",
+ capinfos_source: "path",
+ capinfos_version: "Capinfos (Wireshark) 4.6.6",
+};
+
+it("advertises exact valid pcap schemas and records inline evidence through MCP", async () => {
+ const provider: PcapAnalysisPort = {
+ async inspectAvailability() {
+ return { status: "available", code: null, reason: null, diagnostics: {} };
+ },
+ async close() {},
+ async execute(request) {
+ if (request.operation === "inspect_pcap_client")
+ return ok(
+ createAnalysisExecution({ client: clientIdentity }, identity),
+ );
+ return ok(
+ createAnalysisExecution(
+ {
+ client: clientIdentity,
+ target: {
+ path: "/captures/session.pcap",
+ bytes: 23279,
+ sha256: "a".repeat(64),
+ },
+ file_type: "Wireshark/tcpdump/... - pcap",
+ encapsulation: "Linux cooked-mode capture v2",
+ packet_count: 50,
+ capture_start: "2026-10-11 14:13:40.608505",
+ capture_end: "2026-10-11 14:13:40.981978",
+ capture_duration_seconds: 0.373473,
+ snapshot_length: 262144,
+ endpoints: [
+ { address: "192.168.1.100", port: null, packet_count: 30 },
+ { address: "8.8.8.8", port: 53, packet_count: 5 },
+ ],
+ endpoint_count: 2,
+ dns_queries: [
+ {
+ query: "example.com",
+ response_addresses: ["93.184.216.34"],
+ response_address_count: 1,
+ },
+ ],
+ dns_query_count: 1,
+ tls_sni_values: ["example.com"],
+ tls_sni_count: 1,
+ protocol_distribution: [
+ { protocol: "ip:tcp:tls", packet_count: 25 },
+ { protocol: "ip:udp:dns", packet_count: 5 },
+ ],
+ protocol_count: 2,
+ http_request_uris: ["http://example.com/api"],
+ http_request_uri_count: 1,
+ http_uri_redaction_count: 0,
+ unattributed_dns_addresses: [],
+ unattributed_dns_address_count: 0,
+ unattributed_dns_packet_count: 0,
+ coverage: "complete",
+ },
+ identity,
+ ),
+ );
+ },
+ };
+ const session = createTestBinarySession(() => {
+ throw new Error("deep provider must not start");
+ });
+ const server = createServer(
+ { kind: "session", session },
+ { pcapAnalysis: provider },
+ );
+ onTestFinished(() => server.close());
+ const [clientTransport, serverTransport] =
+ InMemoryTransport.createLinkedPair();
+ await server.connect(serverTransport);
+ const client = new Client({ name: "pcap-boundary", version: "0.0.0" });
+ onTestFinished(() => client.close());
+ await client.connect(clientTransport);
+
+ const { tools } = await client.listTools();
+ assertAdvertisedMcpContracts(
+ ["inspect_pcap_client", "inspect_pcap_capture"],
+ tools,
+ );
+
+ const inspected = await client.callTool({
+ name: "inspect_pcap_capture",
+ arguments: { path: "/captures/session.pcap" },
+ });
+ expect(inspected.isError).not.toBe(true);
+ const text = (inspected.content as { readonly text?: string }[])
+ .map((part) => part.text ?? "")
+ .join("");
+ const evidence = parseEvidence(JSON.parse(text));
+ expect(evidence.normalized_result).toMatchObject({
+ packet_count: 50,
+ tls_sni_values: ["example.com"],
+ coverage: "complete",
+ });
+});
diff --git a/tests/boundary/mcp/processComparisonDiagnosticsMcp.test.ts b/tests/boundary/mcp/processComparisonDiagnosticsMcp.test.ts
index 69fdc3944..bda4672de 100644
--- a/tests/boundary/mcp/processComparisonDiagnosticsMcp.test.ts
+++ b/tests/boundary/mcp/processComparisonDiagnosticsMcp.test.ts
@@ -252,6 +252,56 @@ it("reports CLI trace specification issues like the MCP trace_spec input", async
});
});
+it("rejects a deep trace cycle as an input error through CLI and MCP", async () => {
+ const events = Array.from({ length: 6000 }, (_, index) => ({
+ id: `e${String(index)}`,
+ source: "lifecycle",
+ exact: { marker: index },
+ }));
+ const trace = {
+ events,
+ language: {
+ kind: "partial_order",
+ happens_before: events.map((event, index) => ({
+ before: event.id,
+ after: events[(index + 1) % events.length]!.id,
+ })),
+ not_before: events.map((event, index) => ({
+ event: event.id,
+ anchor: events[(index + 1) % events.length]!.id,
+ })),
+ unordered_groups: [{ events: events.map(({ id }) => id) }],
+ },
+ };
+ const issue = {
+ path: ["trace_spec", "language"],
+ message: "happens-before graph must be acyclic",
+ };
+ const capture = captureEvidence("left");
+ const root = await createTestTempDirectory("rea-process-trace-cycle-");
+ const capturePath = join(root, "capture.json");
+ const specPath = join(root, "spec.json");
+ await writeFile(capturePath, JSON.stringify(capture));
+ await writeFile(specPath, JSON.stringify(trace));
+ expect(
+ await compareProcessEvidenceFiles(capturePath, capturePath, specPath),
+ ).toMatchObject({
+ code: "invalid_request",
+ details: { issues: [issue] },
+ });
+
+ const client = await connect();
+ const response = await client.callTool({
+ name: "compare_process_captures",
+ arguments: { left: capture, right: capture, trace_spec: trace },
+ });
+ expect(response.isError).toBe(true);
+ expect(response.content).toEqual([
+ { type: "text", text: expect.stringContaining(issue.message) },
+ ]);
+ await client.ping();
+});
+
it("names the side and constraint when Evidence is not a usable capture", async () => {
const client = await connect();
const capture = captureEvidence("right");
diff --git a/tests/boundary/mcp/reconstructionCoverageMcp.test.ts b/tests/boundary/mcp/reconstructionCoverageMcp.test.ts
index cb3605d14..1e167b8b0 100644
--- a/tests/boundary/mcp/reconstructionCoverageMcp.test.ts
+++ b/tests/boundary/mcp/reconstructionCoverageMcp.test.ts
@@ -3,7 +3,10 @@ import { ok as resultOk } from "../../../src/domain/result.js";
import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
import { describe, expect, it } from "vitest";
-import { completeReconstructionCoverageData } from "../../../src/domain/reconstructionCoverage.fixture.js";
+import {
+ completeReconstructionCoverageData,
+ reconstructionCoverageEvidenceId,
+} from "../../../src/domain/reconstructionCoverage.fixture.js";
import { createReconstructionCoverageData } from "../../../src/domain/reconstructionCoverage.js";
import { createTestBinarySession } from "../../fixtures/binarySession.js";
import { createServer } from "../../../src/server/createServer.js";
@@ -36,6 +39,42 @@ describe("reconstruction coverage MCP", () => {
boundary_id: boundaryId,
summary: { reasons: 0 },
});
+ const coverage = currentFixtureCoverage(boundaryId);
+ const latest = coverage.verifier_results[0];
+ if (latest === undefined)
+ throw new Error("Expected fixture verifier result");
+ const ambiguous = await client.callTool({
+ name: "evaluate_reconstruction_coverage",
+ arguments: {
+ coverage: createReconstructionCoverageData({
+ ...coverage,
+ verifier_results: [
+ latest,
+ {
+ ...latest,
+ status: "fail",
+ evidence_ids: [reconstructionCoverageEvidenceId("1")],
+ },
+ ],
+ }),
+ boundary_id: boundaryId,
+ },
+ });
+ expect(ambiguous.isError).not.toBe(true);
+ expect(ambiguous.structuredContent).toMatchObject({
+ status: "unknown",
+ boundary_id: boundaryId,
+ reasons: [
+ expect.objectContaining({
+ code: "verifier-result-ambiguous",
+ subject_id: "claim.cli.help",
+ }),
+ ],
+ evidence_ids: expect.arrayContaining([
+ reconstructionCoverageEvidenceId("3"),
+ reconstructionCoverageEvidenceId("1"),
+ ]),
+ });
const unknown = await client.callTool({
name: "evaluate_reconstruction_coverage",
arguments: {
diff --git a/tests/boundary/mcp/serverUnknownsMcp.test.ts b/tests/boundary/mcp/serverUnknownsMcp.test.ts
index 0a27324ec..e39ce2aec 100644
--- a/tests/boundary/mcp/serverUnknownsMcp.test.ts
+++ b/tests/boundary/mcp/serverUnknownsMcp.test.ts
@@ -281,7 +281,7 @@ it("pages filtered unknown heads through the public MCP contract", async () => {
supporting_evidence_ids: [],
contradicting_evidence_ids: [],
});
- expect(result.ok).toBe(true);
+ if (!result.ok) throw result.error;
}
const defaultPage = structured(
@@ -372,12 +372,11 @@ it("pages filtered unknown heads through the public MCP contract", async () => {
.result as typeof defaultPage;
expect(first).toMatchObject({ total: 3, offset: 0, next_offset: 2 });
expect(first.items).toHaveLength(2);
- const second = structured(
- await client.callTool({
- ...request,
- arguments: { ...request.arguments, offset: first.next_offset ?? 0 },
- }),
- ).result as typeof defaultPage;
+ const secondResponse = await client.callTool({
+ ...request,
+ arguments: { ...request.arguments, offset: first.next_offset ?? 0 },
+ });
+ const second = structured(secondResponse).result as typeof defaultPage;
expect(second).toMatchObject({ total: 3, offset: 2, next_offset: null });
expect(second.items).toHaveLength(1);
expect(
@@ -389,7 +388,7 @@ it("pages filtered unknown heads through the public MCP contract", async () => {
);
expect(
toolContract("list_unknowns").outputSchema.safeParse(
- (await client.callTool(request)).structuredContent,
+ secondResponse.structuredContent,
).success,
).toBe(true);
diff --git a/tests/boundary/mcp/wasmArtifactMcp.test.ts b/tests/boundary/mcp/wasmArtifactMcp.test.ts
index 49c7ad762..003a37cba 100644
--- a/tests/boundary/mcp/wasmArtifactMcp.test.ts
+++ b/tests/boundary/mcp/wasmArtifactMcp.test.ts
@@ -213,6 +213,31 @@ it("advertises exact valid schemas and records inline WASM interface evidence wi
expect(close).toHaveBeenCalled();
});
+it("rejects a WASM provider response with a non-file subject before recording Evidence", async () => {
+ const value = wasmArtifactFixture();
+ const execution = wasmArtifactExecution(value);
+ const malformed = {
+ ...execution,
+ subject: { ...execution.subject, format: "elf" },
+ } as unknown as typeof execution;
+ const harness = await createApplicationMcpHarness({
+ serverOptions: {
+ wasmArtifact: new WasmArtifactService({
+ close: () => Promise.resolve(),
+ inspect: () => Promise.resolve(ok(malformed)),
+ }),
+ },
+ });
+ onTestFinished(harness.close);
+ const before = harness.session.exportEvidenceBundle().records.length;
+ const response = await harness.client.callTool({
+ name: "inspect_wasm_artifact",
+ arguments: { path: value.artifact.path },
+ });
+ expect(parseMcpToolError(response).error.code).toBe("unreadable_output");
+ expect(harness.session.exportEvidenceBundle().records).toHaveLength(before);
+});
+
it("reads an oversized completed WASM result through its reported retained reference", async () => {
const text = "(module)\n" + ";;😀\n" + " ".repeat(6 * 1024 * 1024);
const value = {
diff --git a/tests/boundary/pcap/pcapCommand.test.ts b/tests/boundary/pcap/pcapCommand.test.ts
new file mode 100644
index 000000000..cda8dbf77
--- /dev/null
+++ b/tests/boundary/pcap/pcapCommand.test.ts
@@ -0,0 +1,53 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { expect, it, onTestFinished, vi } from "vitest";
+import { runPcapCommand } from "../../../src/pcap/PcapCommand.js";
+import * as ownership from "../../../src/process/ProcessOwnershipObservation.js";
+
+it("does not spend the tool execution deadline preparing native ownership", async () => {
+ const original = ownership.prepareProcessOwnershipInspection;
+ let entered!: () => void;
+ let release!: () => void;
+ const preparing = new Promise((resolve) => {
+ entered = resolve;
+ });
+ const gate = new Promise((resolve) => {
+ release = resolve;
+ });
+ let first = true;
+ const prepare = vi
+ .spyOn(ownership, "prepareProcessOwnershipInspection")
+ .mockImplementation(async (signal) => {
+ await original(signal);
+ if (first) {
+ first = false;
+ entered();
+ await gate;
+ }
+ });
+ onTestFinished(() => {
+ prepare.mockRestore();
+ release();
+ });
+ const pending = runPcapCommand({
+ operation: "inspect_pcap_client",
+ command: process.execPath,
+ arguments: ["--version"],
+ limits: { timeoutMs: 1000, maxOutputBytes: 1024 },
+ environment: {},
+ signal: undefined,
+ retain: (owner) => {
+ onTestFinished(async () => {
+ expect((await owner.stop()).status).not.toBe("incomplete");
+ });
+ },
+ }).then(
+ (value) => ({ ok: true as const, value }),
+ (error: unknown) => ({ ok: false as const, error }),
+ );
+ await preparing;
+ await delay(1100);
+ release();
+ const result = await pending;
+ if (!result.ok) throw result.error;
+ expect(result.value.stdout.trim()).toBe(process.version);
+});
diff --git a/tests/boundary/pcap/pcapProvider.test.ts b/tests/boundary/pcap/pcapProvider.test.ts
new file mode 100644
index 000000000..fcb299ade
--- /dev/null
+++ b/tests/boundary/pcap/pcapProvider.test.ts
@@ -0,0 +1,533 @@
+import { createHash } from "node:crypto";
+import { watch } from "node:fs";
+import { chmod, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { expect, onTestFinished, test, vi } from "vitest";
+
+import { PcapProvider } from "../../../src/pcap/PcapProvider.js";
+import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";
+import {
+ pcapResultSchemas,
+ type PcapRequest,
+} from "../../../src/domain/pcap/pcapAnalysis.js";
+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+import { holdFirstFileRead } from "../../support/holdFirstFileRead.js";
+import { PrivateRuntimeRoot } from "../../../src/process/PrivateRuntimeRoot.js";
+
+const it = test.skipIf(process.platform !== "linux");
+
+const CAPINFOS_OUTPUT = [
+ "File name: /work/capture.pcap",
+ "File type: Wireshark/tcpdump/... - pcap",
+ "File encapsulation: Ethernet",
+ "Packet size limit: file hdr: 262144 bytes",
+ "Number of packets: 3",
+ "Capture duration: 0.123 seconds",
+].join("\n");
+
+const TSHARK_JSON = JSON.stringify([
+ {
+ _source: {
+ layers: {
+ "frame.number": ["1"],
+ "frame.protocols": ["eth:ethertype:ip:udp:dns"],
+ "ip.src": ["192.168.1.100"],
+ "ip.dst": ["8.8.8.8"],
+ "dns.qry.name": ["api.example.com"],
+ "dns.flags.response": ["1"],
+ "dns.a": ["93.184.216.34"],
+ },
+ },
+ },
+ {
+ _source: {
+ layers: {
+ "frame.number": ["2"],
+ "frame.protocols": ["eth:ethertype:ip:tcp:tls"],
+ "ip.src": ["192.168.1.100"],
+ "ip.dst": ["93.184.216.34"],
+ "tls.handshake.extensions_server_name": ["api.example.com"],
+ },
+ },
+ },
+ {
+ _source: {
+ layers: {
+ "frame.number": ["3"],
+ "frame.protocols": ["eth:ethertype:ip:tcp:http"],
+ "ip.src": ["192.168.1.100"],
+ "ip.dst": ["93.184.216.34"],
+ "http.request.full_uri": ["http://api.example.com/v1/data"],
+ },
+ },
+ },
+]);
+
+const writeStubTools = async (
+ root: string,
+ options: { readonly failCapinfos?: boolean } = {},
+): Promise<{ tshark: string; capinfos: string }> => {
+ const tshark = join(root, "tshark");
+ const capinfos = join(root, "capinfos");
+ await writeFile(
+ tshark,
+ `#!/bin/sh
+if [ "$1" = "--version" ]; then printf 'TShark (Wireshark) 4.6.6-stub\\n'; exit 0; fi
+[ "$1" = "-n" ] && [ "$2" = "-r" ] && [ "$4" = "-T" ] && [ "$5" = "json" ] || exit 2
+printf '%s' '${TSHARK_JSON.replace(/'/gu, "'\\''")}'
+exit 0
+`,
+ { mode: 0o755 },
+ );
+ await writeFile(
+ capinfos,
+ `#!/bin/sh
+if [ "$1" = "--version" ]; then printf 'Capinfos (Wireshark) 4.6.6-stub\\n'; exit 0; fi
+[ "$1" = "-M" ] && [ "$2" = "--" ] && [ "$#" = "3" ] || exit 2
+if [ "${String(options.failCapinfos === true)}" = "true" ]; then
+ printf 'capinfos: The file is not a capture file' >&2; exit 1
+fi
+printf '%s\\n' '${CAPINFOS_OUTPUT.replace(/'/gu, "'\\''")}'
+exit 0
+`,
+ { mode: 0o755 },
+ );
+ await chmod(tshark, 0o755);
+ await chmod(capinfos, 0o755);
+ return { tshark, capinfos };
+};
+
+const providerWith = async (options: { failCapinfos?: boolean } = {}) => {
+ const root = await createTestTempDirectory("rea-pcap-");
+ const { tshark, capinfos } = await writeStubTools(root, options);
+ const provider = new PcapProvider({
+ environment: { REA_TSHARK_COMMAND: tshark, REA_CAPINFOS_COMMAND: capinfos },
+ });
+ onTestFinished(() => provider.close());
+ return {
+ provider,
+ root,
+ };
+};
+
+const evidenceResult = async (
+ provider: PcapProvider,
+ request: PcapRequest,
+): Promise> => {
+ const result = await provider.execute(request);
+ if (!result.ok) throw new Error(result.error.message);
+ return pcapResultSchemas[request.operation].parse(result.value.result);
+};
+
+const captureFixture = async (root: string): Promise => {
+ const path = join(root, "capture.pcap");
+ await writeFile(path, Buffer.from("pcap-fixture-bytes"));
+ return path;
+};
+
+it("inspects both tools without reading a capture", async () => {
+ const { provider } = await providerWith();
+ const result = await evidenceResult(provider, {
+ operation: "inspect_pcap_client",
+ input: {},
+ });
+ expect(result.client).toMatchObject({
+ tshark_source: "environment",
+ tshark_version: "TShark (Wireshark) 4.6.6-stub",
+ capinfos_source: "environment",
+ capinfos_version: "Capinfos (Wireshark) 4.6.6-stub",
+ });
+});
+
+it("inspects a capture with endpoints, DNS, TLS SNI, and HTTP", async () => {
+ const { provider, root } = await providerWith();
+ const path = await captureFixture(root);
+ const result = await evidenceResult(provider, {
+ operation: "inspect_pcap_capture",
+ input: { path },
+ });
+ expect(result.target).toMatchObject({
+ path,
+ bytes: 18,
+ sha256: createHash("sha256").update("pcap-fixture-bytes").digest("hex"),
+ });
+ expect(result.file_type).toBe("Wireshark/tcpdump/... - pcap");
+ expect(result.packet_count).toBe(3);
+ expect(result.endpoints).toEqual(
+ expect.arrayContaining([
+ { address: "192.168.1.100", port: null, packet_count: 3 },
+ { address: "8.8.8.8", port: null, packet_count: 1 },
+ ]),
+ );
+ expect(result.dns_queries).toEqual([
+ {
+ query: "api.example.com",
+ response_addresses: ["93.184.216.34"],
+ response_address_count: 1,
+ },
+ ]);
+ expect(result.tls_sni_values).toEqual(["api.example.com"]);
+ expect(result.http_request_uris).toEqual(["http://api.example.com/v1/data"]);
+ expect(result.coverage).toBe("complete");
+});
+
+it("reports a non-capture file as unsupported", async () => {
+ const { provider, root } = await providerWith({ failCapinfos: true });
+ const failPath = join(root, "fail.pcap");
+ await writeFile(failPath, "not a capture file");
+ const result = await provider.execute({
+ operation: "inspect_pcap_capture",
+ input: { path: failPath },
+ });
+ expect(result.ok).toBe(false);
+ if (result.ok) return;
+ expect(projectAnalysisError(result.error)).toMatchObject({
+ code: "unsupported_target",
+ });
+});
+
+it("reports a missing tshark binary as a capability gap", async () => {
+ const provider = new PcapProvider({
+ environment: { REA_TSHARK_COMMAND: "/nonexistent/tshark" },
+ });
+ expect(await provider.inspectAvailability()).toMatchObject({
+ status: "unavailable",
+ code: "executable_missing",
+ });
+});
+
+it("rejects a capture that is not a readable file", async () => {
+ const { provider } = await providerWith();
+ const result = await provider.execute({
+ operation: "inspect_pcap_capture",
+ input: { path: "/nonexistent/capture.pcap" },
+ });
+ expect(result.ok).toBe(false);
+ if (result.ok) return;
+ expect(projectAnalysisError(result.error)).toMatchObject({
+ code: "invalid_request",
+ });
+});
+
+it("cancels before spawning anything", async () => {
+ const { provider, root } = await providerWith();
+ await writeFile(join(root, "spawned"), "");
+ const controller = new AbortController();
+ controller.abort();
+ const result = await provider.execute(
+ {
+ operation: "inspect_pcap_capture",
+ input: { path: "/some/capture.pcap" },
+ },
+ { signal: controller.signal },
+ );
+ expect(result.ok).toBe(false);
+ if (result.ok) return;
+ expect(projectAnalysisError(result.error)).toMatchObject({
+ code: "cancelled",
+ });
+});
+
+it("reports relative configuration and missing capinfos as capability gaps", async () => {
+ const root = await createTestTempDirectory("rea-pcap-config-");
+ const { tshark } = await writeStubTools(root);
+ for (const environment of [
+ { REA_TSHARK_COMMAND: "relative/tshark" },
+ {
+ REA_TSHARK_COMMAND: tshark,
+ REA_CAPINFOS_COMMAND: join(root, "missing-capinfos"),
+ },
+ ]) {
+ const provider = new PcapProvider({ environment });
+ onTestFinished(() => provider.close());
+ expect((await provider.inspectAvailability()).status).toBe("unavailable");
+ const result = await provider.execute({
+ operation: "inspect_pcap_client",
+ input: {},
+ });
+ if (result.ok) throw new Error("expected unavailable tools");
+ const projected = projectAnalysisError(result.error);
+ expect(projected.code).toBe("capability_unavailable");
+ expect(projected.message).toContain(
+ "Supply Wireshark 4.x tshark and capinfos",
+ );
+ }
+});
+
+it("names the prlimit selection when the Linux limiter is unusable", async () => {
+ const root = await createTestTempDirectory("rea-pcap-prlimit-");
+ const tools = await writeStubTools(root);
+ const provider = new PcapProvider({
+ environment: {
+ REA_TSHARK_COMMAND: tools.tshark,
+ REA_CAPINFOS_COMMAND: tools.capinfos,
+ REA_TSHARK_PRLIMIT_COMMAND: "relative/prlimit",
+ },
+ });
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({
+ operation: "inspect_pcap_capture",
+ input: { path: "/not-opened/capture.pcap" },
+ });
+ if (result.ok) throw new Error("expected an unusable limiter");
+ const projected = projectAnalysisError(result.error);
+ expect(projected.code).toBe("capability_unavailable");
+ expect(projected.message).toContain(
+ "(REA_TSHARK_PRLIMIT_COMMAND must be absolute.) Check that REA_TSHARK_PRLIMIT_COMMAND",
+ );
+});
+
+const nodeTool = async (
+ root: string,
+ name: string,
+ body: string,
+): Promise => {
+ const path = join(root, name);
+ await writeFile(
+ path,
+ `#!/usr/bin/env -S ${process.execPath} --jitless --max-old-space-size=64\nconst fs = require('node:fs'); const crypto = require('node:crypto');\n${body}\n`,
+ { mode: 0o755 },
+ );
+ return path;
+};
+const versionProbe =
+ "if (process.argv[2] === '--version') { console.log((process.argv[1].includes('capinfos') ? 'Capinfos' : 'TShark') + ' (Wireshark) 4.6.6-test'); process.exit(0); }";
+
+it("refuses observations whose owned snapshot changed during dissection", async () => {
+ const root = await createTestTempDirectory("rea-pcap-mutated-");
+ const { capinfos } = await writeStubTools(root);
+ const path = await captureFixture(root);
+ const before = await readFile(path);
+ const tshark = await nodeTool(
+ root,
+ "tshark.cjs",
+ `${versionProbe}
+const selected = process.argv[process.argv.indexOf('-r') + 1];
+fs.chmodSync(selected, 0o600); fs.writeFileSync(selected, 'changed private snapshot');
+console.log(${JSON.stringify(TSHARK_JSON)});`,
+ );
+ const provider = new PcapProvider({
+ environment: { REA_TSHARK_COMMAND: tshark, REA_CAPINFOS_COMMAND: capinfos },
+ });
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({
+ operation: "inspect_pcap_capture",
+ input: { path },
+ });
+ expect(result.ok).toBe(false);
+ if (!result.ok)
+ expect(projectAnalysisError(result.error)).toMatchObject({
+ code: "artifact_changed",
+ });
+ expect(await readFile(path)).toEqual(before);
+});
+
+it("binds both tools to the snapshot when the original capture changes", async () => {
+ const root = await createTestTempDirectory("rea-pcap-identity-");
+ const path = join(root, "caller capture.pcap");
+ await writeFile(path, "192.0.2.1");
+ const capinfos = await nodeTool(
+ root,
+ "capinfos.cjs",
+ `${versionProbe}
+const selected = process.argv.at(-1); const bytes = fs.readFileSync(selected);
+console.log('File type: pcap\\nFile encapsulation: Raw IP\\nNumber of packets: 1\\nSHA256: ' + crypto.createHash('sha256').update(bytes).digest('hex'));
+fs.writeFileSync(${JSON.stringify(path)}, '192.0.2.2');`,
+ );
+ const tshark = await nodeTool(
+ root,
+ "tshark.cjs",
+ `${versionProbe}
+const selected = process.argv[process.argv.indexOf('-r') + 1];
+console.log(JSON.stringify([{_source:{layers:{'frame.number':['1'],'frame.protocols':['ip'],'ip.src':[fs.readFileSync(selected,'utf8')]}}}]));`,
+ );
+ const provider = new PcapProvider({
+ environment: { REA_TSHARK_COMMAND: tshark, REA_CAPINFOS_COMMAND: capinfos },
+ });
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({
+ operation: "inspect_pcap_capture",
+ input: { path },
+ });
+ if (!result.ok) throw result.error;
+ const value = pcapResultSchemas.inspect_pcap_capture.parse(
+ result.value.result,
+ );
+ expect(value.target.sha256).toBe(
+ createHash("sha256").update("192.0.2.1").digest("hex"),
+ );
+ expect(value.endpoints).toEqual([
+ { address: "192.0.2.1", port: null, packet_count: 1 },
+ ]);
+ expect(await readFile(path, "utf8")).toBe("192.0.2.2");
+});
+
+it.each(["probe", "capinfos", "tshark"] as const)(
+ "preserves in-flight %s cancellation and cleans up",
+ async (phase) => {
+ const root = await createTestTempDirectory("rea-pcap-cancel-");
+ const marker = join(root, "ready");
+ const slow = await nodeTool(
+ root,
+ `slow-${phase}.cjs`,
+ `${phase !== "probe" ? versionProbe : ""}
+fs.writeFileSync(${JSON.stringify(marker)}, 'ready'); setInterval(() => {}, 1000);`,
+ );
+ const { capinfos, tshark } = await writeStubTools(root);
+ const path = await captureFixture(root);
+ const provider = new PcapProvider({
+ environment: {
+ REA_TSHARK_COMMAND: phase === "capinfos" ? tshark : slow,
+ REA_CAPINFOS_COMMAND: phase === "capinfos" ? slow : capinfos,
+ },
+ });
+ onTestFinished(() => provider.close());
+ const controller = new AbortController();
+ let watcher: ReturnType | undefined;
+ let timer: ReturnType | undefined;
+ const ready = new Promise((resolve, reject) => {
+ watcher = watch(root, (_event, name) => {
+ if (name === "ready") resolve();
+ });
+ timer = setTimeout(() => {
+ controller.abort();
+ reject(new Error("tool did not start"));
+ }, 5000);
+ });
+ try {
+ const pending = provider.execute(
+ { operation: "inspect_pcap_capture", input: { path } },
+ { signal: controller.signal },
+ );
+ await ready;
+ controller.abort(new Error("caller cancellation"));
+ const result = await pending;
+ if (result.ok) throw new Error("expected cancellation");
+ expect(projectAnalysisError(result.error).code).toBe("cancelled");
+ await provider.close();
+ } finally {
+ watcher?.close();
+ clearTimeout(timer);
+ }
+ },
+);
+
+it.each(["change", "cancel"] as const)(
+ "preserves %s during snapshot acquisition",
+ async (action) => {
+ const { provider, root } = await providerWith();
+ const path = await captureFixture(root);
+ const controller = new AbortController();
+ const held = await holdFirstFileRead(path);
+ onTestFinished(() => {
+ vi.restoreAllMocks();
+ });
+ const pending = provider.execute(
+ { operation: "inspect_pcap_capture", input: { path } },
+ { signal: controller.signal },
+ );
+ try {
+ await held.firstRead;
+ if (action === "cancel") controller.abort();
+ else await writeFile(path, "changed source bytes");
+ } finally {
+ held.release();
+ }
+ const result = await pending;
+ if (result.ok) throw new Error("expected interrupted acquisition");
+ expect(result.error._tag).toBe(
+ action === "cancel"
+ ? "AnalysisCancelledError"
+ : "AnalysisArtifactChangedError",
+ );
+ },
+);
+
+it("admits one capture and drains it before close releases resources", async () => {
+ const { provider, root } = await providerWith();
+ const path = await captureFixture(root);
+ const held = await holdFirstFileRead(path);
+ onTestFinished(() => {
+ vi.restoreAllMocks();
+ });
+ const pending = provider.execute({
+ operation: "inspect_pcap_capture",
+ input: { path },
+ });
+ let closing: Promise | undefined;
+ try {
+ await held.firstRead;
+ const concurrent = await provider.execute({
+ operation: "inspect_pcap_capture",
+ input: { path },
+ });
+ expect(concurrent.ok).toBe(false);
+ if (!concurrent.ok)
+ expect(projectAnalysisError(concurrent.error)).toMatchObject({
+ code: "resource_constraint",
+ details: { resource: "capacity" },
+ });
+ let closed = false;
+ closing = provider.close().then(() => {
+ closed = true;
+ });
+ await Promise.resolve();
+ expect(closed).toBe(false);
+ } finally {
+ held.release();
+ }
+ expect((await pending).ok).toBe(true);
+ await closing;
+ const afterClose = await provider.execute({
+ operation: "inspect_pcap_capture",
+ input: { path },
+ });
+ expect(afterClose.ok).toBe(false);
+});
+
+it.each([false, true])(
+ "retains failed snapshot cleanup after an analysis failure=%s",
+ async (failCapinfos) => {
+ const { provider, root } = await providerWith({ failCapinfos });
+ const path = await captureFixture(root);
+ let retained: PrivateRuntimeRoot | undefined;
+ const spy = vi
+ .spyOn(PrivateRuntimeRoot.prototype, "close")
+ .mockImplementation(function (this: PrivateRuntimeRoot) {
+ retained = this;
+ return Promise.reject(new Error("controlled cleanup failure"));
+ });
+ const result = await provider.execute({
+ operation: "inspect_pcap_capture",
+ input: { path },
+ });
+ try {
+ expect(result.ok).toBe(false);
+ if (result.ok) throw new Error("Cleanup failure cannot return success");
+ expect(projectAnalysisError(result.error)).toMatchObject({
+ code: "cleanup_incomplete",
+ });
+ if (failCapinfos)
+ expect(projectAnalysisError(result.error)).toMatchObject({
+ details: {
+ diagnostics: { primary_error: { code: "unsupported_target" } },
+ },
+ });
+ else
+ expect(result.error.partialObservation).toMatchObject({
+ operation: "inspect_pcap_capture",
+ normalized_result: { packet_count: 3 },
+ });
+ expect(retained).toBeDefined();
+ await expect(provider.close()).rejects.toMatchObject({
+ cleanupIncomplete: true,
+ });
+ } finally {
+ spy.mockRestore();
+ }
+ await provider.close();
+ await expect(
+ readFile(join(retained!.path, "capture.pcap")),
+ ).rejects.toMatchObject({ code: "ENOENT" });
+ },
+);
diff --git a/tests/boundary/pcap/pcapProviderCrossPlatform.test.ts b/tests/boundary/pcap/pcapProviderCrossPlatform.test.ts
new file mode 100644
index 000000000..c19e682fe
--- /dev/null
+++ b/tests/boundary/pcap/pcapProviderCrossPlatform.test.ts
@@ -0,0 +1,153 @@
+/**
+ * Cross-platform pcap provider tests.
+ *
+ * POSIX hosts run the #!/bin/sh fixtures;
+ * Windows runs the .cmd stubs from tests/fixtures/pcap/. Both validate
+ * the same provider contract surface: tool probing, capture inspection,
+ * refusal paths, and cancellation before spawn.
+ */
+import { createHash } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { expect, it, onTestFinished } from "vitest";
+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+
+import { PcapProvider } from "../../../src/pcap/PcapProvider.js";
+import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";
+import type { PcapRequest } from "../../../src/domain/pcap/pcapAnalysis.js";
+
+const isWindows = process.platform === "win32";
+const hasNativeBound = process.platform === "linux" || isWindows;
+const stubDir = join(import.meta.dirname, "../../fixtures/pcap");
+const tsharkStub = isWindows
+ ? join(stubDir, "tshark-stub.cmd")
+ : join(stubDir, "tshark-stub.sh");
+const capinfosStub = isWindows
+ ? join(stubDir, "capinfos-stub.cmd")
+ : join(stubDir, "capinfos-stub.sh");
+
+const providerOver = (): PcapProvider => {
+ const provider = new PcapProvider({
+ environment: {
+ REA_TSHARK_COMMAND: tsharkStub,
+ REA_CAPINFOS_COMMAND: capinfosStub,
+ },
+ });
+ onTestFinished(() => provider.close());
+ return provider;
+};
+
+const evidenceResult = async (
+ provider: PcapProvider,
+ request: PcapRequest,
+): Promise> => {
+ const result = await provider.execute(request);
+ if (!result.ok) throw new Error(result.error.message);
+ return result.value.result as Record;
+};
+
+it("inspects both tools through cross-platform stubs", async () => {
+ const result = await evidenceResult(providerOver(), {
+ operation: "inspect_pcap_client",
+ input: {},
+ });
+ expect(result.client).toMatchObject({
+ tshark_source: "environment",
+ tshark_version: expect.stringContaining("4.6.6") as unknown,
+ capinfos_source: "environment",
+ capinfos_version: expect.stringContaining("4.6.6") as unknown,
+ });
+});
+
+it.runIf(hasNativeBound)(
+ "inspects a capture with metadata, endpoints, DNS, and protocol facts",
+ async () => {
+ const root = await createTestTempDirectory("rea-pcap-x-");
+ const capturePath = join(root, "capture.pcap");
+ const captureBytes = "cross-platform-pcap-fixture";
+ await writeFile(capturePath, captureBytes);
+
+ const result = await evidenceResult(providerOver(), {
+ operation: "inspect_pcap_capture",
+ input: { path: capturePath },
+ });
+
+ expect(result.target).toMatchObject({
+ path: capturePath,
+ bytes: captureBytes.length,
+ sha256: createHash("sha256").update(captureBytes).digest("hex"),
+ });
+ expect(result.file_type).toContain("pcap");
+ expect(result.packet_count).toBe(3);
+ expect((result.endpoints as unknown[]).length).toBeGreaterThan(0);
+ expect((result.protocol_distribution as unknown[]).length).toBeGreaterThan(
+ 0,
+ );
+ expect(result.coverage).toBe("complete");
+ },
+);
+
+// Hosts without a native bound refuse before touching the path; that order
+// is pinned by the unsupported-boundary test below.
+it.runIf(hasNativeBound)(
+ "rejects a path that is not a readable file",
+ async () => {
+ const result = await providerOver().execute({
+ operation: "inspect_pcap_capture",
+ input: { path: "/nonexistent/definitely-missing.pcap" },
+ });
+ expect(result.ok).toBe(false);
+ if (result.ok) return;
+ expect(projectAnalysisError(result.error)).toMatchObject({
+ code: "invalid_request",
+ });
+ },
+);
+
+it("reports a missing binary as a capability gap", async () => {
+ const provider = new PcapProvider({
+ environment: { REA_TSHARK_COMMAND: "/nonexistent/tshark" },
+ });
+ expect(await provider.inspectAvailability()).toMatchObject({
+ status: "unavailable",
+ code: "executable_missing",
+ });
+});
+
+it("cancels before spawning anything", async () => {
+ const controller = new AbortController();
+ controller.abort();
+ const result = await providerOver().execute(
+ { operation: "inspect_pcap_capture", input: { path: "/any/capture.pcap" } },
+ { signal: controller.signal },
+ );
+ expect(result.ok).toBe(false);
+ if (result.ok) return;
+ expect(projectAnalysisError(result.error)).toMatchObject({
+ code: "cancelled",
+ });
+});
+
+it.runIf(!hasNativeBound)(
+ "reports an unsupported native memory boundary before reading the capture",
+ async () => {
+ const provider = providerOver();
+ expect(await provider.inspectAvailability()).toMatchObject({
+ status: "unavailable",
+ code: "unsupported_host",
+ });
+ const result = await provider.execute({
+ operation: "inspect_pcap_capture",
+ input: { path: "/not-opened/capture.pcap" },
+ });
+ expect(result.ok).toBe(false);
+ if (result.ok) return;
+ const projected = projectAnalysisError(result.error);
+ expect(projected.code).toBe("capability_unavailable");
+ // The refusal concerns this host, so it must not suggest another target.
+ expect(projected.message).toContain(
+ "Linux with util-linux prlimit, or Windows with owned Job Objects",
+ );
+ expect(projected.remediation.action).toBe(projected.message);
+ },
+);
diff --git a/tests/boundary/pcap/pcapRetainedView.test.ts b/tests/boundary/pcap/pcapRetainedView.test.ts
new file mode 100644
index 000000000..a3f890a37
--- /dev/null
+++ b/tests/boundary/pcap/pcapRetainedView.test.ts
@@ -0,0 +1,196 @@
+import { createHash } from "node:crypto";
+import { readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { expect, it } from "vitest";
+import { parseEvidence } from "../../../src/domain/evidence.js";
+import { connectLocalToolsMcp } from "../../fixtures/localToolsMcp.js";
+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+import { parseMcpToolError } from "../../fixtures/mcpToolError.js";
+
+const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;
+
+const createPcapToolFixture = async (root: string) => {
+ const path = join(root, "caller capture.pcap");
+ const bytes = Buffer.from("recording fixture bytes");
+ const sha = createHash("sha256").update(bytes).digest("hex");
+ await writeFile(path, bytes);
+ const tshark = join(root, "tshark");
+ const capinfos = join(root, "capinfos");
+ const marker = join(root, "reads");
+ const frames = Array.from({ length: 132 }, (_, index) => ({
+ _source: {
+ layers: {
+ "frame.number": [String(index + 1)],
+ "frame.protocols": ["ip:udp:dns"],
+ "ip.src": ["192.0.2.1"],
+ "ip.dst": ["192.0.2.2"],
+ "dns.qry.name": ["many.example"],
+ "dns.flags.response": ["True"],
+ "dns.a": [`198.51.100.${index}`],
+ "tls.handshake.extensions_server_name": [`host${index}.example`],
+ "http.request.full_uri": [
+ "http://user:password@example.invalid/p?q=keep",
+ ],
+ },
+ },
+ }));
+ await writeFile(
+ tshark,
+ `#!/bin/sh\nif [ "$1" = "--version" ]; then printf 'TShark (Wireshark) 4.6.6-emulated\\n'; exit 0; fi\nprintf 'read\\n' >> ${quote(marker)}\nprintf '%s' ${quote(JSON.stringify(frames))}\nprintf 'retained warning' >&2\n`,
+ { mode: 0o755 },
+ );
+ await writeFile(
+ capinfos,
+ `#!/bin/sh\nif [ "$1" = "--version" ]; then printf 'Capinfos (Wireshark) 4.6.6-emulated\\n'; exit 0; fi\nprintf '%s\\n' ${quote(`File type: pcap\nFile encapsulation: Ethernet\nNumber of packets: 132\nSHA256: ${sha}`)}\n`,
+ { mode: 0o755 },
+ );
+ const environment = {
+ REA_TSHARK_COMMAND: tshark,
+ REA_CAPINFOS_COMMAND: capinfos,
+ };
+ return { path, marker, environment };
+};
+
+// Native tools are emulated here; this proves the production CLI/MCP boundary,
+// retention and paging, not Wireshark's real dissector semantics.
+it.runIf(process.platform === "linux")(
+ "retains every fact and pages late DNS/SNI rows after source deletion without another tool launch",
+ async () => {
+ const root = await createTestTempDirectory("rea-pcap-view-");
+ const { path, marker, environment } = await createPcapToolFixture(root);
+ const complete = await promisify(execFile)(
+ process.execPath,
+ [
+ join(import.meta.dirname, "../../../scripts/rea.mjs"),
+ "inspect-pcap-capture",
+ path,
+ "--json",
+ ],
+ { env: { ...process.env, ...environment } },
+ );
+ const parent = parseEvidence(JSON.parse(complete.stdout));
+ expect(parent.normalized_result).toMatchObject({
+ tls_sni_count: 132,
+ tls_sni_values: expect.arrayContaining(["host131.example"]),
+ dns_queries: [{ query: "many.example", response_address_count: 132 }],
+ });
+ expect(JSON.stringify(parent)).not.toContain("user:password");
+ const { call } = await connectLocalToolsMcp(environment);
+ const response = await call("inspect_pcap_capture", {
+ path,
+ detail: "summary",
+ });
+ expect(response.isError, JSON.stringify(response)).not.toBe(true);
+ const summary = parseEvidence(response.structuredContent).normalized_result;
+ expect(summary).toMatchObject({
+ parent_evidence_id: parent.evidence_id,
+ summary: {
+ tls_sni_count: 132,
+ dns_query_count: 1,
+ retained_counts: { tls_sni_values: 132 },
+ diagnostics_code_units: { tshark: 16, capinfos: 0 },
+ },
+ });
+ expect(JSON.stringify(summary)).not.toContain("host131.example");
+ await rm(path);
+ const source = {
+ kind: "retained-evidence",
+ evidence_id: parent.evidence_id,
+ };
+ const before = await readFile(marker, "utf8");
+ const cases = [
+ [
+ { kind: "pcap", facet: "endpoints", limit: 1 },
+ { items: [{ address: "192.0.2.1", packet_count: 132 }] },
+ ],
+ [
+ { kind: "pcap", facet: "dns-queries", limit: 1 },
+ {
+ items: [
+ { query: "many.example", retained_response_address_count: 132 },
+ ],
+ },
+ ],
+ [
+ {
+ kind: "pcap",
+ facet: "dns-addresses",
+ query: "many.example",
+ offset: 130,
+ limit: 2,
+ },
+ { items: ["198.51.100.130", "198.51.100.131"] },
+ ],
+ [
+ { kind: "pcap", facet: "tls-sni", offset: 130, limit: 2 },
+ { items: ["host130.example", "host131.example"] },
+ ],
+ [
+ { kind: "pcap", facet: "protocols" },
+ { items: [{ protocol: "ip:udp:dns", packet_count: 132 }] },
+ ],
+ [
+ { kind: "pcap", facet: "http-uris" },
+ { items: ["http://example.invalid/p?q=keep"] },
+ ],
+ [{ kind: "pcap", facet: "unattributed-addresses" }, { items: [] }],
+ [
+ {
+ kind: "pcap",
+ facet: "diagnostics",
+ stream: "tshark",
+ offset: 9,
+ limit: 7,
+ },
+ { text: "warning", status: "retained" },
+ ],
+ ] as const;
+ for (const [view, expected] of cases) {
+ const response = await call("inspect_analysis_view", { source, view });
+ expect(response.isError, JSON.stringify(response)).not.toBe(true);
+ expect(
+ parseEvidence(response.structuredContent).normalized_result,
+ ).toMatchObject({ page: expected, source_coverage: "complete" });
+ }
+ const workflow = join(root, "portable.json");
+ const view = {
+ kind: "pcap",
+ facet: "dns-addresses",
+ query: "many.example",
+ offset: 130,
+ limit: 2,
+ };
+ await writeFile(
+ workflow,
+ JSON.stringify({ source: { kind: "inline", evidence: parent }, view }),
+ );
+ const portable = await promisify(execFile)(process.execPath, [
+ join(import.meta.dirname, "../../../scripts/rea.mjs"),
+ "inspect-analysis-view",
+ workflow,
+ "--json",
+ ]);
+ const retained = parseEvidence(
+ (await call("inspect_analysis_view", { source, view })).structuredContent,
+ );
+ expect(
+ parseEvidence(JSON.parse(portable.stdout)).normalized_result,
+ ).toEqual(retained.normalized_result);
+ expect(await readFile(marker, "utf8")).toBe(before);
+ expect(
+ parseMcpToolError(
+ await call("inspect_analysis_view", {
+ source,
+ view: {
+ kind: "pcap",
+ facet: "dns-addresses",
+ query: "missing.example",
+ },
+ }),
+ ),
+ ).toMatchObject({ error: { code: "invalid_request" } });
+ },
+ 60_000,
+);
diff --git a/tests/boundary/process/darwinProcessRunTokenReader.test.ts b/tests/boundary/process/darwinProcessRunTokenReader.test.ts
index bfdb047f2..9f377440c 100644
--- a/tests/boundary/process/darwinProcessRunTokenReader.test.ts
+++ b/tests/boundary/process/darwinProcessRunTokenReader.test.ts
@@ -26,6 +26,7 @@ import {
import {
createDarwinProcessRunTokenReader,
DarwinProcessOwnershipInspectionError,
+ SWIFTC_INTERRUPT,
} from "../../../src/process/DarwinProcessRunTokenReader.js";
import { execFileOutput } from "../../../src/process/ExecFileOutput.js";
import {
@@ -1110,16 +1111,8 @@ it.skipIf(!onDarwin)(
try {
await execFileOutput(
"/usr/bin/xcrun",
- [
- "swiftc",
- "-module-cache-path",
- join(root, "modules"),
- core,
- fixture,
- "-o",
- executable,
- ],
- { timeout: 60_000 },
+ ["swiftc", core, fixture, "-o", executable],
+ { timeout: 120_000, stopSignal: SWIFTC_INTERRUPT },
);
const { stdout } = await execFileAsync(executable, [], {
encoding: "utf8",
@@ -1179,6 +1172,7 @@ it.skipIf(!onDarwin)(
await rm(root, { recursive: true, force: true });
}
},
+ 150_000,
);
it.skipIf(!onDarwin)(
@@ -1203,16 +1197,8 @@ it.skipIf(!onDarwin)(
try {
await execFileOutput(
"/usr/bin/xcrun",
- [
- "swiftc",
- "-module-cache-path",
- join(root, "modules"),
- core,
- fixture,
- "-o",
- executable,
- ],
- { timeout: 60_000 },
+ ["swiftc", core, fixture, "-o", executable],
+ { timeout: 120_000, stopSignal: SWIFTC_INTERRUPT },
);
const { stdout } = await execFileAsync(executable, [], {
encoding: "utf8",
@@ -1226,6 +1212,7 @@ it.skipIf(!onDarwin)(
await rm(root, { recursive: true, force: true });
}
},
+ 150_000,
);
it.skipIf(!onDarwin)(
diff --git a/tests/boundary/process/sourceMapUncHosts.test.ts b/tests/boundary/process/sourceMapUncHosts.test.ts
index 293a3f71a..99953509f 100644
--- a/tests/boundary/process/sourceMapUncHosts.test.ts
+++ b/tests/boundary/process/sourceMapUncHosts.test.ts
@@ -73,9 +73,9 @@ processTest.for(cases)(
[
"--input-type=module",
"--eval",
- `import { resolveJavaScriptSourceMapReference } from "./dist/domain/javascript/javascriptSourceMapPaths.js";
+ `import { resolveJavaScriptSourceMapReferences } from "./dist/domain/javascript/javascriptSourceMapPaths.js";
const [source, root] = JSON.parse(process.argv[1]);
- console.log(JSON.stringify(resolveJavaScriptSourceMapReference(source, root, "maps/main.js.map")));`,
+ console.log(JSON.stringify(resolveJavaScriptSourceMapReferences([source], root, "maps/main.js.map")[0]));`,
JSON.stringify([scenario.source, sourceRoot]),
],
{ timeoutMs: 10_000 },
diff --git a/tests/boundary/providers/ghidra/ghidraJavaLaunch.test.ts b/tests/boundary/providers/ghidra/ghidraJavaLaunch.test.ts
index dc4be5ef2..56fec2151 100644
--- a/tests/boundary/providers/ghidra/ghidraJavaLaunch.test.ts
+++ b/tests/boundary/providers/ghidra/ghidraJavaLaunch.test.ts
@@ -286,7 +286,8 @@ describe.skipIf(process.platform === "win32")(
{
platform: process.platform,
architecture: process.arch,
- readText: () => "application.version=12.1.4\n",
+ readText: () =>
+ "application.version=12.1.4\napplication.java.min=21\n",
executable: () => true,
probeJava: () => ({
version: "21.0.12",
diff --git a/tests/boundary/providers/hopper/bridgeLauncher.test.ts b/tests/boundary/providers/hopper/bridgeLauncher.test.ts
index 722a25bed..542858a0d 100644
--- a/tests/boundary/providers/hopper/bridgeLauncher.test.ts
+++ b/tests/boundary/providers/hopper/bridgeLauncher.test.ts
@@ -84,6 +84,7 @@ describe("Hopper bridge launcher selection", () => {
"private",
"/usr/bin/python3",
"/rea/hopper-demo-x11.py",
+ "--owner-stdin",
"--strategy",
"user-mount-namespace",
"--mount-private-x11",
@@ -117,6 +118,7 @@ describe("Hopper bridge launcher selection", () => {
command: "/usr/bin/python3",
args: [
"/rea/hopper-demo-x11.py",
+ "--owner-stdin",
"--strategy",
"direct",
"--hopper",
@@ -202,3 +204,59 @@ it("launches Hopper helpers with the caller-selected environment without restori
await launched.value.releaseLease?.();
}
});
+
+it.skipIf(process.platform !== "linux")(
+ "gives the demo helper a live owner stream through Node's actual stdio transport",
+ async () => {
+ const directory = await createTestTempDirectory("rea-hopper-owner-stdio-");
+ const launcher = new HopperApplicationLauncher(
+ {
+ ...options(process.execPath),
+ launchMode: "verified_linux_demo",
+ demoHelperPath: fileURLToPath(
+ new URL("../../../fixtures/hopperLifetimeLaunch.py", import.meta.url),
+ ),
+ },
+ {
+ selectPrivateDisplay: async () => ({
+ ok: true,
+ strategy: "direct",
+ diagnostic: {
+ component: "hopper_private_display",
+ operation: "probe",
+ status: "ready",
+ failure_code: null,
+ reason: "ready",
+ socket_directory: "/tmp/.X11-unix",
+ socket_directory_mode: "1777",
+ mount_read_only: false,
+ effective_socket_directory_mode: "1777",
+ effective_mount_read_only: false,
+ wsl: false,
+ strategy: "direct",
+ fallback_reason: null,
+ xvfb_stderr_bytes: 0,
+ },
+ }),
+ },
+ );
+ const launched = await launcher.launch({
+ directory,
+ socketPath: join(directory, "bridge.sock"),
+ token: "fixture-token",
+ runId: randomUUID(),
+ });
+ if (!launched.ok) throw launched.error;
+ const supervisor = new ProviderProcessSupervisor(launched.value);
+ try {
+ expect(await supervisor.waitForOutputClose(5_000)).toBe(true);
+ expect(supervisor.snapshot().exitCode).toBe(0);
+ expect(JSON.parse(supervisor.snapshot().stdout.text)).toEqual({
+ owner_alive: true,
+ });
+ } finally {
+ await supervisor.stop();
+ await launched.value.releaseLease?.();
+ }
+ },
+);
diff --git a/tests/boundary/providers/hopper/linuxPrivateDisplay.test.ts b/tests/boundary/providers/hopper/linuxPrivateDisplay.test.ts
index f2c99980f..c5fd45c96 100644
--- a/tests/boundary/providers/hopper/linuxPrivateDisplay.test.ts
+++ b/tests/boundary/providers/hopper/linuxPrivateDisplay.test.ts
@@ -31,6 +31,9 @@ const dialogDetectionFixturePath = fileURLToPath(
const cleanupTimeoutFixturePath = fileURLToPath(
new URL("../../../fixtures/hopperCleanupTimeout.py", import.meta.url),
);
+const ownerLifetimeFixturePath = fileURLToPath(
+ new URL("../../../fixtures/hopperOwnerLifetime.py", import.meta.url),
+);
type DiagnosticOverrides = Partial<
Omit
@@ -107,6 +110,23 @@ describe("Hopper demo dialog detection", () => {
});
describe("Hopper process cleanup", () => {
+ it.skipIf(process.platform !== "linux").each(["startup", "ready"])(
+ "reaps only its own children when the owner pipe closes during %s",
+ (phase) => {
+ const result = spawnSync(
+ "/usr/bin/python3",
+ [ownerLifetimeFixturePath, helperPath, phase],
+ { encoding: "utf8", timeout: 10_000 },
+ );
+ expect(result.status, result.stderr).toBe(0);
+ expect(JSON.parse(result.stdout)).toEqual({
+ phase,
+ children_cleaned: true,
+ sentinel_alive: true,
+ });
+ },
+ );
+
it.skipIf(process.platform !== "linux")(
"kills a child that ignores SIGTERM after the bounded timeout",
() => {
diff --git a/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts b/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts
index 9e03727c1..5d6af987d 100644
--- a/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts
+++ b/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts
@@ -1200,6 +1200,138 @@ describe("native DMG command diagnostics", () => {
});
});
+describe("native DMG verification resource availability", () => {
+ const transientFailure = {
+ stdout: "",
+ stderr:
+ 'hdiutil: verify: unable to recognize "/tmp/image.dmg" as a disk image. (Resource temporarily unavailable)\nhdiutil: verify failed - Resource temporarily unavailable\n',
+ exitCode: 1,
+ };
+
+ it("retries the explicit transient refusal before attachment and retains both attempts", async () => {
+ const { host, state } = createOmittedInventoryHost();
+ state.inventoryMode = "listed";
+ state.detachAttempts = 4;
+ const delays = vi.fn(async () => {});
+ const timeouts: number[] = [];
+ let attempts = 0;
+ const reader = await createAttachedReader(
+ "/tmp/image.dmg",
+ process.env,
+ undefined,
+ {
+ ...host,
+ delay: delays,
+ async run(arguments_, signal, options) {
+ if (arguments_[0] === "verify") {
+ attempts += 1;
+ if (options === undefined)
+ throw new Error("missing verify deadline");
+ timeouts.push(options.timeoutMs);
+ if (attempts === 1) return transientFailure;
+ }
+ return host.run(arguments_, signal, options);
+ },
+ },
+ );
+ onTestFinished(() => reader.close());
+ expect(attempts).toBe(2);
+ expect(delays.mock.calls).toEqual([[250]]);
+ expect(timeouts[0]).toBeLessThanOrEqual(120_000);
+ expect(timeouts[1]).toBeLessThanOrEqual(timeouts[0]!);
+ expect(reader.provenance().slice(0, 2)).toMatchObject([
+ {
+ arguments: ["verify", "/tmp/image.dmg"],
+ exit_code: 1,
+ effects: ["read"],
+ },
+ {
+ arguments: ["verify", "/tmp/image.dmg"],
+ exit_code: 0,
+ effects: ["read"],
+ },
+ ]);
+ await reader.close();
+ expect(state.attached).toBe(false);
+ });
+
+ it("bounds repeated transient refusals and never attaches an unverified image", async () => {
+ const run = vi.fn(async () => transientFailure);
+ const delay = vi.fn(async () => {});
+ const reader = new NativeDmgArtifactReader("/tmp/image.dmg", process.env, {
+ run,
+ delay,
+ });
+ await expect(entryPaths(reader)).rejects.toMatchObject({
+ reason: "unavailable",
+ message: expect.stringContaining("Resource temporarily unavailable"),
+ });
+ await reader.close();
+ expect(run.mock.calls).toHaveLength(3);
+ expect(delay.mock.calls).toEqual([[250], [500]]);
+ expect(reader.provenance().map(({ exit_code }) => exit_code)).toEqual([
+ 1, 1, 1,
+ ]);
+ });
+
+ it("honors cancellation during the wait without starting another command", async () => {
+ const controller = new AbortController();
+ const run = vi.fn(async () => transientFailure);
+ await expect(
+ createAttachedReader("/tmp/image.dmg", process.env, controller.signal, {
+ run,
+ async delay() {
+ controller.abort(new Error("cancel verification"));
+ },
+ }),
+ ).rejects.toMatchObject({ reason: "cancelled" });
+ expect(run).toHaveBeenCalledTimes(1);
+ });
+
+ it("does not start another verification after the shared deadline", async () => {
+ const clock = vi.spyOn(performance, "now").mockReturnValue(0);
+ const run = vi.fn(async () => transientFailure);
+ try {
+ await expect(
+ createAttachedReader("/tmp/image.dmg", process.env, undefined, {
+ run,
+ async delay() {
+ clock.mockReturnValue(120_001);
+ },
+ }),
+ ).rejects.toMatchObject({
+ reason: "unavailable",
+ message: expect.stringContaining("Resource temporarily unavailable"),
+ });
+ expect(run).toHaveBeenCalledTimes(1);
+ } finally {
+ clock.mockRestore();
+ }
+ });
+
+ it.each([
+ ["image data corrupted", "integrity"],
+ ["image not recognized", "format"],
+ ["Permission denied", "io"],
+ ["an unknown failure", "unavailable"],
+ ])("does not retry %s", async (diagnostic, reason) => {
+ const run = vi.fn(async () => ({
+ stdout: "",
+ stderr: `hdiutil: verify failed - ${diagnostic}\n`,
+ exitCode: 1,
+ }));
+ const delay = vi.fn(async () => {});
+ await expect(
+ createAttachedReader("/tmp/image.dmg", process.env, undefined, {
+ run,
+ delay,
+ }),
+ ).rejects.toMatchObject({ reason });
+ expect(run).toHaveBeenCalledTimes(1);
+ expect(delay).not.toHaveBeenCalled();
+ });
+});
+
describe("native DMG real verification diagnostics", () => {
it.skipIf(process.platform !== "darwin")(
"classifies a real hdiutil verify refusal as a format failure with captured output",
diff --git a/tests/evaluation/model-evals/codexAgentEval.test.ts b/tests/evaluation/model-evals/codexAgentEval.test.ts
index d96265202..6b46d9b1d 100644
--- a/tests/evaluation/model-evals/codexAgentEval.test.ts
+++ b/tests/evaluation/model-evals/codexAgentEval.test.ts
@@ -134,6 +134,114 @@ describe("Codex agent release evaluation", () => {
});
});
+describe("Codex completed tool call parsing", () => {
+ it("does not let an unfinished direct event reserve a completed call identity", () => {
+ const evidence = observation();
+ const metrics = evaluateCodexEvents(
+ [
+ {
+ type: "mcp_tool_call",
+ id: "same-call",
+ status: "in_progress",
+ server: "rea",
+ tool: evidence.operation,
+ arguments: {},
+ },
+ {
+ type: "item.completed",
+ item: {
+ id: "same-call",
+ type: "mcp_tool_call",
+ status: "completed",
+ server: "rea",
+ tool: evidence.operation,
+ arguments: {},
+ result: { structuredContent: evidence },
+ },
+ },
+ {
+ type: "item.completed",
+ item: {
+ type: "agent_message",
+ text: `Observed Evidence ${evidence.evidence_id} supports the artifact claim; runtime behavior remains unknown without runtime authority.`,
+ },
+ },
+ ],
+ evidence.operation,
+ { requireEvidence: true },
+ );
+
+ expect(metrics).toMatchObject({
+ naturalUse: true,
+ correctFirstTool: true,
+ reaCalls: [{ id: "same-call" }],
+ evidenceIds: [evidence.evidence_id],
+ finalCitesEvidence: true,
+ answerHeuristicsMet: true,
+ });
+ });
+
+ it.each([
+ { server: "rea", server_name: "other" },
+ { tool: "inspect_managed_artifact", name: "other_tool" },
+ { server: 42 },
+ { arguments: { value: 1 }, input: { value: 2 } },
+ ])(
+ "rejects completed calls with invalid or conflicting fields: %j",
+ (aliases) => {
+ const evidence = observation();
+ const metrics = evaluateCodexEvents(
+ [
+ {
+ type: "item.completed",
+ item: {
+ type: "mcp_tool_call",
+ status: "completed",
+ server: "rea",
+ tool: evidence.operation,
+ arguments: {},
+ result: { structuredContent: evidence },
+ ...aliases,
+ },
+ },
+ ],
+ evidence.operation,
+ { requiredToolSubsequence: [evidence.operation] },
+ );
+
+ expect(metrics).toMatchObject({
+ naturalUse: false,
+ correctFirstTool: false,
+ requiredToolSubsequenceMet: false,
+ evidenceIds: [],
+ });
+ },
+ );
+
+ it("preserves legacy completed calls with no server field", () => {
+ const metrics = evaluateCodexEvents(
+ [
+ {
+ type: "item.completed",
+ item: {
+ type: "mcp_tool_call",
+ status: "completed",
+ tool: "inspect_managed_artifact",
+ arguments: {},
+ },
+ },
+ ],
+ "inspect_managed_artifact",
+ );
+
+ expect(metrics).toMatchObject({
+ naturalUse: true,
+ correctFirstTool: true,
+ reaCalls: [{ server: null }],
+ });
+ });
+});
+
describe("Codex Evidence delivery", () => {
it("rejects diagnostic IDs and failed results as delivered Evidence", () => {
const evidenceId = `ev_${"a".repeat(64)}`;
@@ -524,28 +632,32 @@ describe("Codex agent completion evaluation", () => {
});
});
- it("recognizes Codex MCP failed status when the error field is null", () => {
- const metrics = evaluateCodexEvents(
- [
- {
- type: "item.completed",
- item: {
- id: "item-failed",
- type: "mcp_tool_call",
- server: "rea",
- tool: "analyze_javascript_application",
- arguments: { input_path: "/tmp/app.asar" },
- result: { structured_content: { error: { code: "denied" } } },
- error: null,
- status: "failed",
- },
- },
- ],
- "analyze_javascript_application",
- );
+ it.each(["item.completed", "mcp_tool_call"] as const)(
+ "counts a failed completed invocation from %s without delivering Evidence",
+ (type) => {
+ const item = {
+ id: "item-failed",
+ type: "mcp_tool_call",
+ server: "rea",
+ tool: "analyze_javascript_application",
+ arguments: { input_path: "/tmp/app.asar" },
+ result: { structured_content: { error: { code: "denied" } } },
+ error: null,
+ status: "failed",
+ };
+ const metrics = evaluateCodexEvents(
+ [type === "item.completed" ? { type, item } : item],
+ "analyze_javascript_application",
+ );
- expect(metrics.reaCalls[0]?.error).toBe(true);
- });
+ expect(metrics).toMatchObject({
+ naturalUse: true,
+ correctFirstTool: true,
+ evidenceIds: [],
+ reaCalls: [{ error: true }],
+ });
+ },
+ );
});
describe("Codex agent workflow evaluation", () => {
diff --git a/tests/fixtures/evm/interface.ts b/tests/fixtures/evm/interface.ts
index 23bfcfa02..f0f1960ba 100644
--- a/tests/fixtures/evm/interface.ts
+++ b/tests/fixtures/evm/interface.ts
@@ -1,5 +1,6 @@
import { createHash } from "node:crypto";
import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js";
+import type { EvmInterfaceExecution } from "../../../src/application/evm/EvmInterfacePort.js";
import type { EvmInterface } from "../../../src/domain/evm/evmInterface.js";
/** Source-owned transport seam, independent of real engine verification. */
@@ -27,8 +28,10 @@ export const evmInterfaceFixture = (
});
/** Bind a fixture to its explicit producing seam and carrier identity. */
-export const evmInterfaceExecution = (value = evmInterfaceFixture()) =>
- createAnalysisExecution(
+export const evmInterfaceExecution = (
+ value = evmInterfaceFixture(),
+): EvmInterfaceExecution => {
+ return createAnalysisExecution(
value,
{ id: "fixture-evm", name: "Source-owned EVM seam", version: "1" },
{
@@ -42,3 +45,4 @@ export const evmInterfaceExecution = (value = evmInterfaceFixture()) =>
locations: [{ kind: "artifact-path", path: value.artifact.path }],
},
);
+};
diff --git a/tests/fixtures/hopperLifetimeLaunch.py b/tests/fixtures/hopperLifetimeLaunch.py
new file mode 100644
index 000000000..68d65c9ff
--- /dev/null
+++ b/tests/fixtures/hopperLifetimeLaunch.py
@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""Inspect the real Node launcher stdio with the production lifetime parser."""
+
+import importlib.util
+import json
+from pathlib import Path
+import sys
+
+spec = importlib.util.spec_from_file_location(
+ "hopper_demo_x11", Path(__file__).resolve().parents[2] / "scripts/hopper-demo-x11.py"
+)
+assert spec is not None and spec.loader is not None
+helper = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(helper)
+assert "--owner-stdin" in sys.argv
+print(json.dumps({"owner_alive": helper.OwnerLifetime(True).alive()}))
diff --git a/tests/fixtures/hopperOwnerLifetime.py b/tests/fixtures/hopperOwnerLifetime.py
new file mode 100644
index 000000000..741bffbd9
--- /dev/null
+++ b/tests/fixtures/hopperOwnerLifetime.py
@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Exercise the production runner with real children and a simulated X11 surface."""
+
+import argparse
+import importlib.util
+import json
+from pathlib import Path
+import signal
+import subprocess
+import sys
+import tempfile
+import time
+
+
+spec = importlib.util.spec_from_file_location("hopper_demo_x11", sys.argv[1])
+assert spec is not None and spec.loader is not None
+helper = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(helper)
+
+
+def child_command(receipt):
+ return [
+ sys.executable,
+ "-c",
+ "import os,pathlib,time;"
+ f"receipt=pathlib.Path({str(receipt)!r});"
+ "pending=receipt.with_suffix('.pending');"
+ "pending.write_text(str(os.getpid()));pending.replace(receipt);"
+ "time.sleep(100)",
+ ]
+
+
+if len(sys.argv) > 3:
+ phase, directory = sys.argv[2], Path(sys.argv[3])
+
+ def terminate_worker(*_):
+ raise SystemExit(143)
+
+ # Failed assertions in the parent must still unwind run_launch's finally.
+ signal.signal(signal.SIGTERM, terminate_worker)
+
+ class X11:
+ def XOpenDisplay(self, *_):
+ return 1
+
+ def XDefaultRootWindow(self, *_):
+ return 1
+
+ def XDisplayWidth(self, *_):
+ return 1280
+
+ def XDisplayHeight(self, *_):
+ return 1024
+
+ def XCloseDisplay(self, *_):
+ return 1
+
+ def start_xvfb(*_):
+ child = subprocess.Popen(
+ child_command(directory / "xvfb.pid"),
+ stdin=subprocess.DEVNULL,
+ stdout=subprocess.DEVNULL,
+ stderr=subprocess.PIPE,
+ )
+ return child, ":123", directory / "Xauthority", helper.CapturedStderr(child.stderr)
+
+ helper.digest = lambda _: next(iter(helper.SUPPORTED_HOPPER_SHA256))
+ helper.start_xvfb = start_xvfb
+ helper.ctypes.CDLL = lambda _: X11()
+ helper.configure_x11 = lambda *_: None
+ helper.windows = lambda *_: []
+ socket = directory / "bridge.sock"
+ if phase == "ready":
+ socket.touch()
+ raise SystemExit(helper.run_launch(argparse.Namespace(
+ owner_stdin=True,
+ hopper=sys.executable,
+ socket=str(socket),
+ command=child_command(directory / "hopper.pid"),
+ )))
+
+
+with tempfile.TemporaryDirectory(prefix="rea-owner-lifetime-") as root:
+ directory = Path(root)
+ sentinel = subprocess.Popen([sys.executable, "-c", "import time;time.sleep(100)"])
+ worker = subprocess.Popen(
+ [sys.executable, __file__, sys.argv[1], sys.argv[2], root],
+ stdin=subprocess.PIPE,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE,
+ )
+ try:
+ deadline = time.monotonic() + 5
+ receipts = [directory / "hopper.pid", directory / "xvfb.pid"]
+ while not all(receipt.exists() for receipt in receipts):
+ assert worker.poll() is None, worker.communicate()
+ assert time.monotonic() < deadline, "owned children did not start"
+ time.sleep(0.01)
+ pids = [int(receipt.read_text()) for receipt in receipts]
+ assert worker.poll() is None, "live owner did not retain the helper"
+ assert worker.stdin is not None
+ worker.stdin.close()
+ assert worker.wait(timeout=5) == 0, worker.stderr.read()
+ for pid in pids:
+ assert not Path(f"/proc/{pid}").exists(), f"owned child {pid} survived EOF"
+ assert sentinel.poll() is None, "unrelated process was stopped"
+ print(json.dumps({"phase": sys.argv[2], "children_cleaned": True, "sentinel_alive": True}))
+ finally:
+ helper.stop_process(worker)
+ helper.stop_process(sentinel)
diff --git a/tests/fixtures/localToolsMcp.ts b/tests/fixtures/localToolsMcp.ts
index 1e1e91909..bf9c7617a 100644
--- a/tests/fixtures/localToolsMcp.ts
+++ b/tests/fixtures/localToolsMcp.ts
@@ -34,7 +34,9 @@ const compileValidator = (schema: unknown): ValidateFunction => {
};
/** Start the built production server without configuring deep binary providers. */
-export async function connectLocalToolsMcp() {
+export async function connectLocalToolsMcp(
+ environment: Readonly> = {},
+) {
const transport = new StdioClientTransport({
command: process.execPath,
args: [
@@ -45,6 +47,7 @@ export async function connectLocalToolsMcp() {
PATH: process.env.PATH ?? "/usr/bin:/bin",
REA_LOG_LEVEL: "silent",
HOPPER_LAUNCHER_PATH: "/rea-unconfigured-deep-provider/hopper",
+ ...environment,
},
stderr: "pipe",
});
diff --git a/tests/fixtures/pcap/capinfos-stub.cmd b/tests/fixtures/pcap/capinfos-stub.cmd
new file mode 100644
index 000000000..6f783bcf5
--- /dev/null
+++ b/tests/fixtures/pcap/capinfos-stub.cmd
@@ -0,0 +1,19 @@
+@echo off
+rem capinfos stub for Windows: emulates capinfos --version and metadata output.
+
+if "%~1"=="--version" (
+ echo Capinfos ^(Wireshark^) 4.6.6-windows-stub
+ exit /b 0
+)
+
+if not "%~1"=="-M" exit /b 2
+if not "%~2"=="--" exit /b 2
+if "%~3"=="" exit /b 2
+
+echo File name: capture.pcap
+echo File type: Wireshark/tcpdump/... - pcap
+echo File encapsulation: Ethernet
+echo Packet size limit: file hdr: 262144 bytes
+echo Number of packets: 3
+echo Capture duration: 0.123 seconds
+exit /b 0
diff --git a/tests/fixtures/pcap/capinfos-stub.sh b/tests/fixtures/pcap/capinfos-stub.sh
new file mode 100755
index 000000000..47d61b1b1
--- /dev/null
+++ b/tests/fixtures/pcap/capinfos-stub.sh
@@ -0,0 +1,11 @@
+#!/bin/sh
+# POSIX capinfos stub (mirrors capinfos-stub.cmd for Windows parity).
+if [ "$1" = "--version" ]; then printf 'Capinfos (Wireshark) 4.6.6-posix-stub\n'; exit 0; fi
+[ "$1" = "-M" ] && [ "$2" = "--" ] && [ "$#" = "3" ] || exit 2
+printf '%s\n' 'File name: capture.pcap'
+printf '%s\n' 'File type: Wireshark/tcpdump/... - pcap'
+printf '%s\n' 'File encapsulation: Ethernet'
+printf '%s\n' 'Packet size limit: file hdr: 262144 bytes'
+printf '%s\n' 'Number of packets: 3'
+printf '%s\n' 'Capture duration: 0.123 seconds'
+exit 0
diff --git a/tests/fixtures/pcap/tshark-stub.cmd b/tests/fixtures/pcap/tshark-stub.cmd
new file mode 100644
index 000000000..d157ed721
--- /dev/null
+++ b/tests/fixtures/pcap/tshark-stub.cmd
@@ -0,0 +1,17 @@
+@echo off
+rem Pcap tool stub for Windows: emulates tshark --version and field output.
+rem %1 is the first argument; the capture path arrives as %2 for -r/-c.
+
+if "%~1"=="--version" (
+ echo TShark ^(Wireshark^) 4.6.6-windows-stub
+ exit /b 0
+)
+
+if not "%~1"=="-n" exit /b 2
+if not "%~2"=="-r" exit /b 2
+if not "%~4"=="-T" exit /b 2
+if not "%~5"=="json" exit /b 2
+
+rem Emit the same JSON as the POSIX stub
+echo [{"_source":{"layers":{"frame.number":["1"],"frame.protocols":["eth:ethertype:ip:udp:dns"],"ip.src":["192.168.1.100"],"ip.dst":["8.8.8.8"],"dns.qry.name":["api.example.com"],"dns.flags.response":["1"],"dns.a":["93.184.216.34"]}}},{"_source":{"layers":{"frame.number":["2"],"frame.protocols":["eth:ethertype:ip:tcp:tls"],"ip.src":["192.168.1.100"],"ip.dst":["93.184.216.34"],"tls.handshake.extensions_server_name":["api.example.com"]}}},{"_source":{"layers":{"frame.number":["3"],"frame.protocols":["eth:ethertype:ip:tcp:http"],"ip.src":["192.168.1.100"],"ip.dst":["93.184.216.34"],"http.request.full_uri":["http://api.example.com/v1/data"]}}}]
+exit /b 0
diff --git a/tests/fixtures/pcap/tshark-stub.sh b/tests/fixtures/pcap/tshark-stub.sh
new file mode 100755
index 000000000..8633dd7c0
--- /dev/null
+++ b/tests/fixtures/pcap/tshark-stub.sh
@@ -0,0 +1,6 @@
+#!/bin/sh
+# POSIX pcap tool stub (mirrors tshark-stub.cmd for Windows parity).
+if [ "$1" = "--version" ]; then printf 'TShark (Wireshark) 4.6.6-posix-stub\n'; exit 0; fi
+[ "$1" = "-n" ] && [ "$2" = "-r" ] && [ "$4" = "-T" ] && [ "$5" = "json" ] || exit 2
+printf '%s' '[{"_source":{"layers":{"frame.number":["1"],"frame.protocols":["eth:ethertype:ip:udp:dns"],"ip.src":["192.168.1.100"],"ip.dst":["8.8.8.8"],"dns.qry.name":["api.example.com"],"dns.flags.response":["1"],"dns.a":["93.184.216.34"]}}},{"_source":{"layers":{"frame.number":["2"],"frame.protocols":["eth:ethertype:ip:tcp:tls"],"ip.src":["192.168.1.100"],"ip.dst":["93.184.216.34"],"tls.handshake.extensions_server_name":["api.example.com"]}}},{"_source":{"layers":{"frame.number":["3"],"frame.protocols":["eth:ethertype:ip:tcp:http"],"ip.src":["192.168.1.100"],"ip.dst":["93.184.216.34"],"http.request.full_uri":["http://api.example.com/v1/data"]}}}]'
+exit 0
diff --git a/tests/fixtures/wasm/artifact.ts b/tests/fixtures/wasm/artifact.ts
index d4cc803b4..3b615ca06 100644
--- a/tests/fixtures/wasm/artifact.ts
+++ b/tests/fixtures/wasm/artifact.ts
@@ -1,5 +1,6 @@
import { createHash } from "node:crypto";
import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js";
+import type { WasmArtifactExecution } from "../../../src/application/wasm/WasmArtifactPort.js";
import type { WasmArtifact } from "../../../src/domain/wasm/wasmArtifact.js";
/** Source-owned transport seam; upstream binaries are verified in a separate lane. */
export const wasmArtifactFixture = (
@@ -42,8 +43,10 @@ export const wasmArtifactFixture = (
network_fetch: "not-performed" as const,
limitations: ["Source-owned transport seam."],
});
-export const wasmArtifactExecution = (value = wasmArtifactFixture()) =>
- createAnalysisExecution(
+export const wasmArtifactExecution = (
+ value = wasmArtifactFixture(),
+): WasmArtifactExecution => {
+ return createAnalysisExecution(
value,
{ id: "fixture-wabt", name: "Source-owned WABT seam", version: "1" },
{
@@ -55,3 +58,4 @@ export const wasmArtifactExecution = (value = wasmArtifactFixture()) =>
limitations: value.limitations,
},
);
+};
diff --git a/tests/process-global/pwntoolsStageRetirement.test.ts b/tests/process-global/pwntoolsStageRetirement.test.ts
index bcdaf858f..6ec062535 100644
--- a/tests/process-global/pwntoolsStageRetirement.test.ts
+++ b/tests/process-global/pwntoolsStageRetirement.test.ts
@@ -261,6 +261,14 @@ it.runIf(supportedHost).each([
if (result.ok) throw new Error("Expected unresolved process ownership");
const projected = projectAnalysisError(result.error);
expect(projected.code).toBe("cleanup_incomplete");
+ expect(projected).toMatchObject({
+ details: {
+ resources: expect.arrayContaining([
+ expect.stringMatching(/^pid:\d+$/u),
+ expect.stringMatching(/^process-group:\d+$/u),
+ ]),
+ },
+ });
if (stage === "debugger")
expect(projected).toMatchObject({
details: {
diff --git a/tests/process-global/regularFileNoFollowFallback.test.ts b/tests/process-global/regularFileNoFollowFallback.test.ts
new file mode 100644
index 000000000..44ce66c7c
--- /dev/null
+++ b/tests/process-global/regularFileNoFollowFallback.test.ts
@@ -0,0 +1,55 @@
+import { readFile, symlink } from "node:fs/promises";
+import { join } from "node:path";
+
+import { expect, it, vi } from "vitest";
+
+vi.mock("node:fs", async (importOriginal) => {
+ const original = await importOriginal();
+ return {
+ ...original,
+ constants: { ...original.constants, O_NOFOLLOW: 0 },
+ };
+});
+
+import { openRegularFile } from "../../src/filesystem/RegularFile.js";
+import { ZipArtifactReader } from "../../src/artifacts/ZipArtifactReader.js";
+import { writeOrderedZip } from "../fixtures/artifactEntryOrder.js";
+import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js";
+
+it("rejects a symlink when O_NOFOLLOW is unavailable and still follows when requested", async () => {
+ const root = await createTestTempDirectory("rea-no-nofollow-");
+ const target = join(root, "target.zip");
+ const link = join(root, "selected.zip");
+ await writeOrderedZip(target, ["member.bin"]);
+ await symlink(target, link);
+
+ const reader = new ZipArtifactReader(target, "zip");
+ try {
+ const entries = [];
+ for await (const entry of reader.entries()) entries.push(entry);
+ expect(entries.map(({ path }) => path)).toEqual(["member.bin"]);
+ } finally {
+ await reader.close();
+ }
+
+ const linkedReader = new ZipArtifactReader(link, "zip");
+ try {
+ await expect(async () => {
+ for await (const _entry of linkedReader.entries()) {
+ // Consume through the public reader boundary.
+ }
+ }).rejects.toMatchObject({
+ name: "ArtifactReaderFailure",
+ reason: "format",
+ });
+ } finally {
+ await linkedReader.close();
+ }
+
+ const followed = await openRegularFile(link, { symlinks: "follow" });
+ try {
+ await expect(readFile(followed)).resolves.toEqual(await readFile(target));
+ } finally {
+ await followed.close();
+ }
+});
diff --git a/tests/process-global/updateMaintenance.test.ts b/tests/process-global/updateMaintenance.test.ts
index a60a2e213..ae057bab2 100644
--- a/tests/process-global/updateMaintenance.test.ts
+++ b/tests/process-global/updateMaintenance.test.ts
@@ -126,6 +126,41 @@ describe("OMP integration maintenance", () => {
});
});
+describe("maintenance activation and layered configuration", () => {
+ it("leaves a natively disabled ZCode registration outside maintenance", async () => {
+ const configPath = await writeClient(
+ "zcode",
+ JSON.stringify({
+ mcp: {
+ servers: {
+ rea: { command: entryPoint, args: ["mcp"], enable: false },
+ },
+ },
+ }),
+ );
+ const original = await readFile(configPath, "utf8");
+ await expect(
+ existingMaintenanceScope(home, entryPoint, process.env),
+ ).resolves.toMatchObject({ clients: [] });
+ expect(await readFile(configPath, "utf8")).toBe(original);
+ });
+
+ it("selects an enabled registration inherited through layered OpenCode files", async () => {
+ const directory = join(home, ".config", "opencode");
+ await mkdir(directory, { recursive: true });
+ await writeFile(
+ join(directory, "opencode.json"),
+ JSON.stringify({
+ mcp: { rea: { type: "local", command: [entryPoint, "mcp"] } },
+ }),
+ );
+ await writeClient("opencode", JSON.stringify({ theme: "user-selected" }));
+ await expect(
+ existingMaintenanceScope(home, entryPoint, process.env),
+ ).resolves.toMatchObject({ clients: ["opencode"] });
+ });
+});
+
describe("existing REA integration maintenance", () => {
it("selects owned registrations while preserving unconfigured, foreign, and disabled choices", async () => {
await writeClient("codex", staleCodex);
diff --git a/vitest.config.ts b/vitest.config.ts
index 74dbf5305..bfef8e139 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -51,7 +51,7 @@ const TEST_PROJECTS = [
name: "adapters",
include: [
"src/*.test.ts",
- "src/{apktool,jeb,adb,artifacts,browser,dotnet,evm,firmware,flutter,ghidra,go,hopper,ida,inspector,javascript,native,process,reference,server,wasm,windows}/**/*.test.ts",
+ "src/{apktool,jeb,adb,artifacts,browser,dotnet,evm,firmware,flutter,pcap,ghidra,go,hopper,ida,inspector,javascript,native,process,reference,server,wasm,windows}/**/*.test.ts",
],
pool: "forks" as const,
maxWorkers: MAX_TEST_WORKERS,