rea-agents 2.0.0 → 2.1.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/managedToolContracts.js

@@ -125,7 +125,7 @@ export const MANAGED_TOOL_CONTRACTS = [
     {
         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,

package/dist/contracts/managedWorkflowToolContracts.js

@@ -111,7 +111,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 CIL/signature and structural method-shape tiers. Names are reported as observations but are not used as a matching basis; metadata tokens are remapped as build-local coordinates bound to each artifact SHA-256 and MVID.",
+        description: "Compare two authenticated inspect_managed_members Evidence records using unique-only decoded-CIL-v1/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 v1 tuple digest does not itself remap them.",
         kind: "application",
         inputSchema: compareManagedMembersReferenceInputSchema,
         outputSchema: comparisonOutputSchema,
@@ -147,7 +147,7 @@ export const MANAGED_WORKFLOW_TOOL_CONTRACTS = [
     {
         name: "import_managed_reconstruction",
         ...toolContractMetadata("import_managed_reconstruction"),
-        description: "Import decompiler-produced managed reconstruction against authenticated inspect_managed_members Evidence. The workflow locks each method to artifact SHA-256, MVID, metadata token, signature hash, and normalized IL hash, records the decompiler identity and options, and marks C# or pseudocode as analyst inference rather than canonical byte observation.",
+        description: "Import decompiler-produced managed reconstruction against authenticated inspect_managed_members Evidence. The workflow locks each method to artifact SHA-256, MVID, metadata token, signature hash, and the limited member-result-v1 decoded-IL tuple hash, records the decompiler identity and options, and marks C# or pseudocode as analyst inference rather than canonical byte observation.",
         kind: "application",
         inputSchema: managedReconstructionReferenceInputSchema,
         outputSchema: reconstructionOutputSchema,
@@ -166,7 +166,7 @@ export const MANAGED_WORKFLOW_TOOL_CONTRACTS = [
     {
         name: "plan_managed_runtime_correlation",
         ...toolContractMetadata("plan_managed_runtime_correlation"),
-        description: "Prepare a separately authorized managed runtime-correlation admission plan from authenticated inspect_managed_members Evidence. The operation is default-disabled, requires the managed_runtime permission ceiling and grant, locks the exact artifact SHA-256, MVID, method signature, and normalized IL shape, distinguishes attach/load/debugger/reflection/instrumentation effects, and records that no target code was executed.",
+        description: "Prepare a separately authorized managed runtime-correlation admission plan from authenticated inspect_managed_members Evidence. The operation is default-disabled, requires the managed_runtime permission ceiling and grant, locks the exact artifact SHA-256, MVID, method signature, and limited member-result-v1 decoded-IL tuple hash, distinguishes attach/load/debugger/reflection/instrumentation effects, and records that no target code was executed.",
         kind: "application",
         inputSchema: managedRuntimeCorrelationReferenceInputSchema,
         outputSchema: runtimeOutputSchema,

package/dist/contracts/providerSelection.js

@@ -23,6 +23,8 @@ export const PROVIDER_REJECTION_CODES = [
     "target_kind_unsupported",
     "target_format_unsupported",
     "architecture_unsupported",
+    "target_role_unsupported",
+    "managed_target_unsupported",
     "open_options_invalid",
     "version_unresolved",
 ];

package/dist/contracts/toolContracts.js

@@ -125,8 +125,8 @@ export const OFFICIAL_TOOL_CONTRACTS = [
     })),
     official("procedure_pseudo_code", "Decompile one analyzed procedure by symbol name or provider-normalized address. Returns provider-specific pseudocode, never original source or cross-provider text equivalence, and may return null; request procedure_assembly when instruction precision matters.", z.object({ procedure, document })),
     official("resolve_containing_procedure", "Resolve an arbitrary address, including an interior instruction or exact external entry, to its provider-analyzed containing procedure. A negative result distinguishes outside segments from not in a procedure and is never guessed from nearby symbols.", z.object({ address, document })),
-    official("search_procedures", "Search analyzed procedure names using literal matching by default or regex opt-in. Ghidra bounds literal work and rejects regex constructs, paths, candidates, or cumulative work outside its finite budgets. Results are deterministic and offset-paginated.", z.object(searchInput)),
-    official("search_strings", "Search analyzed strings using literal matching by default or regex opt-in. Ghidra bounds literal work and rejects regex constructs, paths, candidates, or cumulative work outside its finite budgets. Results are deterministic, offset-paginated, and explicitly truncated.", z.object(searchInput)),
+    official("search_procedures", "Search analyzed procedure names using literal matching by default or regex opt-in. Providers bound search work and reject regex constructs, paths, candidates, or cumulative work outside their finite budgets. Results are deterministic and offset-paginated.", z.object(searchInput)),
+    official("search_strings", "Search analyzed strings using literal matching by default or regex opt-in. Providers bound search work and reject regex constructs, paths, candidates, or cumulative work outside their finite budgets. Results are deterministic, offset-paginated, and explicitly truncated.", z.object(searchInput)),
     official("set_address_name", "Assign an analyst name to one hexadecimal address and report Hopper's boolean result. This mutates analysis metadata; read it back with address_name before relying on it.", z.object({ address, name: z.string(), document })),
     official("set_addresses_names", "Assign analyst names to an address/name map and return per-address success booleans. This mutates analysis metadata; use for bounded batches and verify failures individually.", z.object({ names: z.record(z.string(), z.string()), document })),
     official("set_bookmark", "Create or replace a bookmark at a hexadecimal address. This mutates navigation metadata; verify with list_bookmarks and do not treat bookmarks as binary evidence.", z.object({ address, name: z.string().optional(), document })),

package/dist/contracts/toolEffects.js

@@ -99,6 +99,20 @@ export const TOOL_EFFECTS = {
         writesFilesystem: true,
         launchesProcess: true,
     }),
+    prepare_node_characterization: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+    }),
+    execute_node_characterization: effects({
+        mutatesSession: true,
+        writesFilesystem: true,
+        launchesProcess: true,
+    }),
+    commit_reconstruction_coverage: effects({
+        writesFilesystem: true,
+        mutatesSession: true,
+    }),
+    query_reconstruction_coverage: effects({ mutatesSession: true }),
     open_binary: effects({ mutatesSession: true, launchesProcess: true }),
     close_binary: effects({
         mutatesSession: true,