rea-agents 2.0.0 → 2.2.0

package/dist/config.js

@@ -1,375 +1 @@
-import { z } from "zod";
-import { isAbsolute } from "node:path";
-import { ConfigurationError } from "./domain/errors.js";
-import { err, ok } from "./domain/result.js";
-import { browserEndpointSchema, browserOriginSchema, isLiteralLoopbackHostname, } from "./domain/browserObservation.js";
-import { electronFileRootsSchema } from "./domain/electronObservation.js";
-import { analysisProviderSelectorSchema, } from "./contracts/providerSelection.js";
-const DEFAULT_HOPPER_LAUNCHER_PATH = "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";
-const defaultHopperLauncherPath = () => process.platform === "linux"
-    ? "/opt/hopper/bin/Hopper"
-    : DEFAULT_HOPPER_LAUNCHER_PATH;
-const environmentSchema = z
-    .object({
-    REA_ANALYSIS_PROVIDER: analysisProviderSelectorSchema.default("auto"),
-    GHIDRA_INSTALL_DIR: z
-        .string()
-        .min(1)
-        .refine(isAbsolute, "GHIDRA_INSTALL_DIR must be absolute")
-        .optional(),
-    JAVA_HOME: z
-        .string()
-        .min(1)
-        .refine(isAbsolute, "JAVA_HOME must be absolute")
-        .optional(),
-    HOPPER_LAUNCHER_PATH: z.string().min(1).optional(),
-    HOPPER_TARGET_PATH: z.string().min(1).optional(),
-    HOPPER_TARGET_KIND: z
-        .enum(["executable", "database"])
-        .default("executable"),
-    HOPPER_LOADER_ARGS_JSON: z.string().optional(),
-    REA_LOG_LEVEL: z
-        .enum(["trace", "debug", "info", "warn", "error", "fatal", "silent"])
-        .default("info"),
-    REA_PROCESS_CAPTURE_ENABLED: z.enum(["true", "false"]).default("false"),
-    REA_ARTIFACT_NATIVE_MOUNT_ENABLED: z
-        .enum(["true", "false"])
-        .default("false"),
-    REA_ARTIFACT_INTEGRITY_CONTINUE_ENABLED: z
-        .enum(["true", "false"])
-        .default("false"),
-    REA_PROCESS_ALLOW_EXTERNAL_NETWORK: z
-        .enum(["true", "false"])
-        .default("false"),
-    REA_PROCESS_EXECUTABLE_ROOTS_JSON: z.string().default("[]"),
-    REA_PROCESS_WORKING_ROOTS_JSON: z.string().default("[]"),
-    REA_PROCESS_ALLOWED_ENV_JSON: z.string().default("[]"),
-    REA_EVIDENCE_ROOTS_JSON: z.string().default("[]"),
-    REA_INVESTIGATION_INPUT_ROOTS_JSON: z.string().default("[]"),
-    REA_ANALYSIS_SNAPSHOT_ROOTS_JSON: z.string().default("[]"),
-    REA_REFERENCE_ROOTS_JSON: z.string().default("[]"),
-    REA_REFERENCE_SECRET_PATTERNS_JSON: z.string().default("[]"),
-    REA_BROWSER_OBSERVE_ENABLED: z.enum(["true", "false"]).default("false"),
-    REA_BROWSER_CDP_ENDPOINTS_JSON: z.string().default("[]"),
-    REA_BROWSER_ALLOWED_ORIGINS_JSON: z.string().default("[]"),
-    REA_ELECTRON_OBSERVE_ENABLED: z.enum(["true", "false"]).default("false"),
-    REA_ELECTRON_CDP_ENDPOINTS_JSON: z.string().default("[]"),
-    REA_ELECTRON_FILE_ROOTS_JSON: z.string().default("[]"),
-    REA_JAVASCRIPT_REPLAY_ENABLED: z.enum(["true", "false"]).default("false"),
-    REA_JAVASCRIPT_REPLAY_ROOTS_JSON: z.string().default("[]"),
-    REA_JAVASCRIPT_REPLAY_NODE_PATH: z
-        .string()
-        .min(1)
-        .refine(isAbsolute, "REA_JAVASCRIPT_REPLAY_NODE_PATH must be absolute")
-        .default(process.execPath),
-    REA_JAVASCRIPT_REPLAY_BWRAP_PATH: z
-        .string()
-        .min(1)
-        .refine(isAbsolute, "REA_JAVASCRIPT_REPLAY_BWRAP_PATH must be absolute")
-        .default("/usr/bin/bwrap"),
-    REA_JAVASCRIPT_REPLAY_SYSTEMD_RUN_PATH: z
-        .string()
-        .min(1)
-        .refine(isAbsolute, "REA_JAVASCRIPT_REPLAY_SYSTEMD_RUN_PATH must be absolute")
-        .default("/usr/bin/systemd-run"),
-    REA_JAVASCRIPT_REPLAY_SYSTEMCTL_PATH: z
-        .string()
-        .min(1)
-        .refine(isAbsolute, "REA_JAVASCRIPT_REPLAY_SYSTEMCTL_PATH must be absolute")
-        .default("/usr/bin/systemctl"),
-    REA_JAVASCRIPT_REPLAY_SHELL_PATH: z
-        .string()
-        .min(1)
-        .refine(isAbsolute, "REA_JAVASCRIPT_REPLAY_SHELL_PATH must be absolute")
-        .default("/usr/bin/bash"),
-    REA_MANAGED_RUNTIME_ENABLED: z.enum(["true", "false"]).default("false"),
-    REA_MANAGED_RUNTIME_ROOTS_JSON: z.string().default("[]"),
-    REA_MANAGED_RUNTIME_EXECUTABLE_PATH: z
-        .string()
-        .min(1)
-        .refine(isAbsolute, "REA_MANAGED_RUNTIME_EXECUTABLE_PATH must be absolute")
-        .default("/usr/bin/dotnet"),
-    REA_PERMISSION_PROJECT_ROOT: z.string().min(1).optional(),
-    REA_PERMISSION_PROJECT_STORE: z.string().min(1).optional(),
-})
-    .refine((value) => (value.REA_PERMISSION_PROJECT_ROOT === undefined) ===
-    (value.REA_PERMISSION_PROJECT_STORE === undefined), {
-    message: "REA_PERMISSION_PROJECT_ROOT and REA_PERMISSION_PROJECT_STORE must be configured together",
-});
-const parseStringArray = (encoded, name) => {
-    try {
-        const parsed = z
-            .array(z.string().min(1))
-            .max(128)
-            .safeParse(JSON.parse(encoded));
-        return parsed.success
-            ? ok(parsed.data)
-            : err(new ConfigurationError(parsed.error.issues.some(({ code }) => code === "too_big")
-                ? `${name} must encode at most 128 strings`
-                : `${name} must encode an array of strings`, { cause: parsed.error }));
-    }
-    catch (cause) {
-        return err(new ConfigurationError(`${name} must be valid JSON`, { cause }));
-    }
-};
-const parseBrowserArray = (encoded, name, itemSchema, maximum) => {
-    try {
-        const parsed = z
-            .array(itemSchema)
-            .max(maximum)
-            .safeParse(JSON.parse(encoded));
-        return parsed.success
-            ? ok([...new Set(parsed.data)].sort())
-            : err(new ConfigurationError(`${name} must encode valid browser scopes`, {
-                cause: parsed.error,
-            }));
-    }
-    catch (cause) {
-        return err(new ConfigurationError(`${name} must be valid JSON`, { cause }));
-    }
-};
-const parseElectronFileRoots = (encoded) => {
-    try {
-        const decoded = JSON.parse(encoded);
-        if (Array.isArray(decoded) && decoded.length === 0)
-            return ok([]);
-        const parsed = electronFileRootsSchema.safeParse(decoded);
-        return parsed.success
-            ? ok(parsed.data)
-            : err(new ConfigurationError("REA_ELECTRON_FILE_ROOTS_JSON must encode absolute roots", { cause: parsed.error }));
-    }
-    catch (cause) {
-        return err(new ConfigurationError("REA_ELECTRON_FILE_ROOTS_JSON must be valid JSON", { cause }));
-    }
-};
-const filePolicy = (roots) => ({
-    roots,
-    maxBytes: 64 * 1024 * 1024,
-    maxDepth: 64,
-    maxStringLength: 1024 * 1024,
-    maxNodes: 1_000_000,
-});
-const permissionScope = (capability, roots, options = {}) => ({
-    capability,
-    roots,
-    executables: options.executables ?? [],
-    environment_names: options.environment_names ?? [],
-    ...(options.origins === undefined ? {} : { origins: options.origins }),
-    network: options.network ?? "none",
-    mount: options.mount ?? false,
-});
-const administratorGrants = (ceilings) => ceilings.map((ceiling) => ({
-    ...ceiling,
-    grant_id: `administrator:${ceiling.capability}`,
-    lifetime: "administrator",
-    operation_identity: null,
-    expires_at: null,
-}));
-const parseLoaderArgs = (encoded) => {
-    if (encoded === undefined)
-        return ok([]);
-    let decoded;
-    try {
-        decoded = JSON.parse(encoded);
-    }
-    catch (cause) {
-        return err(new ConfigurationError("HOPPER_LOADER_ARGS_JSON must be valid JSON", {
-            cause,
-        }));
-    }
-    const parsed = z.array(z.string()).safeParse(decoded);
-    return parsed.success
-        ? ok(parsed.data)
-        : err(new ConfigurationError("HOPPER_LOADER_ARGS_JSON must encode an array of strings", { cause: parsed.error }));
-};
-/**
- * Parse provider and authority configuration once at the composition root.
- * Explicit loader arguments override REA's header-derived defaults for a
- * supported target, allowing callers to refine Hopper's loader behavior without
- * bypassing REA's path and executable-header checks.
- */
-export const parseConfig = (environment) => {
-    const parsedEnvironment = environmentSchema.safeParse(environment);
-    if (!parsedEnvironment.success) {
-        return err(new ConfigurationError("Invalid REA environment configuration", {
-            cause: parsedEnvironment.error,
-        }));
-    }
-    const loaderArgs = parseLoaderArgs(parsedEnvironment.data.HOPPER_LOADER_ARGS_JSON);
-    if (!loaderArgs.ok)
-        return loaderArgs;
-    const executableRoots = parseStringArray(parsedEnvironment.data.REA_PROCESS_EXECUTABLE_ROOTS_JSON, "REA_PROCESS_EXECUTABLE_ROOTS_JSON");
-    if (!executableRoots.ok)
-        return executableRoots;
-    const workingRoots = parseStringArray(parsedEnvironment.data.REA_PROCESS_WORKING_ROOTS_JSON, "REA_PROCESS_WORKING_ROOTS_JSON");
-    if (!workingRoots.ok)
-        return workingRoots;
-    const allowedEnvironment = parseStringArray(parsedEnvironment.data.REA_PROCESS_ALLOWED_ENV_JSON, "REA_PROCESS_ALLOWED_ENV_JSON");
-    if (!allowedEnvironment.ok)
-        return allowedEnvironment;
-    const evidenceRoots = parseStringArray(parsedEnvironment.data.REA_EVIDENCE_ROOTS_JSON, "REA_EVIDENCE_ROOTS_JSON");
-    if (!evidenceRoots.ok)
-        return evidenceRoots;
-    const investigationInputRoots = parseStringArray(parsedEnvironment.data.REA_INVESTIGATION_INPUT_ROOTS_JSON, "REA_INVESTIGATION_INPUT_ROOTS_JSON");
-    if (!investigationInputRoots.ok)
-        return investigationInputRoots;
-    const analysisSnapshotRoots = parseStringArray(parsedEnvironment.data.REA_ANALYSIS_SNAPSHOT_ROOTS_JSON, "REA_ANALYSIS_SNAPSHOT_ROOTS_JSON");
-    if (!analysisSnapshotRoots.ok)
-        return analysisSnapshotRoots;
-    const referenceRoots = parseStringArray(parsedEnvironment.data.REA_REFERENCE_ROOTS_JSON, "REA_REFERENCE_ROOTS_JSON");
-    if (!referenceRoots.ok)
-        return referenceRoots;
-    const secretPatterns = parseStringArray(parsedEnvironment.data.REA_REFERENCE_SECRET_PATTERNS_JSON, "REA_REFERENCE_SECRET_PATTERNS_JSON");
-    if (!secretPatterns.ok)
-        return secretPatterns;
-    const browserEndpoints = parseBrowserArray(parsedEnvironment.data.REA_BROWSER_CDP_ENDPOINTS_JSON, "REA_BROWSER_CDP_ENDPOINTS_JSON", browserEndpointSchema, 16);
-    if (!browserEndpoints.ok)
-        return browserEndpoints;
-    const browserOrigins = parseBrowserArray(parsedEnvironment.data.REA_BROWSER_ALLOWED_ORIGINS_JSON, "REA_BROWSER_ALLOWED_ORIGINS_JSON", browserOriginSchema, 32);
-    if (!browserOrigins.ok)
-        return browserOrigins;
-    const electronEndpoints = parseBrowserArray(parsedEnvironment.data.REA_ELECTRON_CDP_ENDPOINTS_JSON, "REA_ELECTRON_CDP_ENDPOINTS_JSON", browserEndpointSchema, 16);
-    if (!electronEndpoints.ok)
-        return electronEndpoints;
-    const electronFileRoots = parseElectronFileRoots(parsedEnvironment.data.REA_ELECTRON_FILE_ROOTS_JSON);
-    if (!electronFileRoots.ok)
-        return electronFileRoots;
-    const javascriptReplayRoots = parseStringArray(parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_ROOTS_JSON, "REA_JAVASCRIPT_REPLAY_ROOTS_JSON");
-    if (!javascriptReplayRoots.ok)
-        return javascriptReplayRoots;
-    if (javascriptReplayRoots.value.some((root) => !isAbsolute(root)))
-        return err(new ConfigurationError("REA_JAVASCRIPT_REPLAY_ROOTS_JSON must encode absolute roots"));
-    const managedRuntimeRoots = parseStringArray(parsedEnvironment.data.REA_MANAGED_RUNTIME_ROOTS_JSON, "REA_MANAGED_RUNTIME_ROOTS_JSON");
-    if (!managedRuntimeRoots.ok)
-        return managedRuntimeRoots;
-    if (managedRuntimeRoots.value.some((root) => !isAbsolute(root)))
-        return err(new ConfigurationError("REA_MANAGED_RUNTIME_ROOTS_JSON must encode absolute roots"));
-    const permissionCeilings = [
-        ...(parsedEnvironment.data.REA_PROCESS_CAPTURE_ENABLED === "true"
-            ? [
-                permissionScope("process_capture", workingRoots.value, {
-                    executables: executableRoots.value,
-                    environment_names: allowedEnvironment.value,
-                    network: parsedEnvironment.data.REA_PROCESS_ALLOW_EXTERNAL_NETWORK ===
-                        "true"
-                        ? "external"
-                        : "none",
-                }),
-            ]
-            : []),
-        permissionScope("evidence_read", evidenceRoots.value),
-        permissionScope("evidence_write", evidenceRoots.value),
-        permissionScope("investigation_input", investigationInputRoots.value),
-        permissionScope("investigation_workspace_read", evidenceRoots.value),
-        permissionScope("investigation_workspace_write", evidenceRoots.value),
-        permissionScope("snapshot_read", analysisSnapshotRoots.value),
-        permissionScope("snapshot_write", analysisSnapshotRoots.value),
-        permissionScope("artifact_extract", ["/"]),
-        permissionScope("reference_read", referenceRoots.value),
-        ...(parsedEnvironment.data.REA_BROWSER_OBSERVE_ENABLED === "true"
-            ? [
-                permissionScope("browser_observe", [], {
-                    origins: [...browserEndpoints.value, ...browserOrigins.value],
-                    network: browserNetworkScope(browserOrigins.value),
-                }),
-            ]
-            : []),
-        ...(parsedEnvironment.data.REA_ELECTRON_OBSERVE_ENABLED === "true"
-            ? [
-                permissionScope("electron_observe", electronFileRoots.value, {
-                    origins: electronEndpoints.value,
-                    network: "loopback",
-                }),
-            ]
-            : []),
-        ...(parsedEnvironment.data.REA_ARTIFACT_NATIVE_MOUNT_ENABLED === "true"
-            ? [permissionScope("native_mount", [], { mount: true })]
-            : []),
-        ...(parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_ENABLED === "true"
-            ? [
-                permissionScope("javascript_replay", javascriptReplayRoots.value, {
-                    executables: [
-                        parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_NODE_PATH,
-                        parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_BWRAP_PATH,
-                        parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_SYSTEMD_RUN_PATH,
-                        parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_SYSTEMCTL_PATH,
-                        parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_SHELL_PATH,
-                    ],
-                    network: "none",
-                    mount: true,
-                }),
-            ]
-            : []),
-        ...(parsedEnvironment.data.REA_MANAGED_RUNTIME_ENABLED === "true"
-            ? [
-                permissionScope("managed_runtime", managedRuntimeRoots.value, {
-                    executables: [
-                        parsedEnvironment.data.REA_MANAGED_RUNTIME_EXECUTABLE_PATH,
-                    ],
-                    network: "none",
-                }),
-            ]
-            : []),
-    ];
-    return ok({
-        analysisProvider: parsedEnvironment.data.REA_ANALYSIS_PROVIDER,
-        ghidraInstallDir: parsedEnvironment.data.GHIDRA_INSTALL_DIR,
-        ghidraJavaHome: parsedEnvironment.data.JAVA_HOME,
-        hopperLauncherPath: parsedEnvironment.data.HOPPER_LAUNCHER_PATH ??
-            defaultHopperLauncherPath(),
-        hopperTargetPath: parsedEnvironment.data.HOPPER_TARGET_PATH,
-        hopperTargetKind: parsedEnvironment.data.HOPPER_TARGET_KIND,
-        hopperLoaderArgs: loaderArgs.value,
-        logLevel: parsedEnvironment.data.REA_LOG_LEVEL,
-        processExecutionPolicy: {
-            enabled: parsedEnvironment.data.REA_PROCESS_CAPTURE_ENABLED === "true",
-            executableRoots: executableRoots.value,
-            workingRoots: workingRoots.value,
-            allowedEnvironment: allowedEnvironment.value,
-            allowExternalNetwork: parsedEnvironment.data.REA_PROCESS_ALLOW_EXTERNAL_NETWORK === "true",
-        },
-        artifactNativeMountEnabled: parsedEnvironment.data.REA_ARTIFACT_NATIVE_MOUNT_ENABLED === "true",
-        artifactIntegrityContinueEnabled: parsedEnvironment.data.REA_ARTIFACT_INTEGRITY_CONTINUE_ENABLED === "true",
-        evidenceFilePolicy: filePolicy(evidenceRoots.value),
-        investigationInputRoots: investigationInputRoots.value,
-        analysisSnapshotFilePolicy: filePolicy(analysisSnapshotRoots.value),
-        referenceSourcePolicy: {
-            roots: referenceRoots.value,
-            secretPatterns: secretPatterns.value,
-            maxBytes: 16 * 1024 * 1024,
-            maxEntries: 10_000,
-            maxDepth: 32,
-            maxPathBytes: 4_096,
-        },
-        browserObservationEnabled: parsedEnvironment.data.REA_BROWSER_OBSERVE_ENABLED === "true",
-        browserCdpEndpoints: browserEndpoints.value,
-        browserAllowedOrigins: browserOrigins.value,
-        electronObservationEnabled: parsedEnvironment.data.REA_ELECTRON_OBSERVE_ENABLED === "true",
-        electronCdpEndpoints: electronEndpoints.value,
-        electronFileRoots: electronFileRoots.value,
-        javascriptReplayPolicy: {
-            enabled: parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_ENABLED === "true",
-            roots: javascriptReplayRoots.value,
-            nodePath: parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_NODE_PATH,
-            bubblewrapPath: parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_BWRAP_PATH,
-            systemdRunPath: parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_SYSTEMD_RUN_PATH,
-            systemctlPath: parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_SYSTEMCTL_PATH,
-            shellPath: parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_SHELL_PATH,
-        },
-        managedRuntimePolicy: {
-            enabled: parsedEnvironment.data.REA_MANAGED_RUNTIME_ENABLED === "true",
-            roots: managedRuntimeRoots.value,
-            executablePath: parsedEnvironment.data.REA_MANAGED_RUNTIME_EXECUTABLE_PATH,
-        },
-        permissionCeilings,
-        administratorPermissionGrants: administratorGrants(permissionCeilings),
-        permissionProjectRoot: parsedEnvironment.data.REA_PERMISSION_PROJECT_ROOT,
-        permissionProjectStore: parsedEnvironment.data.REA_PERMISSION_PROJECT_STORE,
-    });
-};
-const browserNetworkScope = (origins) => origins.every((origin) => {
-    const hostname = new URL(origin).hostname;
-    return isLiteralLoopbackHostname(hostname);
-})
-    ? "loopback"
-    : "external";
+export { parseConfig } from "./config/parseConfig.js";

