@eyeauras/insight-cli 0.3.1 → 0.4.0

package/dist/src/function-boundaries.js

@@ -0,0 +1,68 @@
+import { fail, object } from './model.js';
+const hex = (v) => { if (typeof v !== 'string' || !/^(?:0|[1-9a-f][a-f0-9]{0,15})$/.test(v))
+    fail('partial', 'Malformed runtime boundary address.'); return v; };
+const big = (v) => BigInt('0x' + v);
+const unavailable = new Set(['headers_not_mapped', 'unsupported_machine', 'unsupported_optional_header', 'unsupported_language', 'table_not_mapped', 'runtime_range_not_initialized_executable', 'unwind_not_mapped', 'memory_read_failed', 'short_read']);
+const malformed = new Set(['invalid_dos_signature', 'invalid_pe_offset', 'invalid_pe_signature', 'short_optional_header', 'invalid_image_headers', 'address_overflow', 'invalid_rva', 'invalid_exception_directory', 'invalid_runtime_range', 'unordered_or_overlapping_ranges', 'invalid_unwind_rva']);
+/** Validate evidence and selection policy independently, before any function inspection/save. */
+export function locatedBoundaries(raw, request, modification) {
+    const v = object(raw), s = object(v.boundaryLookup), items = object(v.items);
+    if (v.protocol !== 'insight-function-boundaries-v1' || typeof v.modification !== 'string')
+        fail('partial', 'Malformed function-boundary protocol.');
+    if (v.modification !== modification)
+        fail('binding', 'Native view changed during boundary lookup.', { reason: 'changed_view' });
+    const state = String(s.state), complete = state === 'validated' || state === 'absent';
+    const reason = String(s.reason), reasonValid = state === 'validated' ? reason === 'validated' : state === 'absent' ? reason === 'no_exception_directory' : state === 'incomplete' ? ['byte_limit', 'timeout'].includes(reason) : state === 'unavailable' ? unavailable.has(reason) : state === 'malformed' && malformed.has(reason);
+    if (!reasonValid || s.complete !== complete || s.headersSource !== 'current-mapped-memory' || s.maximumBytes !== request.unwindMaximum || s.deadlineMilliseconds !== 5000)
+        fail('partial', 'Malformed function-boundary coverage.');
+    for (const key of ['recordCount', 'recordsValidated', 'bytesRead'])
+        if (!Number.isSafeInteger(s[key]) || Number(s[key]) < 0)
+            fail('partial', 'Malformed boundary counters.');
+    if (Number(s.bytesRead) > request.unwindMaximum || Number(s.recordCount) > Math.floor(0xffffffff / 12) || Number(s.recordsValidated) > Number(s.recordCount) || Number(s.recordsValidated) * 12 > Number(s.bytesRead) || state === 'validated' && (s.recordCount !== s.recordsValidated || Number(s.recordCount) < 1) || state === 'absent' && Number(s.recordCount) !== 0)
+        fail('partial', 'Inconsistent function-boundary counters.');
+    if (complete && Number(s.bytesRead) < (state === 'absent' ? 200 : 208 + 12 * Number(s.recordCount)))
+        fail('partial', 'Impossible complete boundary read accounting.');
+    if (Object.keys(items).length !== request.addresses.length || request.addresses.some(at => !Object.hasOwn(items, at)))
+        fail('binding', 'Boundary selector set changed.', { reason: 'selector_mismatch' });
+    const entries = new Map();
+    for (const at of request.addresses) {
+        const row = object(items[at]);
+        let database = null, boundary = null;
+        if (row.database !== null) {
+            database = object(row.database);
+            const entry = hex(database.entryPoint);
+            if (!['exact-entry', 'recorded-containing'].includes(String(database.kind)) || database.recordedBodyContainsAddress !== true || (database.kind === 'exact-entry') !== (entry === at))
+                fail('partial', 'Malformed recorded boundary facts.');
+        }
+        if (row.boundary !== null) {
+            boundary = object(row.boundary);
+            const lo = hex(boundary.begin), hi = boundary.endExclusive === '10000000000000000' ? boundary.endExclusive : hex(boundary.endExclusive);
+            hex(boundary.tableRecordAddress);
+            if (!complete || state !== 'validated' || Number(s.recordCount) < 1 || big(lo) > big(at) || big(at) >= big(hi) || boundary.source !== 'pe-exception-directory' || boundary.semanticMembership !== 'not-established' || boundary.instructionBoundary !== 'not-checked' || boundary.unwindInfo !== 'not-parsed')
+                fail('partial', 'Malformed or unvalidated runtime region.');
+        }
+        const conflict = boundary && database && boundary.begin !== database.entryPoint;
+        const resolution = { requestedAddress: at, kind: 'unresolved', recordedBodyContainsAddress: database !== null, database, boundary };
+        if (row.status === 'resolved') {
+            const entry = hex(row.entryPoint), kind = boundary ? 'pe-runtime-range' : database?.kind;
+            if (!complete || conflict || !kind || row.kind !== kind || entry !== (boundary?.begin ?? database?.entryPoint) || row.recordedBodyContainsAddress !== (database !== null))
+                fail('partial', 'Inconsistent runtime entry selection.');
+            entries.set(at, { entry, resolution: { ...resolution, kind: String(kind) } });
+        }
+        else {
+            let expected;
+            if (!complete)
+                expected = 'boundary_lookup_' + state;
+            else if (conflict)
+                expected = 'boundary_conflict';
+            else if (boundary)
+                expected = 'runtime_entry_not_defined';
+            else
+                expected = 'no_runtime_range_or_recorded_function';
+            if (row.status !== 'unresolved' || row.reason !== expected || complete && !boundary && database || expected === 'runtime_entry_not_defined' && database || row.entryPoint !== undefined || row.kind !== undefined)
+                fail('partial', 'Inconsistent unresolved runtime boundary.');
+            entries.set(at, { status: 'partial', reason: expected, resolution });
+        }
+    }
+    return { entries, boundaryLookup: s };
+}

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

