From 41681742ccea83a7956e7bc303da4aa223ed4877 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Tue, 29 Sep 2026 17:36:59 +0800 Subject: [PATCH] docs(tools): clarify complete inline workflows --- docs/javascript-application-graph.md | 5 ++-- docs/javascript-application-workflows.md | 13 +++++----- docs/javascript-runtime-reconciliation.md | 17 +++++------- docs/mcp-contracts.md | 5 ++-- docs/product-catalog.json | 4 +-- skills/reverse-engineer-anything/SKILL.md | 2 +- .../references/javascript-applications.md | 26 +++++++++---------- 7 files changed, 31 insertions(+), 41 deletions(-) diff --git a/docs/javascript-application-graph.md b/docs/javascript-application-graph.md index 9446478c6d..d62552cbf0 100644 --- a/docs/javascript-application-graph.md +++ b/docs/javascript-application-graph.md @@ -159,9 +159,8 @@ so callers cannot preserve a stale ID after changing semantic content. ## Structure -The graph does not impose aggregate caps on roots, nodes, edges, or observations. -Each properties object is valid JSON with at most 64 keys, depth 6, 512 -structural nodes, and 4,096 characters per string. Field-specific validation +The graph does not impose aggregate caps on roots, nodes, edges, observations, +or JSON properties. Properties must be valid JSON; field-specific validation still applies to paths, identifiers, and evidence values. Extractors report actual omissions in coverage instead of silently dropping a prefix. diff --git a/docs/javascript-application-workflows.md b/docs/javascript-application-workflows.md index 16414e0e18..ccc0dd5725 100644 --- a/docs/javascript-application-workflows.md +++ b/docs/javascript-application-workflows.md @@ -49,7 +49,7 @@ The extractor covers lexical definitions and reads, literal seeds, static property slots, object reads/writes/spreads/destructuring, closure captures, uniquely resolved local calls, argument/return flow, and explicit Promise construction, chaining, aggregation, await, return, assignment, and -detachment. It also recovers bounded static candidates for EventEmitter +detachment. It also recovers static candidates for EventEmitter registrations/removals and dispatch, Node timers and cancellation handles, asynchronous `node:child_process` creation and ownership, configuration sources and direct defaults, request construction and response consumers, parse/coercion/ @@ -58,9 +58,9 @@ validation boundaries, and built-in resource acquisition/release. Function fingerprints commit normalized syntax, control-flow shape, relation shape, literal sets, arity, and detected effects without using local names or source offsets. Equal duplicate fingerprints remain ambiguous. Dynamic -calls/properties/names, parser recovery, unresolved handles, unsupported API -shapes, and every reached bound stay explicit unknowns; a missing relation is -never reported as proven behavioral absence. +calls/properties/names, parser recovery, unresolved handles, and unsupported API +shapes stay explicit unknowns; a missing relation is never reported as proven +behavioral absence. Semantic relations use static-inference authority. `resolved` means the static target identity was unique within admitted analysis; it does not mean the path @@ -122,9 +122,8 @@ relationships recovered by the AST analysis. Direct return expressions, including expression-bodied arrows, are evaluated through an execution-free value lattice. Literal object fields and direct -return sites are retained without count quotas. Calls, dynamic spreads, -computed keys, parser recovery, and the value-recursion depth guard remain -partial or unknown. +return sites are represented in the result. Calls, dynamic spreads, computed +keys, and parser recovery remain partial or unknown. Nested callable returns are not assigned to their parent callable. Projected graph observations carry source ranges but never source text. diff --git a/docs/javascript-runtime-reconciliation.md b/docs/javascript-runtime-reconciliation.md index 8ee62aa5a0..cdd340079f 100644 --- a/docs/javascript-runtime-reconciliation.md +++ b/docs/javascript-runtime-reconciliation.md @@ -47,12 +47,7 @@ are complete Evidence objects, not only evidence IDs: ] } ], - "runtime_observations": ["INSPECT_WEB_PAGE_EVIDENCE"], - "limits": { - "max_runtime_entities": 10000, - "max_reconciliation_items": 20000, - "max_static_load_states": 20000 - } + "runtime_observations": ["INSPECT_WEB_PAGE_EVIDENCE"] } ``` @@ -101,13 +96,13 @@ nodes. REA evaluates compatible static candidates conservatively: 3. Without captured bytes, one unique mapped artifact path can produce a medium-confidence location match. 4. Multiple candidates remain `ambiguous`; no `observed_as` edge is emitted. - `candidate_static_count` reports the full qualified layer/node count while - `candidate_static_nodes` retains a deterministic bounded prefix. + `candidate_static_count` reports the full qualified layer/node count, and + `candidate_static_nodes` includes every unique candidate reference. 5. If captured bytes disagree with the static candidate at the mapped path, the result is an explicit mismatch. A path never overrides a digest disagreement. -6. Missing authorization mappings, incomplete input coverage, and output - limits remain unknown or truncated rather than becoming absence claims. +6. Missing authorization mappings and incomplete or truncated input coverage + remain unknown or truncated rather than becoming absence claims. Every successful cross-layer `observed_as` edge has `authority: cross-layer-reconciliation` and `state: inferred`. The underlying @@ -124,7 +119,7 @@ classification: - `resident-in-loaded-asset` means a containing asset was observed, but the embedded module was not independently observed or shown to execute; - `not-observed-in-capture` means the entity did not appear in the complete - bounded captures supplied to this call and its artifact path falls beneath + authorized captures supplied to this call and its artifact path falls beneath an exercised automatic or operator-declared mapping prefix; - `unknown` covers incomplete captures, layers outside runtime scope, and unresolved correspondence. Nodes outside a mapped artifact prefix stay diff --git a/docs/mcp-contracts.md b/docs/mcp-contracts.md index f299da833a..70fdb738c3 100644 --- a/docs/mcp-contracts.md +++ b/docs/mcp-contracts.md @@ -58,9 +58,8 @@ shutdown rules still apply; REA never kills a process it cannot prove it owns. ## Tool results Evidence-producing tools return their result and Evidence context inline. Read -that result directly; do not fetch a bundle or resource to inspect it. Use -`get_evidence_bundle` only when the task explicitly needs broader retained -session history or a bundle for transfer. +that result directly. Use `get_evidence_bundle` when the task needs broader +retained session history or an explicit bundle for transfer. ## Aggregate native context diff --git a/docs/product-catalog.json b/docs/product-catalog.json index 3776a82c23..54e846f92a 100644 --- a/docs/product-catalog.json +++ b/docs/product-catalog.json @@ -501,9 +501,9 @@ "mcp_prompts": 6 }, "digests": { - "tools_sha256": "dcc3c3dbe9068ac7ec6774552ca309faaf0a6f5f992dd857b3dffea47f7bbf31", + "tools_sha256": "37c7ca2a93d9c78dd5372b88db55626d7ee5474bbb1b82477d14363631d68ddf", "prompts_sha256": "fa889fc671185ac9c968c6dc8309cf609e709cdc837dbbf39b7cdfadb84ac2d7", - "combined_sha256": "10ddf103b5e479182562331658d8bb5f128e356002ddb40431371af1a1cf7794", + "combined_sha256": "64e291ccdfb45d454eb084b2944e94d5b46fbdec61802cff95ad6bd420125526", "providers_sha256": "7247eece8fad09c8023af8d5c682d223d7ed7ebd68eac79e9154962a7e03b66b" } } diff --git a/skills/reverse-engineer-anything/SKILL.md b/skills/reverse-engineer-anything/SKILL.md index 5df0f4ff65..e8e686dd30 100644 --- a/skills/reverse-engineer-anything/SKILL.md +++ b/skills/reverse-engineer-anything/SKILL.md @@ -4,7 +4,7 @@ description: Reverse engineer native, managed, Electron/JavaScript, packaged, an metadata: version: "23" tool_count: 111 - catalog_digest: "10ddf103b5e479182562331658d8bb5f128e356002ddb40431371af1a1cf7794" + catalog_digest: "64e291ccdfb45d454eb084b2944e94d5b46fbdec61802cff95ad6bd420125526" --- # REA diff --git a/skills/reverse-engineer-anything/references/javascript-applications.md b/skills/reverse-engineer-anything/references/javascript-applications.md index 9b6d8aea04..195e05f1ba 100644 --- a/skills/reverse-engineer-anything/references/javascript-applications.md +++ b/skills/reverse-engineer-anything/references/javascript-applications.md @@ -1,12 +1,10 @@ # JavaScript and Electron application artifacts Use `analyze_javascript_application` directly on the operator-supplied ASAR or -extracted tree. It reads the selected local path without an approval flag or -configured investigation root. The complete result, graph, and Evidence context -are returned inline, so inspect them directly without fetching resource links. -Source-map contents are part of the static analysis. Start from its findings, -coverage, unknowns, and graph context, then make a focused follow-up only when a -specific question remains unanswered. +extracted tree. The complete result, graph, and Evidence context are returned +inline. Source-map contents are part of the static analysis. Start from its +findings, coverage, unknowns, and graph context, then make a focused follow-up +only when a specific question remains unanswered. BrowserWindow preferences, preload and contextBridge surfaces, IPC registrations, utility processes, and native binding requests are static syntax @@ -17,8 +15,8 @@ registration, defaults, or policy enforcement from static analysis. Use `trace_application_feature` on existing application Evidence for one literal node ID, route, string, API, IPC channel, module, or native export. -Choose a direction and finite bounds. Link Hopper or Ghidra Evidence only when -the exact artifact digest matches. +Choose a direction and include the complete application Evidence inline. Include +Hopper or Ghidra Evidence only when its artifact digest matches exactly. For version comparison, analyze each version once, then call `compare_application_versions`. Accept only its digest, source-map, structural @@ -29,9 +27,9 @@ opposite-side coverage; otherwise report unknown. When the question asks how one exact exported callable's returned object shape changed, analyze each version once and then call `compare_javascript_export_shapes` with explicit module paths and export names. -Use the Evidence IDs returned by the two analysis calls. Accept variant pairing -only through the tool's unique exact literal discriminant. Cite the comparison -Evidence and report JSON Pointer changes; dynamic values, ambiguous variants, -and incomplete parent-property coverage stay unknown. This is static inference, -not runtime behavior. Use `run_controlled_replay` separately only when the user -needs approved runtime semantics. +Include the complete Evidence records from both analysis calls. Accept variant +pairing only through the tool's unique exact literal discriminant. Cite the +comparison Evidence and report JSON Pointer changes; dynamic values, ambiguous +variants, and incomplete parent-property coverage stay unknown. This is static +inference, not runtime behavior. Use `run_controlled_replay` separately only +when the user needs approved runtime semantics.