package/dist/contracts/applicationToolContracts.js

@@ -1,11 +1,77 @@
 import { applicationVersionComparisonResultSchema, compareApplicationVersionsInputSchema, } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
 import { applicationFeatureTraceResultSchema, traceApplicationFeatureInputSchema, } from "../domain/javascriptFeatureTraceSchemas.js";
 import { controlledReplayInputSchema, controlledReplayOutputSchema, } from "../domain/javascriptReplay.js";
+import { nodeCharacterizationExecutionInputSchema, nodeCharacterizationExecutionOutputSchema, nodeCharacterizationPreparationInputSchema, nodeCharacterizationPreparationOutputSchema, } from "../domain/nodeRuntimeCharacterization.js";
+import { reconstructionCoverageCommitInputSchema, reconstructionCoverageCommitOutputSchema, reconstructionCoverageQueryInputSchema, } from "../application/ReconstructionCoverageService.js";
+import { reconstructionClosureResultSchema } from "../domain/reconstructionCoverage.js";
+import { jsonObjectSchema } from "../domain/jsonValue.js";
 import { toolContractMetadata } from "./toolEffects.js";
 import { evidenceResultOf } from "./toolOutputSchemas.js";
 import { JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE, JAVASCRIPT_FEATURE_TRACE_EXAMPLE, } from "./javascriptApplicationWorkflowExamples.js";
 const traceOutputSchema = evidenceResultOf(applicationFeatureTraceResultSchema);
 const comparisonOutputSchema = evidenceResultOf(applicationVersionComparisonResultSchema);