@@ -0,0 +1,33 @@
+export interface EntryOptions {
+    resolveAddress?: string;
+    maxEntryDistance?: number;
+    maxUnwindBytes?: number;
+}
+export interface LegacyEntryRequest {
+    addresses: string[];
+    maximum: number;
+}
+export type EntryRequest = LegacyEntryRequest | {
+    addresses: string[];
+    unwindMaximum: number;
+};
+export interface EntryResolution {
+    requestedAddress: string;
+    kind: string;
+    recordedBodyContainsAddress: boolean;
+    distanceBytes?: number;
+    database?: unknown;
+    boundary?: unknown;
+}
+export interface LocatedEntry {
+    entry?: string;
+    resolution?: EntryResolution;
+    reason?: string;
+    status?: 'partial';
+}
+export declare function functionSelectors(parameters: Record<string, unknown>): string[];
+export declare function entryAddress(value: unknown): string;
+/** Validate before opening/probing native state; ordinary inspection keeps its original contract. */
+export declare function entryRequest(parameters: Record<string, unknown>, options: EntryOptions): EntryRequest | undefined;
+/** The authenticated native lookup supplies DB facts, never inferred semantic membership. */
+export declare function locatedEntries(raw: unknown, request: LegacyEntryRequest, modification: string): Map<string, LocatedEntry>;

package/dist/src/function-entries.js

