docs: document resource snapshot workflow

2026-10-19 04:19:54 -05:00 · 2026-07-29 17:37:00 +00:00
1 parent ba098f24e5
commit 2a45d8de7d
@@ -389,7 +389,7 @@ REA handles the app analysis in steps 1–5. The agent performs step 6 with its
 | Electron analysis         |     4 | passive root-confined observation, bounded static application mapping, and evidence-backed static/runtime reconciliation                                                                                                                                                                                                         |
 | JavaScript runtime        |     2 | approved attach-only Node/Electron Inspector target discovery plus bounded script and execution-context observation without evaluation or instrumentation                                                                                                                                                                        |
 | Application workflows     |    12 | bounded cross-layer traces, unique-only version matching, historical-source to bundle mapping, static export return-shape comparison, approved Linux-isolated extracted-module replay, managed-runtime characterization, reconstruction coverage closure, deterministic obligation ledgers, and end-to-end readiness conformance |
-| Workspace and observation |    19 | target lifecycle, Evidence v2 bundles, direct finite replay-machine evaluation, process/artifact/function comparison, evidence-linked residual-unknown lifecycle                                                                                                                                                                 |
+| Workspace and observation |    22 | target lifecycle, Evidence v2 bundle snapshots, aggregate navigation/address context, direct finite replay-machine evaluation, process/artifact/function comparison, evidence-linked residual-unknown lifecycle                                                                                                                  |

 The public interface describes what the agent is trying to learn. Providers decide how to answer. macOS utilities handle common semantic inspection without launching Hopper; Hopper handles deeper native analysis; the process harness implements controlled behavioral capture.

@@ -170,7 +170,7 @@ rea uninstall --purge-data
 | تحليل Electron        |     4 | مراقبة سلبية ضمن جذور canonical، ورسم ثابت ومحدود للتطبيق، ومطابقة ثابتة/وقت تشغيل قائمة على Evidence                                                                                                                                 |
 | وقت تشغيل JavaScript  |     2 | اكتشاف أهداف Node/Electron Inspector المعتمدة للاتصال فقط، ومراقبة محدودة للبرامج النصية وسياقات التنفيذ دون تقييم أو تجهيز                                                                                                           |
 | سير عمل التطبيقات     |    12 | تتبع محدود ومقارنة إصدارات فريدة ومقارنة ثابتة لأشكال قيم إرجاع الصادرات وإعادة تشغيل وحدات معزولة ومعتمدة على Linux وتوصيف وقت التشغيل المُدار وإغلاق تغطية إعادة البناء ودفاتر التزامات حتمية والتحقق الشامل من جاهزية إعادة البناء |
-| جلسة الملف التنفيذي   |    19 | فتح الأهداف وحزم الأدلة وتشغيل آلة إعادة محدودة ومقارنة العمليات والقطع والدوال وسجل المجهولات المتبقية                                                                                                                               |
+| جلسة الملف التنفيذي   |    22 | فتح الأهداف وحزم الأدلة وتشغيل آلة إعادة محدودة ومقارنة العمليات والقطع والدوال وسجل المجهولات المتبقية                                                                                                                               |

 ## استخدام REA مع وكلاء برمجة آخرين

@@ -160,7 +160,7 @@ REA は手順 1〜5 のバイナリ解析を処理し、手順 6 はエージェ
 | Electron 解析          |   4 | canonical ファイルルート内の受動観察、有界な静的アプリマッピング、Evidence に基づく静的/実行時の照合                                                                                                                                        |
 | JavaScript ランタイム  |   2 | 承認済みのアタッチ専用 Node/Electron Inspector ターゲット検出と、評価や計装を行わない有界なスクリプト／実行コンテキスト観察                                                                                                                 |
 | アプリケーション       |  12 | 有界なクロスレイヤー追跡、一意限定のバージョン比較、静的なエクスポート戻り値形状比較、承認済み Linux 隔離 extracted-module replay、マネージドランタイム特性評価、再構築カバレッジ閉包、決定論的な義務台帳、エンドツーエンドの準備適合性検証 |