+const HASH = "0".repeat(64);
+const NODE_PREPARATION_EXAMPLE = jsonObjectSchema.parse({
+    preparation_approved: true,
+    selected_alias: "bundle",
+    expected_effect: "pure",
+    instrumentation: {
+        artifact_path: "/approved/bundle.js",
+        artifact_sha256: HASH,
+        selection: {
+            byte_start: 100,
+            byte_end: 120,
+            selected_sha256: HASH,
+            export_name: "selected",
+        },
+    },
+    replay: {
+        mode: "plan",
+        left: {
+            modules: [
+                {
+                    alias: "bundle",
+                    path: "/approved/bundle.js",
+                    format: "commonjs-factory",
+                    role: "module",
+                    dependencies: {},
+                },
+            ],
+            entry_alias: "bundle",
+            entry_export: "selected",
+        },
+        cases: [{ case_id: "empty", arguments: [""] }],
+        approved: false,
+    },
+});
+const COVERAGE_WORKSPACE_EXAMPLE = jsonObjectSchema.parse({
+    schema_version: 1,
+    workspace_id: `rcw_${HASH}`,
+    name: "replacement",
+    revision: 1,
+    previous_revision_sha256: null,
+    revision_sha256: HASH,
+    evidence_bundle: {
+        bundle_version: 2,
+        artifacts: [],
+        providers: [],
+        environments: [],
+        scenarios: [],
+        captures: [],
+        unknowns: [],
+        records: [],
+    },
+    artifacts: [],
+    surfaces: [],
+    owners: [],
+    claims: [],
+    verifier_contracts: [],
+    verifier_results: [],
+    residual_unknown_ids: [],
+    contradictions: [],
+    package_proofs: [],
+    boundaries: [],
+});
 /** Provider-neutral graph workflow contracts shared by MCP and CLI adapters. */
 export const APPLICATION_TOOL_CONTRACTS = [
     {
@@ -88,4 +154,72 @@ export const APPLICATION_TOOL_CONTRACTS = [
             },
         ],
     },
