rea-agents 2.2.0 → 2.4.0

package/dist/process/ProcessOwnership.js

@@ -44,7 +44,7 @@ export const parseProcessEnvironment = (value) => Object.fromEntries(value
     return [entry.slice(0, separator), entry.slice(separator + 1)];
 }));
 const systemHost = {
-    async listMembers(processGroupId) {
+    async listProcesses() {
         if (process.platform === "win32")
             return [];
         const { stdout } = await execFileAsync("ps", [
@@ -61,8 +61,7 @@ const systemHost = {
             processGroupId: Number(match[3]),
             state: match[4] ?? "",
             command: match[5] ?? "",
-        }))
-            .filter((member) => member.processGroupId === processGroupId);
+        }));
     },
     async environment(pid) {
         if (process.platform === "linux") {
@@ -95,73 +94,140 @@ const systemWindowsProcessTreeHost = {
 };
 /** Read the capture run token currently exposed by one live process. */
 export const readProcessRunId = async (pid, host = systemHost) => (await host.environment(pid)).REA_PROCESS_RUN_ID;
-/**
- * Verify run-token ownership before signaling a POSIX process group.
- *
- * Process IDs and group IDs can be reused. REA therefore re-reads every live
- * member's environment immediately before signaling and fails closed if any
- * member cannot be inspected or lacks the per-capture run token.
- */
+/** Token-validate every rooted POSIX process group before signaling any. */
 export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) => {
-    let members;
+    let processes;
     try {
-        members = await host.listMembers(ownership.processGroupId);
+        processes = liveProcesses(await host.listProcesses());
     }
     catch {
-        return { cleaned: false, reason: "process group could not be inspected" };
+        return { cleaned: false, reason: "process table could not be inspected" };
     }
-    const liveMembers = liveProcessGroupMembers(members);
-    if (liveMembers.length === 0)
+    const plan = await createOwnedCleanupPlan(ownership, processes, host);
+    if ("cleaned" in plan)
+        return plan;
+    let signaled = false;
+    for (const processGroupId of plan.signalOrder) {
+        const revalidation = await revalidateOwnedProcessGroup(processGroupId, ownership, host);
+        if ("cleaned" in revalidation)
+            return revalidation;
+        if (revalidation.empty)
+            continue;
+        try {
+            host.signalGroup(processGroupId, "SIGKILL");
+            signaled = true;
+        }
+        catch (cause) {
+            const code = cause instanceof Error && "code" in cause ? cause.code : undefined;
+            if (code !== "ESRCH")
+                return { cleaned: false, reason: "owned process group signal failed" };
+        }
+    }
+    return { cleaned: true, signaled };
+};
+const createOwnedCleanupPlan = async (ownership, processes, host) => {
+    const launcher = processes.find(({ pid }) => pid === ownership.leaderPid);
+    const rootMembers = processes.filter(({ processGroupId }) => processGroupId === ownership.processGroupId);
+    if (launcher === undefined && rootMembers.length === 0)
         return { cleaned: true, signaled: false };
-    const leader = liveMembers.find((member) => member.pid === ownership.leaderPid);
-    if (leader !== undefined) {
-        if (ownership.expectedParentPid !== undefined &&
-            leader.parentPid !== ownership.expectedParentPid)
-            return {
-                cleaned: false,
-                reason: "owned launcher parent identity did not match",
-            };
-        if (ownership.expectedCommand !== undefined &&
-            !commandMatches(leader.command, ownership.expectedCommand))
+    let descendants = [];
+    if (launcher !== undefined) {
+        const identityFailure = launcherIdentityFailure(launcher, ownership);
+        if (identityFailure !== null)
+            return { cleaned: false, reason: identityFailure };
+        descendants = descendantsOf(launcher.pid, processes);
+    }
+    const descendantPids = new Set(descendants.map(({ pid }) => pid));
+    const processGroupIds = new Set([ownership.processGroupId]);
+    for (const descendant of descendants)
+        processGroupIds.add(descendant.processGroupId);
+    for (const processGroupId of processGroupIds) {
+        if (processGroupId === ownership.processGroupId)
+            continue;
+        const groupLeader = processes.find(({ pid, processGroupId: observedGroupId }) => pid === processGroupId && observedGroupId === processGroupId);
+        if (groupLeader === undefined || !descendantPids.has(groupLeader.pid))
             return {
                 cleaned: false,
-                reason: "owned launcher command identity did not match",
+                reason: "descendant process-group leader identity could not be verified",
             };
     }
+    const liveMembers = processes.filter(({ processGroupId }) => processGroupIds.has(processGroupId));
+    const failures = await processOwnershipFailures(liveMembers, ownership.runId, host);
+    if (failures.length > 0)
+        return cleanupValidationFailure(failures);
+    return {
+        signalOrder: [ownership.processGroupId].concat([...processGroupIds]
+            .filter((processGroupId) => processGroupId !== ownership.processGroupId)
+            .sort((left, right) => left - right)),
+    };
+};
+const launcherIdentityFailure = (launcher, ownership) => {
+    if (launcher.processGroupId !== ownership.processGroupId)
+        return "owned launcher process-group identity did not match";
+    if (ownership.expectedParentPid !== undefined &&
+        launcher.parentPid !== ownership.expectedParentPid)
+        return "owned launcher parent identity did not match";
+    if (ownership.expectedCommand !== undefined &&
+        !commandMatches(launcher.command, ownership.expectedCommand))
+        return "owned launcher command identity did not match";
+    return null;
+};
+const revalidateOwnedProcessGroup = async (processGroupId, ownership, host) => {
+    let members;
+    try {
+        members = liveProcesses(await host.listProcesses()).filter(({ processGroupId: observedGroupId }) => observedGroupId === processGroupId);
+    }
+    catch {
+        return {
+            cleaned: false,
+            reason: "process ownership could not be revalidated",
+        };
+    }
+    const failures = await processOwnershipFailures(members, ownership.runId, host);
+    if (failures.length > 0)
+        return cleanupValidationFailure(failures);
+    if (processGroupId === ownership.processGroupId) {
+        const launcher = members.find(({ pid }) => pid === ownership.leaderPid);
+        if (launcher !== undefined) {
+            const identityFailure = launcherIdentityFailure(launcher, ownership);
+            if (identityFailure !== null)
+                return { cleaned: false, reason: identityFailure };
+        }
+    }
+    if (processGroupId !== ownership.processGroupId &&
+        members.length > 0 &&
+        !members.some(({ pid }) => pid === processGroupId))
+        return {
+            cleaned: false,
+            reason: "descendant process-group leader identity could not be revalidated",
+        };
+    return { empty: members.length === 0 };
+};
+const cleanupValidationFailure = (failures) => ({
+    cleaned: false,
+    reason: failures.some(({ reason }) => reason === "run-token-mismatch")
+        ? "process tree contains an unowned or PID-reused process"
+        : "process ownership could not be revalidated",
+    failures,
+});
+const processOwnershipFailures = async (members, runId, host) => {
     const failures = [];
-    for (const member of liveMembers) {
+    for (const member of members) {
         try {
-            const environment = await host.environment(member.pid);
-            if (environment.REA_PROCESS_RUN_ID !== ownership.runId)
+            if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !== runId)
                 failures.push({ pid: member.pid, reason: "run-token-mismatch" });
         }
         catch {
             failures.push({ pid: member.pid, reason: "environment-unreadable" });
         }
     }
-    if (failures.length > 0)
-        return {
-            cleaned: false,
-            reason: failures.some(({ reason }) => reason === "run-token-mismatch")
-                ? "process group contains an unowned or PID-reused process"
-                : "process ownership could not be revalidated",
-            failures,
-        };
-    try {
-        host.signalGroup(ownership.processGroupId, "SIGKILL");
-    }
-    catch (cause) {
-        const code = cause instanceof Error && "code" in cause ? cause.code : undefined;
-        if (code !== "ESRCH")
-            return { cleaned: false, reason: "owned process group signal failed" };
-    }
-    return { cleaned: true, signaled: true };
+    return failures;
 };
 /** Observe one group without signaling it, failing closed on identity doubt. */
 export const observeOwnedProcessGroup = async (ownership, host = systemHost) => {
     let members;
     try {
-        members = await host.listMembers(ownership.processGroupId);
+        members = (await host.listProcesses()).filter(({ processGroupId }) => processGroupId === ownership.processGroupId);
     }
     catch {
         return {
@@ -169,7 +235,7 @@ export const observeOwnedProcessGroup = async (ownership, host = systemHost) =>
             reason: "process group could not be inspected",
         };
     }
-    const liveMembers = liveProcessGroupMembers(members);
+    const liveMembers = liveProcesses(members);
     if (liveMembers.length === 0)
         return { state: "empty" };
     for (const member of liveMembers) {
@@ -190,10 +256,91 @@ export const observeOwnedProcessGroup = async (ownership, host = systemHost) =>
     }
     return { state: "alive" };
 };
-const liveProcessGroupMembers = (members) => members.filter(({ state }) => !state.startsWith("Z"));
+/**
+ * Record the live launcher and descendant lineage after run-token validation.
+ *
+ * The observation is intentionally point-in-time. A verified empty descendant
+ * list means no descendants were live during this observation, not that the
+ * run never created a short-lived child.
+ */
+export const observeOwnedProcessLineage = async (ownership, host = systemHost) => {
+    let processes;
+    try {
+        processes = liveProcesses(await host.listProcesses());
+    }
+    catch {
+        return unavailableLineage(ownership, "process table could not be inspected");
+    }
+    const launcher = processes.find(({ pid }) => pid === ownership.leaderPid);
+    if (launcher === undefined)
+        return unavailableLineage(ownership, "owned launcher is not live");
+    if (launcher.processGroupId !== ownership.processGroupId)
+        return unavailableLineage(ownership, "owned launcher process-group identity did not match");
+    if (ownership.expectedParentPid !== undefined &&
+        launcher.parentPid !== ownership.expectedParentPid)
+        return unavailableLineage(ownership, "owned launcher parent identity did not match");
+    if (ownership.expectedCommand !== undefined &&
+        !commandMatches(launcher.command, ownership.expectedCommand))
+        return unavailableLineage(ownership, "owned launcher command identity did not match");
+    const descendants = descendantsOf(launcher.pid, processes);
+    for (const member of [launcher, ...descendants]) {
+        try {
+            if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !==
+                ownership.runId)
+                return unavailableLineage(ownership, "process lineage contains an unowned or PID-reused process");
+        }
+        catch {
+            return unavailableLineage(ownership, "process ownership could not be revalidated");
+        }
+    }
+    return {
+        status: "verified",
+        observedAt: new Date().toISOString(),
+        lineage: {
+            schemaVersion: 1,
+            runId: ownership.runId,
+            launcherPid: launcher.pid,
+            launcherParentPid: launcher.parentPid,
+            processGroupId: launcher.processGroupId,
+            descendants: descendants
+                .sort((left, right) => left.pid - right.pid)
+                .map(({ pid, parentPid, processGroupId }) => ({
+                pid,
+                parentPid,
+                processGroupId,
+            })),
+        },
+    };
+};
+const descendantsOf = (launcherPid, processes) => {
+    const childrenByParent = new Map();
+    for (const process of processes) {
+        const siblings = childrenByParent.get(process.parentPid) ?? [];
+        siblings.push(process);
+        childrenByParent.set(process.parentPid, siblings);
+    }
+    const descendants = [];
+    const pending = [...(childrenByParent.get(launcherPid) ?? [])];
+    const visited = new Set([launcherPid]);
+    for (const process of pending) {
+        if (visited.has(process.pid))
+            continue;
+        visited.add(process.pid);
+        descendants.push(process);
+        pending.push(...(childrenByParent.get(process.pid) ?? []));
+    }
+    return descendants;
+};
+const unavailableLineage = (ownership, reason) => ({
+    status: "unavailable",
+    observedAt: new Date().toISOString(),
+    runId: ownership.runId,
+    launcherPid: ownership.leaderPid,
+    processGroupId: ownership.processGroupId,
+    reason,
+});
+const liveProcesses = (members) => members.filter(({ state }) => !state.startsWith("Z"));
 const commandMatches = (actual, expected) => {
-    const normalizedActual = actual.trim();
-    const normalizedExpected = expected.trim();
-    return (normalizedActual === normalizedExpected ||
-        normalizedActual.startsWith(`${normalizedExpected} `));
+    return (actual.trim() === expected.trim() ||
+        actual.trim().startsWith(`${expected.trim()} `));
 };

package/dist/process/ProviderRunLineage.js

@@ -0,0 +1,21 @@
+import { observeOwnedProcessLineage } from "./ProcessOwnership.js";
+/** Retain the latest truthful process-lineage observation for one client. */
+export class ProviderRunLineage {
+    #observation = null;
+    /** Clear stale lineage before a new launch attempt. */
+    reset() {
+        this.#observation = null;
+    }
+    /** Observe a token-owned launcher without signaling it. */
+    async observe(launch) {
+        if (launch?.ownership === undefined)
+            return;
+        this.#observation = await observeOwnedProcessLineage(launch.ownership);
+    }
+    /** Return a detached copy suitable for caller-visible status. */
+    snapshot() {
+        return this.#observation === null
+            ? null
+            : structuredClone(this.#observation);
+    }
+}

package/dist/server/createServer.js

@@ -15,7 +15,7 @@ import { createServerIdentity } from "../serverIdentity.js";
 import { registerBrowserTools } from "./registerBrowserTools.js";
 import { registerElectronTools } from "./registerElectronTools.js";
 import { registerApplicationTools } from "./registerApplicationTools.js";
-const TARGET_FREE_INSTRUCTIONS = "REA analyzes shipped artifacts and approved runtime evidence; use repository tools for source. Route: ASAR/JavaScript -> analyze_javascript_application; archive/package -> inventory_artifact; managed PE/CLI -> inspect_managed_artifact; browser/Electron runtime -> list_browser_targets/list_electron_targets; native binary/database -> open_binary, then binary_overview. Start with summaries and cite Evidence IDs. Never repeat identical analysis or read full Evidence unless a missing detail requires it.";
+const TARGET_FREE_INSTRUCTIONS = "REA analyzes shipped artifacts. Route: ASAR/JavaScript -> analyze_javascript_application (configured root required); archive/package -> inventory_artifact; managed PE/CLI -> inspect_managed_artifact; browser/Electron runtime -> list_browser_targets/list_electron_targets; native binary/database -> open_binary, then binary_overview. Check binary_session for policy. Start with summaries and cite Evidence IDs. Never repeat identical analysis or read full Evidence without a specific need.";
 const ACTIVE_TARGET_INSTRUCTIONS = "REA analyzes the active reverse-engineering target. Start native analysis with binary_overview, then narrow with analyze_function, literal search, callers, callees, and xrefs. Prefer summary views, never repeat an identical call, and read full Evidence only when the task requires it.";
 import { LinuxJavaScriptReplayRunner } from "../replay/LinuxJavaScriptReplayRunner.js";
 import { SystemJavaScriptReplayHost } from "../replay/SystemJavaScriptReplayHost.js";
@@ -205,6 +205,9 @@ const registerObservationTools = ({ server, session, options, logger, permission
         logger,
         recordEvidence,
         recordEvidenceWithUnknown,
+        evidenceLookup: session === undefined
+            ? undefined
+            : (evidenceId) => session.evidenceById(evidenceId),
         evidenceFilePolicy: options.evidenceFilePolicy ?? {
             roots: [],
             maxBytes: 1,

package/dist/server/javascriptApplicationResult.js

@@ -46,7 +46,7 @@ export const summarizeJavaScriptApplicationEvidence = (evidence) => {
             location: observation.evidence.location,
         };
     });
-    const { graph: _graph, ...summary } = result;
+    const summary = result.schema_version === 1 ? omitGraph(result) : omitGraphs(result);
     const unknowns = new Set([
         ...result.limitations,
         ...result.graph.limitations,
@@ -59,6 +59,19 @@ export const summarizeJavaScriptApplicationEvidence = (evidence) => {
         unknowns.add(`Application graph coverage is ${result.graph.coverage.status}; omitted facts remain unknown.`);
     return javascriptApplicationAnalysisSummarySchema.parse({
         ...summary,
+        ...(result.schema_version === 1
+            ? {}
+            : {
+                semantic_graph: {
+                    graph_id: result.semantic_graph.graph_id,
+                    nodes: result.semantic_graph.nodes.length,
+                    relations: result.semantic_graph.relations.length,
+                    unknown_frontiers: result.semantic_graph.unknowns.length,
+                    fingerprints: result.semantic_graph.fingerprints.length,
+                    coverage: result.semantic_graph.coverage.status,
+                    query_tool: "trace_javascript_semantics",
+                },
+            }),
         unknowns: [...unknowns],
         graph: {
             graph_id: result.graph.graph_id,
@@ -83,3 +96,11 @@ export const summarizeJavaScriptApplicationEvidence = (evidence) => {
         },
     });
 };
+const omitGraph = (result) => {
+    const { graph: _graph, ...summary } = result;
+    return summary;
+};
+const omitGraphs = (result) => {
+    const { graph: _graph, semantic_graph: _semanticGraph, ...summary } = result;
+    return summary;
+};

package/dist/server/registerApplicationTools/characterization.js

@@ -1,5 +1,5 @@
 import { executeNodeCharacterization, prepareNodeCharacterization, } from "../../application/NodeRuntimeCharacterizationService.js";
-import { APPLICATION_TOOL_CONTRACTS } from "../../contracts/applicationToolContracts.js";
+import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
 import { nodeCharacterizationExecutionInputSchema, nodeCharacterizationExecutionOutputSchema, nodeCharacterizationPreparationInputSchema, nodeCharacterizationPreparationOutputSchema, } from "../../domain/nodeRuntimeCharacterization.js";
 import { parseEvidence } from "../../domain/evidence.js";
 import { logToolExecution } from "../toolLogging.js";
@@ -8,8 +8,8 @@ import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
 import { safeParseToolInput } from "../toolInputValidation.js";
 import { mcpProgressReporter } from "../mcpProgress.js";
 import { recordSources } from "./helpers.js";
-const prepareContract = APPLICATION_TOOL_CONTRACTS[3];
-const executeContract = APPLICATION_TOOL_CONTRACTS[4];
+const prepareContract = applicationToolContract("prepare_node_characterization");
+const executeContract = applicationToolContract("execute_node_characterization");
 /** Register node runtime characterization prepare and execute tools. */
 export const registerCharacterizationTools = (server, options) => {
     server.registerTool(prepareContract.name, toolRegistrationOptions(prepareContract), async (input, context) => {

package/dist/server/registerApplicationTools/compareExportShapes.js

@@ -0,0 +1,37 @@
+import { resolveCompareJavaScriptExportShapesRequestValidated } from "../../application/ApplicationWorkflowEvidenceResolver.js";
+import { compareJavaScriptExportShapesEvidenceValidated } from "../../application/JavaScriptApplicationWorkflowService.js";
+import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
+import { compareJavaScriptExportShapesRequestSchema } from "../../contracts/applicationWorkflowInputContracts.js";
+import { javaScriptExportShapeComparisonResultSchema } from "../../domain/javascriptExportShapeComparisonSchemas.js";
+import { safeParseToolInput } from "../toolInputValidation.js";
+import { logToolExecution } from "../toolLogging.js";
+import { toCallToolResult } from "../toolResult.js";
+import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
+import { recordResult, recordSources } from "./helpers.js";
+const contract = applicationToolContract("compare_javascript_export_shapes");
+/** Register the execution-free exact JavaScript export-shape comparison. */
+export const registerCompareJavaScriptExportShapesTool = (server, options) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input) => {
+        const parsedInput = safeParseToolInput(compareJavaScriptExportShapesRequestSchema, input, contract.name);
+        if (!parsedInput.ok)
+            return toCallToolResult(parsedInput, contract);
+        const resolved = resolveCompareJavaScriptExportShapesRequestValidated(parsedInput.value, options.evidenceLookup);
+        if (!resolved.ok)
+            return toCallToolResult(resolved, contract);
+        const parsed = resolved.value;
+        const result = await logToolExecution(options.logger, contract.name, () => Promise.resolve(compareJavaScriptExportShapesEvidenceValidated(parsed)));
+        if (!result.ok)
+            return toCallToolResult(result, contract);
+        const recorded = recordSources(options.recordEvidence, [
+            parsed.left,
+            parsed.right,
+        ]);
+        if (!recorded.ok)
+            return toCallToolResult(recorded, contract);
+        const comparison = javaScriptExportShapeComparisonResultSchema.parse(result.value.normalized_result);
+        const unknown = comparison.summary.unknown > 0;
+        return recordResult(options, contract, result.value, parsed.unknown_registry_approved === true && unknown
+            ? "javascript-export-shape"
+            : undefined);
+    });
+};

package/dist/server/registerApplicationTools/compareVersions.js

@@ -1,20 +1,24 @@
 import { compareApplicationVersionsEvidenceValidated } from "../../application/JavaScriptApplicationWorkflowService.js";
-import { APPLICATION_TOOL_CONTRACTS } from "../../contracts/applicationToolContracts.js";
-import { compareApplicationVersionsInputSchema } from "../../domain/javascriptApplicationVersionComparisonSchemas.js";
+import { resolveCompareApplicationVersionsRequestValidated } from "../../application/ApplicationWorkflowEvidenceResolver.js";
+import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
+import { compareApplicationVersionsRequestSchema } from "../../contracts/applicationWorkflowInputContracts.js";
 import { applicationVersionComparisonResultSchema } from "../../domain/javascriptApplicationVersionComparisonSchemas.js";
 import { logToolExecution } from "../toolLogging.js";
 import { toCallToolResult } from "../toolResult.js";
 import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
 import { safeParseToolInput } from "../toolInputValidation.js";
 import { recordResult, recordSources } from "./helpers.js";
-const compareContract = APPLICATION_TOOL_CONTRACTS[1];
+const compareContract = applicationToolContract("compare_application_versions");
 /** Register the provider-neutral JavaScript version comparison tool. */
 export const registerCompareApplicationVersionsTool = (server, options) => {
     server.registerTool(compareContract.name, toolRegistrationOptions(compareContract), async (input) => {
-        const parsedInput = safeParseToolInput(compareApplicationVersionsInputSchema, input, compareContract.name);
+        const parsedInput = safeParseToolInput(compareApplicationVersionsRequestSchema, input, compareContract.name);
         if (!parsedInput.ok)
             return toCallToolResult(parsedInput, compareContract);
-        const parsed = parsedInput.value;
+        const resolved = resolveCompareApplicationVersionsRequestValidated(parsedInput.value, options.evidenceLookup);
+        if (!resolved.ok)
+            return toCallToolResult(resolved, compareContract);
+        const parsed = resolved.value;
         const result = await logToolExecution(options.logger, compareContract.name, () => Promise.resolve(compareApplicationVersionsEvidenceValidated(parsed)));
         if (!result.ok)
             return toCallToolResult(result, compareContract);
@@ -29,6 +33,8 @@ export const registerCompareApplicationVersionsTool = (server, options) => {
             return toCallToolResult(recorded, compareContract);
         const comparison = applicationVersionComparisonResultSchema.parse(result.value.normalized_result);
         const unknown = comparison.summary.unknown > 0;
-        return recordResult(options, compareContract, result.value, parsed.unknown_registry_approved === true && unknown);
+        return recordResult(options, compareContract, result.value, parsed.unknown_registry_approved === true && unknown
+            ? "application-version-comparison"
+            : undefined);
     });
 };

package/dist/server/registerApplicationTools/controlledReplay.js

@@ -1,5 +1,5 @@
 import { runControlledReplayValidated } from "../../application/JavaScriptReplayService.js";
-import { APPLICATION_TOOL_CONTRACTS } from "../../contracts/applicationToolContracts.js";
+import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
 import { controlledReplayInputSchema, controlledReplayOutputSchema, } from "../../domain/javascriptReplay.js";
 import { parseEvidence } from "../../domain/evidence.js";
 import { logToolExecution } from "../toolLogging.js";
@@ -8,7 +8,7 @@ import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
 import { safeParseToolInput } from "../toolInputValidation.js";
 import { mcpProgressReporter } from "../mcpProgress.js";
 import { recordSources } from "./helpers.js";
-const replayContract = APPLICATION_TOOL_CONTRACTS[2];
+const replayContract = applicationToolContract("run_controlled_replay");
 /** Register the controlled JavaScript replay tool. */
 export const registerControlledReplayTool = (server, options) => {
     server.registerTool(replayContract.name, toolRegistrationOptions(replayContract), async (input, context) => {

package/dist/server/registerApplicationTools/coverage.js

@@ -1,7 +1,7 @@
 import { commitReconstructionCoverage, queryReconstructionCoverage, } from "../../application/ReconstructionCoverageService.js";
 import { readReconstructionCoverageWorkspace } from "../../application/ReconstructionCoverageWorkspaceStore.js";
 import { authorizeFileReadWithDeferredWrite, authorizeRootPermission, } from "../../application/DeferredFileAuthorization.js";
-import { APPLICATION_TOOL_CONTRACTS } from "../../contracts/applicationToolContracts.js";
+import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
 import { reconstructionCoverageCommitInputSchema, reconstructionCoverageQueryInputSchema, } from "../../application/ReconstructionCoverageService.js";
 import { reconstructionClosureResultSchema } from "../../domain/reconstructionCoverage.js";
 import { AnalysisCapabilityUnavailableError, EvidenceIntegrityError, } from "../../domain/errors.js";
@@ -11,8 +11,8 @@ import { toCallToolResult } from "../toolResult.js";
 import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
 import { safeParseToolInput } from "../toolInputValidation.js";
 import { coverageWorkspaceUri } from "./helpers.js";
-const commitContract = APPLICATION_TOOL_CONTRACTS[5];
-const queryContract = APPLICATION_TOOL_CONTRACTS[6];
+const commitContract = applicationToolContract("commit_reconstruction_coverage");
+const queryContract = applicationToolContract("query_reconstruction_coverage");
 /** Register reconstruction coverage commit and query tools. */
 export const registerCoverageTools = (server, options) => {
     registerCommitTool(server, options);

package/dist/server/registerApplicationTools/helpers.js

@@ -9,34 +9,46 @@ export const recordSources = (recordEvidence, sources) => {
     }
     return { ok: true, value: null };
 };
-export const recordResult = (options, contract, evidence, recordUnknown = false) => {
-    const recorded = recordUnknown
-        ? options.recordEvidenceWithUnknown?.(evidence, {
-            approved: true,
-            question: "Which application entities remain unmatched or ambiguous across these versions?",
-            severity: "medium",
-            domain: "application-version-comparison",
-            supporting_evidence_ids: [evidence.evidence_id],
-            contradicting_evidence_ids: [],
-            required_authority: "shipped-artifact",
-            required_confidence: "observed",
-            required_environment: null,
-            recommended_probes: [
-                {
-                    operation: "analyze_javascript_application",
-                    rationale: "Repeat static reconstruction with complete artifacts and source maps when available.",
-                },
-                {
-                    operation: "reconcile_javascript_runtime",
-                    rationale: "Add approved passive runtime Evidence without promoting it to static fact.",
-                },
-            ],
-            relationships: [],
-        })
-        : options.recordEvidence?.(evidence);
+export const recordResult = (options, contract, evidence, unknownKind) => {
+    const recorded = unknownKind === undefined
+        ? options.recordEvidence?.(evidence)
+        : options.recordEvidenceWithUnknown?.(evidence, unknownRegistration(evidence, unknownKind));
     if (recorded !== undefined && !recorded.ok)
         return toCallToolResult(recorded, contract);
     return toCallToolResult({ ok: true, value: evidence }, contract, {
         evidenceResourcesAvailable: recorded !== undefined,
     });
 };
+const unknownRegistration = (evidence, kind) => ({
+    approved: true,
+    question: kind === "application-version-comparison"
+        ? "Which application entities remain unmatched or ambiguous across these versions?"
+        : "Which selected JavaScript export return shapes remain dynamic, incomplete, or ambiguously paired?",
+    severity: "medium",
+    domain: kind,
+    supporting_evidence_ids: [evidence.evidence_id],
+    contradicting_evidence_ids: [],
+    required_authority: "shipped-artifact",
+    required_confidence: "observed",
+    required_environment: null,
+    recommended_probes: [
+        {
+            operation: "analyze_javascript_application",
+            rationale: "Repeat static reconstruction with complete artifacts and source maps when available.",
+        },
+        ...(kind === "application-version-comparison"
+            ? [
+                {
+                    operation: "reconcile_javascript_runtime",
+                    rationale: "Add approved passive runtime Evidence without promoting it to static fact.",
+                },
+            ]
+            : [
+                {
+                    operation: "run_controlled_replay",
+                    rationale: "Validate exact approved module behavior separately when runtime semantics are required.",
+                },
+            ]),
+    ],
+    relationships: [],
+});

package/dist/server/registerApplicationTools/traceFeature.js

@@ -1,19 +1,23 @@
 import { traceApplicationFeatureEvidenceValidated } from "../../application/JavaScriptApplicationWorkflowService.js";
-import { APPLICATION_TOOL_CONTRACTS } from "../../contracts/applicationToolContracts.js";
-import { traceApplicationFeatureInputSchema } from "../../domain/javascriptFeatureTraceSchemas.js";
+import { resolveTraceApplicationFeatureRequestValidated } from "../../application/ApplicationWorkflowEvidenceResolver.js";
+import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
+import { traceApplicationFeatureRequestSchema } from "../../contracts/applicationWorkflowInputContracts.js";
 import { logToolExecution } from "../toolLogging.js";
 import { toCallToolResult } from "../toolResult.js";
 import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
 import { safeParseToolInput } from "../toolInputValidation.js";
 import { recordResult, recordSources } from "./helpers.js";
-const traceContract = APPLICATION_TOOL_CONTRACTS[0];
+const traceContract = applicationToolContract("trace_application_feature");
 /** Register the provider-neutral JavaScript feature trace tool. */
 export const registerTraceFeatureTool = (server, options) => {
     server.registerTool(traceContract.name, toolRegistrationOptions(traceContract), async (input) => {
-        const parsedInput = safeParseToolInput(traceApplicationFeatureInputSchema, input, traceContract.name);
+        const parsedInput = safeParseToolInput(traceApplicationFeatureRequestSchema, input, traceContract.name);
         if (!parsedInput.ok)
             return toCallToolResult(parsedInput, traceContract);
-        const parsed = parsedInput.value;
+        const resolved = resolveTraceApplicationFeatureRequestValidated(parsedInput.value, options.evidenceLookup);
+        if (!resolved.ok)
+            return toCallToolResult(resolved, traceContract);
+        const parsed = resolved.value;
         const result = await logToolExecution(options.logger, traceContract.name, () => Promise.resolve(traceApplicationFeatureEvidenceValidated(parsed)));
         if (!result.ok)
             return toCallToolResult(result, traceContract);