rea-agents 1.7.0 → 2.1.0

package/dist/config/parsers.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { ConfigurationError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import {} from "../domain/browserObservation.js";
+import { electronFileRootsSchema } from "../domain/electronObservation.js";
+export 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 }));
+    }
+};
+export 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 }));
+    }
+};
+export 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 }));
+    }
+};
+export 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 }));
+};

package/dist/config/permissions.js

@@ -0,0 +1,30 @@
+import { isLiteralLoopbackHostname } from "../domain/browserObservation.js";
+export const filePolicy = (roots) => ({
+    roots,
+    maxBytes: 64 * 1024 * 1024,
+    maxDepth: 64,
+    maxStringLength: 1024 * 1024,
+    maxNodes: 1_000_000,
+});
+export 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,
+});
+export const administratorGrants = (ceilings) => ceilings.map((ceiling) => ({
+    ...ceiling,
+    grant_id: `administrator:${ceiling.capability}`,
+    lifetime: "administrator",
+    operation_identity: null,
+    expires_at: null,
+}));
+export const browserNetworkScope = (origins) => origins.every((origin) => {
+    const hostname = new URL(origin).hostname;
+    return isLiteralLoopbackHostname(hostname);
+})
+    ? "loopback"
+    : "external";

package/dist/config/types.js

@@ -0,0 +1 @@
+export {};

package/dist/config.js

@@ -1,292 +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_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 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 })]
-            : []),
-    ];
-    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,
-        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

@@ -0,0 +1,225 @@
+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 = [
+    {
+        name: "trace_application_feature",
+        ...toolContractMetadata("trace_application_feature"),
+        description: "Trace a typed literal seed through an authenticated JavaScript Application Graph with explicit direction, depth, node, edge, and path bounds. 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: traceApplicationFeatureInputSchema,
+        outputSchema: traceOutputSchema,
+        examples: [
+            {
+                title: "Trace one module seed through a retained application graph",
+                input: JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
+            },
+        ],
+    },
+    {
+        name: "compare_application_versions",
+        ...toolContractMetadata("compare_application_versions"),
+        description: "Compare two authenticated JavaScript Application Graph versions using 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 a bounded changed_from graph without fuzzy or module-ordinal pairing.",
+        kind: "application",
+        inputSchema: compareApplicationVersionsInputSchema,
+        outputSchema: comparisonOutputSchema,
+        examples: [
+            {
+                title: "Compare authenticated static and reconciled application graphs",
+                input: JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
+            },
+        ],
+    },
+    {
+        name: "run_controlled_replay",
+        ...toolContractMetadata("run_controlled_replay"),
+        description: "Plan or execute a content-bound extracted-module JavaScript replay inside the Linux Bubblewrap, seccomp, and cgroup boundary. Execution requires approved: true and the exact plan digest. Supports deterministic boundary cases and optional left/right differential comparison; observations have controlled-replay authority and do not claim real application runtime behavior.",
+        kind: "application",
+        inputSchema: controlledReplayInputSchema,
+        outputSchema: controlledReplayOutputSchema,
+        examples: [
+            {
+                title: "Plan one extracted ESM parser replay",
+                input: {
+                    mode: "plan",
+                    left: {
+                        modules: [
+                            {
+                                alias: "parser",
+                                path: "/approved/parser.mjs",
+                                format: "esm",
+                                role: "module",
+                                dependencies: {},
+                            },
+                        ],
+                        entry_alias: "parser",
+                        entry_export: "default",
+                    },
+                    cases: [{ case_id: "empty", arguments: [""] }],
+                    determinism: {
+                        clock_iso: "2000-01-01T00:00:00.000Z",
+                        random_seed: 0,
+                        locale: "en-US",
+                        timezone: "UTC",
+                        platform: "linux",
+                    },
+                    limits: {
+                        wall_time_ms: 3000,
+                        memory_bytes: 134217728,
+                        tasks: 8,
+                        cpu_quota_percent: 50,
+                        tmpfs_bytes: 16777216,
+                        module_bytes: 4194304,
+                        input_bytes: 262144,
+                        protocol_bytes: 16777216,
+                        output_bytes: 524288,
+                        stderr_bytes: 32768,
+                        result_depth: 16,
+                        result_nodes: 10000,
+                    },
+                    approved: false,
+                },
+            },
+        ],
+    },
+    {
+        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/artifactToolContracts.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { artifactOutputSchemas } from "./toolOutputSchemas.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
+import { toolContractMetadata } from "./toolEffects.js";
 const pageInput = {
     node_offset: z.number().int().min(0).default(0),
     node_limit: z.number().int().min(1).max(500).default(100),
@@ -67,22 +68,17 @@ const examples = {
         occurrence_ids: [`occ_${"0".repeat(64)}`],
     },
 };
-const artifact = (name, description, inputSchema, mutatesFilesystem) => {
+const artifact = (name, description, inputSchema) => {
     const outputSchema = artifactOutputSchemas[name];
     if (outputSchema === undefined)
         throw new Error(`Missing artifact output schema for ${name}`);
     return {
         name,
+        ...toolContractMetadata(name),
         description,
         kind: "artifact-provider",
         inputSchema,
         outputSchema,
-        annotations: {
-            readOnlyHint: !mutatesFilesystem,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
         examples: [
             {
                 title: `Example ${name.replaceAll("_", " ")} request`,
@@ -93,6 +89,6 @@ const artifact = (name, description, inputSchema, mutatesFilesystem) => {
 };
 /** Artifact-graph inventory and explicitly approved safe extraction contracts. */
 export const ARTIFACT_TOOL_CONTRACTS = [
-    artifact("inventory_artifact", "Inventory the active application or package as a deterministic, content-addressed artifact graph. Returns bounded node and edge pages without extracting or mounting by default.", artifactInventoryInputSchema, false),
-    artifact("extract_artifact", "Extract selected graph artifacts beneath an explicit output root. Requires approval, rejects traversal and symlink escapes, never overwrites, enforces bomb limits, and verifies cleanup.", artifactExtractionInputSchema, true),
+    artifact("inventory_artifact", "Inventory the active application or package as a deterministic, content-addressed artifact graph. Returns bounded node and edge pages without extracting or mounting by default.", artifactInventoryInputSchema),
+    artifact("extract_artifact", "Extract selected graph artifacts beneath an explicit output root. Requires approval, rejects traversal and symlink escapes, never overwrites, enforces bomb limits, and verifies cleanup.", artifactExtractionInputSchema),
 ];