+    {
+        name: "prepare_node_characterization",
+        ...toolContractMetadata("prepare_node_characterization"),
+        description: "Prepare a hash-bound Node/JavaScript characterization plan and deterministic reversible export transformation without executing target code. The exact source, selected byte range, runtime closure, sandbox profile, cases, and limits are committed for separate execution approval.",
+        kind: "application",
+        inputSchema: nodeCharacterizationPreparationInputSchema,
+        outputSchema: nodeCharacterizationPreparationOutputSchema,
+        examples: [
+            {
+                title: "Prepare one exact bundled callable characterization",
+                input: NODE_PREPARATION_EXAMPLE,
+            },
+        ],
+    },
+    {
+        name: "execute_node_characterization",
+        ...toolContractMetadata("execute_node_characterization"),
+        description: "Recompute and execute one separately approved exact Node characterization plan in the owned controlled-replay boundary. Returns transformation, replay, cleanup, and provider-neutral characterization Evidence v2; stale plans fail before execution.",
+        kind: "application",
+        inputSchema: nodeCharacterizationExecutionInputSchema,
+        outputSchema: nodeCharacterizationExecutionOutputSchema,
+        examples: [
+            {
+                title: "Execute one approved exact characterization plan",
+                input: {
+                    execution_approved: true,
+                    approved_plan_sha256: HASH,
+                    preparation: NODE_PREPARATION_EXAMPLE,
+                },
+            },
+        ],
+    },
+    {
+        name: "commit_reconstruction_coverage",
+        ...toolContractMetadata("commit_reconstruction_coverage"),
+        description: "Atomically commit one canonical evidence-backed reconstruction coverage workspace revision under an approved root. CAS revisions reject lost updates; every Evidence and residual-unknown reference must resolve in the embedded canonical bundle.",
+        kind: "application",
+        inputSchema: reconstructionCoverageCommitInputSchema,
+        outputSchema: reconstructionCoverageCommitOutputSchema,
+        examples: [
+            {
+                title: "Commit the first canonical coverage revision",
+                input: {
+                    approved: true,
+                    workspace_path: "/approved/coverage.json",
+                    expected_revision: null,
+                    workspace: COVERAGE_WORKSPACE_EXAMPLE,
+                },
+            },
+        ],
+    },
+    {
+        name: "query_reconstruction_coverage",
+        ...toolContractMetadata("query_reconstruction_coverage"),
+        description: "Evaluate one named reconstruction boundary from a canonical coverage workspace. 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.",
+        kind: "application",
+        inputSchema: reconstructionCoverageQueryInputSchema,
+        outputSchema: reconstructionClosureResultSchema,
+        examples: [
+            {
+                title: "Evaluate one replacement boundary",
+                input: {
+                    workspace_path: "/approved/coverage.json",
+                    boundary_id: "replacement.cli",
+                },
+            },
+        ],
+    },
 ];