-| バイナリセッション     |  19 | `open_binary`、`binary_session`、証拠バンドル、有限リプレイ状態機械、プロセス／成果物／関数比較、残余未知レジストリ                                                                                                                         |
+| バイナリセッション     |  22 | `open_binary`、`binary_session`、証拠バンドル、有限リプレイ状態機械、プロセス／成果物／関数比較、残余未知レジストリ                                                                                                                         |

 ## 他のコーディングエージェントで使う

@@ -160,7 +160,7 @@ REA는 1–5단계의 바이너리 분석을 처리합니다. 6단계는 에이
 | Electron 분석       |   4 | canonical 파일 루트 내 수동 관찰, 제한된 정적 앱 매핑, Evidence 기반 정적/런타임 조정                                                                                                                          |
 | JavaScript 런타임   |   2 | 승인된 연결 전용 Node/Electron Inspector 대상 탐색과 평가·계측 없는 제한된 스크립트 및 실행 컨텍스트 관찰                                                                                                      |
 | 애플리케이션        |  12 | 제한된 교차 계층 추적, 고유 일치 버전 비교, 정적 export 반환 형태 비교, 승인된 Linux 격리 extracted-module replay, 관리형 런타임 특성화, 재구성 커버리지 폐쇄, 결정론적 의무 원장, 엔드투엔드 준비 적합성 검증 |
-| 바이너리 세션       |  19 | `open_binary`, `binary_session`, 증거 번들, 유한 replay 상태 머신, 프로세스·아티팩트·함수 비교, 잔여 미지수 레지스트리                                                                                         |
+| 바이너리 세션       |  22 | `open_binary`, `binary_session`, 증거 번들, 유한 replay 상태 머신, 프로세스·아티팩트·함수 비교, 잔여 미지수 레지스트리                                                                                         |

 ## 다른 코딩 에이전트에서 사용하기

@@ -160,7 +160,7 @@ REA 负责第 1–5 步中的二进制分析。第 6 步由智能体使用其常
 | Electron 分析     |    4 | 限定 canonical 文件根的被动观察、有界静态应用映射，以及基于 Evidence 的静态/运行时对账                                                                                      |
 | JavaScript 运行时 |    2 | 经批准的只附加 Node/Electron Inspector 目标发现，以及不执行求值或插桩的有界脚本和执行上下文观察                                                                             |
 | 应用工作流        |   12 | 有界跨层追踪、唯一匹配跨版本图比较、静态导出返回形状比较、经批准的 Linux 隔离 extracted-module replay、托管运行时表征、重建覆盖闭合、确定性义务账本和端到端就绪性一致性验证 |
-| 二进制会话        |   19 | `open_binary`、`binary_session`、证据包、有限重放状态机、进程、制品与函数比较、残余未知项注册表                                                                             |
+| 二进制会话        |   22 | `open_binary`、`binary_session`、证据包、有限重放状态机、进程、制品与函数比较、残余未知项注册表                                                                             |

 ## 与其他编程智能体一起使用

@@ -60,8 +60,10 @@ shutdown rules still apply; REA never kills a process it cannot prove it owns.

 ## Evidence resources

-Evidence remains inline for compatibility and successful Evidence-producing
-tools also return `resource_link` content. Session resources are connection-local:
+Evidence-producing tools return compact summaries plus `resource_link` content.
+Every link is accompanied by an ordinary instruction to copy its opaque URI
+unchanged and call MCP `resources/read` (Codex: `read_mcp_resource`). Session
+resources are connection-local:

 - `rea://evidence/{evidenceId}` returns the complete immutable Evidence v2 record.
 - `rea://evidence/{evidenceId}/section/{section}` returns a bounded result section.
@@ -69,9 +71,10 @@ tools also return `resource_link` content. Session resources are connection-loca
  `protocol`, `nodes`, `occurrences`, and `edges` when present.
 - `rea://unknown/{unknownId}` returns the current residual-unknown head and its
  immutable revision history.
