windows-exe-decompiler-mcp-server 0.1.0 → 0.1.3

package/dist/runtime-correlation.js

@@ -109,6 +109,22 @@ export function deriveRuntimeStageCandidates(input) {
         semanticCorpus.includes('overlay')) {
         stages.add('scan_pe_layout');
     }
+    if (behaviorTags.has('dll_lifecycle') ||
+        /\b(dllmain|dllregisterserver|dllunregisterserver|dllinstall|dllcanunloadnow|dll_process_attach|dll_thread_attach|disablethreadlibrarycalls)\b/i.test(semanticCorpus)) {
+        stages.add('dll_lifecycle');
+    }
+    if (behaviorTags.has('com_activation') ||
+        /\b(cocreateinstance|queryinterface|registerclassobject|dllgetclassobject|iclassfactory|clsid_|progid|inprocserver32|localserver32)\b/i.test(semanticCorpus)) {
+        stages.add('com_activation');
+    }
+    if (behaviorTags.has('export_dispatch') ||
+        /\b(export dispatch|forwarded export|ordinal|dispatch exported|dllcanunloadnow|dllgetclassobject)\b/i.test(semanticCorpus)) {
+        stages.add('export_dispatch');
+    }
+    if (behaviorTags.has('plugin_callback') ||
+        /\b(callback|plugin|hook|event sink|notify|host extension|host interaction)\b/i.test(semanticCorpus)) {
+        stages.add('callback_surface');
+    }
     return Array.from(stages);
 }
 function regionMatchersForStage(stage) {
@@ -127,10 +143,110 @@ function regionMatchersForStage(stage) {
             return [/registry/i, /key/i];
         case 'scan_pe_layout':
             return [/packer/i, /entropy/i, /section/i, /layout/i];
+        case 'dll_lifecycle':
+            return [/dll/i, /lifecycle/i, /attach/i, /detach/i, /module/i];
+        case 'com_activation':
+            return [/com/i, /class/i, /factory/i, /activation/i, /registration/i];
+        case 'export_dispatch':
+            return [/export/i, /dispatch/i, /ordinal/i, /forward/i];
+        case 'callback_surface':
+            return [/callback/i, /plugin/i, /hook/i, /notify/i, /host/i];
         default:
             return [];
     }
 }