package/dist/contracts/electronToolContracts.js

@@ -1,12 +1,59 @@
+import { z } from "zod";
 import { toolContractMetadata } from "./toolEffects.js";
 import { evidenceResultOf } from "./toolOutputSchemas.js";
 import { electronPageInspectionSchema, electronTargetListSchema, inspectElectronPageInputSchema, listElectronTargetsInputSchema, } from "../domain/electronObservation.js";
 import { analyzeJavaScriptApplicationInputSchema, javascriptApplicationAnalysisResultSchema, } from "../domain/javascriptApplicationAnalysis.js";
+import { JAVASCRIPT_APPLICATION_NODE_KINDS } from "../domain/javascriptApplicationGraphSchemas.js";
+import { applicationCoverageSchema } from "../domain/javascriptApplicationEvidenceSchemas.js";
 import { javascriptRuntimeReconciliationResultSchema, reconcileJavaScriptRuntimeInputSchema, } from "../domain/javascriptRuntimeReconciliationSchemas.js";
 import { JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE } from "./javascriptRuntimeReconciliationExample.js";
 const listOutputSchema = evidenceResultOf(electronTargetListSchema);
 const inspectionOutputSchema = evidenceResultOf(electronPageInspectionSchema);
-const applicationOutputSchema = evidenceResultOf(javascriptApplicationAnalysisResultSchema);
+/** MCP-only response selection; analysis identity does not depend on projection. */
+export const analyzeJavaScriptApplicationToolInputSchema = analyzeJavaScriptApplicationInputSchema.extend({
+    detail: z
+        .enum(["summary", "full"])
+        .default("summary")
+        .describe("summary returns bounded findings and paged graph resource URIs; full returns the complete graph only when explicitly required"),
+});
+/** Bounded default projection for agent-facing JavaScript application analysis. */
+export const javascriptApplicationAnalysisSummarySchema = javascriptApplicationAnalysisResultSchema.omit({ graph: true }).extend({
+    unknowns: z.array(z.string().min(1).max(4_096)).max(1_000),
+    graph: z.strictObject({
+        graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
+        node_count: z.number().int().min(0),
+        edge_count: z.number().int().min(0),
+        roots: z.strictObject({
+            items: z.array(z.string().regex(/^jag_node_[a-f0-9]{64}$/u)),
+            total: z.number().int().min(0),
+            truncated: z.boolean(),
+        }),
+        node_kinds: z.array(z.strictObject({
+            kind: z.enum(JAVASCRIPT_APPLICATION_NODE_KINDS),
+            count: z.number().int().min(1),
+        })),
+        top_findings: z.array(z.strictObject({
+            node_id: z.string().regex(/^jag_node_[a-f0-9]{64}$/u),
+            kind: z.enum(JAVASCRIPT_APPLICATION_NODE_KINDS),
+            label: z.string().nullable(),
+            authority: z.string(),
+            state: z.string(),
+            confidence: z.string(),
+            location: z.json(),
+        })),
+        coverage: applicationCoverageSchema,
+        limitations: z.array(z.string()),
+        pages: z.strictObject({
+            nodes: z.string().startsWith("rea://evidence/"),
+            edges: z.string().startsWith("rea://evidence/"),
+            page_limit: z.number().int().min(1).max(500),
+        }),
+    }),
+});
+const applicationOutputSchema = evidenceResultOf(z.union([
+    javascriptApplicationAnalysisSummarySchema,
+    javascriptApplicationAnalysisResultSchema,
+]));
 const reconciliationOutputSchema = evidenceResultOf(javascriptRuntimeReconciliationResultSchema);
 const endpoint = "http://127.0.0.1:9223";
 const root = "/Applications/Example.app/Contents/Resources";
