@eyeauras/insight-cli 0.2.3 → 0.3.0

package/dist/src/cli.js

@@ -29,6 +29,7 @@ import { nativeInputs } from './native-inputs.js';
 import { Research, scope, address, commentKind, scalarText, number } from './research.js';
 import { fail, id, text, digest, object } from './model.js';
 import { queryCommands, extendQueries } from './queries.js';
+import { decodedInstructions } from './decode-results.js';
 import { mutationCommands } from './mutations.js';
 import { crossCommands } from './cross.js';
 import { Administration, administrationCommands } from './administration.js';
@@ -50,9 +51,11 @@ import { artifactsCommands } from './saved-materials.js';
 import { RuntimeManager, runtimeCommands, runtimeProcesses } from './runtime-manager.js';
 import { packageVersion } from './package-version.js';
 import { runtimeSelection } from './runtime-selection.js';
+import { AnalysisStorage, analysisDirectory } from './analysis-storage.js';
 const bindingFields = ['java', 'ghidraHome', 'mcpJar', 'mcpJarSha256', 'server', 'repository', 'readerUser', 'publisherUser', 'maxContexts', 'debuggerPython', 'windbgDir', 'archiveUrl'];
 class Owner {
     options;
+    storage;
     profiles = new Map();
     runtimeChanging = new Set();
     async runtime(c, action, quiescent = true) {
@@ -87,10 +90,11 @@ class Owner {
         const directory = c.appArguments.AppDataDirectory;
         if (this.runtimeChanging.has(directory))
             fail('busy', 'Runtime preparation is in progress.');
-        const configuration = digest({ runtime: runtimeSelection(directory), profile: Object.fromEntries(bindingFields.map(key => [key, c.profile.values[key]])), extensions: extensionState(join(directory, 'workspace')).modules.filter(m => m.enabled).map(m => [m.name, m.sha256]) });
+        const root = analysisDirectory(c);
+        const configuration = digest({ analysisDirectory: root, runtime: runtimeSelection(directory, root), profile: Object.fromEntries(bindingFields.map(key => [key, c.profile.values[key]])), extensions: extensionState(join(root, 'workspace')).modules.filter(m => m.enabled).map(m => [m.name, m.sha256]) });
         let profile = this.profiles.get(directory);
         if (!profile) {
-            profile = { workspace: new Workspace(join(directory, 'workspace'), c.profile.name), tasks: new Map(), configuration };
+            profile = { workspace: new Workspace(join(root, 'workspace'), c.profile.name), tasks: new Map(), configuration };
             this.profiles.set(directory, profile);
         }
         if (profile.configuration !== configuration)
@@ -115,6 +119,8 @@ class Owner {
     }
     async invalidateProfile(app) {
         const directory = app.AppDataDirectory, profile = this.profiles.get(directory);
+        if (this.storage?.busy(directory))
+            fail('busy', 'Storage migration is in progress.');
         if (this.runtimeChanging.has(directory))
             fail('busy', 'Runtime preparation is in progress; finish it before changing or deleting the profile.');
         if (toolProfileBusy(directory))
@@ -123,7 +129,7 @@ class Owner {
             fail('busy', 'The profile has active or unverified tool processes.');
         const materials = await readdir(join(directory, 'materials')).catch(error => { if (error.code === 'ENOENT')
             return []; throw error; });
-        if (existsSync(join(directory, 'workspace', 'workspace.sqlite')) || materials.length)
+        if (existsSync(join(directory, 'storage', 'migration.json')) || existsSync(join(directory, 'workspace', 'workspace.sqlite')) || materials.length)
             fail('blocked', 'Profile has retained research data; preserve its workspace and materials before deleting or reconfiguring it.');
         if (profile) {
             await (await profile.backend)?.dispose();
@@ -131,6 +137,16 @@ class Owner {
             this.profiles.delete(directory);
         }
     }
+    async releaseStorage(c) {
+        const directory = c.appArguments.AppDataDirectory, profile = this.profiles.get(directory);
+        if (!profile)
+            return;
+        if (profile.tasks.size)
+            fail('busy', 'Research commands are active.');
+        await (await profile.backend)?.dispose();
+        profile.workspace.close();
+        this.profiles.delete(directory);
+    }
     async dispose() {
         for (const profile of this.profiles.values()) {
             await Promise.allSettled([...profile.tasks.values()]);
@@ -259,6 +275,8 @@ function scopedFailures(entry, owner, parents = []) {
 }
 export function createDefinition(options = {}) {
     const owner = new Owner(options);
+    const storage = new AnalysisStorage(options.runtime?.profileStore, c => owner.releaseStorage(c));
+    owner.storage = storage;
     const definition = {
         name: 'insight-cli', applicationId: 'insight-cli', version: packageVersion, description: 'Isolated research contexts and coordinated Ghidra analysis',
         resources: [owner], permissions: { categories: [{ name: 'Destructive', description: 'Explicit deletion or replacement of retained research data', enabledByDefault: false }] }, ...(options.runtime ? { runtime: options.runtime } : {}),
@@ -449,6 +467,12 @@ export function createDefinition(options = {}) {
                             { flags: '--execute', description: 'Enable execution permission' }, request] }),
                 ]),
                 command('functions', 'Read or name functions', [
+                    command('decode', 'Decode executable bytes without defining instructions or functions', async ({ options: o }, c) => {
+                        const selected = owner.selected(c), who = scope(o), at = address(o.address), maxBytes = number(o.maxBytes ?? 64, 4096, 1), maxInstructions = number(o.maxInstructions ?? 16, 256, 1);
+                        const value = decodedInstructions(await selected.research.read(who, '/decode_instructions', { address: at, max_bytes: maxBytes, max_instructions: maxInstructions }), at, maxBytes, maxInstructions);
+                        const context = selected.workspace.context(who);
+                        return { ...who, value: { ...value, view: { revision: context.baseRevision, identity: digest({ context: context.id, generation: context.generation, snapshot: context.workingSnapshot, nativeModification: object(value.read_only).modification }) } } };
+                    }, { permission: Permission.ReadOnly, options: [...scoped, at, { flags: '--max-bytes <count>', description: 'Read 1–4096 executable bytes', defaultValue: 64 }, { flags: '--max-instructions <count>', description: 'Decode at most 1–256 instructions', defaultValue: 16 }] }),
                     command('set-function-prototype', 'Set a C prototype and optional explicit compiler-supported calling convention', ({ options: o }, c) => {
                         const selected = owner.selected(c), who = scope(o), parameters = { function_address: address(o.address), prototype: text(o.prototype, 16000),
                             ...(o.callingConvention === undefined ? {} : { calling_convention: text(o.callingConvention, 512) }) };
@@ -476,8 +500,9 @@ export function createDefinition(options = {}) {
             ]),
         ],
     };
-    return { ...definition, commands: definition.commands?.map(entry => entry.name === 'ghidra' ?
-            scopedFailures({ ...entry, children: extendQueries(extendQueries(extendQueries(entry.children ?? [], queryCommands(c => owner.selected(c).research)), mutationCommands(c => owner.selected(c).research)), [...sdkCommands(c => owner.selected(c).research), ...sdkFileCommands(c => owner.selected(c).sdkFiles), ...trackingCommands(c => owner.selected(c).tracking), ...crossCommands(c => owner.selected(c).research), ...administrationCommands(c => owner.selected(c).administration, options.backend ? undefined : async (c) => { const status = await new RuntimeManager(c).status(); return status.state === 'not_ready' ? { ...status.server, connected: false, state: 'runtime_not_ready', missing: status.missing } : undefined; }),
-                    ...extensionCommands(c => new Extensions(join(c.appArguments.AppDataDirectory, 'workspace'))), ...extensionInventoryCommands(c => owner.selected(c).backend), ...pluginCommands(c => owner.selected(c).ui), ...synchronizationCommands(c => owner.selected(c).synchronization), ...utilityCommands(), ...runtimeCommands((c, action, quiescent) => owner.runtime(c, action, quiescent)), ...lifecycleCommands(c => owner.selected(c).lifecycle, c => new RuntimeManager(c).status()), ...projectCommands(c => owner.selected(c).projects), ...uiCommands(c => owner.selected(c).ui), ...debuggerCommands(c => owner.selected(c).debugger), ...archiveCommands(c => owner.selected(c).archive)]) }, owner) : entry) };
+    const commands = definition.commands?.map(entry => entry.name === 'ghidra' ?
+        scopedFailures({ ...entry, children: extendQueries(extendQueries(extendQueries(entry.children ?? [], queryCommands(c => owner.selected(c).research)), mutationCommands(c => owner.selected(c).research)), [...sdkCommands(c => owner.selected(c).research), ...sdkFileCommands(c => owner.selected(c).sdkFiles), ...trackingCommands(c => owner.selected(c).tracking), ...crossCommands(c => owner.selected(c).research), ...administrationCommands(c => owner.selected(c).administration, options.backend ? undefined : async (c) => { const status = await new RuntimeManager(c).status(); return status.state === 'not_ready' ? { ...status.server, connected: false, state: 'runtime_not_ready', missing: status.missing } : undefined; }),
+                ...extensionCommands(c => new Extensions(join(analysisDirectory(c), 'workspace'))), ...extensionInventoryCommands(c => owner.selected(c).backend), ...pluginCommands(c => owner.selected(c).ui), ...synchronizationCommands(c => owner.selected(c).synchronization), ...utilityCommands(), ...runtimeCommands((c, action, quiescent) => owner.runtime(c, action, quiescent)), ...lifecycleCommands(c => owner.selected(c).lifecycle, c => new RuntimeManager(c).status()), ...projectCommands(c => owner.selected(c).projects), ...uiCommands(c => owner.selected(c).ui), ...debuggerCommands(c => owner.selected(c).debugger), ...archiveCommands(c => owner.selected(c).archive)]) }, owner) : entry);
+    return { ...definition, commands: [...(commands ?? []).map(e => storage.wrap(e)), storage.commands()] };
 }
 export const createInsightCli = (options = {}) => createCli(createDefinition(options));

package/dist/src/contexts.d.ts

@@ -62,6 +62,7 @@ export declare class GhidraContexts {
     private privateCopy;
     open(scope: Scope, request?: string): Promise<GhidraContext>;
     private selected;
+    observation(scope: Scope): Promise<unknown>;
     call(scope: Scope, operation: string, parameters?: Record<string, unknown>): Promise<unknown>;
     saved(scope: Scope): Promise<Artifact>;
     scripts(scope: Scope, filter: string, limit: number, offset: number): Promise<import("./scripts.js").ScriptPage>;

package/dist/src/contexts.js

@@ -167,8 +167,8 @@ export class GhidraContexts {
         }
     }
     async verified(binding, target, verifySource = true) {
-        const root = resolve(binding.root);
-        if (!root.startsWith(resolve(this.directory()) + sep) || await realpath(root) !== root || binding.target !== target.id || binding.runtimeFingerprint !== this.inputs.fingerprint)
+        const root = await realpath(binding.root);
+        if (!root.startsWith(resolve(this.directory()) + sep) || binding.target !== target.id || binding.runtimeFingerprint !== this.inputs.fingerprint)
             fail('binding', 'Native context receipt does not match its profile, target or runtime.');
         if (stable(JSON.parse(await readFile(join(root, 'process.json'), 'utf8'))) !== stable(binding))
             fail('binding', 'Native context receipt changed.');
@@ -219,11 +219,11 @@ export class GhidraContexts {
         this.running.delete(binding.root);
     }
     async debuggerReleased(binding) {
-        const root = resolve(binding.root);
-        if (!root.startsWith(resolve(this.directory()) + sep) || await realpath(root) !== root ||
+        const root = await realpath(binding.root);
+        if (!root.startsWith(resolve(this.directory()) + sep) ||
             stable(JSON.parse(await readFile(join(root, 'process.json'), 'utf8'))) !== stable(binding))
             fail('binding', 'Debugger lifetime binding moved outside its owned context.');
-        const directory = join(binding.root, 'debugger-supervisors'), deadline = Date.now() + 15000;
+        const directory = join(root, 'debugger-supervisors'), deadline = Date.now() + 15000;
         for (;;) {
             let names;
             try {
@@ -305,7 +305,7 @@ export class GhidraContexts {
             if (await realpath(root) !== resolve(root))
                 fail('binding', 'Legacy initial-import stage moved outside owned storage.');
             const binding = JSON.parse(await readFile(join(root, 'process.json'), 'utf8'));
-            if (binding.root !== root || binding.target !== target.id || binding.kind !== 'bootstrap' || binding.program !== programPath(target.id))
+            if (await realpath(binding.root) !== root || binding.target !== target.id || binding.kind !== 'bootstrap' || binding.program !== programPath(target.id))
                 fail('binding', 'Legacy bootstrap receipt changed.');
             let stopped = false;
             try {
@@ -447,6 +447,7 @@ export class GhidraContexts {
             fail('binding', 'Context process binding changed.');
         return this.verified(binding, this.workspace.target(scope.target));
     }
+    async observation(scope) { return this.call(scope, '/research_view'); }
     async call(scope, operation, parameters = {}) {
         if (Object.hasOwn(parameters, 'program'))
             fail('invalid', 'Program routing is owned by the session and target selectors.');
@@ -871,8 +872,8 @@ public class ${name} extends GhidraScript {
     }
     async closed(scope) {
         const context = this.workspace.context(scope), path = join(this.directory(), 'context', context.id, 'current.json');
-        const binding = JSON.parse(await readFile(path, 'utf8')), root = resolve(binding.root);
-        if (!root.startsWith(resolve(this.directory()) + sep) || await realpath(root) !== root || binding.context !== context.id || binding.target !== scope.target ||
+        const binding = JSON.parse(await readFile(path, 'utf8')), root = await realpath(binding.root);
+        if (!root.startsWith(resolve(this.directory()) + sep) || binding.context !== context.id || binding.target !== scope.target ||
             stable(JSON.parse(await readFile(join(root, 'process.json'), 'utf8'))) !== stable(binding))
             fail('binding', 'Closed context receipt changed.');
         try {

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

@@ -0,0 +1 @@
+export declare function decodedInstructions(raw: unknown, at: string, maxBytes: number, maxInstructions: number): Record<string, unknown>;

package/dist/src/decode-results.js

@@ -0,0 +1,21 @@
+import { createHash } from 'node:crypto';
+import { object, fail } from './model.js';
+import { address } from './research.js';
+export function decodedInstructions(raw, at, maxBytes, maxInstructions) {
+    const value = object(raw), input = value.input_bytes;
+    if (typeof input !== 'string' || !/^(?:[a-f0-9]{2})+$/.test(input) || input.length > maxBytes * 2 || value.input_sha256 !== createHash('sha256').update(Buffer.from(input, 'hex')).digest('hex') || address(value.address) !== at || !Array.isArray(value.instructions) || value.instructions.length > maxInstructions || typeof value.language !== 'string' || typeof value.stop_reason !== 'string' || !['byte_limit', 'instruction_limit', 'truncated_instruction', 'executable_block_end', 'terminal_flow', 'control_flow', 'context_unavailable', 'undecodable'].includes(value.stop_reason))
+        fail('partial', 'Malformed bounded instruction result.');
+    let consumed = 0;
+    for (const raw of value.instructions) {
+        const row = object(raw);
+        if (!Number.isSafeInteger(row.length) || Number(row.length) < 1 || typeof row.bytes !== 'string' || row.bytes !== input.slice(consumed * 2, (consumed + Number(row.length)) * 2) || row.bytes.length !== Number(row.length) * 2 || typeof row.mnemonic !== 'string' || !Array.isArray(row.operands) || row.operands.some(v => typeof v !== 'string') || !Array.isArray(row.direct_targets) || row.direct_targets.some(v => typeof v !== 'string') || typeof row.computed_flow !== 'boolean' || row.computed_flow && row.direct_targets.length)
+            fail('partial', 'Decoded instruction does not match input bytes or flow.');
+        const [space, offset] = at.includes(':') ? at.split(':') : [undefined, at];
+        if (address(row.address) !== (space ? space + ':' : '') + (BigInt('0x' + offset) + BigInt(consumed)).toString(16))
+            fail('partial', 'Decoded instruction address changed.');
+        consumed += Number(row.length);
+    }
+    if (value.consumed_bytes !== consumed || object(value.read_only ?? {}).modification_unchanged !== true)
+        fail('partial', 'Decoder omitted consumed bytes or read-only proof.');
+    return value;
+}

package/dist/src/function-inspection.d.ts

@@ -0,0 +1,31 @@
+import type { ResearchBackend } from './research.js';
+import type { Scope } from './workspace.js';
+export interface FunctionInspectionOptions {
+    limit: number;
+    offset: number;
+    total: number;
+    expectView?: string;
+    saveDirectory?: string;
+}
+export declare function inspectFunctions(backend: ResearchBackend, scope: Scope, parameters: Record<string, unknown>, options: FunctionInspectionOptions, view: {
+    revision?: string;
+    identity: string;
+}, observation?: unknown): Promise<{
+    value: {
+        save?: {
+            host: string;
+            directory: string;
+            manifest: string;
+        } | undefined;
+        view: {
+            revision?: string;
+            identity: string;
+        };
+        textBudget: {
+            maximumCharacters: number;
+            returnedCharacters: number;
+        };
+    };
+    session: string;
+    target: string;
+}>;

package/dist/src/function-inspection.js

@@ -0,0 +1,78 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { resolve, join, isAbsolute } from 'node:path';
+import { fail, object, digest } from './model.js';
+import { functionResult } from './function-results.js';
+import { textWindow } from './text-window.js';
+import { CliError } from '@eyeauras/cli-factory';
+const fields = new Set('signature classification return_type entry_point body_start body_end decompiled_code plate_comment comments labels tags parameters locals callers call_context callees xrefs disassembly jump_targets refs'.split(' '));
+export async function inspectFunctions(backend, scope, parameters, options, view, observation) {
+    if (options.saveDirectory !== undefined && !isAbsolute(options.saveDirectory))
+        fail('invalid', 'Save directory must be an absolute path on the owner host.');
+    const selectors = String(parameters.functions || parameters.function || '').split(',').map(s => s.trim());
+    if (!selectors.length || selectors.length > 20 || selectors.some(s => !s || s.length > 128) || new Set(selectors).size !== selectors.length)
+        fail('invalid', 'Select 1–20 distinct function names or addresses.');
+    const selectedFields = String(parameters.fields ?? '').split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+    if (selectedFields.some(s => !fields.has(s)))
+        fail('invalid', 'Unknown function field. Allowed fields: ' + [...fields].join(', '));
+    if (options.expectView !== undefined && options.expectView !== view.identity)
+        fail('binding', 'Function continuation view changed.', { reason: 'changed_view', view });
+    const raw = object(await backend.call(scope, '/get_functions', { ...parameters, functions: selectors.join(',') }));
+    if (backend.observation && digest(observation) !== digest(await backend.observation(scope)))
+        fail('binding', 'Native view changed during bulk function inspection.', { reason: 'changed_view', view });
+    const functions = object(raw.functions);
+    if (Object.keys(functions).length !== selectors.length || selectors.some(s => !Object.hasOwn(functions, s)))
+        fail('partial', 'Bulk function selectors changed.');
+    const output = Object.create(null), saved = [];
+    let remaining = options.total;
+    for (const [index, selector] of selectors.entries()) {
+        let found;
+        try {
+            found = functionResult({ functions: { [selector]: functions[selector] } }, selector);
+        }
+        catch (error) {
+            if (!(error instanceof CliError))
+                throw error;
+            const detail = object(error.result);
+            output[selector] = { error: detail.nativeDiagnostic ?? error.message, ...detail, status: detail.reason === 'function_not_found' ? 'not_found' : 'failed' };
+            continue;
+        }
+        const row = { ...found, status: 'success' };
+        if (typeof row.decompiled_code === 'string') {
+            const source = row.decompiled_code, window = textWindow(source, options.saveDirectory ? 0 : Math.min(options.limit, remaining), options.saveDirectory ? 0 : options.offset, Boolean(object(row.truncation ?? {}).decompiled_code));
+            const { content, ...metadata } = window;
+            remaining -= Array.from(content).length;
+            row.decompiled_code = content;
+            row.text = { ...metadata, returnedCharacters: Array.from(content).length, nextOffset: Math.min(window.totalCharacters, window.offset + Array.from(content).length) };
+            if (options.saveDirectory) {
+                if (Buffer.byteLength(source) > 4 * 1024 ** 2)
+                    fail('limit', 'Native function text exceeds the four MiB saved-file bound.');
+                const name = String(index).padStart(2, '0') + '-' + window.textSha256 + '.c';
+                saved.push({ name, content: source });
+                delete row.decompiled_code;
+                row.savedText = { file: join(resolve(options.saveDirectory), name), textSha256: window.textSha256, totalCharacters: window.totalCharacters, sourceTruncated: window.sourceTruncated, coverage: 'entire returned native text' };
+            }
+        }
+        else if (!selectedFields.length || selectedFields.includes('decompiled_code')) {
+            row.status = 'partial';
+            row.text = { reason: 'missing_decompiler_text' };
+        }
+        output[selector] = row;
+    }
+    if (!parameters.functions) {
+        const single = object(output[selectors[0]]);
+        if (single.status === 'failed' || single.status === 'not_found')
+            fail('partial', String(single.error), single);
+    }
+    const result = { ...(parameters.functions ? { ...raw, functions: output } : object(output[selectors[0]])), view, textBudget: { maximumCharacters: options.total, returnedCharacters: options.total - remaining }, ...(options.saveDirectory ? { save: { host: 'owner', directory: resolve(options.saveDirectory), manifest: join(resolve(options.saveDirectory), 'manifest.json') } } : {}) };
+    if (Buffer.byteLength(JSON.stringify(result)) > 1048576)
+        fail('limit', 'Function response exceeds one MiB; narrow fields or selectors.');
+    if (options.saveDirectory) {
+        // A fresh directory prevents overwrite and makes a partial filesystem failure observable.
+        const directory = resolve(options.saveDirectory);
+        await mkdir(directory, { recursive: false });
+        for (const file of saved)
+            await writeFile(join(directory, file.name), file.content, { flag: 'wx', mode: 0o600 });
+        await writeFile(join(directory, 'manifest.json'), JSON.stringify({ ...scope, value: result }, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    }
+    return { ...scope, value: result };
+}

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

@@ -0,0 +1,2 @@
+export declare function functionFailure(selector: string, reason: string, diagnostic?: unknown): never;
+export declare function functionResult(value: unknown, selector: string): Record<string, unknown>;

package/dist/src/function-results.js

@@ -0,0 +1,21 @@
+import { fail } from './model.js';
+const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+export function functionFailure(selector, reason, diagnostic) {
+    const nativeDiagnostic = typeof diagnostic === 'string' ? Array.from(diagnostic.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ')).slice(0, 500).join('') : undefined;
+    fail('partial', 'Function inspection failed: ' + reason + '.', { selector, reason, ...(nativeDiagnostic ? { nativeDiagnostic } : {}) });
+}
+export function functionResult(value, selector) {
+    if (!record(value) || !record(value.functions))
+        functionFailure(selector, 'invalid_native_shape');
+    const functions = value.functions;
+    if (Object.keys(functions).length !== 1 || !Object.hasOwn(functions, selector))
+        functionFailure(selector, 'selector_mismatch');
+    const found = functions[selector];
+    if (!record(found))
+        functionFailure(selector, 'invalid_native_shape');
+    if (found.error !== undefined)
+        functionFailure(selector, typeof found.error === 'string' && /^Function not found\b/i.test(found.error) ? 'function_not_found' : 'native_function_failure', found.error);
+    if (typeof found.name !== 'string' || !found.name || typeof found.entry_point !== 'string' || found.entry_point.length > 128 || !/^(?:[A-Za-z0-9_]+:)?(?:0x)?[a-fA-F0-9]+$/.test(found.entry_point))
+        functionFailure(selector, 'invalid_native_shape');
+    return found;
+}

package/dist/src/ghidra-processes.js

@@ -5,16 +5,17 @@ import { serverIdentity, stopLocalServer } from './server.js';
 import { HttpBridge } from './transport.js';
 import { registerExistingProcess } from './tool-runtime/supervisor.js';
 import { fail } from './model.js';
+import { analysisDirectory } from './analysis-storage.js';
 async function ownedPath(c, path) {
     if (typeof path !== 'string')
         fail('binding', 'Tool resource moved outside this profile.');
-    const supplied = resolve(path), profile = resolve(c.appArguments.AppDataDirectory), canonical = await realpath(profile);
-    const base = supplied.startsWith(profile + sep) ? profile : supplied.startsWith(canonical + sep) ? canonical : undefined;
+    const supplied = resolve(path), profile = resolve(c.appArguments.AppDataDirectory), canonical = await realpath(profile), analysis = await realpath(analysisDirectory(c));
+    const base = supplied.startsWith(profile + sep) ? profile : supplied.startsWith(canonical + sep) ? canonical : supplied.startsWith(analysis + sep) ? analysis : undefined;
     if (!base)
         fail('binding', 'Tool resource moved outside this profile.');
     // Keep Factory's raw AppData identity in process records, but compare native resources
     // under its canonical profile. Accept the parent alias, never a replaced child link.
-    const expected = join(canonical, relative(base, supplied));
+    const suffix = relative(base, supplied), expected = base === analysis ? supplied : ['workspace', 'runtime', 'materials', 'temp'].some(tree => suffix === tree || suffix.startsWith(tree + sep)) ? join(analysis, suffix) : join(canonical, suffix);
     if (await realpath(supplied) !== expected)
         fail('binding', 'Tool resource moved outside this profile.');
     return expected;
@@ -53,7 +54,7 @@ export function ghidraProcessHooks(workspace, close) {
     return {
         verify: verifyGhidraProcess,
         async discover(c) {
-            const directory = c.appArguments.AppDataDirectory, executable = runtimeSelection(directory)?.java ?? String(c.profile.values.java ?? 'unverified-legacy-executable');
+            const directory = c.appArguments.AppDataDirectory, executable = runtimeSelection(directory, analysisDirectory(c))?.java ?? String(c.profile.values.java ?? 'unverified-legacy-executable');
             async function walk(path, depth = 0) {
                 if (depth > 6)
                     return;

package/dist/src/initial-model.js

@@ -54,7 +54,8 @@ export async function initializeModel(workspace, target, binding, server, finger
         intent = await initialIntent(workspace, target.id);
     }
     if (!intent || typeof intent.id !== 'string' || !/^[a-f0-9-]{36}$/.test(intent.id) ||
-        Object.entries(expected).some(([key, value]) => stable(intent[key]) !== stable(value)))
+        Object.entries(expected).filter(([key]) => key !== 'input').some(([key, value]) => stable(intent[key]) !== stable(value)) ||
+        typeof intent.input !== 'string' || await realpath(intent.input) !== expected.input)
         fail('binding', 'Retained initial model differs from its input, load settings, runtime or repository authority.');
     if (workspace.model(target.id).state === 'opening')
         workspace.beginModelInitialization(target.id);

package/dist/src/native-inputs.js

@@ -81,7 +81,7 @@ export async function nativeRuntimeFingerprint(ghidraVersion, files) {
 }
 export async function nativeInputs(values, directory, c) {
     if (directory)
-        values = runtimeValues(dirname(directory), values);
+        values = runtimeValues(c?.appArguments.AppDataDirectory ?? dirname(directory), values, typeof values.analysisDirectory === 'string' ? values.analysisDirectory : undefined);
     if (!values.java || !values.ghidraHome)
         fail('configuration', 'Ghidra is not installed. Run insight-cli ghidra install, or supply external runtime paths.');
     const requested = [text(values.java, 4096), text(values.ghidraHome, 4096), text(values.mcpJar ?? packagedMcpJar, 4096)];
@@ -118,7 +118,7 @@ export async function nativeInputs(values, directory, c) {
     const files = await nativeRuntimeFiles(ghidraHome, java);
     const baseFingerprint = await nativeRuntimeFingerprint(ghidraVersion, [...files, { name: 'bridge/GhidraMCP-7.0.0.jar', path: mcpJar }]);
     if (directory) {
-        const selected = runtimeSelection(dirname(directory));
+        const selected = runtimeSelection(c?.appArguments.AppDataDirectory ?? dirname(directory), typeof values.analysisDirectory === 'string' ? values.analysisDirectory : undefined);
         if (selected && selected.fingerprint !== baseFingerprint)
             fail('binding', 'Selected runtime inputs differ from their installation receipt; reinstall or restore the verified files.');
     }

package/dist/src/queries.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { command, Permission } from '@eyeauras/cli-factory';
-import { scope } from './research.js';
+import { scope, number } from './research.js';
 import { fail } from './model.js';
 import { queryResult } from './query-results.js';
 import { key, flag, parsed, option, selectedOptions } from './arguments.js';
@@ -50,6 +50,8 @@ export function queryCommands(research) {
                 }
                 parameters[p.name] = parsed(p, input);
             }
+            if (q.path === '/get_functions')
+                return research(c).inspectFunctions(scope(o), parameters, { limit: number(o.limitChars ?? 16000, 32768, 1), offset: number(o.offsetChars ?? 0, 4 * 1024 ** 2), total: number(o.totalChars ?? 64000, 128000, 1), ...(o.expectView === undefined ? {} : { expectView: String(o.expectView) }), ...(o.saveOwnerDirectory === undefined ? {} : { saveDirectory: String(o.saveOwnerDirectory) }) });
             if (nativeQueries.has(q.path)) {
                 if (Number(parameters.timeout_seconds ?? 5) > 30)
                     fail('invalid', 'Native query timeout must be at most 30 seconds.');
@@ -62,7 +64,13 @@ export function queryCommands(research) {
                 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' ?
+        }, { permission: Permission.ReadOnly, options: [...selectedOptions, ...q.params.map(option), ...(q.path === '/get_functions' ? [
+                    { flags: '--limit-chars <count>', description: 'Per-function Unicode window, 1–32768', defaultValue: 16000 },
+                    { flags: '--offset-chars <count>', description: 'Per-function Unicode offset', defaultValue: 0 },
+                    { flags: '--total-chars <count>', description: 'Total returned decompiler characters, 1–128000', defaultValue: 64000 },
+                    { flags: '--expect-view <identity>', description: 'Reject continuation from another observed view' },
+                    { flags: '--save-owner-directory <path>', description: 'Save full returned native text and manifest in a NEW directory on the owner host' }
+                ] : []), ...(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));

package/dist/src/query-policy.js

@@ -1,6 +1,6 @@
 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',
+export const nativeQueries = new Set(['/research_view', '/decode_instructions', '/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']);

package/dist/src/research.d.ts

@@ -1,9 +1,11 @@
+import { type FunctionInspectionOptions } from './function-inspection.js';
 import type { Artifact } from './artifacts.js';
 import type { GhidraContext, Scope, ScalarChange, Publication, DebuggerState, GhidraLoadSettings } from './workspace.js';
 import { Workspace } from './workspace.js';
 import type { ToolMode } from './contexts.js';
 import type { ScriptPage } from './scripts.js';
 export interface ResearchBackend {
+    observation?(scope: Scope): Promise<unknown>;
     sdkFile?(operation: string, p: Record<string, unknown>): Promise<Record<string, unknown>>;
     archivePayloads?(scope: Scope, p: Record<string, unknown>): Promise<unknown>;
     debuggerStart?(scope: Scope): Promise<void>;
@@ -149,6 +151,25 @@ export declare class Research {
         session: string;
         target: string;
     }>;
+    inspectFunctions(selected: Scope, parameters: Record<string, unknown>, options: FunctionInspectionOptions): Promise<{
+        value: {
+            save?: {
+                host: string;
+                directory: string;
+                manifest: string;
+            } | undefined;
+            view: {
+                revision?: string;
+                identity: string;
+            };
+            textBudget: {
+                maximumCharacters: number;
+                returnedCharacters: number;
+            };
+        };
+        session: string;
+        target: string;
+    }>;
     xrefs(selected: Scope, at: string, limit: number, offset: number): Promise<{
         items: ({
             from: null;

package/dist/src/research.js

@@ -1,4 +1,6 @@
 import { textWindow } from './text-window.js';
+import { functionResult, functionFailure } from './function-results.js';
+import { inspectFunctions } from './function-inspection.js';
 import { fail, id, object, text, digest } from './model.js';
 import { fieldKey, scalarMerge, scalarRefresh } from './merge.js';
 import { verifyMutation } from './mutation-effects.js';
@@ -45,12 +47,6 @@ function comments(value) {
     }
     return observed;
 }
-function functionResult(value, selector) {
-    const result = object(value), functions = object(result.functions), found = object(functions[selector]);
-    if (Object.keys(functions).length !== 1 || found.error || typeof found.name !== 'string' || !found.name || !found.entry_point)
-        fail('partial', 'Function result omitted, failed or changed the requested selector.');
-    return found;
-}
 function pageResult(value, key, limit, offset) {
     const result = object(value);
     if (!Array.isArray(result[key]) || result[key].length > limit || !Number.isSafeInteger(result.total) || Number(result.total) < 0 ||
@@ -286,15 +282,25 @@ export class Research {
             const value = await backend.call(selected, '/get_functions', { functions: at, fields: decompile ? 'entry_point,signature,decompiled_code' : 'entry_point,signature', include_call_context: false });
             const result = functionResult(value, at);
             if (typeof result.signature !== 'string')
-                fail('partial', 'Function result lacks its signature.');
+                functionFailure(at, 'missing_signature');
             if (decompile && typeof result.decompiled_code !== 'string')
-                fail('partial', 'Function decompilation did not produce text.');
+                functionFailure(at, 'missing_decompiler_text');
             const listing = object(await backend.call(selected, '/get_comment', { address: result.entry_point }));
             const window = decompile ? textWindow(String(result.decompiled_code), page?.limit ?? 16000, page?.offset ?? 0, Boolean(object(result.truncation ?? {}).decompiled_code)) : undefined;
             const { content, ...paging } = window ?? { content: undefined };
             return { ...selected, address: publicAddress(result.entry_point), name: result.name, signature: result.signature, comments: comments(listing), ...(window ? { code: content, ...paging } : {}) };
         });
     }
+    async inspectFunctions(selected, parameters, options) {
+        return this.ordered(selected, async () => {
+            const backend = await this.backend();
+            await backend.open(selected);
+            const context = this.workspace.context(selected);
+            const observation = await backend.observation?.(selected);
+            const view = { revision: revision(context.baseRevision), identity: digest({ target: selected.target, context: context.id, generation: context.generation, snapshot: context.workingSnapshot, epoch: context.viewEpoch ?? 0, observation }) };
+            return inspectFunctions(backend, selected, parameters, options, view, observation);
+        });
+    }
     async xrefs(selected, at, limit, offset) {
         return this.ordered(selected, async () => {
             const backend = await this.backend();

package/dist/src/runtime-manager.js

@@ -1,4 +1,5 @@
 import { runTool } from './tool-runtime/run.js';
+import { analysisDirectory } from './analysis-storage.js';
 import { readFile, mkdir, rename, rm, realpath, readdir, stat, cp } from 'node:fs/promises';
 import { existsSync, realpathSync } from 'node:fs';
 import { join, dirname, resolve, delimiter, basename } from 'node:path';
@@ -104,9 +105,9 @@ export class RuntimeManager {
     }
     // Canonicalize storage once the profile exists, without creating it for passive status.
     // Keep the Factory directory for shared process/lock identity and existing run receipts.
-    get root() { return runtimeRoot(existsSync(this.directory) ? realpathSync.native(this.directory) : this.directory); }
+    get root() { const root = runtimeRoot(existsSync(this.directory) ? realpathSync.native(this.directory) : this.directory); return existsSync(root) ? realpathSync.native(root) : root; }
     async status() {
-        const selected = runtimeSelection(this.directory), values = selected ? runtimeValuesForStatus(selected, this.c.profile.values) : this.c.profile.values;
+        const selected = runtimeSelection(this.directory, analysisDirectory(this.c)), values = selected ? runtimeValuesForStatus(selected, this.c.profile.values) : this.c.profile.values;
         const java = typeof values.java === 'string' ? values.java : undefined, home = typeof values.ghidraHome === 'string' ? values.ghidraHome : undefined;
         const missing = [];
         if (!java || !existsSync(java))
@@ -203,7 +204,7 @@ export class RuntimeManager {
             for (const name of names) {
                 if (!/^[a-f0-9-]{36}$/.test(name))
                     continue;
-                const root = join(this.root, parent, name, ...(parent === 'stages' ? ['validation'] : []));
+                const root = join(analysisDirectory(this.c), 'runtime', parent, name, ...(parent === 'stages' ? ['validation'] : []));
                 if (existsSync(join(root, 'server/local.json'))) {
                     if (await realpath(root) !== resolve(root))
                         fail('binding', 'Retained runtime probe moved outside its owned storage.');
@@ -285,7 +286,7 @@ export class RuntimeManager {
         return withToolLock(this.directory, 'ghidra', async () => {
             await assertUnused(this.directory, 'ghidra');
             await this.cleanupProbes();
-            const selected = runtimeSelection(this.directory);
+            const selected = runtimeSelection(this.directory, analysisDirectory(this.c));
             if (!selected)
                 fail('configuration', 'No managed selection exists; externally configured profile paths are never removed.');
             if (purgeCache && selected.id) {
@@ -339,7 +340,7 @@ export class RuntimeManager {
     }
     async doctor() {
         await this.cleanupProbes();
-        const root = join(this.root, 'checks', randomUUID()), values = runtimeValues(this.directory, this.c.profile.values);
+        const root = join(analysisDirectory(this.c), 'runtime/checks', randomUUID()), values = runtimeValues(this.directory, this.c.profile.values, analysisDirectory(this.c));
         const inputs = await nativeInputs(values, undefined, this.c), native = await this.probe(inputs, root);
         let debuggerCheck = { state: 'host_specific' };
         if (managedGhidraDebugger())

package/dist/src/runtime-selection.d.ts

@@ -9,5 +9,5 @@ export interface RuntimeSelection {
     uninstalledAt?: string;
 }
 export declare const runtimeRoot: (directory: string) => string;
-export declare function runtimeSelection(directory: string): RuntimeSelection | undefined;
-export declare function runtimeValues(directory: string, values: Record<string, unknown>): Record<string, unknown>;
+export declare function runtimeSelection(directory: string, analysis?: string): RuntimeSelection | undefined;
+export declare function runtimeValues(directory: string, values: Record<string, unknown>, analysis?: string): Record<string, unknown>;