- `rea://unknowns/active` returns current unresolved heads.
- `rea://snapshot/{snapshotDigest}` returns the current immutable analysis
-  snapshot when its canonical content digest matches.
+- `rea://evidence-bundle/{bundleDigest}` returns immutable canonical bytes
+  retained by `snapshot_evidence_bundle`.
+- `rea://snapshot/current` returns the mutable native analysis cache as an
+  `available` or `unavailable` state.
 - `rea://artifact/{manifestId}/{collection}` returns a canonical artifact
  `nodes`, `occurrences`, or `edges` page with Evidence provenance.
 - `rea://function/{targetSha256}/{address}` returns a retained function dossier
@@ -84,11 +87,24 @@ workspace `resource_link` blocks. Workspace resources preserve revision and
 `previous_revision_digest` commitments; persistent workspace files remain
 subject to configured read/write roots.

+`export_evidence_bundle` is file-only and requires `path`; existing files
+require `overwrite: true`. Use `snapshot_evidence_bundle` and then
+`resources/read` when the complete bundle is needed within the current session.
+
 An Evidence URI is discoverability, not authorization. It cannot authorize file
 access, extraction, mounting, execution, or networking. IDs disappear when the
 session ends unless the existing Evidence bundle or workspace persistence flow
 explicitly retains them.

+## Aggregate native context
+
+`get_navigation_context` combines the selected document, current address, and
+current/containing procedure. A cursor outside a procedure is represented as
+`procedure: null`. `inspect_address_context` requires an explicit address and
+returns bounded name, procedure, comment, inline-comment, and bookmark facets;
+unsupported facets are local `unavailable` outcomes. The scalar getters remain
+available while the aggregate contracts are evaluated.
+
 ## Permission policy

 All local side effects use one scope vocabulary: capability, canonical roots,