+function protectionMatchersForStage(stage) {
+    switch (stage) {
+        case 'resolve_dynamic_apis':
+            return [/image/i, /r-x/i, /execute/i];
+        case 'prepare_remote_process_access':
+            return [/read_write/i, /write/i, /execute/i, /rwx/i];
+        case 'anti_analysis_checks':
+        case 'check_execution_environment':
+            return [/read/i, /image/i];
+        case 'file_operations':
+            return [/file/i, /read_write/i, /container/i];
+        case 'registry_operations':
+        case 'stage_registry_state':
+            return [/read_write/i, /data/i];
+        case 'scan_pe_layout':
+            return [/image/i, /container/i, /read/i];
+        case 'dll_lifecycle':
+        case 'com_activation':
+        case 'export_dispatch':
+        case 'callback_surface':
+            return [/image/i, /read/i, /execute/i];
+        default:
+            return [];
+    }
+}
+function ownerMatchersForStage(stage) {
+    switch (stage) {
+        case 'resolve_dynamic_apis':
+        case 'prepare_remote_process_access':
+            return [/kernel32/i, /kernelbase/i, /ntdll/i, /\.exe$/i, /\.dll$/i];
+        case 'anti_analysis_checks':
+        case 'check_execution_environment':
+            return [/kernel32/i, /kernelbase/i, /ntdll/i];
+        case 'file_operations':
+            return [/kernel32/i, /kernelbase/i, /shlwapi/i];
+        case 'registry_operations':
+        case 'stage_registry_state':
+            return [/advapi32/i];
+        case 'scan_pe_layout':
+            return [/\.exe$/i, /\.dll$/i];
+        case 'dll_lifecycle':
+            return [/\.dll$/i, /\.ocx$/i, /\.cpl$/i];
+        case 'com_activation':
+            return [/ole32/i, /oleaut32/i, /combase/i, /rpcrt4/i, /\.dll$/i];
+        case 'export_dispatch':
+            return [/\.dll$/i, /\.ocx$/i, /\.cpl$/i];
+        case 'callback_surface':
+            return [/plugin/i, /host/i, /extension/i, /addin/i, /\.dll$/i];
+        default:
+            return [];
+    }
+}
+function segmentMatchersForStage(stage) {
+    switch (stage) {
+        case 'scan_pe_layout':
+            return [/\.pdata/i, /\.xdata/i, /\.text/i, /\.rsrc/i];
+        case 'dll_lifecycle':
+            return [/\.tls/i, /\.crt/i, /\.rdata/i, /init/i];
+        case 'com_activation':
+            return [/\.idata/i, /\.rdata/i, /class/i, /factory/i];
+        case 'export_dispatch':
+            return [/\.edata/i, /export/i, /dispatch/i];
+        case 'callback_surface':
+            return [/callback/i, /hook/i, /event/i, /notify/i];
+        case 'prepare_remote_process_access':
+            return [/\.text/i, /\.data/i];
+        default:
+            return [];
+    }
+}
+function collectMatchedMetadataValues(values, candidateStages, input, matchersForStage, fallbackMatcher) {
+    const semanticCorpus = buildSemanticCorpus(input);
+    const matched = new Set();
+    for (const value of values) {
+        const lowered = value.toLowerCase();
+        for (const stage of candidateStages) {
+            if (matchersForStage(stage).some((matcher) => matcher.test(lowered))) {
+                matched.add(value);
+            }
+        }
+        if (fallbackMatcher?.(lowered, semanticCorpus)) {
+            matched.add(value);
+        }
+    }
+    return Array.from(matched).slice(0, 6);
+}
+function collectMatchedAddressRanges(matchedMemoryRegions, dynamicEvidence) {
+    if (matchedMemoryRegions.length === 0) {
+        return [];
+    }
+    return dedupe(dynamicEvidence.address_ranges || []).slice(0, Math.max(1, matchedMemoryRegions.length));
+}
 function collectMatchedMemoryRegions(candidateStages, input, dynamicEvidence) {
     const semanticCorpus = buildSemanticCorpus(input);
     const matched = new Set();
@@ -168,6 +284,11 @@ export function correlateFunctionWithRuntimeEvidence(input, dynamicEvidence) {
     const observedStages = new Set((dynamicEvidence.stages || []).map((item) => item.toLowerCase()));
     const matchedStages = candidateStages.filter((item) => observedStages.has(item.toLowerCase()));
     const matchedMemoryRegions = collectMatchedMemoryRegions(candidateStages, input, dynamicEvidence);
+    const matchedProtections = collectMatchedMetadataValues(dynamicEvidence.protections || [], candidateStages, input, protectionMatchersForStage, (lowered, semanticCorpus) => semanticCorpus.includes('remote') && /(read_write|write|execute|rwx)/i.test(lowered));
+    const matchedRegionOwners = collectMatchedMetadataValues(dynamicEvidence.region_owners || [], candidateStages, input, ownerMatchersForStage, (lowered, semanticCorpus) => semanticCorpus.includes('com') && /(ole32|oleaut32|combase|rpcrt4)/i.test(lowered));
+    const matchedObservedModules = collectMatchedMetadataValues(dynamicEvidence.observed_modules || [], candidateStages, input, ownerMatchersForStage, (lowered, semanticCorpus) => semanticCorpus.includes('com') && /(ole32|oleaut32|combase|rpcrt4)/i.test(lowered));
+    const matchedSegmentNames = collectMatchedMetadataValues(dynamicEvidence.segment_names || [], candidateStages, input, segmentMatchersForStage);
+    const matchedAddressRanges = collectMatchedAddressRanges(matchedMemoryRegions, dynamicEvidence);
     const evidenceSources = summarizeEvidenceSources(dynamicEvidence);
     const sourceNames = summarizeSourceNames(dynamicEvidence);
     const provenanceLayers = summarizeProvenanceLayers(dynamicEvidence);
@@ -178,7 +299,13 @@ export function correlateFunctionWithRuntimeEvidence(input, dynamicEvidence) {
         (input.stringHints || []).length > 0 ? 'string_hint' : '',
         input.semanticSummary ? 'semantic_summary' : '',
     ]);
-    if (matchedApis.length === 0 && matchedStages.length === 0 && matchedMemoryRegions.length === 0) {
+    if (matchedApis.length === 0 &&
+        matchedStages.length === 0 &&
+        matchedMemoryRegions.length === 0 &&
+        matchedProtections.length === 0 &&
+        matchedRegionOwners.length === 0 &&
+        matchedObservedModules.length === 0 &&
+        matchedSegmentNames.length === 0) {
         return undefined;
     }
     const highSignalMatches = matchedApis.filter((item) => highSignalSet.has(normalizeRuntimeApiName(item).toLowerCase()));
@@ -192,6 +319,21 @@ export function correlateFunctionWithRuntimeEvidence(input, dynamicEvidence) {
     if (matchedMemoryRegions.length > 0) {
         notes.push(`Runtime memory regions align with this function: ${matchedMemoryRegions.slice(0, 4).join(', ')}`);
     }
+    if (matchedProtections.length > 0) {
+        notes.push(`Runtime protections align with this function: ${matchedProtections.slice(0, 4).join(', ')}`);
+    }
+    if (matchedRegionOwners.length > 0) {
+        notes.push(`Runtime region owners align with this function: ${matchedRegionOwners.slice(0, 4).join(', ')}`);
+    }
+    if (matchedObservedModules.length > 0) {
+        notes.push(`Runtime modules align with this function: ${matchedObservedModules.slice(0, 4).join(', ')}`);
+    }
+    if (matchedSegmentNames.length > 0) {
+        notes.push(`Runtime segments align with this function: ${matchedSegmentNames.slice(0, 4).join(', ')}`);
+    }
+    if (matchedAddressRanges.length > 0) {
+        notes.push(`Runtime address ranges associated with this function: ${matchedAddressRanges.slice(0, 3).join(', ')}`);
+    }
     if (dynamicEvidence.executed) {
         notes.push('Correlation includes executed runtime evidence, not just static or memory-only hints.');
     }
@@ -225,6 +367,22 @@ export function correlateFunctionWithRuntimeEvidence(input, dynamicEvidence) {
         ...(matchedMemoryRegions.some((item) => /network|socket|http|pipe|ipc/i.test(item))
             ? ['network_ops']
             : []),
+        ...(matchedRegionOwners.some((item) => /ole32|oleaut32|combase|rpcrt4/i.test(item)) ||
+            matchedObservedModules.some((item) => /ole32|oleaut32|combase|rpcrt4/i.test(item))
+            ? ['com_activation']
+            : []),
+        ...(matchedSegmentNames.some((item) => /\.edata|export|dispatch/i.test(item)) ||
+            matchedStages.some((item) => item.toLowerCase() === 'export_dispatch')
+            ? ['export_dispatch']
+            : []),
+        ...(matchedSegmentNames.some((item) => /\.tls|\.crt|init/i.test(item)) ||
+            matchedStages.some((item) => item.toLowerCase() === 'dll_lifecycle')
+            ? ['dll_lifecycle']
+            : []),
+        ...(matchedStages.some((item) => item.toLowerCase() === 'callback_surface') ||
+            matchedObservedModules.some((item) => /plugin|host|extension|addin/i.test(item))
+            ? ['callback_surface']
+            : []),
     ]);
     if (suggestedModules.length > 0) {
         notes.push(`Suggested semantic modules: ${suggestedModules.slice(0, 4).join(', ')}`);
@@ -233,7 +391,9 @@ export function correlateFunctionWithRuntimeEvidence(input, dynamicEvidence) {
         Math.min(0.24, dedupe(matchedApis).length * 0.08) +
         Math.min(0.16, dedupe(matchedStages).length * 0.06) +
         Math.min(0.12, highSignalMatches.length * 0.05) +
-        Math.min(0.1, matchedMemoryRegions.length * 0.04), 0.45, 0.97);
+        Math.min(0.1, matchedMemoryRegions.length * 0.04) +
+        Math.min(0.07, matchedProtections.length * 0.02) +
+        Math.min(0.07, (matchedRegionOwners.length + matchedObservedModules.length + matchedSegmentNames.length) * 0.015), 0.45, 0.97);
     return {
         corroborated_apis: dedupe(matchedApis).slice(0, 8),
         corroborated_stages: dedupe(matchedStages).slice(0, 6),
@@ -245,6 +405,11 @@ export function correlateFunctionWithRuntimeEvidence(input, dynamicEvidence) {
         artifact_count: dynamicEvidence.artifact_count,
         executed_artifact_count: dynamicEvidence.executed_artifact_count || 0,
         matched_memory_regions: matchedMemoryRegions,
+        matched_protections: matchedProtections,
+        matched_address_ranges: matchedAddressRanges,
+        matched_region_owners: matchedRegionOwners,
+        matched_observed_modules: matchedObservedModules,
+        matched_segment_names: matchedSegmentNames,
         suggested_modules: suggestedModules,
         matched_by: matchedBy,
         provenance_layers: provenanceLayers,
@@ -273,6 +438,18 @@ export function modulesSuggestedByRuntimeStages(stages = []) {
         else if (stage === 'resolve_dynamic_apis') {
             modules.add('process_ops');
         }
+        else if (stage === 'dll_lifecycle') {
+            modules.add('dll_lifecycle');
+        }
+        else if (stage === 'com_activation') {
+            modules.add('com_activation');
+        }
+        else if (stage === 'export_dispatch') {
+            modules.add('export_dispatch');
+        }
+        else if (stage === 'callback_surface') {
+            modules.add('callback_surface');
+        }
     }
     return Array.from(modules);
 }

package/dist/sample-workspace.d.ts

@@ -0,0 +1,28 @@
+import type { WorkspaceManager } from './workspace-manager.js';
+export type SampleWorkspaceStatus = 'ready' | 'workspace_missing' | 'original_dir_missing' | 'original_file_missing';
+export interface SampleWorkspaceIntegrity {
+    status: SampleWorkspaceStatus;
+    workspace_root: string | null;
+    original_dir: string | null;
+    reports_dir: string | null;
+    ghidra_dir: string | null;
+    workspace_exists: boolean;
+    original_dir_exists: boolean;
+    reports_dir_exists: boolean;
+    ghidra_dir_exists: boolean;
+    original_present: boolean;
+    original_file_count: number;
+    original_files: string[];
+    alternate_workspace_root: string | null;
+    alternate_original_dir: string | null;
+    alternate_original_present: boolean;
+    alternate_original_files: string[];
+    remediation: string[];
+}
+export declare function inspectSampleWorkspace(workspaceManager: WorkspaceManager, sampleId: string): Promise<SampleWorkspaceIntegrity>;
+export declare function formatMissingOriginalError(sampleId: string, integrity: SampleWorkspaceIntegrity): string;
+export declare function resolvePrimarySamplePath(workspaceManager: WorkspaceManager, sampleId: string): Promise<{
+    samplePath: string;
+    integrity: SampleWorkspaceIntegrity;
+}>;
+//# sourceMappingURL=sample-workspace.d.ts.map

package/dist/sample-workspace.js

@@ -0,0 +1,186 @@
+import fs from 'fs/promises';
+import path from 'path';
+function buildRemediation(status, sampleId) {
+    const shared = [
+        `Re-ingest the sample with sample.ingest(path=<absolute path>) for ${sampleId}.`,
+        'Or restore the original binary into workspace/original before running PE/Ghidra recovery tools.',
+    ];
+    if (status === 'workspace_missing') {
+        return [
+            `Workspace directory is missing for ${sampleId}.`,
+            ...shared,
+        ];
+    }
+    if (status === 'original_dir_missing') {
+        return [
+            'workspace/original is missing even though the sample record still exists.',
+            ...shared,
+        ];
+    }
+    if (status === 'original_file_missing') {
+        return [
+            'workspace/original exists but contains no sample file.',
+            ...shared,
+        ];
+    }
+    return [];
+}
+function inferStatus(options) {
+    if (!options.workspaceExists) {
+        return 'workspace_missing';
+    }
+    if (!options.originalDirExists) {
+        return 'original_dir_missing';
+    }
+    if (options.originalFileCount <= 0) {
+        return 'original_file_missing';
+    }
+    return 'ready';
+}
+export async function inspectSampleWorkspace(workspaceManager, sampleId) {
+    const workspaceRootBase = workspaceManager.getWorkspaceRoot();
+    let workspaceRoot = null;
+    let originalDir = null;
+    let reportsDir = null;
+    let ghidraDir = null;
+    let workspaceExists = false;
+    let originalDirExists = false;
+    let reportsDirExists = false;
+    let ghidraDirExists = false;
+    let originalFiles = [];
+    let alternateWorkspaceRoot = null;
+    let alternateOriginalDir = null;
+    let alternateOriginalFiles = [];
+    try {
+        const workspace = await workspaceManager.getWorkspace(sampleId);
+        workspaceRoot = workspace.root;
+        originalDir = workspace.original;
+        reportsDir = workspace.reports;
+        ghidraDir = workspace.ghidra;
+        try {
+            await fs.access(workspace.root);
+            workspaceExists = true;
+        }
+        catch {
+            workspaceExists = false;
+        }
+        try {
+            await fs.access(workspace.original);
+            originalDirExists = true;
+            const entries = await fs.readdir(workspace.original, { withFileTypes: true });
+            originalFiles = entries
+                .filter((entry) => entry.isFile())
+                .map((entry) => entry.name)
+                .sort();
+        }
+        catch {
+            originalDirExists = false;
+        }
+        try {
+            await fs.access(workspace.reports);
+            reportsDirExists = true;
+        }
+        catch {
+            reportsDirExists = false;
+        }
+        try {
+            await fs.access(workspace.ghidra);
+            ghidraDirExists = true;
+        }
+        catch {
+            ghidraDirExists = false;
+        }
+    }
+    catch {
+        workspaceExists = false;
+    }
+    const status = inferStatus({
+        workspaceExists,
+        originalDirExists,
+        originalFileCount: originalFiles.length,
+    });
+    if (status !== 'ready') {
+        const workspaceParent = path.dirname(path.dirname(workspaceRootBase));
+        const candidateRoots = Array.from(new Set([
+            path.join(workspaceParent, 'workspaces'),
+        ])).filter((candidate) => path.resolve(candidate) !== path.resolve(workspaceRootBase));
+        const sampleHash = sampleId.startsWith('sha256:') ? sampleId.slice(7).toLowerCase() : null;
+        if (sampleHash && /^[a-f0-9]{64}$/.test(sampleHash)) {
+            for (const candidateRoot of candidateRoots) {
+                const candidateOriginalDir = path.join(candidateRoot, sampleHash.slice(0, 2), sampleHash.slice(2, 4), sampleHash, 'original');
+                try {
+                    const entries = await fs.readdir(candidateOriginalDir, { withFileTypes: true });
+                    const files = entries.filter((entry) => entry.isFile()).map((entry) => entry.name).sort();
+                    if (files.length > 0) {
+                        alternateWorkspaceRoot = candidateRoot;
+                        alternateOriginalDir = candidateOriginalDir;
+                        alternateOriginalFiles = files;
+                        break;
+                    }
+                }
+                catch {
+                    // ignore missing legacy workspace candidates
+                }
+            }
+        }
+    }
+    return {
+        status,
+        workspace_root: workspaceRoot,
+        original_dir: originalDir,
+        reports_dir: reportsDir,
+        ghidra_dir: ghidraDir,
+        workspace_exists: workspaceExists,
+        original_dir_exists: originalDirExists,
+        reports_dir_exists: reportsDirExists,
+        ghidra_dir_exists: ghidraDirExists,
+        original_present: originalFiles.length > 0,
+        original_file_count: originalFiles.length,
+        original_files: originalFiles,
+        alternate_workspace_root: alternateWorkspaceRoot,
+        alternate_original_dir: alternateOriginalDir,
+        alternate_original_present: alternateOriginalFiles.length > 0,
+        alternate_original_files: alternateOriginalFiles,
+        remediation: buildRemediation(status, sampleId),
+    };
+}
+export function formatMissingOriginalError(sampleId, integrity) {
+    const parts = [
+        `Sample original file is unavailable for ${sampleId}.`,
+        `status=${integrity.status}`,
+    ];
+    if (integrity.workspace_root) {
+        parts.push(`workspace_root=${integrity.workspace_root}`);
+    }
+    if (integrity.original_dir) {
+        parts.push(`original_dir=${integrity.original_dir}`);
+    }
+    if (integrity.alternate_original_present && integrity.alternate_original_dir) {
+        parts.push(`alternate_original_dir=${integrity.alternate_original_dir}`);
+        parts.push('alternate_workspace_fallback=available');
+    }
+    if (integrity.remediation.length > 0) {
+        parts.push(`remediation=${integrity.remediation.join(' ')}`);
+    }
+    return parts.join(' ');
+}
+export async function resolvePrimarySamplePath(workspaceManager, sampleId) {
+    const integrity = await inspectSampleWorkspace(workspaceManager, sampleId);
+    if (integrity.original_present && integrity.original_dir) {
+        return {
+            samplePath: path.join(integrity.original_dir, integrity.original_files[0]),
+            integrity,
+        };
+    }
+    if (integrity.alternate_original_present && integrity.alternate_original_dir) {
+        return {
+            samplePath: path.join(integrity.alternate_original_dir, integrity.alternate_original_files[0]),
+            integrity,
+        };
+    }
+    if (!integrity.original_present || !integrity.original_dir) {
+        throw new Error(formatMissingOriginalError(sampleId, integrity));
+    }
+    throw new Error(formatMissingOriginalError(sampleId, integrity));
+}
+//# sourceMappingURL=sample-workspace.js.map

package/dist/semantic-name-suggestion-artifacts.d.ts

@@ -5,6 +5,8 @@ export declare const SEMANTIC_NAME_SUGGESTIONS_ARTIFACT_TYPE = "semantic_name_su
 export declare const SEMANTIC_NAME_PREPARE_BUNDLE_ARTIFACT_TYPE = "semantic_name_prepare_bundle";
 export declare const SEMANTIC_EXPLANATION_PREPARE_BUNDLE_ARTIFACT_TYPE = "semantic_explanation_prepare_bundle";
 export declare const SEMANTIC_FUNCTION_EXPLANATIONS_ARTIFACT_TYPE = "semantic_function_explanations";
+export declare const SEMANTIC_MODULE_REVIEW_PREPARE_BUNDLE_ARTIFACT_TYPE = "semantic_module_review_prepare_bundle";
+export declare const SEMANTIC_MODULE_REVIEWS_ARTIFACT_TYPE = "semantic_module_reviews";
 export interface SemanticNameSuggestionEntry {
     address?: string | null;
     function?: string | null;
@@ -102,15 +104,69 @@ export interface SemanticFunctionExplanationIndex {
     latest_created_at: string | null;
     scope_note: string;
 }
+export interface SemanticModuleReviewEntry {
+    module_name: string;
+    refined_name?: string | null;
+    summary: string;
+    role_hint?: string | null;
+    confidence: number;
+    assumptions?: string[];
+    evidence_used?: string[];
+    rewrite_guidance?: string[];
+    focus_areas?: string[];
+    priority_functions?: string[];
+}
+export interface SemanticModuleReviewArtifactPayload {
+    schema_version: 1;
+    sample_id: string;
+    created_at: string;
+    session_tag?: string | null;
+    client_name?: string | null;
+    model_name?: string | null;
+    prepare_artifact_id?: string | null;
+    reviews: SemanticModuleReviewEntry[];
+}
+export interface LoadedSemanticModuleReview {
+    module_name: string;
+    refined_name: string | null;
+    summary: string;
+    role_hint: string | null;
+    confidence: number;
+    assumptions: string[];
+    evidence_used: string[];
+    rewrite_guidance: string[];
+    focus_areas: string[];
+    priority_functions: string[];
+    artifact_id: string;
+    created_at: string;
+    client_name: string | null;
+    model_name: string | null;
+    session_tag: string | null;
+    prepare_artifact_id: string | null;
+}
+export interface SemanticModuleReviewIndex {
+    byModule: Map<string, LoadedSemanticModuleReview>;
+    marker: string;
+    artifact_ids: string[];
+    session_tags: string[];
+    earliest_created_at: string | null;
+    latest_created_at: string | null;
+    scope_note: string;
+}
 export declare function normalizeFunctionKey(value: string | null | undefined): string | null;
 export declare function normalizeAddressKey(value: string | null | undefined): string | null;
 export declare function sanitizeSemanticName(value: string | null | undefined): string | null;
+export declare function normalizeModuleKey(value: string | null | undefined): string | null;
 export declare function persistSemanticNamePrepareBundleArtifact(workspaceManager: WorkspaceManager, database: DatabaseManager, sampleId: string, payload: unknown, sessionTag?: string | null): Promise<ArtifactRef>;
 export declare function persistSemanticExplanationPrepareBundleArtifact(workspaceManager: WorkspaceManager, database: DatabaseManager, sampleId: string, payload: unknown, sessionTag?: string | null): Promise<ArtifactRef>;
 export declare function persistSemanticFunctionExplanationsArtifact(workspaceManager: WorkspaceManager, database: DatabaseManager, payload: SemanticFunctionExplanationArtifactPayload): Promise<ArtifactRef>;
+export declare function persistSemanticModuleReviewPrepareBundleArtifact(workspaceManager: WorkspaceManager, database: DatabaseManager, sampleId: string, payload: unknown, sessionTag?: string | null): Promise<ArtifactRef>;
+export declare function persistSemanticModuleReviewsArtifact(workspaceManager: WorkspaceManager, database: DatabaseManager, payload: SemanticModuleReviewArtifactPayload): Promise<ArtifactRef>;
 export declare function persistSemanticNameSuggestionsArtifact(workspaceManager: WorkspaceManager, database: DatabaseManager, payload: SemanticNameSuggestionArtifactPayload): Promise<ArtifactRef>;
 export declare function loadSemanticNameSuggestionIndex(workspaceManager: WorkspaceManager, database: DatabaseManager, sampleId: string, options?: LoadSemanticArtifactOptions): Promise<SemanticNameSuggestionIndex>;
 export declare function loadSemanticFunctionExplanationIndex(workspaceManager: WorkspaceManager, database: DatabaseManager, sampleId: string, options?: LoadSemanticArtifactOptions): Promise<SemanticFunctionExplanationIndex>;
+export declare function loadSemanticModuleReviewIndex(workspaceManager: WorkspaceManager, database: DatabaseManager, sampleId: string, options?: LoadSemanticArtifactOptions): Promise<SemanticModuleReviewIndex>;
 export declare function findSemanticNameSuggestion(index: SemanticNameSuggestionIndex | null | undefined, address: string | null | undefined, funcName: string | null | undefined): LoadedSemanticNameSuggestion | null;
 export declare function findSemanticFunctionExplanation(index: SemanticFunctionExplanationIndex | null | undefined, address: string | null | undefined, funcName: string | null | undefined): LoadedSemanticFunctionExplanation | null;
+export declare function findSemanticModuleReview(index: SemanticModuleReviewIndex | null | undefined, moduleName: string | null | undefined): LoadedSemanticModuleReview | null;
 //# sourceMappingURL=semantic-name-suggestion-artifacts.d.ts.map

package/dist/semantic-name-suggestion-artifacts.js

@@ -6,6 +6,8 @@ export const SEMANTIC_NAME_SUGGESTIONS_ARTIFACT_TYPE = 'semantic_name_suggestion
 export const SEMANTIC_NAME_PREPARE_BUNDLE_ARTIFACT_TYPE = 'semantic_name_prepare_bundle';
 export const SEMANTIC_EXPLANATION_PREPARE_BUNDLE_ARTIFACT_TYPE = 'semantic_explanation_prepare_bundle';
 export const SEMANTIC_FUNCTION_EXPLANATIONS_ARTIFACT_TYPE = 'semantic_function_explanations';
+export const SEMANTIC_MODULE_REVIEW_PREPARE_BUNDLE_ARTIFACT_TYPE = 'semantic_module_review_prepare_bundle';
+export const SEMANTIC_MODULE_REVIEWS_ARTIFACT_TYPE = 'semantic_module_reviews';
 const LATEST_SEMANTIC_ARTIFACT_WINDOW_MS = 10 * 1000;
 function sanitizePathSegment(value, fallback) {
     const normalized = (value || fallback)
@@ -46,6 +48,10 @@ export function sanitizeSemanticName(value) {
     }
     return collapsed;
 }
+export function normalizeModuleKey(value) {
+    const normalized = sanitizeSemanticName(value);
+    return normalized && normalized.length > 0 ? normalized : null;
+}
 async function persistSemanticNamingJsonArtifact(workspaceManager, database, sampleId, artifactType, filePrefix, payload, sessionTag) {
     const workspace = await workspaceManager.createWorkspace(sampleId);
     const sessionSegment = sanitizePathSegment(sessionTag || undefined, 'default');
@@ -85,6 +91,12 @@ export async function persistSemanticExplanationPrepareBundleArtifact(workspaceM
 export async function persistSemanticFunctionExplanationsArtifact(workspaceManager, database, payload) {
     return persistSemanticNamingJsonArtifact(workspaceManager, database, payload.sample_id, SEMANTIC_FUNCTION_EXPLANATIONS_ARTIFACT_TYPE, 'semantic_function_explanations', payload, payload.session_tag);
 }
+export async function persistSemanticModuleReviewPrepareBundleArtifact(workspaceManager, database, sampleId, payload, sessionTag) {
+    return persistSemanticNamingJsonArtifact(workspaceManager, database, sampleId, SEMANTIC_MODULE_REVIEW_PREPARE_BUNDLE_ARTIFACT_TYPE, 'module_review_bundle', payload, sessionTag);
+}
+export async function persistSemanticModuleReviewsArtifact(workspaceManager, database, payload) {
+    return persistSemanticNamingJsonArtifact(workspaceManager, database, payload.sample_id, SEMANTIC_MODULE_REVIEWS_ARTIFACT_TYPE, 'semantic_module_reviews', payload, payload.session_tag);
+}
 export async function persistSemanticNameSuggestionsArtifact(workspaceManager, database, payload) {
     return persistSemanticNamingJsonArtifact(workspaceManager, database, payload.sample_id, SEMANTIC_NAME_SUGGESTIONS_ARTIFACT_TYPE, 'semantic_name_suggestions', payload, payload.session_tag);
 }
@@ -283,6 +295,71 @@ export async function loadSemanticFunctionExplanationIndex(workspaceManager, dat
                 : 'Semantic explanation artifacts reflect the selected artifact scope.',
     };
 }
+export async function loadSemanticModuleReviewIndex(workspaceManager, database, sampleId, options = {}) {
+    const byModule = new Map();
+    const artifacts = database.findArtifactsByType(sampleId, SEMANTIC_MODULE_REVIEWS_ARTIFACT_TYPE);
+    const loadedArtifacts = [];
+    for (const artifact of artifacts) {
+        const payload = (await readArtifactJson(workspaceManager, database, sampleId, artifact.id));
+        loadedArtifacts.push({ artifact, payload });
+    }
+    const filteredArtifacts = filterSemanticArtifactsByScope(loadedArtifacts, options);
+    for (const { artifact, payload } of filteredArtifacts) {
+        if (!payload || !Array.isArray(payload.reviews)) {
+            continue;
+        }
+        for (const review of payload.reviews) {
+            const moduleKey = normalizeModuleKey(review.module_name);
+            if (!moduleKey || byModule.has(moduleKey)) {
+                continue;
+            }
+            byModule.set(moduleKey, {
+                module_name: review.module_name,
+                refined_name: review.refined_name || null,
+                summary: review.summary,
+                role_hint: review.role_hint || null,
+                confidence: review.confidence,
+                assumptions: review.assumptions || [],
+                evidence_used: review.evidence_used || [],
+                rewrite_guidance: review.rewrite_guidance || [],
+                focus_areas: review.focus_areas || [],
+                priority_functions: review.priority_functions || [],
+                artifact_id: artifact.id,
+                created_at: artifact.created_at,
+                client_name: payload.client_name || null,
+                model_name: payload.model_name || null,
+                session_tag: payload.session_tag || null,
+                prepare_artifact_id: payload.prepare_artifact_id || null,
+            });
+        }
+    }
+    return {
+        byModule,
+        marker: filteredArtifacts.length > 0
+            ? filteredArtifacts.map(({ artifact }) => `${artifact.id}:${artifact.sha256}`).join('|')
+            : 'none',
+        artifact_ids: filteredArtifacts.map(({ artifact }) => artifact.id),
+        session_tags: Array.from(new Set(filteredArtifacts.flatMap(({ artifact, payload }) => collectSemanticArtifactSessionTags(artifact.path, payload?.session_tag)))),
+        earliest_created_at: filteredArtifacts.length > 0
+            ? filteredArtifacts
+                .map(({ artifact }) => artifact.created_at)
+                .filter((item) => typeof item === 'string' && item.length > 0)
+                .sort()[0] || null
+            : null,
+        latest_created_at: filteredArtifacts.length > 0
+            ? filteredArtifacts
+                .map(({ artifact }) => artifact.created_at)
+                .filter((item) => typeof item === 'string' && item.length > 0)
+                .sort()
+                .slice(-1)[0] || null
+            : null,
+        scope_note: options.scope === 'session' && options.sessionTag?.trim()
+            ? `Semantic module review artifacts are limited to session selector "${options.sessionTag.trim()}".`
+            : options.scope === 'latest'
+                ? 'Semantic module review artifacts are limited to the latest artifact window.'
+                : 'Semantic module review artifacts reflect the selected artifact scope.',
+    };
+}
 export function findSemanticNameSuggestion(index, address, funcName) {
     if (!index) {
         return null;
@@ -311,4 +388,14 @@ export function findSemanticFunctionExplanation(index, address, funcName) {
     }
     return null;
 }
+export function findSemanticModuleReview(index, moduleName) {
+    if (!index) {
+        return null;
+    }
+    const moduleKey = normalizeModuleKey(moduleName);
+    if (moduleKey && index.byModule.has(moduleKey)) {
+        return index.byModule.get(moduleKey) || null;
+    }
+    return null;
+}
 //# sourceMappingURL=semantic-name-suggestion-artifacts.js.map

package/dist/server.js

@@ -30,7 +30,7 @@ export class MCPServer {
         // Initialize MCP SDK server
         this.server = new Server({
             name: 'windows-exe-decompiler-mcp-server',
-            version: '0.1.0',
+            version: '0.1.3',
         }, {
             capabilities: {
                 tools: {},