@@ -0,0 +1,84 @@
+import { fail, object } from './model.js';
+export function functionSelectors(parameters) {
+    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.');
+    return selectors;
+}
+export function entryAddress(value) {
+    if (typeof value !== 'string' || !/^(?:0x)?[a-f0-9]{1,16}$/i.test(value))
+        fail('invalid', 'Address resolution requires 1–20 default-space hexadecimal addresses, not names.');
+    return BigInt('0x' + value.replace(/^0x/i, '')).toString(16);
+}
+/** Validate before opening/probing native state; ordinary inspection keeps its original contract. */
+export function entryRequest(parameters, options) {
+    if (options.resolveAddress === undefined) {
+        if (options.maxEntryDistance !== undefined || options.maxUnwindBytes !== undefined)
+            fail('invalid', 'Resolution budgets require --resolve-address.');
+        return;
+    }
+    if (options.resolveAddress === 'containing-or-pe-runtime') {
+        if (options.maxEntryDistance !== undefined)
+            fail('invalid', 'PE runtime resolution excludes --max-entry-distance.');
+        const unwindMaximum = options.maxUnwindBytes ?? 4194304;
+        if (!Number.isSafeInteger(unwindMaximum) || unwindMaximum < 1 || unwindMaximum > 16777216)
+            fail('invalid', '--max-unwind-bytes must be between 1 and 16777216.');
+        if (parameters.function && parameters.functions)
+            fail('invalid', 'Supply --function or --functions, not both, for address resolution.');
+        return { addresses: [...new Set(functionSelectors(parameters).map(entryAddress))], unwindMaximum };
+    }
+    if (options.maxUnwindBytes !== undefined)
+        fail('invalid', '--max-unwind-bytes requires containing-or-pe-runtime.');
+    if (options.resolveAddress !== 'containing-or-preceding')
+        fail('invalid', '--resolve-address must be containing-or-preceding.');
+    const maximum = options.maxEntryDistance;
+    if (typeof maximum !== 'number' || !Number.isSafeInteger(maximum) || maximum < 1 || maximum > 65536)
+        fail('invalid', 'Address resolution requires --max-entry-distance between 1 and 65536 bytes.');
+    if (parameters.function && parameters.functions)
+        fail('invalid', 'Supply --function or --functions, not both, for address resolution.');
+    return { addresses: [...new Set(functionSelectors(parameters).map(entryAddress))], maximum };
+}
+const misses = new Set(['address_out_of_range', 'address_not_in_initialized_executable_block', 'no_preceding_entry', 'entry_outside_block', 'entry_distance_exceeded']);
+/** The authenticated native lookup supplies DB facts, never inferred semantic membership. */
+export function locatedEntries(raw, request, modification) {
+    const result = object(raw), items = object(result.items);
+    if (result.protocol !== 'insight-function-entries-v1' || typeof result.modification !== 'string')
+        fail('partial', 'Function-entry lookup returned malformed protocol facts.');
+    if (result.modification !== modification)
+        fail('binding', 'Native view changed during function-entry lookup.', { reason: 'changed_view' });
+    if (Object.keys(items).length !== request.addresses.length ||
+        request.addresses.some(at => !Object.hasOwn(items, at)))
+        fail('binding', 'Function-entry lookup returned another view or selector set.', { reason: 'selector_mismatch' });
+    const out = new Map();
+    for (const at of request.addresses) {
+        const row = object(items[at]);
+        if (row.status === 'not_found') {
+            if (typeof row.reason !== 'string' || !misses.has(row.reason))
+                fail('partial', 'Function-entry lookup returned an invalid policy miss.');
+            out.set(at, { reason: row.reason });
+            continue;
+        }
+        if (row.status !== 'resolved' || typeof row.entryPoint !== 'string' || !/^[a-f0-9]{1,16}$/.test(row.entryPoint) ||
+            entryAddress(row.entryPoint) !== row.entryPoint || typeof row.recordedBodyContainsAddress !== 'boolean')
+            fail('partial', 'Function-entry lookup returned malformed entry facts.');
+        const entry = row.entryPoint, contains = row.recordedBodyContainsAddress, kind = row.kind;
+        // Address strings are hexadecimal even when they contain digits only.
+        const actualDistance = BigInt('0x' + at) - BigInt('0x' + entry);
+        if (kind === 'exact-entry') {
+            if (entry !== at || !contains || row.distanceBytes !== 0)
+                fail('partial', 'Function-entry lookup returned inconsistent exact-entry facts.');
+        }
+        else if (kind === 'recorded-containing') {
+            if (entry === at || !contains || row.distanceBytes !== undefined)
+                fail('partial', 'Function-entry lookup returned inconsistent recorded containment.');
+        }
+        else if (kind === 'preceding-entry-candidate') {
+            if (contains || actualDistance < 1n || actualDistance > BigInt(request.maximum) || row.distanceBytes !== Number(actualDistance))
+                fail('partial', 'Function-entry lookup returned an out-of-policy candidate.');
+        }
+        else
+            fail('partial', 'Function-entry lookup returned an unknown resolution kind.');
+        out.set(at, { entry, resolution: { requestedAddress: at, kind, recordedBodyContainsAddress: contains, ...(kind === 'recorded-containing' ? {} : { distanceBytes: row.distanceBytes }) } });
+    }
+    return out;
+}

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

@@ -1,6 +1,7 @@
 import type { ResearchBackend } from './research.js';
 import type { Scope } from './workspace.js';