@@ -11,7 +11,7 @@
    "skill_version": "23"
  },
  "tools": {
-    "total": 111,
+    "total": 114,
    "families": [
      {
        "id": "direct",
@@ -167,7 +167,7 @@
      {
        "id": "session",
        "surface": "session",
-        "count": 19,
+        "count": 22,
        "tools": [
          "binary_session",
          "build_call_path",
@@ -180,11 +180,14 @@
          "correlate_static_and_runtime",
          "export_evidence_bundle",
          "find_changed_behavior",
+          "get_navigation_context",
          "import_evidence_bundle",
+          "inspect_address_context",
          "list_unknowns",
          "open_binary",
          "record_unknown",
          "run_replay_machine",
+          "snapshot_evidence_bundle",
          "update_unknown",
          "verify_reconstruction",
          "verify_unknown_resolution"
@@ -662,16 +665,16 @@
  "runtime_catalog": {
    "counts": {
      "cli_commands": 67,
-      "mcp_tools": 111,
+      "mcp_tools": 114,
      "mcp_prompts": 6,
      "mcp_resources": 2,
      "mcp_resource_templates": 11
    },
    "digests": {
-      "tools_sha256": "092dd59990f61b1011ac0cd4f5b8d6a3e4a2cf7ade49c86892963c87b71dc65b",
+      "tools_sha256": "ea2b9be5eb6230a65e25e6b52a9df9b60812aeb43dd08612ac96458cfb5a7f9a",
      "prompts_sha256": "2dd61fd4e29657e7faf739ef67be7b1f637ddf446e7d73acc0d2fd1d9f06b43e",
-      "resources_sha256": "339a984ea8cd8be5f234adf24395bf0295258d990492005cf6fe1f293d12cd46",
-      "combined_sha256": "461b4dbea03ef60d637f4b74debca4dbea0e1dd423d7d9c9a631e62204528c05",
+      "resources_sha256": "e0e872276ebf6f88e916ef24930a99eed27ce4c93e494e60820e9bd8cc8497c3",
+      "combined_sha256": "2c55a0742cca841ba58200cf87d851fdaeae24cfaadcd356d3642c67fd70a2a2",
      "providers_sha256": "918ccd6b8ae442cd5844dcfde55086f458176241c8d166c1e9dd0f242ccd2bb0"
    }
  }
@@ -3,8 +3,8 @@ name: reverse-engineer-anything
 description: Reverse engineer native, managed, Electron/JavaScript, packaged, and browser applications with REA. Use shipped-artifact or approved runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
 metadata:
  version: "23"
-  tool_count: 111
-  catalog_digest: "461b4dbea03ef60d637f4b74debca4dbea0e1dd423d7d9c9a631e62204528c05"
+  tool_count: 114
+  catalog_digest: "2c55a0742cca841ba58200cf87d851fdaeae24cfaadcd356d3642c67fd70a2a2"
 ---

 # REA
@@ -30,7 +30,7 @@ interface GeneratedPayload {
 }

 const GENERATED_PAYLOAD_JSON =
-  '{"catalog":[{"name":"address_name","analysisOperation":"address_name","title":"Address Name","description":"Resolve the primary analyzed name at a code or data address. Headless providers require an explicit address; GUI providers may default to their current cursor. Null means the provider has no primary name at that address.","kind":"official-proxy","requiresSession":false,"inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"document":{"description":"The document name","type":"string"},"address":{"type":"string","description":"A provider-normalized address; default memory uses 0x-prefixed hexadecimal"},"unknown_registry_approved":{"description":"Explicit approval to record typed capability unavailability as a residual unknown","type":"boolean","const":true}},"additionalProperties":false,"examples":[{}]},"outputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"result":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary structured result returned by this operation."},"evidence_id":{"type":"string","pattern":"^ev_[a-f0-9]{64}$","description":"Stable identifier of the recorded Evidence v2 observation."},"evidence_uri":{"type":"string","pattern":"^rea:\\\\/\\\\/evidence\\\\/ev_[a-f0-9]{64}$","description":"Session resource URI for the recorded Evidence v2 observation."}},"required":["result","evidence_id","evidence_uri"],"additionalProperties":false},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"effects":{"mutatesTarget":false,"mutatesSession":true,"writesFilesystem":false,"launchesProcess":false,"accessesNetwork":false,"changesUiState":false,"mayDiscardData":false,"idempotent":true}},{"name":"comment","analysisOperation":"comment","title":"Comment","description":"Read the regular analysis comment at an address, defaulting to the current cursor. This is read-only and returns null when no comment exists; use set_comment to persist a finding.","kind":"official-proxy","requiresSession":false,"inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"document":{"description":"The document name","type":"string"},"address":{"type":"string","description":"A provider-normalized address; default memory uses 0x-prefixed hexadecimal"},"unknown_registry_approved":{"description":"Explicit approval to record typed capability unavailability as a residual unknown","type":"boolean","const":true}},"additionalProperties":false,"examples":[{}]},"outputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"result":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary structured result returned by this operation."},"evidence_id":{"type":"string","pattern":"^ev_[a-f0-9]{64}$","description":"Stable identifier of the recorded Evidence v2 observation."},"evidence_uri":{"type":"string","pattern":"^rea:\\\\/\\\\/evidence\\\\/ev_[a-f0-9]{64}$","description":"Session resource URI for the recorded Evidence v2 observation."}},"required":["result","evidence_id","evidence_uri"],"additionalProperties":false},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"effects":{"mutatesTarget":false,"mutatesSession":true,"writesFilesystem":false,"launchesProcess":false,"accessesNetwork":false,"changesUiState":false,"mayDiscardData":false,"idempotent":true}},{"name":"current_address","analysisOperation":"current_address","title":"Current Address","description":"Return Hopper\'s current cursor address for the selected document. Use only for interactive navigation state; prefer explicit addresses in reproducible investigations.","kind":"official-proxy","requiresSession":false,"inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"document":{"description":"The document name","type":"string"},"unknown_registry_approved":{"description":"Explicit approval to record typed capability unavailability as a residual unknown","type":"boolean","const":true}},"additionalProperties":false,"examples":[{}]},"outputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"result":{"type":"string","description":"Primary structured result returned by this operation."},"evidence_id":{"type":"string","pattern":"^ev_[a-f0-9]{64}$","description":"Stable identifier of the recorded Evidence v2 observation."},"evidence_uri":{"type":"string","pattern":"^rea:\\\\/\\\\/evidence\\\\/ev_[a-f0-9]{64}$","description":"Session resource URI for the recorded Evidence v2 observation."}},"required":["result","evidence_id","evidence_uri"],"additionalProperties":false},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"effects":{"mutatesTarget":false,"mutatesSession":true,"writesFilesystem":false,"launchesProcess":false,"accessesNe
Line truncated
+  '{"catalog":[{"name":"address_name","analysisOperation":"address_name","title":"Address Name","description":"Resolve the primary analyzed name at a code or data address. Headless providers require an explicit address; GUI providers may default to their current cursor. Null means the provider has no primary name at that address.","kind":"official-proxy","requiresSession":false,"inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"document":{"description":"The document name","type":"string"},"address":{"type":"string","description":"A provider-normalized address; default memory uses 0x-prefixed hexadecimal"},"unknown_registry_approved":{"description":"Explicit approval to record typed capability unavailability as a residual unknown","type":"boolean","const":true}},"additionalProperties":false,"examples":[{}]},"outputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"result":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary structured result returned by this operation."},"evidence_id":{"type":"string","pattern":"^ev_[a-f0-9]{64}$","description":"Stable identifier of the recorded Evidence v2 observation."},"evidence_uri":{"type":"string","pattern":"^rea:\\\\/\\\\/evidence\\\\/ev_[a-f0-9]{64}$","description":"Session resource URI for the recorded Evidence v2 observation."}},"required":["result","evidence_id","evidence_uri"],"additionalProperties":false},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"effects":{"mutatesTarget":false,"mutatesSession":true,"writesFilesystem":false,"launchesProcess":false,"accessesNetwork":false,"changesUiState":false,"mayDiscardData":false,"idempotent":true}},{"name":"comment","analysisOperation":"comment","title":"Comment","description":"Read the regular analysis comment at an address, defaulting to the current cursor. This is read-only and returns null when no comment exists; use set_comment to persist a finding.","kind":"official-proxy","requiresSession":false,"inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"document":{"description":"The document name","type":"string"},"address":{"type":"string","description":"A provider-normalized address; default memory uses 0x-prefixed hexadecimal"},"unknown_registry_approved":{"description":"Explicit approval to record typed capability unavailability as a residual unknown","type":"boolean","const":true}},"additionalProperties":false,"examples":[{}]},"outputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"result":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary structured result returned by this operation."},"evidence_id":{"type":"string","pattern":"^ev_[a-f0-9]{64}$","description":"Stable identifier of the recorded Evidence v2 observation."},"evidence_uri":{"type":"string","pattern":"^rea:\\\\/\\\\/evidence\\\\/ev_[a-f0-9]{64}$","description":"Session resource URI for the recorded Evidence v2 observation."}},"required":["result","evidence_id","evidence_uri"],"additionalProperties":false},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"effects":{"mutatesTarget":false,"mutatesSession":true,"writesFilesystem":false,"launchesProcess":false,"accessesNetwork":false,"changesUiState":false,"mayDiscardData":false,"idempotent":true}},{"name":"current_address","analysisOperation":"current_address","title":"Current Address","description":"Return Hopper\'s current cursor address for the selected document. Use only for interactive navigation state; prefer explicit addresses in reproducible investigations.","kind":"official-proxy","requiresSession":false,"inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"document":{"description":"The document name","type":"string"},"unknown_registry_approved":{"description":"Explicit approval to record typed capability unavailability as a residual unknown","type":"boolean","const":true}},"additionalProperties":false,"examples":[{}]},"outputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"result":{"type":"string","description":"Primary structured result returned by this operation."},"evidence_id":{"type":"string","pattern":"^ev_[a-f0-9]{64}$","description":"Stable identifier of the recorded Evidence v2 observation."},"evidence_uri":{"type":"string","pattern":"^rea:\\\\/\\\\/evidence\\\\/ev_[a-f0-9]{64}$","description":"Session resource URI for the recorded Evidence v2 observation."}},"required":["result","evidence_id","evidence_uri"],"additionalProperties":false},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"effects":{"mutatesTarget":false,"mutatesSession":true,"writesFilesystem":false,"launchesProcess":false,"accessesNe
Line truncated
 const generatedPayload: unknown = JSON.parse(GENERATED_PAYLOAD_JSON);
 if (!isGeneratedPayload(generatedPayload))
  throw new TypeError("Generated MCP catalog payload is invalid");