rea-agents 4.0.1 → 5.0.0

package/dist/contracts/applicationToolContracts.js

@@ -1,15 +1,18 @@
-import { applicationVersionComparisonResultSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
-import { applicationFeatureTraceResultSchema } from "../domain/javascriptFeatureTraceSchemas.js";
-import { javaScriptSemanticTraceResultSchema } from "../domain/javascriptSemanticTraceSchemas.js";
-import { javaScriptExportShapeComparisonResultSchema } from "../domain/javascriptExportShapeComparisonSchemas.js";
-import { sourceToBundleComparisonResultSchema } from "../domain/sourceToBundleComparisonSchemas.js";
-import { compareApplicationVersionsRequestSchema, compareJavaScriptExportShapesRequestSchema, compareSourceToBundleRequestSchema, traceApplicationFeatureRequestSchema, traceJavaScriptSemanticsRequestSchema, } from "./applicationWorkflowInputContracts.js";
-import { reconstructionCoverageEvaluationInputSchema } from "../application/ReconstructionCoverageService.js";
+import { applicationVersionComparisonResultSchema } from "../domain/javascript/javascriptApplicationVersionComparisonSchemas.js";
+import { applicationFeatureTraceResultSchema } from "../domain/javascript/javascriptFeatureTraceSchemas.js";
+import { javaScriptSemanticTraceResultSchema } from "../domain/javascript/javascriptSemanticTraceSchemas.js";
+import { javaScriptExportShapeComparisonResultSchema } from "../domain/javascript/javascriptExportShapeComparisonSchemas.js";
+import { sourceToBundleComparisonResultSchema } from "../domain/javascript/sourceToBundleComparisonSchemas.js";
+import { compareApplicationVersionsRequestSchema, compareJavaScriptExportShapesRequestSchema, compareSourceToBundleRequestSchema, traceApplicationFeatureRequestSchema, traceJavaScriptSemanticsRequestSchema, } from "./javascript/applicationWorkflowInputContracts.js";
+import { reconstructionCoverageEvaluationInputSchema } from "../domain/reconstructionCoverageInput.js";
 import { reconstructionClosureResultSchema } from "../domain/reconstructionCoverage.js";
 import { reconstructionObligationLedgerInputSchema, reconstructionObligationLedgerSchema, } from "../domain/reconstructionObligationLedgerSchemas.js";
+import { androidApplicationProjectionInputSchema, androidApplicationProjectionResultSchema, } from "../domain/android/androidApplication.js";
+import { appleApplicationProjectionInputSchema, appleApplicationProjectionResultSchema, } from "../domain/apple/appleApplication.js";
 import { toolContractMetadata } from "./toolEffects.js";
 import { evidenceResultOf } from "./toolOutputSchemas.js";
-import { JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE, JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE, JAVASCRIPT_FEATURE_TRACE_EXAMPLE, SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE, } from "./javascriptApplicationWorkflowExamples.js";
+import { JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE, JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE, JAVASCRIPT_FEATURE_TRACE_EXAMPLE, SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE, } from "./javascript/javascriptApplicationWorkflowExamples.js";
+import { ANDROID_APPLICATION_GRAPH_EXAMPLE, APPLE_APPLICATION_GRAPH_EXAMPLE, MACOS_APPLICATION_GRAPH_EXAMPLE, } from "./mobileApplicationGraphExamples.js";
 const traceOutputSchema = evidenceResultOf(applicationFeatureTraceResultSchema);
 const semanticTraceOutputSchema = evidenceResultOf(javaScriptSemanticTraceResultSchema);
 const comparisonOutputSchema = evidenceResultOf(applicationVersionComparisonResultSchema);
@@ -17,12 +20,16 @@ const sourceToBundleOutputSchema = evidenceResultOf(sourceToBundleComparisonResu
 const exportShapeComparisonOutputSchema = evidenceResultOf(javaScriptExportShapeComparisonResultSchema);
 const reconstructionObligationLedgerOutputSchema = evidenceResultOf(reconstructionObligationLedgerSchema);
 const HASH = "0".repeat(64);
+const retained = (evidence_id) => ({
+    kind: "retained-evidence",
+    evidence_id,
+});
 /** Provider-neutral graph workflow contracts shared by MCP and CLI adapters. */
 export const APPLICATION_TOOL_CONTRACTS = [
     {
         name: "trace_application_feature",
         ...toolContractMetadata("trace_application_feature"),
-        description: "Trace a typed literal seed through every reachable part of an authenticated JavaScript Application Graph supplied as inline Evidence. Original static, native, passive-runtime, inferred, and unknown authorities remain distinct; native addon handoffs never open a provider or execute the application.",
+        description: "Trace a typed literal seed through every reachable part of an authenticated JavaScript Application Graph supplied as inline Evidence or exact same-session retained references. Original static, native, passive-runtime, inferred, and unknown authorities remain distinct; native addon handoffs never open a provider or execute the application.",
         kind: "application",
         inputSchema: traceApplicationFeatureRequestSchema,
         outputSchema: traceOutputSchema,
@@ -31,12 +38,19 @@ export const APPLICATION_TOOL_CONTRACTS = [
                 title: "Trace one module seed through a retained application graph",
                 input: JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
             },
+            {
+                title: "Use exact Evidence already retained in this session",
+                input: {
+                    ...JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
+                    application: retained(JAVASCRIPT_FEATURE_TRACE_EXAMPLE.application.evidence_id),
+                },
+            },
         ],
     },
     {
         name: "trace_javascript_semantics",
         ...toolContractMetadata("trace_javascript_semantics"),
-        description: "Trace static JavaScript data-flow, direct call/return, and closure relations from inline application Evidence. Dynamic or unsupported semantics remain explicit unknowns; static reachability never claims runtime execution.",
+        description: "Trace static JavaScript data-flow, direct call/return, and closure relations from inline application Evidence or an exact same-session retained reference. Dynamic or unsupported semantics remain explicit unknowns; static reachability never claims runtime execution.",
         kind: "application",
         inputSchema: traceJavaScriptSemanticsRequestSchema,
         outputSchema: semanticTraceOutputSchema,
@@ -56,7 +70,7 @@ export const APPLICATION_TOOL_CONTRACTS = [
     {
         name: "compare_application_versions",
         ...toolContractMetadata("compare_application_versions"),
-        description: "Compare two authenticated JavaScript Application Graph versions supplied as inline Evidence. Uses unique-only exact digest, module source digest, source-map identity, structural fingerprint, and non-module semantic-key tiers. Reports added, removed, changed, ambiguous, and unknown entities plus the complete matching changed_from graph without fuzzy or module-ordinal pairing.",
+        description: "Compare two authenticated JavaScript Application Graph versions supplied as inline Evidence or exact same-session retained references. Uses unique-only exact digest, module source digest, source-map identity, structural fingerprint, and non-module semantic-key tiers. Reports added, removed, changed, ambiguous, and unknown entities plus the complete matching changed_from graph without fuzzy or module-ordinal pairing.",
         kind: "application",
         inputSchema: compareApplicationVersionsRequestSchema,
         outputSchema: comparisonOutputSchema,
@@ -65,12 +79,20 @@ export const APPLICATION_TOOL_CONTRACTS = [
                 title: "Compare authenticated static and reconciled application graphs",
                 input: JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
             },
+            {
+                title: "Use exact Evidence already retained in this session",
+                input: {
+                    ...JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
+                    left: retained(JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE.left.evidence_id),
+                    right: retained(JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE.right.evidence_id),
+                },
+            },
         ],
     },
     {
         name: "compare_source_to_bundle",
         ...toolContractMetadata("compare_source_to_bundle"),
-        description: "Compare a cryptographically committed HistoricalSourceGraph with inline authenticated JavaScript Application Graph Evidence. Uses explicit exact-digest, source-map path, current-path, suffix, and basename signals with stable weights. Classifies unchanged, modified, removed, split, merged, duplicated, and unknown; incomplete coverage and ambiguous weak signals never become absence or forced matches.",
+        description: "Compare a cryptographically committed HistoricalSourceGraph with authenticated JavaScript Application Graph Evidence supplied inline or by exact same-session retained reference. Uses explicit exact-digest, source-map path, current-path, suffix, and basename signals with stable weights. Classifies unchanged, modified, removed, split, merged, duplicated, and unknown; incomplete coverage and ambiguous weak signals never become absence or forced matches.",
         kind: "application",
         inputSchema: compareSourceToBundleRequestSchema,
         outputSchema: sourceToBundleOutputSchema,
@@ -84,7 +106,7 @@ export const APPLICATION_TOOL_CONTRACTS = [
     {
         name: "compare_javascript_export_shapes",
         ...toolContractMetadata("compare_javascript_export_shapes"),
-        description: "Compare static return shapes for one exact module/export selector on each authenticated JavaScript Application Graph supplied as inline Evidence. Variants pair only by reciprocal unique literal discriminants; dynamic values, incomplete properties, and ambiguous variants remain unknown. Reports JSON Pointer changes without executing JavaScript; runtime behavior requires a separate agent-run probe.",
+        description: "Compare static return shapes for one exact module/export selector on each authenticated JavaScript Application Graph supplied as inline Evidence or exact same-session retained references. Variants pair only by reciprocal unique literal discriminants; dynamic values, incomplete properties, and ambiguous variants remain unknown. Reports JSON Pointer changes without executing JavaScript; runtime behavior requires a separate agent-run probe.",
         kind: "application",
         inputSchema: compareJavaScriptExportShapesRequestSchema,
         outputSchema: exportShapeComparisonOutputSchema,
@@ -93,6 +115,14 @@ export const APPLICATION_TOOL_CONTRACTS = [
                 title: "Compare one exact parser export without execution",
                 input: JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE,
             },
+            {
+                title: "Use exact Evidence already retained in this session",
+                input: {
+                    ...JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE,
+                    left: retained(JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE.left.evidence_id),
+                    right: retained(JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE.right.evidence_id),
+                },
+            },
         ],
     },
     {
@@ -174,6 +204,38 @@ export const APPLICATION_TOOL_CONTRACTS = [
             },
         ],
     },
+    {
+        name: "project_android_application_graph",
+        ...toolContractMetadata("project_android_application_graph"),
+        description: "Project authenticated APK inventory_artifact Evidence into an execution-free Android application inventory. Reports exact component paths and hashes, runtime-family hints, and path-based bridge hypotheses without decoding DEX, executing the APK, or claiming observed runtime calls.",
+        kind: "application",
+        inputSchema: androidApplicationProjectionInputSchema,
+        outputSchema: evidenceResultOf(androidApplicationProjectionResultSchema),
+        examples: [
+            {
+                title: "Project APK inventory Evidence into an Android application graph",
+                input: ANDROID_APPLICATION_GRAPH_EXAMPLE,
+            },
+        ],
+    },
+    {
+        name: "project_apple_application_graph",
+        ...toolContractMetadata("project_apple_application_graph"),
+        description: "Project authenticated IPA, macOS .app directory, ZIP, or DMG inventory Evidence into an execution-free Apple application inventory. Reports application roots, nested bundles with path-convention roles (app extensions, XPC services, login items, privileged helpers, system extensions, frameworks), launchd plists, exact component paths and hashes, runtime-family hints, and path-based bridge hypotheses without parsing plist/CMS semantics or claiming observed runtime calls.",
+        kind: "application",
+        inputSchema: appleApplicationProjectionInputSchema,
+        outputSchema: evidenceResultOf(appleApplicationProjectionResultSchema),
+        examples: [
+            {
+                title: "Project IPA inventory Evidence into an Apple application graph",
+                input: APPLE_APPLICATION_GRAPH_EXAMPLE,
+            },
+            {
+                title: "Project a macOS .app directory inventory into its bundle anatomy",
+                input: MACOS_APPLICATION_GRAPH_EXAMPLE,
+            },
+        ],
+    },
 ];
 export function applicationToolContract(name) {
     const contract = APPLICATION_TOOL_CONTRACTS.find(({ name: candidate }) => candidate === name);

package/dist/contracts/artifactComparisonExample.js

@@ -1,11 +1,10 @@
-import { createHash } from "node:crypto";
-import canonicalize from "canonicalize";
+import { canonicalDigest } from "../domain/comparisonSemantics.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 const inventory = (digit) => {
     const sha = digit.repeat(64);
-    const artifactId = `art_${digestCanonical({ sha256: sha })}`;
-    const occurrenceId = `occ_${digestCanonical({ root: artifactId })}`;
+    const artifactId = `art_${canonicalDigest({ sha256: sha }, "Artifact example")}`;
+    const occurrenceId = `occ_${canonicalDigest({ root: artifactId }, "Artifact example")}`;
     const nodes = [
         {
             artifact_id: artifactId,
@@ -36,18 +35,18 @@ const inventory = (digit) => {
             limitations: [],
         },
     ];
-    const graphSha256 = digestCanonical({
+    const graphSha256 = canonicalDigest({
         nodes,
         occurrences,
         edges: [],
         integrity_contradictions: [],
-    });
+    }, "Artifact example");
     return jsonValueSchema.parse({
         manifest: {
-            manifest_id: `agm_${digestCanonical({
+            manifest_id: `agm_${canonicalDigest({
                 root_artifact_id: artifactId,
                 graph_sha256: graphSha256,
-            })}`,
+            }, "Artifact example")}`,
             root_artifact_id: artifactId,
             root_sha256: sha,
             root_format: "file",
@@ -63,12 +62,6 @@ const inventory = (digit) => {
         limitations: [],
     });
 };
-const digestCanonical = (value) => {
-    const encoded = canonicalize(value);
-    if (encoded === undefined)
-        throw new TypeError("Artifact example is not canonical JSON");
-    return createHash("sha256").update(encoded).digest("hex");
-};
 const provider = {
     id: "rea-artifact",
     name: "REA artifact graph",

package/dist/contracts/artifactToolContracts.js

@@ -3,8 +3,8 @@ import { artifactOutputSchemas } from "./toolOutputSchemas.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { toolContractMetadata } from "./toolEffects.js";
 import { requireOutputSchema } from "./toolOutputSchemaPrimitives.js";
-import { appleAssetCatalogInputSchema } from "../domain/appleAssetCatalog.js";
-import { keyedArchiveInputSchema } from "../domain/keyedArchive.js";
+import { appleAssetCatalogInputSchema } from "../domain/apple/appleAssetCatalog.js";
+import { keyedArchiveInputSchema } from "../domain/apple/keyedArchive.js";
 /** Exact caller boundary for deterministic artifact inventory. */
 export const artifactInventoryInputSchema = z.strictObject({
     integrity_policy: z.enum(["fail", "record-and-continue"]).default("fail"),

package/dist/contracts/browserScenarioToolContracts.js

@@ -21,7 +21,7 @@ export const BROWSER_SCENARIO_TOOL_CONTRACTS = [
     {
         name: "capture_browser_scenario",
         ...toolContractMetadata("capture_browser_scenario"),
-        description: "Run a controlled browser scenario when passive observation cannot exercise the application. Launch the selected executable or connect to a loopback CDP target, provide a start URL and actions, and select storage or artifacts when needed. Environment, empty storage, and a URL-only final capture are defaults; provide initial storage or additional artifacts when needed. Agents can run their own local fixture servers to control application responses. Actions run until completion or cancellation unless timeout_ms is set. Results are returned inline.",
+        description: "Run a controlled browser scenario when passive observation cannot exercise the application. Launch the selected executable or connect to a loopback CDP target, provide a start URL and actions, and select storage or artifacts when needed. Environment, empty storage, and a URL-only final capture are defaults. capture.network selects request_body, response_body, and header_values independently; selected content is returned inline with transaction and event references, byte digests, and explicit unavailable states. Credentials and declared secrets are redacted. Agents can run their own local fixture servers to control application responses. Actions run until completion or cancellation unless timeout_ms is set. Results are returned inline.",
         kind: "browser-provider",
         inputSchema: browserScenarioInputSchema,
         outputSchema: evidenceResultOf(browserScenarioCaptureSchema),

package/dist/contracts/enhancedInputs.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { nativeValueTraceInputSchema } from "../domain/nativeValueTrace.js";
+import { nativeValueTraceInputSchema } from "../domain/native/nativeValueTrace.js";
 const traceLiteralInputSchema = z.strictObject({
     query: z.string().min(1),
     case_sensitive: z.boolean().default(false),

package/dist/contracts/enhancedToolContracts.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { enhancedInputSchemas } from "./enhancedInputs.js";
+import { enhancedOutputSchemas, requireOutputSchema, } from "./toolOutputSchemas.js";
+import { examplesFor } from "./toolContractHelpers.js";
+import { toolContractMetadata } from "./toolEffects.js";
+import { FUNCTION_WORKFLOW_TOOL_CONTRACTS } from "./functionWorkflowToolContracts.js";
+const enhanced = (name, description, inputSchema) => ({
+    name,
+    ...toolContractMetadata(name),
+    description,
+    kind: "enhanced",
+    inputSchema,
+    outputSchema: requireOutputSchema(enhancedOutputSchemas, name),
+    examples: examplesFor(name, inputSchema),
+});
+/** Workflow tools composed from one or more provider operations. */
+export const ENHANCED_TOOL_CONTRACTS = [
+    enhanced("inspect_native_dispatch_metadata", "Inspect the bound provider's name inventory for Objective-C class/method symbols and Swift mangled symbols, returning at most max_records decoded names. Includes target SHA-256 when available, provider identity/version, analysis-profile digest, facet coverage, and per-record Evidence. This is symbol-level evidence, not runtime metadata: ivar layouts, protocol conformances, witness/class tables, and relative pointers are explicitly marked unsupported unless a provider supplies those decoders. The provider controls how its name inventory is acquired.", enhancedInputSchemas.inspect_native_dispatch_metadata),
+    enhanced("get_objc_classes", "Discover and deduplicate Objective-C class labels, optionally filtering by literal substring.", enhancedInputSchemas.get_objc_classes),
+    enhanced("get_objc_protocols", "Discover and deduplicate Objective-C and Swift protocol labels.", enhancedInputSchemas.get_objc_protocols),
+    enhanced("batch_decompile", "Decompile each explicit procedure symbol or address concurrently. Returns ordered per-item success or error results and aggregate counts.", enhancedInputSchemas.batch_decompile),
+    enhanced("get_call_graph", "Traverse the bound provider's caller or callee relationships from one symbol or address until the reachable graph is exhausted. Every node has an ok/error status and failures use safe typed projections; unresolved indirect calls may be missing and results are not a whole-program CFG.", enhancedInputSchemas.get_call_graph),
+    enhanced("analyze_swift_types", 'Categorize analyzed procedure names into Swift classes, structs, enums, protocols, extensions, and other symbols. Returns deduplicated names grouped with counts. Optionally select one category and/or apply a case-sensitive literal name filter; for example, use {category: "classes", pattern: "Account"} to find matching class symbols.', enhancedInputSchemas.analyze_swift_types),
+    enhanced("find_xrefs_to_name", "Resolve an exact name against the bound provider's name inventory and return a resolved or unresolved result. Unresolved names use the stable name_not_found reason; this xref workflow returns address-only projections.", enhancedInputSchemas.find_xrefs_to_name),
+    enhanced("binary_overview", "Return native-binary metadata, every segment with its length, and exhaustive procedure/string counts. Use search_procedures, list_procedures, or analyze_function directly when you already know which procedure to inspect.", enhancedInputSchemas.binary_overview),
+    ...FUNCTION_WORKFLOW_TOOL_CONTRACTS,
+    enhanced("trace_feature", "Trace a literal feature query through every matching string and procedure, their xrefs, and truthful containing-procedure resolution. Returns observations, operation count, and residual unknowns without inferring reference kinds.", enhancedInputSchemas.trace_feature),
+    enhanced("trace_call_path", "Trace direct callers or callees from one exact procedure address until the graph is exhausted or the optional goal is reached. Returns visited nodes, direct-call edges, a shortest traversal path, provider failures, and residual unknowns; unresolved indirect calls remain unknown.", enhancedInputSchemas.trace_call_path),
+    enhanced("trace_native_ui_action", "Trace one unique compiled UI action, object ID, native symbol or exact function address through authored connections, encoded or symbolized Objective-C handlers, and bounded static call references. Typed direct and resolved indirect calls, ambiguous candidates, inferred untyped provider callees, and targetless sites remain distinct. Runtime reachability is unknown; use trace_native_values for recovered value dependencies.", enhancedInputSchemas.trace_native_ui_action),
+    enhanced("trace_native_values", "Trace a bounded static dependency graph from one explicit native procedure. Includes high-p-code def-use, constants, operators, memory and branch operations, resolved call edges, and derived argument/parameter and return/output bindings. Missing bindings, alias semantics, persistent state and RNG roles remain unknown. Budgets bound depth, decompilations, graph size and payloads; nodes are paginated.", enhancedInputSchemas.trace_native_values),
+];

package/dist/contracts/errorSchemas.js

@@ -56,14 +56,16 @@ export const analysisErrorProjectionSchema = z.discriminatedUnion("code", [
     generic("target_unavailable"),
     generic("execution_failure"),
 ]);
-/** Legacy CLI envelope: a human label plus the canonical projected error fields. */
+/** CLI label and input diagnostics surrounding the strict canonical error projection. */
 export const analysisCliErrorEnvelopeSchema = z
     .object({
     error: z.string().min(1),
+    input_path: z.string().optional(),
+    input_reason: z.enum(["invalid-json", "read-failed"]).optional(),
 })
     .passthrough()
     .superRefine((value, context) => {
-    const { error: _label, ...projection } = value;
+    const { error: _label, input_path: _inputPath, input_reason: _inputReason, ...projection } = value;
     const parsed = analysisErrorProjectionSchema.safeParse(projection);
     if (!parsed.success) {
         context.addIssue({

package/dist/contracts/evidenceInputContracts.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { evidenceSchema } from "../domain/evidence.js";
+import { prefixedDigestSchema } from "../domain/digests.js";
+/** Exact reference to Evidence already retained by the current session. */
+export const retainedEvidenceReferenceSchema = z.strictObject({
+    kind: z.literal("retained-evidence"),
+    evidence_id: prefixedDigestSchema("ev"),
+});
+/** Portable inline Evidence or an exact, session-scoped reference. */
+export const evidenceInputSchema = z.union([
+    evidenceSchema,
+    retainedEvidenceReferenceSchema,
+]);

package/dist/contracts/firmware/firmwareToolContracts.js

@@ -0,0 +1,38 @@
+import { firmwareInputSchemas, firmwareResultSchemas, } from "../../domain/firmware/firmwareAnalysis.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "../toolEffects.js";
+/** Explicit local firmware observations and extraction, backed by caller-supplied tools. */
+export const FIRMWARE_TOOL_CONTRACTS = [
+    {
+        name: "inspect_firmware_regions",
+        ...toolContractMetadata("inspect_firmware_regions"),
+        kind: "firmware-provider",
+        description: "Inspect signature candidates in a local firmware file with Binwalk 3.1.x (verified with 3.1.0). Returns offsets, reported lengths, descriptions and raw confidence values. Length validation and runtime addresses remain unknown. No extraction or target execution. Linux, caller-supplied tool and util-linux prlimit required; 128 MiB input limit, one worker and 120-second deadline.",
+        inputSchema: firmwareInputSchemas.inspect_firmware_regions,
+        outputSchema: evidenceResultOf(firmwareResultSchemas.inspect_firmware_regions),
+        examples: [
+            {
+                title: "Inspect firmware regions",
+                input: { path: "/tmp/firmware.bin" },
+            },
+        ],
+    },
+    {
+        name: "extract_firmware",
+        ...toolContractMetadata("extract_firmware"),
+        kind: "firmware-provider",
+        description: "Extract caller-selected firmware bytes with Unblob 26.6.x (verified with 26.6.4) into an absent output directory. Returns verified child paths/digests, task derivations, unknown chunks and extraction diagnostics inline. Preserves the default sandbox; publishes regular files only. Linux, caller-supplied tool, format-specific extractors and util-linux prlimit required. No mounts or extracted-code execution. Select a returned native file with open_binary for Ghidra analysis; decompressed offsets are not original-file addresses.",
+        inputSchema: firmwareInputSchemas.extract_firmware,
+        outputSchema: evidenceResultOf(firmwareResultSchemas.extract_firmware),
+        examples: [
+            {
+                title: "Extract selected firmware",
+                input: {
+                    path: "/tmp/firmware.bin",
+                    output_directory: "/tmp/firmware-output",
+                    range: { offset: 64, length: 4096 },
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/{applicationWorkflowInputContracts.js → javascript/applicationWorkflowInputContracts.js}

@@ -1,42 +1,42 @@
 import { z } from "zod";
-import { evidenceSchema } from "../domain/evidence.js";
-import { compareApplicationVersionsInputSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
-import { compareJavaScriptExportShapesInputSchema } from "../domain/javascriptExportShapeComparisonSchemas.js";
-import { traceApplicationFeatureInputSchema } from "../domain/javascriptFeatureTraceSchemas.js";
-import { javaScriptSemanticQueryInputSchema } from "../domain/javascriptSemanticQuerySchemas.js";
-import { compareSourceToBundleInputSchema } from "../domain/sourceToBundleComparisonSchemas.js";
+import { evidenceInputSchema } from "../evidenceInputContracts.js";
+import { compareApplicationVersionsInputSchema } from "../../domain/javascript/javascriptApplicationVersionComparisonSchemas.js";
+import { compareJavaScriptExportShapesInputSchema } from "../../domain/javascript/javascriptExportShapeComparisonSchemas.js";
+import { traceApplicationFeatureInputSchema } from "../../domain/javascript/javascriptFeatureTraceSchemas.js";
+import { javaScriptSemanticQueryInputSchema } from "../../domain/javascript/javascriptSemanticQuerySchemas.js";
+import { compareSourceToBundleInputSchema } from "../../domain/javascript/sourceToBundleComparisonSchemas.js";
 const traceApplicationFeatureFacts = {
     native_observations: traceApplicationFeatureInputSchema.shape.native_observations,
     seed: traceApplicationFeatureInputSchema.shape.seed,
     direction: traceApplicationFeatureInputSchema.shape.direction,
 };
-/** MCP/CLI trace request carrying all Evidence inline. */
+/** Application trace request accepting inline or same-session application Evidence. */
 export const traceApplicationFeatureRequestSchema = z.strictObject({
     ...traceApplicationFeatureFacts,
-    application: evidenceSchema,
+    application: evidenceInputSchema,
 });
-/** MCP/CLI semantic trace request carrying Evidence inline. */
+/** Semantic trace request accepting inline or same-session application Evidence. */
 export const traceJavaScriptSemanticsRequestSchema = z.strictObject({
-    application: evidenceSchema,
+    application: evidenceInputSchema,
     query: javaScriptSemanticQueryInputSchema,
 });
 const compareApplicationVersionsFacts = {
     left_native_observations: compareApplicationVersionsInputSchema.shape.left_native_observations,
     right_native_observations: compareApplicationVersionsInputSchema.shape.right_native_observations,
 };
-/** MCP/CLI comparison request carrying all Evidence inline. */
+/** Application comparison request accepting inline or same-session application Evidence. */
 export const compareApplicationVersionsRequestSchema = z.strictObject({
     ...compareApplicationVersionsFacts,
-    left: evidenceSchema,
-    right: evidenceSchema,
+    left: evidenceInputSchema,
+    right: evidenceInputSchema,
 });
 const compareSourceToBundleFacts = {
     reference: compareSourceToBundleInputSchema.shape.reference,
 };
-/** Historical-source comparison carrying application Evidence inline. */
+/** Historical-source comparison accepting inline or same-session application Evidence. */
 export const compareSourceToBundleRequestSchema = z.strictObject({
     ...compareSourceToBundleFacts,
-    application: evidenceSchema,
+    application: evidenceInputSchema,
 });
 const compareJavaScriptExportShapesFacts = {
     left_module_path: compareJavaScriptExportShapesInputSchema.shape.left_module_path,
@@ -44,9 +44,9 @@ const compareJavaScriptExportShapesFacts = {
     right_module_path: compareJavaScriptExportShapesInputSchema.shape.right_module_path,
     right_export_name: compareJavaScriptExportShapesInputSchema.shape.right_export_name,
 };
-/** MCP/CLI export-shape request carrying application Evidence inline. */
+/** Export-shape request accepting inline or same-session application Evidence. */
 export const compareJavaScriptExportShapesRequestSchema = z.strictObject({
     ...compareJavaScriptExportShapesFacts,
-    left: evidenceSchema,
-    right: evidenceSchema,
+    left: evidenceInputSchema,
+    right: evidenceInputSchema,
 });

package/dist/contracts/{electronToolContracts.js → javascript/electronToolContracts.js}

@@ -1,9 +1,9 @@
-import { toolContractMetadata } from "./toolEffects.js";
-import { evidenceResultOf } from "./toolOutputSchemas.js";
-import { electronPageInspectionSchema, electronTargetListSchema, inspectElectronPageInputSchema, listElectronTargetsInputSchema, } from "../domain/electronObservation.js";
-import { electronActiveObservationInputSchema, electronActiveObservationResultSchema, } from "../domain/electronActiveObservation.js";
-import { analyzeJavaScriptApplicationInputSchema, javascriptApplicationAnalysisResultSchema, } from "../domain/javascriptApplicationAnalysis.js";
-import { javascriptRuntimeReconciliationResultSchema, reconcileJavaScriptRuntimeInputSchema, } from "../domain/javascriptRuntimeReconciliationSchemas.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import { evidenceResultOf } from "../toolOutputSchemas.js";
+import { electronPageInspectionSchema, electronTargetListSchema, inspectElectronPageInputSchema, listElectronTargetsInputSchema, } from "../../domain/javascript/electronObservation.js";
+import { electronActiveObservationInputSchema, electronActiveObservationResultSchema, } from "../../domain/javascript/electronActiveObservation.js";
+import { analyzeJavaScriptApplicationInputSchema, javascriptApplicationAnalysisResultSchema, } from "../../domain/javascript/javascriptApplicationAnalysis.js";
+import { javascriptRuntimeReconciliationResultSchema, reconcileJavaScriptRuntimeInputSchema, } from "../../domain/javascript/javascriptRuntimeReconciliationSchemas.js";
 import { JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE } from "./javascriptRuntimeReconciliationExample.js";
 const listOutputSchema = evidenceResultOf(electronTargetListSchema);
 const inspectionOutputSchema = evidenceResultOf(electronPageInspectionSchema);

package/dist/contracts/{javascriptApplicationWorkflowExamples.js → javascript/javascriptApplicationWorkflowExamples.js}

@@ -1,7 +1,7 @@
-import { createEvidence } from "../domain/evidence.js";
-import { reconcileJavaScriptRuntime } from "../domain/javascriptRuntimeReconciliation.js";
+import { createEvidence } from "../../domain/evidence.js";
+import { reconcileJavaScriptRuntime } from "../../domain/javascript/javascriptRuntimeReconciliation.js";
 import { JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE, JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE, } from "./javascriptRuntimeReconciliationExample.js";
-import { createHistoricalSourceGraph } from "../domain/referenceSourceGraph.js";
+import { createHistoricalSourceGraph } from "../../domain/referenceSourceGraph.js";
 const reconciliation = reconcileJavaScriptRuntime(JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE);
 const reconciliationEvidence = createEvidence(undefined, {
     id: "rea-javascript-runtime-reconciliation",

package/dist/contracts/javascript/javascriptRecoveryToolContracts.js

@@ -0,0 +1,23 @@
+import { javascriptRecoveryInputSchema, javascriptRecoveryResultSchema, } from "../../domain/javascript/javascriptRecovery.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+/** Derived script artifacts from optional upstream recovery adapters. */
+export const JAVASCRIPT_RECOVERY_TOOL_CONTRACTS = [
+    {
+        name: "recover_javascript_sources",
+        ...toolContractMetadata("recover_javascript_sources"),
+        kind: "application",
+        description: "Recover readable modules from one local UTF-8 JavaScript script/bundle into an absent directory, using caller-supplied Wakaru 1.13.0 on Linux x64. Returns original/derived digests, extraction byte ranges, emitted source maps, warnings and analysis_input inline. Structural splitting may fall back to one module; original names and runtime equivalence remain unknown. No application code execution. Requires util-linux prlimit; one worker, 1 GiB address-space ceiling, 120-second deadline, 64 MiB input, 128 MiB output, 10000 entries and 8 MiB per diagnostic/report stream.",
+        inputSchema: javascriptRecoveryInputSchema,
+        outputSchema: evidenceResultOf(javascriptRecoveryResultSchema),
+        examples: [
+            {
+                title: "Recover a captured production bundle",
+                input: {
+                    path: "/tmp/web-scripts/app.js",
+                    output_directory: "/tmp/recovered-app",
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/{javascriptRuntimeObservationToolContracts.js → javascript/javascriptRuntimeObservationToolContracts.js}

@@ -1,6 +1,6 @@
-import { toolContractMetadata } from "./toolEffects.js";
-import { evidenceResultOf } from "./toolOutputSchemas.js";
-import { javascriptRuntimeObservationSchema, javascriptRuntimeTargetListSchema, listJavaScriptRuntimeTargetsInputSchema, observeJavaScriptRuntimeInputSchema, } from "../domain/javascriptRuntimeObservation.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import { evidenceResultOf } from "../toolOutputSchemas.js";
+import { javascriptRuntimeObservationSchema, javascriptRuntimeTargetListSchema, listJavaScriptRuntimeTargetsInputSchema, observeJavaScriptRuntimeInputSchema, } from "../../domain/javascript/javascriptRuntimeObservation.js";
 const endpoint = "http://127.0.0.1:9229";
 /** Passive Node/Electron V8 Inspector discovery and observation contracts. */
 export const JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS = [

package/dist/contracts/{javascriptRuntimeReconciliationExample.js → javascript/javascriptRuntimeReconciliationExample.js}

@@ -1,8 +1,8 @@
-import { createEvidence } from "../domain/evidence.js";
-import { createJavaScriptApplicationGraph, createJavaScriptApplicationNode, } from "../domain/javascriptApplicationGraph.js";
-import { createWebTextArtifact } from "../domain/webContentArtifact.js";
-import { createJavaScriptSemanticGraph, createJavaScriptSemanticGraphNode, } from "../domain/javascriptSemanticGraph.js";
-import { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES } from "../domain/javascriptSemanticGraphSchemas.js";
+import { createEvidence } from "../../domain/evidence.js";
+import { createJavaScriptApplicationGraph, createJavaScriptApplicationNode, } from "../../domain/javascript/javascriptApplicationGraph.js";
+import { createWebTextArtifact } from "../../domain/webContentArtifact.js";
+import { createJavaScriptSemanticGraph, createJavaScriptSemanticGraphNode, } from "../../domain/javascript/javascriptSemanticGraph.js";
+import { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES } from "../../domain/javascript/javascriptSemanticGraphSchemas.js";
 const applicationSha256 = "1".repeat(64);
 const script = createWebTextArtifact("export const example = true;\n", "text/javascript");
 const inputPath = "/Applications/Example.app/Contents/Resources/app";

package/dist/contracts/{managedToolContracts.js → managed/managedToolContracts.js}

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { managedOutputSchemas } from "./toolOutputSchemas.js";
-import { toolContractMetadata } from "./toolEffects.js";
-import { requireOutputSchema } from "./toolOutputSchemaPrimitives.js";
+import { managedOutputSchemas } from "../toolOutputSchemas.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import { requireOutputSchema } from "../toolOutputSchemaPrimitives.js";
 /** Exact caller boundary for execution-free PE/CLI triage and identity. */
 const managedTargetInputSchema = z.object({
     path: z

package/dist/contracts/{managedWorkflowExamples.js → managed/managedWorkflowExamples.js}

@@ -1,4 +1,4 @@
-import { createEvidence } from "../domain/evidence.js";
+import { createEvidence } from "../../domain/evidence.js";
 const MANAGED_STATIC_EXAMPLE_PROVIDER = {
     id: "rea-dotnet-static",
     name: "REA managed static analysis provider",

package/dist/contracts/{managedWorkflowToolContracts.js → managed/managedWorkflowToolContracts.js}

@@ -1,10 +1,10 @@
 import { z } from "zod";
-import { evidenceSchema } from "../domain/evidence.js";
-import { managedReconstructionImportInputSchema } from "../domain/managedReconstruction.js";
-import { managedWorkflowOutputSchemas } from "./toolOutputSchemas.js";
+import { evidenceSchema } from "../../domain/evidence.js";
+import { managedReconstructionImportInputSchema } from "../../domain/managed/managedReconstruction.js";
+import { managedWorkflowOutputSchemas } from "../toolOutputSchemas.js";
 import { MANAGED_MEMBER_COMPARISON_EXAMPLE, MANAGED_NATIVE_VERIFICATION_EXAMPLE, MANAGED_APPLICATION_GRAPH_EXAMPLE, MANAGED_RECONSTRUCTION_IMPORT_EXAMPLE, } from "./managedWorkflowExamples.js";
-import { toolContractMetadata } from "./toolEffects.js";
-import { requireOutputSchema } from "./toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import { requireOutputSchema } from "../toolOutputSchemaPrimitives.js";
 /** Inputs for comparing two managed observations carried inline. */
 export const compareManagedMembersReferenceInputSchema = z
     .strictObject({
@@ -96,7 +96,7 @@ export const MANAGED_WORKFLOW_TOOL_CONTRACTS = [
     {
         name: "compare_managed_members",
         ...toolContractMetadata("compare_managed_members"),
-        description: "Compare two authenticated inspect_managed_members Evidence records using unique-only decoded-CIL/signature and structural method-shape tiers. Names are reported as observations but are not used as a matching basis; metadata tokens remain build-local coordinates bound to each artifact SHA-256 and MVID, and the tuple digest does not itself remap them.",
+        description: "Compare two authenticated inspect_managed_members Evidence records using unique-only tiers: exact CIL/signature, exact declared type, name, and raw signature (decoded or not), and decoded structural method shape. Names alone are never a matching basis; a member whose signature was not decoded, or whose same-named counterpart's was not, stays unknown rather than added or removed. Metadata tokens remain build-local coordinates bound to each artifact SHA-256 and MVID, and the tuple digest does not itself remap them.",
         kind: "application",
         inputSchema: compareManagedMembersReferenceInputSchema,
         outputSchema: comparisonOutputSchema,