-export interface FunctionInspectionOptions {
+import { type EntryOptions } from './function-entries.js';
+export interface FunctionInspectionOptions extends EntryOptions {
     limit: number;
     offset: number;
     total: number;
@@ -10,7 +11,7 @@ export interface FunctionInspectionOptions {
 export declare function inspectFunctions(backend: ResearchBackend, scope: Scope, parameters: Record<string, unknown>, options: FunctionInspectionOptions, view: {
     revision?: string;
     identity: string;
-}, observation?: unknown): Promise<{
+}, observation?: unknown, observe?: () => Promise<unknown>): Promise<{
     value: {
         save?: {
             host: string;
@@ -25,6 +26,7 @@ export declare function inspectFunctions(backend: ResearchBackend, scope: Scope,
             maximumCharacters: number;
             returnedCharacters: number;
         };
+        boundaryLookup?: Record<string, unknown> | undefined;
     };
     session: string;
     target: string;

package/dist/src/function-inspection.js

@@ -2,77 +2,112 @@ 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 { timed } from './internal-timing.js';
 import { textWindow } from './text-window.js';
 import { CliError } from '@eyeauras/cli-factory';
+import { entryAddress, entryRequest, functionSelectors, locatedEntries } from './function-entries.js';
+import { locatedBoundaries } from './function-boundaries.js';
 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) {
+export async function inspectFunctions(backend, scope, parameters, options, view, observation, observe) {
     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 selectors = functionSelectors(parameters), lookup = entryRequest(parameters, options);
     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' };
+    const observeAfter = observe ?? (backend.observation ? () => backend.observation(scope) : undefined);
+    let entries, boundaryLookup, raw, nativeSelectors;
+    const guard = async () => { if (observeAfter && digest(observation) !== digest(await observeAfter()))
+        fail('binding', 'Native view changed during bulk function inspection.', { reason: 'changed_view', view }); };
+    try {
+        if (lookup) {
+            if (!observeAfter || typeof object(observation ?? {}).modification !== 'string')
+                fail('unsupported', 'Address resolution requires guarded native observations.');
+            if ('unwindMaximum' in lookup) {
+                const result = locatedBoundaries(await backend.call(scope, '/insight/function-boundaries/v1', { addresses: lookup.addresses.join(','), max_unwind_bytes: lookup.unwindMaximum }), lookup, String(object(observation).modification));
+                entries = result.entries;
+                boundaryLookup = result.boundaryLookup;
             }
+            else
+                entries = locatedEntries(await backend.call(scope, '/insight/function-entries/v1', { addresses: lookup.addresses.join(','), max_entry_distance: lookup.maximum }), lookup, String(object(observation).modification));
         }
-        else if (!selectedFields.length || selectedFields.includes('decompiled_code')) {
-            row.status = 'partial';
-            row.text = { reason: 'missing_decompiler_text' };
-        }
-        output[selector] = row;
+        nativeSelectors = entries ? [...new Set([...entries.values()].flatMap(row => row.entry ? [row.entry] : []))] : selectors;
+        const nativeParameters = { ...parameters, ...(entries ? { function: '' } : {}), functions: nativeSelectors.join(','), ...(entries && selectedFields.length ? { fields: [...new Set([...selectedFields, 'entry_point'])].join(',') } : {}) };
+        raw = nativeSelectors.length ? object(await backend.call(scope, '/get_functions', nativeParameters)) : { functions: {} };
     }
-    if (!parameters.functions) {
-        const single = object(output[selectors[0]]);
-        if (single.status === 'failed' || single.status === 'not_found')
-            fail('partial', String(single.error), single);
+    catch (error) {
+        await guard();
+        throw error;
     }
-    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 };
+    await guard();
+    return timed('adapter.normalize', 'functions.inspect', async () => {
+        const functions = object(raw.functions);
+        if (Object.keys(functions).length !== nativeSelectors.length || nativeSelectors.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()) {
+            const located = entries?.get(entryAddress(selector)), selected = located?.entry ?? selector;
+            const provenance = located?.resolution ? { ...(located.entry ? { entry_point: located.entry } : {}), resolution: { ...located.resolution, requestedAddress: selector } } : {};
+            if (located?.reason) {
+                output[selector] = { status: located.status ?? 'not_found', selector, reason: located.reason, error: 'No function was selected by the explicit address-resolution policy.', ...provenance };
+                continue;
+            }
+            let found;
+            try {
+                found = functionResult({ functions: { [selected]: functions[selected] } }, selected, { requireEntryPoint: Boolean(entries) || !selectedFields.length || selectedFields.includes('entry_point') });
+            }
+            catch (error) {
+                if (!(error instanceof CliError))
+                    throw error;
+                const detail = object(error.result);
+                output[selector] = { error: error.message, ...detail, ...provenance, ...(entries ? { selector } : {}), status: detail.reason === 'function_not_found' ? 'not_found' : 'failed' };
+                continue;
+            }
+            if (located?.entry && entryAddress(found.entry_point) !== located.entry)
+                fail('binding', 'Inspected function differs from the resolved entry.', { reason: 'selector_mismatch' });
+            const row = { ...found, ...provenance, 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' || boundaryLookup && single.reason)
+                fail('partial', String(single.error), { ...single, ...(boundaryLookup ? { boundaryLookup } : {}), view });
+        }
+        const result = { ...(parameters.functions ? { ...(entries ? (typeof raw.program === 'string' ? { program: raw.program } : {}) : raw), functions: output } : object(output[selectors[0]])), ...(boundaryLookup ? { boundaryLookup } : {}), 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.
+            await timed('adapter.save-text', 'functions.inspect', async () => {
+                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

@@ -1,2 +1,4 @@
 export declare function functionFailure(selector: string, reason: string, diagnostic?: unknown): never;
-export declare function functionResult(value: unknown, selector: string): Record<string, unknown>;
+export declare function functionResult(value: unknown, selector: string, options?: {
+    requireEntryPoint?: boolean;
+}): Record<string, unknown>;

package/dist/src/function-results.js

@@ -2,9 +2,11 @@ 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 } : {}) });
+    const recovery = reason === 'function_not_found' ? ' For a sparse interior address, use ghidra functions inspect --functions <address> --resolve-address containing-or-preceding --max-entry-distance <bytes> with the same session/target; a preceding entry is only a candidate. For known executable bytes without a function definition, use ghidra functions decode --address <hex> --max-bytes 64 --max-instructions 16 with the same session/target. Decode is read-only and does not create functions or xrefs.' :
+        reason === 'native_function_failure' || reason === 'missing_decompiler_text' ? ' For an existing function entry, try ghidra functions force-decompile --function <entry> with the same session/target. This refreshes decompiler output, not Listing instructions or stored xrefs; use functions decode for bounded local bytes.' : '';
+    fail('partial', 'Function inspection failed: ' + reason + '.' + recovery, { selector, reason, ...(nativeDiagnostic ? { nativeDiagnostic } : {}) });
 }
-export function functionResult(value, selector) {
+export function functionResult(value, selector, options = {}) {
     if (!record(value) || !record(value.functions))
         functionFailure(selector, 'invalid_native_shape');
     const functions = value.functions;
@@ -15,7 +17,11 @@ export function functionResult(value, selector) {
         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))
+    if (typeof found.name !== 'string' || !found.name)
         functionFailure(selector, 'invalid_native_shape');
+    if (options.requireEntryPoint !== false || found.entry_point !== undefined) {
+        if (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/inline-script.d.ts

@@ -0,0 +1,15 @@
+import type { HttpBridge } from './transport.js';
+export declare const inlineSourceHash: (code: string) => string;
+/** Native facts come from the fixed helper's receipt, never from caller console output. */
+export declare function inlineReceipt(raw: unknown, expected: {
+    attemptId: string;
+    requestId: string;
+    sourceSha256: string;
+}): {
+    response: Record<string, unknown>;
+    safe: boolean;
+};
+export declare function runInline(http: HttpBridge, program: string, root: string, parameters: Record<string, unknown>, requestId: string): Promise<{
+    response: Record<string, unknown>;
+    safe: boolean;
+}>;

package/dist/src/inline-script.js

@@ -0,0 +1,62 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, writeFile, readFile, open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join } from 'node:path';
+import { object, fail } from './model.js';
+export const inlineSourceHash = (code) => createHash('sha256').update(code, 'utf8').digest('hex');
+/** Native facts come from the fixed helper's receipt, never from caller console output. */
+export function inlineReceipt(raw, expected) {
+    const r = object(raw), execution = object(r.execution), build = object(r.compilerOutput);
+    if (r.protocol !== 'insight-inline-v1' || r.attemptId !== expected.attemptId || r.requestId !== expected.requestId || r.sourceSha256 !== expected.sourceSha256 ||
+        typeof r.success !== 'boolean' || !['prepare', 'compile', 'load', 'initialize', 'construct', 'execute'].includes(String(execution.stage)) ||
+        !['not_started', 'may_have_started'].includes(String(execution.userCode)) || ![false, null].includes(execution.entrypointInvoked) ||
+        typeof build.text !== 'string' || Buffer.byteLength(build.text) > 32772 || typeof build.truncated !== 'boolean' ||
+        typeof r.console_output !== 'string' || Buffer.byteLength(r.console_output) > 32772 || typeof r.outputTruncated !== 'boolean')
+        fail('partial', 'Native inline-script receipt is absent, malformed or belongs to another attempt.');
+    if (r.success === false) {
+        const d = object(r.diagnostic);
+        if (typeof d.kind !== 'string' || typeof d.message !== 'string' || d.message.length > 2048)
+            fail('partial', 'Native inline-script failure omitted its diagnostic.');
+    }
+    if (r.success === true && (execution.userCode !== 'may_have_started' || execution.stage !== 'execute'))
+        fail('partial', 'Native inline-script completion contradicts its execution facts.');
+    const safe = r.success === false && execution.userCode === 'not_started' && execution.entrypointInvoked === false && ['prepare', 'compile', 'load'].includes(String(execution.stage));
+    if (execution.userCode === 'not_started' && !safe)
+        fail('partial', 'Native inline-script non-execution facts contradict their stage.');
+    return { response: r, safe };
+}
+export async function runInline(http, program, root, parameters, requestId) {
+    if (typeof parameters.code !== 'string' || Buffer.byteLength(parameters.code) > 1048576 || parameters.code.includes('\0'))
+        fail('invalid', 'Inline Java source must contain at most one MiB of UTF-8 text without NUL.');
+    const attemptId = randomUUID(), sourceSha256 = inlineSourceHash(parameters.code), directory = join(root, 'inline-attempts', attemptId);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const request = join(directory, 'request.json');
+    await writeFile(request, JSON.stringify({ attemptId, requestId, sourceSha256, code: parameters.code, args: parameters.args ?? '' }), { mode: 0o600, flag: 'wx' });
+    const name = 'InsightInlineScript_' + randomUUID().replaceAll('-', ''), source = await readFile(new URL('../../references/native/InsightInlineScript.java', import.meta.url), 'utf8');
+    // Only this fixed shim enters the upstream provider. User source is compiled separately.
+    const ack = object(await http.call('/run_script_inline', { program, code: source.replace('public class InsightInlineScript ', 'public class ' + name + ' '), args: Buffer.from(request, 'utf8').toString('base64') }));
+    if (ack.success !== true || typeof ack.console_output !== 'string' || !ack.console_output.includes('INSIGHT_INLINE_COMPLETE'))
+        fail('partial', 'Native inline-script executor did not acknowledge its completed attempt.');
+    const handle = await open(join(directory, 'receipt.json'), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    let raw;
+    try {
+        const maximum = 1048576, stat = await handle.stat();
+        if (!stat.isFile() || stat.size > maximum)
+            fail('partial', 'Native inline-script receipt exceeds its bound.');
+        const bytes = Buffer.alloc(maximum + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            const next = await handle.read(bytes, length, bytes.length - length, null);
+            if (!next.bytesRead)
+                break;
+            length += next.bytesRead;
+        }
+        if (length > maximum)
+            fail('partial', 'Native inline-script receipt exceeds its bound.');
+        raw = JSON.parse(bytes.subarray(0, length).toString('utf8'));
+    }
+    finally {
+        await handle.close();
+    }
+    return inlineReceipt(raw, { attemptId, requestId, sourceSha256 });
+}

package/dist/src/internal-timing.d.ts

@@ -0,0 +1,3 @@
+/** Internal diagnostics only: fixed operation names, never argv, payloads, paths or errors. */
+export declare function timed<T>(phase: string, operation: string, action: () => Promise<T>): Promise<T>;
+export declare function traceCommand<T>(root: string, command: string, action: () => Promise<T>): Promise<T>;

package/dist/src/internal-timing.js

@@ -0,0 +1,52 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { mkdir, appendFile, stat, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { performance } from 'node:perf_hooks';
+const current = new AsyncLocalStorage(), writes = new Map();
+/** Internal diagnostics only: fixed operation names, never argv, payloads, paths or errors. */
+export async function timed(phase, operation, action) {
+    const trace = current.getStore();
+    if (!trace)
+        return action();
+    const span = randomUUID(), started = performance.now();
+    let outcome = 'success';
+    try {
+        return await current.run({ ...trace, parent: span }, action);
+    }
+    catch (error) {
+        outcome = 'failure';
+        throw error;
+    }
+    finally {
+        if (trace.rows.length < 1024)
+            trace.rows.push({ trace: trace.id, span, parent: trace.parent ?? null, command: trace.command, phase, operation, startedMs: started - trace.started, durationMs: performance.now() - started, outcome });
+        else
+            trace.overflow.count++;
+    }
+}
+export async function traceCommand(root, command, action) {
+    const trace = { id: randomUUID(), command, started: performance.now(), rows: [], overflow: { count: 0 } }, at = new Date().toISOString();
+    try {
+        return await current.run(trace, () => timed('facade.command', command, action));
+    }
+    finally {
+        const directory = join(root, 'diagnostics'), path = join(directory, 'timings.jsonl'), previous = writes.get(path) ?? Promise.resolve();
+        const pending = previous.catch(() => { }).then(async () => {
+            await mkdir(directory, { recursive: true, mode: 0o700 });
+            if (await stat(path).then(s => s.size, () => 0) > 8 * 1024 ** 2)
+                await rename(path, path + '.previous');
+            await appendFile(path, trace.rows.map(row => JSON.stringify({ schema: 1, at, ...row, droppedSpans: trace.overflow.count })).join('\n') + '\n', { mode: 0o600 });
+        });
+        writes.set(path, pending);
+        // Telemetry loss cannot change an acknowledged program operation into a failed write.
+        try {
+            await pending;
+        }
+        catch { }
+        finally {
+            if (writes.get(path) === pending)
+                writes.delete(path);
+        }
+    }
+}

package/dist/src/lifecycle.js

@@ -1,4 +1,4 @@
-import { command, Permission } from '@eyeauras/cli-factory';
+import { command, Permission, CliError } from '@eyeauras/cli-factory';
 import { scope } from './research.js';
 import { id, fail, object, digest } from './model.js';
 import { selectedOptions } from './arguments.js';
@@ -24,13 +24,23 @@ export class Lifecycle {
     async change(selected, operation, callerId) {
         const reserved = this.workspace.reserveRequest(selected, 'ghidra.' + operation, {}, callerId);
         return this.research.ordered(selected, async () => {
-            const request = this.workspace.request(reserved.request.id);
+            let request = this.workspace.request(reserved.request.id), backend;
+            if (reserved.replay && ['running', 'unknown'].includes(request.state)) {
+                backend = await this.backend();
+                await this.research.reconcileRequests(selected, backend);
+                request = this.workspace.request(request.id);
+            }
             if (reserved.replay && request.state !== 'accepted') {
                 if (request.state === 'applied')
                     return request.result;
-                fail('unknown', 'This lifecycle outcome is retained; it is not re-executed.', request.result);
+                throw new CliError('This lifecycle outcome remains unresolved; inspect its retained worker before retrieving it again.', {
+                    code: 'coordinator.unknown', result: { ...selected, state: request.state, requestId: request.callerId ?? request.id },
+                    next: [['sessions', 'status', selected.session, '--target', selected.target],
+                        ...(operation === 'close' ? [['tools', 'processes', '--tool', 'ghidra', '--session', selected.session, '--target', selected.target]] : [['ghidra', 'open', '--session', selected.session, '--target', selected.target]])]
+                });
             }
-            const backend = await this.backend(), unresolved = this.workspace.unresolved(selected);
+            backend ??= await this.backend();
+            const unresolved = this.workspace.unresolved(selected);
             const closingExternal = operation === 'close' && unresolved.length > 0 && unresolved.every(intent => ['debugger', 'ui'].includes(String(object(intent.execution ?? {}).kind)));
             const alreadyEnded = closingExternal && backend.closed ? await backend.closed(selected) : false;
             if (!closingExternal)

package/dist/src/native-inputs.d.ts

@@ -11,7 +11,7 @@ export interface NativeInputs {
     extensionRoots?: string[];
     serverClasspath?: string;
 }
-export declare const pinnedMcpJar = "7084e2fda16dc779dd05398e48821ff3f9ace4d32757ea143b257b39689e5fbd";
+export declare const pinnedMcpJar = "f4a9272e911466ed774c8cf73bc1adf1daef6009d895fda57aa0b28522fcdf32";
 export declare const packagedMcpJar: string;
 /** Ghidra has its own cache/settings overrides in addition to Java's home/tmp properties. */
 export declare const nativeJvmDirectories: (root: string) => string[];