@@ -66,9 +113,9 @@ export const ELECTRON_TOOL_CONTRACTS = [
     {
         name: "analyze_javascript_application",
         ...toolContractMetadata("analyze_javascript_application"),
-        description: "Statically reconstruct one approved local ASAR or extracted JavaScript application as Evidence v2 and JavaScript Application Graph v1. Maps BrowserWindow preferences, preload and contextBridge APIs, literal and dynamic IPC, handler locations, sender-validation observations, utility processes, and requested native addon bindings without executing JavaScript; source-map contents require separate approval.",
+        description: "Statically reconstruct one approved local ASAR or extracted JavaScript application without executing it. The default summary returns architecture/security counts, top evidence-backed findings, unknowns, and paged graph resource URIs; request detail=full only when the complete graph must be returned immediately. Identical inputs are deterministic, so do not repeat the call or reread full Evidence without a specific missing detail.",
         kind: "electron-provider",
-        inputSchema: analyzeJavaScriptApplicationInputSchema,
+        inputSchema: analyzeJavaScriptApplicationToolInputSchema,
         outputSchema: applicationOutputSchema,
         examples: [
             {
@@ -78,6 +125,7 @@ export const ELECTRON_TOOL_CONTRACTS = [
                     format: "auto",
                     approved: true,
                     source_map_read_approved: false,
+                    detail: "summary",
                 },
             },
         ],

package/dist/contracts/managedToolContracts.js

@@ -3,6 +3,11 @@ import { managedOutputSchemas } from "./toolOutputSchemas.js";
 import { toolContractMetadata } from "./toolEffects.js";
 /** Exact caller boundary for execution-free PE/CLI triage and identity. */
 export const managedArtifactInputSchema = z.object({
+    path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Managed PE/CLI path to open before inspection; omit only when a managed target is already active"),
     reference_offset: z.number().int().min(0).default(0),
     reference_limit: z.number().int().min(1).max(500).default(100),
     resource_offset: z.number().int().min(0).default(0),
@@ -111,21 +116,21 @@ export const MANAGED_TOOL_CONTRACTS = [
     {
         name: "inspect_managed_artifact",
         ...toolContractMetadata("inspect_managed_artifact"),
-        description: "Classify the active PE/CLI artifact and inventory exact assembly/module identity, target framework evidence, references, resources, and custom attributes without loading or executing target code. Returns bounded pages and explicit partial or malformed coverage.",
+        description: "Open and classify an explicit managed PE/CLI path, or inspect the active managed target, then inventory exact assembly/module identity, target framework evidence, references, resources, and custom attributes without loading or executing target code. Returns bounded pages and explicit partial or malformed coverage.",
         kind: "managed-provider",
         inputSchema: managedArtifactInputSchema,
         outputSchema,
         examples: [
             {
                 title: "Example inspect managed artifact request",
-                input: {},
+                input: { path: "/tmp/Example.dll" },
             },
         ],
     },
     {
         name: "inspect_managed_members",
         ...toolContractMetadata("inspect_managed_members"),
-        description: "Inspect bounded PE/CLI metadata members, signatures, method body IL hashes, exception regions, call edges, and field-access anchors without loading or executing target code. Metadata tokens are reported as build-local coordinates bound to the artifact SHA-256 and MVID.",
+        description: "Inspect bounded PE/CLI metadata members, signatures, raw CIL hashes, limited member-result-v1 decoded-instruction-tuple hashes, separately reported exception regions, call edges, and field-access anchors without loading or executing target code. Metadata tokens are reported as build-local coordinates bound to the artifact SHA-256 and MVID; the v1 tuple hash does not resolve them or fully commit control flow.",
         kind: "managed-provider",
         inputSchema: managedMemberInputSchema,
         outputSchema: memberOutputSchema,