@eyeauras/insight-cli 0.0.0-stage → 0.2.0

package/dist/src/prototype-cli.js

@@ -0,0 +1,155 @@
+// Historical publication fixture only. The shipped executable uses cli.ts.
+import { command, createCli, Permission } from '@eyeauras/cli-factory';
+import { readFile, stat } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Store } from './store.js';
+import { Coordinator } from './coordinator.js';
+import { GhidraRuntime } from './ghidra.js';
+import { id, text, fail } from './model.js';
+class Owner {
+    options;
+    profiles = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    selected(c) {
+        const path = c.appArguments.AppDataDirectory;
+        let profile = this.profiles.get(path);
+        if (!profile) {
+            const root = join(path, 'ghidra');
+            profile = { store: new Store(root, c.profile.name, text(c.profile.values.server)), runtime: new GhidraRuntime(root, c), tasks: new Map() };
+            this.profiles.set(path, profile);
+        }
+        if (profile.store.server !== c.profile.values.server)
+            fail('binding', 'Profile server changed while durable work remains; restore its original binding before recovery.');
+        const runtime = profile.runtime.fork(c);
+        return { ...profile, ghidra: runtime, coordinator: new Coordinator(profile.store, this.options.publisher?.(c) ?? runtime, undefined, profile.tasks) };
+    }
+    async invalidateProfile(app) {
+        const profile = this.profiles.get(app.AppDataDirectory);
+        if (Store.pending(join(app.AppDataDirectory, 'ghidra')))
+            fail('blocked', 'Profile contains unverified findings; its journal must be preserved.');
+        if (!profile)
+            return;
+        if (profile.tasks.size || profile.store.batches().some(b => !['published_verified', 'conflict_pending'].includes(b.state)))
+            fail('blocked', 'Profile has unresolved publication work; its AppData must be preserved.');
+        await profile.runtime.dispose();
+        profile.store.close();
+        this.profiles.delete(app.AppDataDirectory);
+    }
+    async dispose() {
+        for (const profile of this.profiles.values()) {
+            await Promise.allSettled([...profile.tasks.values()]);
+            await profile.runtime.dispose();
+            profile.store.close();
+        }
+        this.profiles.clear();
+    }
+}
+async function jsonFile(c, path) {
+    const absolute = resolve(c.cwd, text(path, 4096));
+    const info = await stat(absolute);
+    if (!info.isFile() || info.size > 65536)
+        fail('limit', 'Proposal must be a regular file of at most 64 KiB.');
+    try {
+        const content = await readFile(absolute);
+        if (content.length > 65536)
+            fail('limit', 'Proposal file exceeds 64 KiB.');
+        return JSON.parse(content.toString('utf8'));
+    }
+    catch {
+        fail('invalid', 'File must contain valid JSON.');
+    }
+}
+const fileOption = [{ flags: '--file <path>', description: 'Read the JSON proposal file', required: true }];
+const fields = [
+    ['server', '--server <origin>', 'Select the Ghidra Server origin'],
+    ['readerUser', '--reader-user <user>', 'Select the read-only server account'],
+    ['publisherUser', '--publisher-user <user>', 'Select the publisher server account'],
+    ['java', '--java <path>', 'Locate Java 21'],
+    ['ghidraHome', '--ghidra-home <path>', 'Locate the matching Ghidra installation'],
+    ['mcpJar', '--mcp-jar <path>', 'Locate the GhidraMCP jar'],
+    ['mcpJarSha256', '--mcp-jar-sha256 <sha>', 'Verify the GhidraMCP artifact hash'],
+    ['python', '--python <path>', 'Locate the bridge Python executable'],
+    ['bridgeDirectory', '--bridge-directory <path>', 'Locate the pinned Python bridge module'],
+];
+export function createDefinition(options = {}) {
+    const owner = new Owner(options);
+    return {
+        name: 'insight-ghidra', applicationId: 'insight-ghidra', version: '0.1.0',
+        description: 'Coordinate Ghidra readers and scoped comment publication',
+        permissions: {}, resources: [owner], ...(options.runtime ? { runtime: options.runtime } : {}),
+        profile: { fields: fields.map(([name, flags, description]) => ({ name: name, flags: flags, description: description, ...(name === 'server' ? { required: true, normalize: (value) => { const server = text(value); if (!/^ghidra:\/\/[^/?#@]+$/.test(server))
+                        fail('invalid', 'Server must be a ghidra://host:port origin.'); return server; } } : {}) })) },
+        auth: {
+            loginOptions: [{ flags: '--role <role>', description: 'Select reader or publisher credentials', defaultValue: 'reader' }, { flags: '--password-stdin', description: 'Read the password from stdin' }],
+            async login(c, o) {
+                const role = text(o.role);
+                if (!['reader', 'publisher'].includes(role))
+                    fail('invalid', 'Role must be reader or publisher.');
+                if (!o.passwordStdin || !c.stdinAvailable)
+                    fail('credentials', 'Supply --password-stdin for the selected role.');
+                let candidate = '';
+                for await (const chunk of c.io.input) {
+                    candidate += chunk.toString();
+                    if (candidate.length > 4096)
+                        fail('limit', 'Password input exceeds 4096 characters.');
+                }
+                candidate = candidate.replace(/\r?\n$/, '');
+                if (!candidate || /[\r\n\0]/.test(candidate))
+                    fail('credentials', 'Password must be one non-empty line.');
+                await c.secrets.set(role + 'Password', candidate);
+                return { authenticated: true, identity: { role, user: c.profile.values[role + 'User'], validation: 'stored; server checked at worker startup' } };
+            },
+            async status(c) { const reader = Boolean(await c.secrets.get('readerPassword')), publisher = Boolean(await c.secrets.get('publisherPassword')); return { authenticated: reader, identity: { readerStored: reader, publisherStored: publisher } }; },
+            async logout(c) { await c.secrets.delete('readerPassword'); await c.secrets.delete('publisherPassword'); },
+        },
+        builtins: [command('skill', 'Locate the installed workflow skill', () => ({ version: '0.1.0', path: fileURLToPath(new URL('../../SKILL.md', import.meta.url)) }))],
+        commands: [
+            command('targets', 'Select versioned programs', [
+                command('register', 'Register a complete program identity', async ({ options: o }, c) => owner.selected(c).store.register(await jsonFile(c, o.file)), { permission: Permission.Update, options: fileOption }),
+                command('list', 'List registered program identities', (_i, c) => owner.selected(c).store.targets(), { permission: Permission.ReadOnly }),
+                command('show <target>', 'Show a registered program identity', ({ args }, c) => owner.selected(c).store.target(id(args.target)), { permission: Permission.ReadOnly }),
+            ]),
+            command('workers', 'Manage independent reader processes', [
+                command('start <target> <worker>', 'Start a reader and dedicated bridge', async ({ args }, c) => {
+                    const selected = owner.selected(c), target = selected.store.target(id(args.target)), worker = id(args.worker);
+                    if (selected.store.workers().some(w => w.id === worker))
+                        fail('workerExists', 'Worker ID is already registered.');
+                    const binding = await selected.ghidra.startReader(target, worker);
+                    try {
+                        selected.store.putWorker(worker, target.id, binding);
+                    }
+                    catch (error) {
+                        await selected.ghidra.stop(target, binding);
+                        throw error;
+                    }
+                    return { id: worker, targetId: target.id, ...binding };
+                }, { permission: Permission.Update }),
+                command('list', 'List registered reader bindings', (_i, c) => owner.selected(c).store.workers(), { permission: Permission.ReadOnly }),
+                command('stop <worker>', 'Stop an owned reader process', async ({ args }, c) => {
+                    const selected = owner.selected(c), worker = id(args.worker), binding = selected.store.worker(worker);
+                    await selected.ghidra.stop(binding.identity, binding);
+                    selected.store.removeWorker(worker);
+                    return { id: worker, state: 'stopped' };
+                }, { permission: Permission.Update }),
+            ]),
+            command('inspect <worker>', 'Read selected functions from a worker', async ({ args, options: o }, c) => {
+                const selected = owner.selected(c), binding = selected.store.worker(id(args.worker));
+                const result = await selected.ghidra.inspect(binding.identity, binding, text(o.functions));
+                selected.store.updateReader(id(args.worker), result.binding);
+                return result;
+            }, { permission: Permission.ReadOnly, options: [{ flags: '--functions <selectors>', description: 'Select up to eight function references', required: true }] }),
+            command('findings', 'Journal scoped comment proposals', [
+                command('submit', 'Persist an idempotent finding proposal', async ({ options: o }, c) => owner.selected(c).store.submit(await jsonFile(c, o.file)), { permission: Permission.Update, options: fileOption }),
+                command('list', 'List durable findings', ({ options: o }, c) => owner.selected(c).store.findings(o.target ? id(o.target) : undefined), { permission: Permission.ReadOnly, options: [{ flags: '--target <id>', description: 'Filter by registered target' }] }),
+                command('show <finding>', 'Show a finding and its outcome', ({ args }, c) => owner.selected(c).store.getFinding(id(args.finding)), { permission: Permission.ReadOnly }),
+            ]),
+            command('integrate <target>', 'Publish queued comments for one program', ({ args }, c) => owner.selected(c).coordinator.integrate(id(args.target)), { permission: Permission.Update }),
+            command('status', 'Show durable publication state', (_i, c) => { const selected = owner.selected(c); return { ownerPid: process.pid, profile: c.profile.name, targets: selected.store.targets(), workers: selected.store.workers(), batches: selected.store.batches() }; }, { permission: Permission.ReadOnly }),
+            command('recover <batch>', 'Reconcile an interrupted publication batch', ({ args, options: o }, c) => owner.selected(c).coordinator.recover(id(args.batch), Boolean(o.abandonStaged)), { permission: Permission.Update, options: [{ flags: '--abandon-staged', description: 'Abandon a stopped pre-publication stage' }] }),
+        ],
+    };
+}
+export const createInsightCli = (options = {}) => createCli(createDefinition(options));

package/dist/src/queries.d.ts

@@ -0,0 +1,5 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { Research } from './research.js';
+/** Static pinned domain leaves. Callers choose typed flags, never endpoint/payload routing. */
+export declare function queryCommands(research: (context: CommandContext) => Research): CommandDefinition[];
+export declare function extendQueries(existing: readonly CommandDefinition[], queries: readonly CommandDefinition[]): CommandDefinition[];

package/dist/src/queries.js

@@ -0,0 +1,84 @@
+import { readFileSync } from 'node:fs';
+import { command, Permission } from '@eyeauras/cli-factory';
+import { scope } from './research.js';
+import { fail } from './model.js';
+import { queryResult } from './query-results.js';
+import { key, flag, parsed, option, selectedOptions } from './arguments.js';
+import { nativeQueries, qualifyQuery, queryDescription } from './query-policy.js';
+const catalog = JSON.parse(readFileSync(new URL('../../references/queries.json', import.meta.url), 'utf8'));
+if (catalog.source !== '57e37a8bf388b1279cff46378f85be1554548f61' || catalog.tools.length !== 74)
+    throw Error('Installed query contracts differ from the pinned facade build.');
+function value(result) {
+    if (result === undefined || result === null)
+        fail('partial', 'Query did not return its result.');
+    let encoded;
+    try {
+        encoded = JSON.stringify(result);
+    }
+    catch {
+        fail('partial', 'Query returned malformed JSON.');
+    }
+    if (encoded.length > 1048576)
+        fail('limit', 'Query result exceeds one MiB; narrow its scope or request a smaller page.');
+    if (typeof result === 'object' && !Array.isArray(result)) {
+        const o = result;
+        if (o.error || o.success === false || o.status === 'error')
+            fail('remote', 'Query reported a failure.');
+        for (const name of ['total', 'count', 'offset', 'limit'])
+            if (o[name] !== undefined && (!Number.isSafeInteger(o[name]) || Number(o[name]) < 0))
+                fail('partial', 'Query returned inconsistent pagination metadata.');
+    }
+    return result;
+}
+/** Static pinned domain leaves. Callers choose typed flags, never endpoint/payload routing. */
+export function queryCommands(research) {
+    const groups = new Map();
+    for (const q of catalog.tools) {
+        const [group, leaf, ...rest] = q.command.split(' ');
+        if (!group || !leaf || rest.length || q.params.some(p => ['session', 'target', 'program'].includes(p.name)))
+            throw Error('Invalid installed query contract.');
+        const children = groups.get(group) ?? [];
+        groups.set(group, children);
+        children.push(command(leaf, queryDescription(q.path, leaf.replaceAll('-', ' ')), async ({ options: o }, c) => {
+            const parameters = {};
+            for (const p of q.params) {
+                const input = o[key(p.name)];
+                if (input === undefined) {
+                    if (p.required)
+                        fail('invalid', `Missing --${flag(p.name)}.`);
+                    continue;
+                }
+                parameters[p.name] = parsed(p, input);
+            }
+            if (nativeQueries.has(q.path)) {
+                if (Number(parameters.timeout_seconds ?? 5) > 30)
+                    fail('invalid', 'Native query timeout must be at most 30 seconds.');
+                if (Number(parameters.max_steps ?? 10000) > 100000)
+                    fail('invalid', 'Native emulation supports at most 100000 steps per candidate.');
+                if (parameters.abi !== undefined && !['auto', 'x86-cdecl', 'windows-x64', 'sysv-x64'].includes(String(parameters.abi)))
+                    fail('invalid', 'ABI must be auto, x86-cdecl, windows-x64 or sysv-x64.');
+            }
+            const who = scope(o), result = q.path === '/list_scripts' ?
+                await research(c).scripts(who, String(parameters.filter ?? ''), Number(o.limit), Number(o.offset)) :
+                await research(c).read(who, q.path, parameters);
+            return { ...who, value: value(qualifyQuery(q.path, queryResult(q.path, parameters, value(result)))) };
+        }, { permission: Permission.ReadOnly, options: [...selectedOptions, ...q.params.map(option), ...(q.path === '/list_scripts' ?
+                    [option({ name: 'limit', type: 'integer', required: false, default: '50' }), option({ name: 'offset', type: 'integer', required: false, default: '0' })] : [])] }));
+    }
+    return [...groups].map(([group, children]) => command(group, `${group} research`, children));
+}
+export function extendQueries(existing, queries) {
+    const result = [...existing];
+    for (const group of queries) {
+        const index = result.findIndex(entry => entry.name === group.name);
+        if (index < 0)
+            result.push(group);
+        else {
+            const before = result[index];
+            if (!before.children || group.children?.some(leaf => before.children.some(entry => entry.name === leaf.name)))
+                throw Error('Duplicate query command.');
+            result[index] = { ...before, children: [...before.children, ...group.children] };
+        }
+    }
+    return result;
+}

package/dist/src/query-policy.d.ts

@@ -0,0 +1,6 @@
+/** These operations have facade-owned, bounded native implementations. */
+export declare const nativeQueries: Set<string>;
+export declare function queryDescription(path: string, fallback: string): string;
+/** Reject placeholder/error payloads anywhere in the returned domain value. */
+export declare function rejectPlaceholders(value: unknown, depth?: number): void;
+export declare function qualifyQuery(path: string, value: unknown): unknown;

package/dist/src/query-policy.js

@@ -0,0 +1,72 @@
+import { fail, object } from './model.js';
+/** These operations have facade-owned, bounded native implementations. */
+export const nativeQueries = new Set(['/find_dead_code', '/detect_crypto_constants', '/get_valid_data_types',
+    '/validate_data_type', '/validate_function_prototype', '/get_entry_points', '/list_globals',
+    '/list_strings', '/search_strings', '/find_data_types', '/search_byte_patterns', '/search_instructions',
+    '/emulate_function', '/emulate_hash_batch']);
+const heuristics = Object.fromEntries([
+    ['/find_similar_functions_fuzzy', 'similarity', 'mcp-fuzzy-instruction-match'],
+    ['/bulk_fuzzy_match', 'similarity', 'mcp-fuzzy-instruction-match'],
+    ['/analyze_function_completeness', 'score', 'mcp-documentation-completeness'],
+    ['/analyze_for_documentation', 'suggestion', 'mcp-documentation-suggestions'],
+    ['/find_similar_functions', 'similarity', 'mcp-function-metrics'],
+    ['/analyze_global_completeness', 'score', 'mcp-global-documentation-completeness'],
+    ['/audit_global', 'score', 'mcp-global-documentation-audit'],
+    ['/audit_globals_in_function', 'score', 'mcp-global-documentation-audit'],
+    ['/suggest_field_names', 'suggestion', 'mcp-type-name-patterns'],
+    ['/detect_array_bounds', 'estimate', 'mcp-reference-stride-estimator'],
+    ['/analyze_api_call_chains', 'pattern-match', 'mcp-api-name-patterns'],
+    ['/detect_malware_behaviors', 'pattern-match', 'mcp-api-instruction-patterns'],
+    ['/find_anti_analysis_techniques', 'pattern-match', 'mcp-symbol-instruction-patterns'],
+    ['/extract_iocs_with_context', 'pattern-match', 'mcp-string-patterns'],
+    ['/find_undocumented_by_string', 'suggestion', 'mcp-string-reference-documentation'],
+].map(([path, kind, algorithm]) => [path, { kind: kind, algorithm: algorithm, limitations: [
+            'A static observation, heuristic or suggestion; not a proof of runtime behavior or completeness.',
+            'Scores and confidence labels are not calibrated probabilities; the agent decides what to accept.',
+        ] }]));
+export function queryDescription(path, fallback) {
+    if (path === '/find_dead_code')
+        return 'Find blocks unreachable in the bounded static CFG; unresolved flow is reported';
+    if (path === '/detect_crypto_constants')
+        return 'Match versioned constant-table signatures within an explicit byte budget';
+    if (path === '/get_valid_data_types')
+        return 'Enumerate actually resolvable program/builtin types, with provenance and scan limits';
+    if (path === '/validate_function_prototype')
+        return 'Parse a prototype and resolve its convention without persisting changes';
+    if (path === '/validate_data_type')
+        return 'Resolve a type and report layout/alignment diagnostics without changing the program';
+    if (path === '/get_entry_points')
+        return 'Read external-entry metadata; report name/image-base candidates separately';
+    if (path === '/list_globals')
+        return 'Read structured global records with bounded symbol/reference scanning';
+    if (path.startsWith('/emulate_'))
+        return 'Bounded isolated x86/x64 emulation with explicit ABI and termination reason';
+    return heuristics[path] ? fallback + ' (qualified ' + heuristics[path].kind + '; not ground truth)' : fallback;
+}
+/** Reject placeholder/error payloads anywhere in the returned domain value. */
+export function rejectPlaceholders(value, depth = 0) {
+    if (depth > 64)
+        fail('partial', 'Query result nesting exceeds 64 levels.');
+    if (!value || typeof value !== 'object')
+        return;
+    const row = value;
+    if (typeof row.status === 'string' && /not[ _-]*(?:yet[ _-]*)?implemented|placeholder|unsupported|unavailable/i.test(row.status))
+        fail('unsupported', 'The backend returned an unavailable analysis instead of a completed result.');
+    for (const child of Object.values(row))
+        rejectPlaceholders(child, depth + 1);
+}
+export function qualifyQuery(path, value) {
+    rejectPlaceholders(value);
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    const result = object(value), semantics = heuristics[path];
+    if (path === '/suggest_field_names' && Array.isArray(result.suggestions))
+        result.suggestions = result.suggestions.map(raw => ({
+            ...object(raw), confidence: null, confidence_kind: 'uncalibrated',
+        }));
+    return { ...result, ...(semantics ? { semantics } : {}), ...(!nativeQueries.has(path) ? { scanPolicy: {
+                execution: 'pinned-upstream', pagination: 'may-follow-full-scan', workBound: 'not-guaranteed',
+                maximumAcceptedResultBytes: 1048576,
+                note: 'A page/output limit does not bound backend scan cost. Use a narrow function/address/filter; heavy upstream work may continue after transport cancellation.',
+            } } : {}) };
+}

package/dist/src/query-results.d.ts

@@ -0,0 +1,2 @@
+/** Validate the pinned operation's result variant, independently of its HTTP acknowledgment. */
+export declare function queryResult(path: string, parameters: Record<string, unknown>, result: unknown): unknown;

package/dist/src/query-results.js

@@ -0,0 +1,224 @@
+import { fail } from './model.js';
+import { rejectPlaceholders } from './query-policy.js';
+const shapes = {
+    '/analyze_data_region': { start_address: 'string', end_address: 'string', byte_span: 'number', xref_count: 'number', classification_hint: 'string' },
+    '/detect_array_bounds': { address: 'string', estimated_size: 'number', stride: 'number', element_count: 'number', confidence: 'string' },
+    '/analyze_control_flow': { function_name: 'string', entry_point: 'string', metrics: 'object', basic_block_details: 'array' },
+    '/analyze_dataflow': { function: 'object', anchor: 'object', direction: 'string', chain: 'array', truncated: 'boolean' },
+    '/analyze_for_documentation': { name: 'string', address: 'string', parameters: 'array', locals: 'array' },
+    '/analyze_function_complete': { name: 'string', address: 'string' },
+    '/analyze_function_completeness': { function_name: 'string', completeness_score: 'number' },
+    '/find_code_gaps': { gaps: 'array', total: 'number', offset: 'number', limit: 'number' },
+    '/find_next_undefined_function': { found: 'boolean' },
+    '/find_similar_functions': { target_function: 'string', similar_functions: 'array', matches_found: 'number' },
+    '/get_field_access_context': { struct_address: 'string', field_offset: 'number', examples: 'array' },
+    '/get_function_pcode': { name: 'string', address: 'string', basic_blocks: 'array' },
+    '/inspect_memory_content': { address: 'string', bytes_read: 'number', hex_dump: 'string' },
+    '/list_analyzers': { analyzers: 'array', count: 'number' },
+    '/search_instructions': { matches: 'array' },
+    '/analyze_global_completeness': { address: 'string', score: 'number', issues: 'array' },
+    '/analyze_struct_field_usage': { struct_name: 'string', struct_size: 'number', field_usage: 'object' },
+    '/audit_global': { address: 'string', issues: 'array', fully_documented: 'boolean' },
+    '/audit_globals_in_function': { function: 'object', globals: 'array', summary: 'object' },
+    '/get_enum_values': { name: 'string', size: 'number', values: 'array' },
+    '/get_struct_layout': { name: 'string', size: 'number', alignment: 'number', fields: 'array' },
+    '/get_type_size': { type_name: 'string', size: 'number', alignment: 'number' },
+    '/get_valid_data_types': { builtin_types: 'array', windows_types: 'array' },
+    '/suggest_field_names': { struct_address: 'string', suggestions: 'array' },
+    '/validate_data_type': { type_name: 'string', valid: 'boolean', warnings: 'array' },
+    '/validate_function_prototype': { valid: 'boolean' },
+    '/batch_string_anchor_report': { anchors: 'array', total_anchors: 'number' },
+    '/find_undocumented_by_string': { undocumented_functions: 'array', undocumented_count: 'number' },
+    '/get_function_documentation': { hash: 'string', function_name: 'string', parameters: 'array', comments: 'array', labels: 'array' },
+    '/emulate_function': { success: 'boolean', steps_executed: 'number', stop_reason: 'string', registers: 'object' },
+    '/emulate_hash_batch': { tested: 'number', matches: 'array', resolved: 'boolean' },
+    '/disassemble_function': { instructions: 'array', count: 'number' },
+    '/force_decompile': { address: 'string', name: 'string', decompiled: 'string' },
+    '/get_functions': { functions: 'object', count: 'number', requested: 'number' },
+    '/list_class_members': { class_name: 'string', members: 'array', total_members: 'number' },
+    '/list_function_tags': { tags: 'array', total: 'number' },
+    '/find_functions': { functions: 'array', total: 'number', count: 'number' },
+    '/get_entry_points': { entry_points: 'array', count: 'number' },
+    '/get_function_count': { function_count: 'number' },
+    '/list_calling_conventions': { calling_conventions: 'array', count: 'number' },
+    '/list_globals': { globals: 'array', count: 'number', total: 'number' },
+    '/list_program_items': { kind: 'string', items: 'array', count: 'number', total: 'number' },
+    '/list_shadowed_globals': { shadowed: 'array', count: 'number', total: 'number' },
+    '/list_strings': { strings: 'array', count: 'number', total: 'number' },
+    '/search_strings': { matches: 'array', total: 'number', offset: 'number', limit: 'number' },
+    '/analyze_api_call_chains': { detected_patterns: 'array', total_patterns_detected: 'number' },
+    '/detect_malware_behaviors': { behaviors: 'array', total_behaviors_detected: 'number' },
+    '/extract_iocs_with_context': { iocs: 'array', total_iocs: 'number' },
+    '/find_anti_analysis_techniques': { findings: 'array', total_findings: 'number' },
+    '/analysis_status': { analyzing: 'boolean', analyzed: 'boolean', function_count: 'number' },
+    '/get_address_spaces': { address_spaces: 'array', count: 'number' },
+    '/get_language_metadata': { language_id: 'string', processor: 'string', endian: 'string', address_spaces: 'array' },
+    '/get_metadata': { architecture: 'string', compiler: 'string', language: 'string', base_address: 'string', function_count: 'number' },
+    '/get_property': { address: 'string', has_value: 'boolean' },
+    '/list_bookmarks': { bookmarks: 'array', count: 'number' },
+    '/list_properties': { map: 'string', entries: 'array', count: 'number', total: 'number' },
+    '/read_memory': { address: 'string', length: 'number', data: 'array', hex: 'string' },
+    '/can_rename_at_address': { can_rename: 'boolean', type: 'string' },
+    '/get_function_call_graph': { edges: 'array', count: 'number' },
+    '/get_xrefs_from': { references: 'array', count: 'number', total: 'number' },
+    '/get_xrefs_to': { references: 'array', count: 'number', total: 'number' },
+};
+function checkShape(result, shape) {
+    if (!result || typeof result !== 'object' || Array.isArray(result))
+        fail('partial', 'Query expected a result object.');
+    const value = result;
+    for (const [key, type] of Object.entries(shape)) {
+        const item = value[key], valid = type === 'array' ? Array.isArray(item) : type === 'object' ? Boolean(item) && typeof item === 'object' && !Array.isArray(item) :
+            type === 'number' ? typeof item === 'number' && Number.isFinite(item) : typeof item === type;
+        if (!valid)
+            fail('partial', `Query omitted or malformed ${key}.`);
+    }
+    return value;
+}
+/** Validate the pinned operation's result variant, independently of its HTTP acknowledgment. */
+export function queryResult(path, parameters, result) {
+    rejectPlaceholders(result);
+    let shape = shapes[path];
+    if (path === '/find_dead_code')
+        shape = { findings: 'array', complete: 'boolean', unresolved_flow: 'boolean', algorithm: 'string', scan: 'object', truncated: 'boolean' };
+    if (path === '/detect_crypto_constants' || path === '/search_byte_patterns')
+        shape = { matches: 'array', complete: 'boolean', scanned_bytes: 'number', maximum_bytes: 'number', algorithm: 'string', scan: 'object', truncated: 'boolean' };
+    if (path === '/get_valid_data_types')
+        shape = { types: 'array', scope: 'string', scan: 'object', truncated: 'boolean' };
+    if (path === '/validate_function_prototype')
+        shape = { valid: 'boolean', diagnostics: 'array', parser: 'string', persisted_changes: 'boolean' };
+    const bulkComments = path === '/get_comment' && Boolean(String(parameters.addresses ?? '').trim());
+    if (path === '/get_comment')
+        shape = bulkComments ? { results: 'array', requested: 'number', returned: 'number', with_comments: 'number' } : { address: 'string', has_comment: 'boolean' };
+    if (path === '/find_data_types')
+        shape = { ...(parameters.categories ? { categories: 'array' } : { data_types: 'array' }), count: 'number' };
+    if (path === '/get_function_hash')
+        shape = parameters.function ? { hash: 'string', function_name: 'string', instruction_count: 'number' } : { functions: 'array' };
+    // The pinned service returns a bare bundle for function=, a map/counts for functions=.
+    // Bulk selection takes precedence even when both selectors are supplied.
+    if (path === '/get_functions' && !String(parameters.functions ?? '').trim())
+        shape = { name: 'string', size: 'number' };
+    if (path === '/get_program_options')
+        shape = parameters.group ? { options: 'array' } : { groups: 'array' };
+    // The pinned implementation retains format as a deprecated no-op and always returns JSON.
+    if (path === '/list_data_items_by_xrefs')
+        shape = { data_items: 'array', count: 'number', total: 'number' };
+    if (path === '/get_external_location')
+        shape = { address: 'string' };
+    if (path === '/get_full_call_graph')
+        shape = parameters.format === 'json_edges' ? { edges: 'array', edge_count: 'number', caller_count: 'number' } :
+            parameters.format === 'dot' || parameters.format === 'mermaid' ? { format: 'string', diagram: 'string', count: 'number' } :
+                parameters.format === 'adjacency' ? { format: 'string', adjacency: 'object', count: 'number' } : { edges: 'array', count: 'number' };
+    if (path === '/analyze_call_graph')
+        shape = parameters.analysis_type === undefined || parameters.analysis_type === 'summary' ? { total_functions: 'number', total_call_edges: 'number' } : { analysis_type: 'string' };
+    if (path === '/get_assembly_context') {
+        const value = checkShape(result, {}), input = parameters.xref_sources;
+        const addresses = Array.isArray(input) ? input : typeof input === 'string' ? input.split(',').map(v => v.trim()).filter(Boolean) : [];
+        for (const at of addresses)
+            if (!Object.hasOwn(value, String(at)))
+                fail('partial', 'Assembly context omitted a requested address.');
+        return result;
+    }
+    if (path === '/list_scripts')
+        shape = { items: 'array', count: 'number', total: 'number', offset: 'number', limit: 'number', truncated: 'boolean' };
+    if (!shape)
+        fail('schema', 'Pinned query has no result contract.');
+    const value = checkShape(result, shape);
+    const rowShapes = {
+        '/list_globals': { key: 'globals', shape: { address: 'string', name: 'string', type: 'string', size: 'number', xrefs: 'number', named: 'boolean', typed: 'boolean' } },
+        '/list_strings': { key: 'strings', shape: { address: 'string', value: 'string', encoding: 'string' } },
+        '/search_strings': { key: 'matches', shape: { address: 'string', value: 'string', encoding: 'string' } },
+        '/search_instructions': { key: 'matches', shape: { address: 'string', mnemonic: 'string', instruction: 'string', length: 'number' } },
+        '/get_valid_data_types': { key: 'types', shape: { name: 'string', path: 'string', size: 'number', alignment: 'number', source: 'string' } },
+        '/find_dead_code': { key: 'findings', shape: { address: 'string', end: 'string', size: 'number', kind: 'string' } },
+        '/detect_crypto_constants': { key: 'matches', shape: { address: 'string', signature: 'string', length: 'number', kind: 'string' } },
+        '/search_byte_patterns': { key: 'matches', shape: { address: 'string', signature: 'string', length: 'number', kind: 'string' } },
+        '/get_function_call_graph': { key: 'edges', shape: { caller: 'string', callee: 'string' } },
+    };
+    const checkedRows = rowShapes[path];
+    if (checkedRows)
+        for (const row of value[checkedRows.key])
+            checkShape(row, checkedRows.shape);
+    if (value.scan !== undefined) {
+        const scan = checkShape(value.scan, { visited: 'number', maximum: 'number', complete: 'boolean', reason: 'string' });
+        if (!Number.isSafeInteger(scan.visited) || !Number.isSafeInteger(scan.maximum) || Number(scan.visited) < 0 || Number(scan.visited) > Number(scan.maximum))
+            fail('partial', 'Query scan counters are inconsistent.');
+        if (scan.complete === false && value.truncated !== true)
+            fail('partial', 'Incomplete query scan was reported as untruncated.');
+    }
+    for (const entry of [['globals', 'count'], ['strings', 'count'], ['matches', 'count'], ['types', 'count']])
+        if (Array.isArray(value[entry[0]]) && value[entry[1]] !== undefined && value[entry[1]] !== value[entry[0]].length)
+            fail('partial', 'Query row count is inconsistent.');
+    if (path === '/find_dead_code' && (value.complete === false || value.unresolved_flow === true) && value.findings.length)
+        fail('partial', 'Incomplete CFG analysis cannot classify unreachable blocks.');
+    if (path === '/detect_crypto_constants' || path === '/search_byte_patterns') {
+        if (Number(value.scanned_bytes) > Number(value.maximum_bytes) || Number(value.scanned_bytes) < 0)
+            fail('partial', 'Byte scan exceeded its declared budget.');
+        if (value.complete === false && typeof value.next_address !== 'string')
+            fail('partial', 'Partial byte scan omitted its continuation.');
+        if (path === '/detect_crypto_constants') {
+            const database = checkShape(value.database, { version: 'string', signatures: 'array' });
+            for (const row of database.signatures)
+                checkShape(row, { name: 'string', length: 'number' });
+        }
+    }
+    if (path === '/get_entry_points') {
+        for (const raw of value.entry_points) {
+            const row = checkShape(raw, { address: 'string', name: 'string', kind: 'string', confirmed: 'boolean', provenance: 'string' });
+            if (row.confirmed !== true || row.kind !== 'external_entry' || row.provenance !== 'ghidra.symbol.external-entry-point')
+                fail('partial', 'Entry-point metadata was replaced by an unconfirmed candidate.');
+        }
+        if (!Array.isArray(value.candidates))
+            fail('partial', 'Entry-point result omitted its candidates.');
+        for (const raw of value.candidates) {
+            const row = checkShape(raw, { address: 'string', name: 'string', kind: 'string', confirmed: 'boolean', provenance: 'string' });
+            if (row.confirmed !== false)
+                fail('partial', 'Entry candidate was labeled confirmed.');
+        }
+    }
+    if (path === '/validate_function_prototype' || path === '/validate_data_type') {
+        if (!Array.isArray(value.diagnostics))
+            fail('partial', 'Validation omitted parser/resolution diagnostics.');
+        for (const raw of value.diagnostics)
+            checkShape(raw, { severity: 'string', code: 'string', message: 'string' });
+        if (value.valid === true) {
+            if (path === '/validate_data_type')
+                checkShape(value.resolved, { name: 'string', path: 'string', size: 'number', alignment: 'number' });
+            else
+                checkShape(value.signature, { name: 'string', return_type: 'object', parameters: 'array', calling_convention: 'string' });
+        }
+    }
+    if (path === '/emulate_function' && value.completed !== undefined) {
+        checkShape(value, { completed: 'boolean', hit_return: 'boolean', abi: 'string', pointer_bytes: 'number' });
+        if (value.completed !== value.hit_return || value.completed === true && value.stop_reason !== 'return')
+            fail('partial', 'Emulation termination was reported inconsistently.');
+    }
+    if (path === '/get_comment') {
+        const rows = bulkComments ? value.results : [value];
+        if (bulkComments && (!['requested', 'returned', 'with_comments'].every(key => Number.isSafeInteger(value[key]) && Number(value[key]) >= 0) || value.returned !== rows.length || Number(value.returned) > Number(value.requested) || Number(value.with_comments) > Number(value.requested)))
+            fail('partial', 'Bulk comment counts are inconsistent.');
+        for (const row of rows) {
+            const comment = checkShape(row, { address: 'string', has_comment: 'boolean' });
+            for (const kind of ['plate', 'pre', 'eol', 'post', 'repeatable'])
+                if (comment[kind] !== null && typeof comment[kind] !== 'string')
+                    fail('partial', 'Query omitted or malformed comment kind.');
+        }
+    }
+    if (path === '/get_full_call_graph' && parameters.format === 'json_edges') {
+        const rows = value.edges;
+        if (value.edge_count !== rows.length || !Number.isSafeInteger(value.caller_count) || Number(value.caller_count) < 0)
+            fail('partial', 'Call graph counts are inconsistent.');
+        for (const row of rows)
+            checkShape(row, { caller_addr: 'string', callee_addr: 'string', caller_name: 'string', callee_name: 'string' });
+    }
+    if (path === '/get_struct_layout')
+        for (const field of value.fields)
+            checkShape(field, { offset: 'number', size: 'number', type: 'string', name: 'string' });
+    if (path === '/get_enum_values')
+        for (const member of value.values) {
+            const observed = checkShape(member, { name: 'string' }), number = observed.value;
+            if (!(typeof number === 'number' && Number.isSafeInteger(number) || typeof number === 'string' && /^-?\d+$/.test(number)))
+                fail('partial', 'Enum result omitted its exact integer value.');
+        }
+    return result;
+}